gopdf 0.6.1

This page is generated from the same registries used by the application.

Configuration options

Assign options with gopdf.options.<name> = <value> in Lua or :set <name>=<value> at runtime. Colors use { r, g, b } in Lua and r,g,b or #RRGGBB with :set.

Option	Type	Default	Description
`alt_background`	color	`{20, 20, 20}`	Viewer background in alternate-color mode.
`alt_colors`	boolean	`false`	Start with alternate colors enabled.
`alt_colors_keep_images`	boolean	`true`	Keep raster images in their own colors in alternate-color mode.
`alt_foreground`	color	`{255, 255, 255}`	UI foreground in alternate-color mode.
`alt_page_background`	color	`{17, 17, 17}`	Page background in alternate-color mode.
`alt_status_bar_color`	color	`{20, 20, 20}`	Status bar background in alternate-color mode.
`anchor_position`	string	`"center"`	Viewport anchor: center, top, or bottom.
`animation_frame_ms`	integer	`16`	Animation timestep in milliseconds; clamped to at least 1.
`annotation_colors`	table	`{"#ffe066", "#8ce99a", "#74c0fc", "#ffa8a8"}`	Highlight colours offered by the highlight picker, as #RRGGBB.
`anti_aliasing`	integer	`8`	MuPDF antialiasing level from 0 through 8.
`auto_reload`	boolean	`true`	Reload the document when its file changes on disk.
`auto_reload_delay_ms`	integer	`200`	Milliseconds a changed file must stay unwritten before it reloads, so a file being written reloads once.
`autoscroll_max_speed`	number	`20000`	Fastest autoscroll speed in pixels per second, however far the pointer is from the anchor; 0 or less removes the limit.
`autoscroll_speed_factor`	number	`1`	Multiplier for autoscroll speed at every pointer distance from the anchor, up to autoscroll_max_speed; clamped to at least 0.01.
`background`	color	`{220, 220, 220}`	Viewer background color.
`completion_max_items`	integer	`10`	Maximum command-completion rows.
`copy_on_select`	boolean	`true`	Copy selected text to the clipboard when the mouse selection is released.
`dual_page`	boolean	`false`	Start in dual-page mode.
`first_page_offset`	boolean	`true`	Treat the first page as a standalone cover in dual-page mode.
`fit_mode`	string	`"page"`	Initial fit mode: page, width, height, or manual.
`foreground`	color	`{20, 20, 20}`	UI foreground color.
`highlight_foreground`	color	`{0, 0, 0}`	Border and text of highlights: selections, search matches and link hints.
`hint_chars`	string	`"asdfghjkl"`	Characters used for link hint labels, in order of preference.
`invert_scroll`	boolean	`false`	Invert horizontal and vertical discrete mouse-wheel scrolling.
`invert_smooth_scroll`	boolean	`false`	Invert horizontal and vertical smooth wheel or trackpad scrolling.
`link_preview`	boolean	`true`	Preview the destination of an internal link after hovering it briefly.
`link_preview_delay_ms`	integer	`400`	Milliseconds to hover an internal link before its preview appears.
`link_schemes`	table	`{"http", "https", "mailto"}`	URI schemes that document links may open externally; other links only show their target.
`loading_indicator`	boolean	`true`	Animate a loading indicator on pages still rendering for the first time.
`max_zoom`	number	`8`	Maximum manual zoom scale.
`min_zoom`	number	`0.5`	Minimum manual zoom scale.
`mouse_text_select`	boolean	`true`	Enable text selection with the left mouse button.
`mupdf_store_mb`	integer	`256`	MuPDF cache for fonts and decoded images in MiB; applies to newly opened documents.
`outline_height_percent`	integer	`80`	Outline overlay height as a percentage of the window.
`outline_initial_depth`	integer	`1`	Outline levels expanded when the outline opens.
`outline_width_percent`	integer	`70`	Outline overlay width as a percentage of the window.
`overview_gap`	integer	`16`	Gap in pixels between the page overview’s cells.
`overview_max_columns`	integer	`12`	Most columns the page overview shows, whether fitted to the window or set with zoom_out.
`overview_thumb_width`	integer	`220`	Width in pixels the page overview aims to show each page at, which sets how many columns fit.
`page_background`	color	`{255, 255, 255}`	Normal page background color.
`page_cache_memory_mb`	integer	`512`	Maximum memory in MiB for cached page renders; 0 disables the limit.
`page_cache_size`	integer	`0`	Deprecated and ignored; the cache is bounded by page_cache_memory_mb.
`page_gap`	integer	`0`	Vertical gap between pages; aliases page_gap_vertical.
`page_gap_horizontal`	integer	`0`	Horizontal gap between pages in a spread.
`page_gap_vertical`	integer	`0`	Vertical gap between page rows.
`pinch_sensitivity`	number	`1`	Trackpad pinch zoom sensitivity; 1 preserves the gesture scale.
`presentation_background`	color	`{0, 0, 0}`	Background around the page in presentation mode.
`prompt_history_max`	integer	`100`	Maximum entries kept in each of the command and search prompt histories; 0 keeps none.
`recent_files_max`	integer	`20`	Maximum recent files retained and displayed.
`render_mode`	string	`"continuous"`	Initial render mode: continuous or single.
`render_oversample`	number	`1`	Render scale multiplier; values above 1 supersample.
`render_threads`	integer	`0`	Page rendering threads; 0 picks one per core up to 4, leaving a core free. Applies to newly opened documents.
`scroll_off`	integer	`0`	Minimum number of rows kept visible above and below the selected item in UI menus, like Vim’s scrolloff.
`scroll_step`	integer	`64`	Keyboard and mouse scroll distance in pixels.
`search_current_color`	color	`{255, 150, 50}`	Highlight of the current search match.
`search_highlight_color`	color	`{255, 224, 102}`	Highlight of search matches.
`selection_color`	color	`{255, 224, 102}`	Highlight of selected text, the selected menu row, link hints and the overview’s selected page.
`sequence_timeout_ms`	integer	`700`	Maximum delay between keys in a binding sequence.
`session_database`	boolean	`true`	Persist per-document view state, marks, and recent files.
`smooth_scroll`	table	`{ mouse = true, trackpad = true, keyboard = true }`	Animate scrolling for selected inputs; assignments update only specified mouse, trackpad, and keyboard fields.
`smooth_scroll_dampening`	number	`0.8`	Catch-up factor for smooth scrolling per animation frame; higher values are more responsive and less damped; clamped to 0.01 through 1.
`smooth_zoom`	table	`{ mouse = true, trackpad = true, keyboard = true }`	Animate zooming for selected inputs; assignments update only specified mouse, trackpad, and keyboard fields.
`smooth_zoom_dampening`	number	`0.8`	Catch-up factor for smooth zooming per animation frame; higher values are more responsive and less damped; clamped to 0.01 through 1.
`spread_gap`	integer	`0`	Horizontal spread gap; aliases page_gap_horizontal.
`status_bar_color`	color	`{220, 220, 220}`	Normal status bar background color.
`status_bar_left`	string	`"{modified}{message}"`	Left status bar template.
`status_bar_padding`	integer	`8`	Horizontal status bar padding in pixels.
`status_bar_right`	string	`"{page}/{total} {mode} fit={fit} rot={rot} {zoom}"`	Right status bar template.
`status_bar_visible`	boolean	`true`	Show the status bar.
`trim_margins`	boolean	`false`	Lay pages out by their content, trimming blank margins.
`trim_padding`	integer	`8`	Margin in points kept around a page’s content when trimming margins.
`ui_font`	string	`""`	Installed UI font family; empty uses the built-in font.
`ui_font_path`	string	`""`	Explicit UI font file path; overrides ui_font, ui_font_style, and ui_font_weight.
`ui_font_size`	integer	`14`	UI font size in pixels.
`ui_font_style`	string	`"normal"`	UI font style: normal, italic, or oblique.
`ui_font_weight`	font-weight	`400`	UI font weight as CSS number 100-900 or alias such as normal, medium, semibold, bold, or black.
`zoom_step`	number	`1.15`	Factor zoom_in multiplies the zoom by, and zoom_out divides it by; above 1.

Commands

Command	Description
`:back`	Jump back to the previous position
`:colors normal\|alt`	Set color mode
`:copy`	Copy the selection
`:cover [on\|off]`	Show the first page alone in dual-page mode
`:dual [on\|off]`	Toggle or set dual-page mode
`:fit width\|height\|page\|manual`	Set fit mode
`:forward`	Jump forward again after :back
`:fullscreen [on\|off]`	Toggle or set fullscreen
`:help`	Show commands, key bindings, search flags and options
`:highlight`	Highlight the selection in the last colour used
`:hints`	Label links on screen to follow one by typing its hint
`:keybinds`	Toggle the keybinds menu
`:lua <code>`	Execute Lua code inline
`:matches`	List every match of the current search
`:mode continuous\|single`	Set render mode
`:next`	Go to the next search match
`:noh`	Clear the search highlights
`:open <filename>`	Open another PDF relative to the current document
`:open_file_picker`	Open the PDF file picker
`:outline`	Open the document outline
`:overview`	Toggle the page overview grid
`:page PAGE, :p PAGE, :N`	Jump to a page number or label
`:present`	Toggle presentation mode
`:prev`	Go to the previous search match
`:print [lp options]`	Print the saved document from a dialog, or directly with lp options such as -d office -P 1-3
`:quit, :q`	Exit; :q! discards unsaved edits
`:recent`	Open the recent-files menu
`:redo`	Reapply the last undone edit
`:reload-config`	Reload the config file
`:rotate [cw\|ccw\|DEGREES]`	Rotate by a quarter turn, or to 0, 90, 180 or 270
`:search [-r] [-i] [-w] [-p] <text>`	Search document text
`:set [option[?]\|option!\|option=value]`	Inspect or change options
`:statusbar [on\|off]`	Show or hide the status bar
`:trim [on\|off]`	Lay pages out by their content, trimming margins
`:undo`	Undo the last edit
`:write [path], :w`	Save edits, or a copy to path; :wq saves and exits
`:zoom in\|out\|reset\|PERCENT`	Zoom a step, reset, or set e.g. :zoom 150

Search flags: -r regular expression, -i ignore case, -w whole word, -p current page only. Flags can be combined.

Lua functions

The index below is followed by a detailed entry for every function. Lua errors are raised as protected-call errors; use pcall when a script should handle them without aborting the current dispatch.

Index

Function	Summary
`gopdf.bind(key, action)`	binds a key sequence to an action or Lua callback.
`gopdf.bind_mouse(event, action)`	binds a mouse event to an action or Lua callback.
`gopdf.cache.clear()`	drops all rendered tiles and thumbnails.
`gopdf.cache.entries()`	returns the number of cached page tiles and thumbnails.
`gopdf.cache.limit([mib])`	reads or changes the render cache memory limit in MiB.
`gopdf.cache.pending()`	returns the number of queued tile renders.
`gopdf.clear_pending_keys()`	clears pending key, mark, and numeric-count input.
`gopdf.clipboard.get_text()`	returns the current clipboard contents as UTF-8 text.
`gopdf.clipboard.set_text(text)`	replaces the clipboard with UTF-8 text.
`gopdf.command(command)`	executes a viewer command.
`gopdf.current_count()`	returns the pending numeric action count.
`gopdf.fit_mode([mode])`	reads or changes the fit mode. Valid modes are manual, page, width, and height.
`gopdf.formats.extensions()`	returns extensions supported by the linked document engine.
`gopdf.formats.supports(path)`	checks whether a path extension names a supported format.
`gopdf.fullscreen([enabled])`	reads or changes fullscreen state.
`gopdf.goto_document_point(spec)`	moves to a page coordinate in document space.
`gopdf.log(level, message)`	writes a diagnostic without changing the user-facing message.
`gopdf.message([text])`	reads or replaces the viewer’s status message.
`gopdf.mode()`	returns the current viewer input mode.
`gopdf.open(path)`	opens another document.
`gopdf.open_external(uri_or_path)`	asks the operating system to open a URI or path.
`gopdf.page([page])`	reads or changes the current physical page.
`gopdf.page_count()`	returns the current document’s page count.
`gopdf.pending_keys()`	returns pending key-sequence tokens.
`gopdf.pick_directory(callback)`	opens the native directory picker and invokes a callback with its result.
`gopdf.pick_file(callback)`	opens the native document picker, filtered to the formats this build can open, and invokes a callback with its result.
`gopdf.plugin.register(id[, spec])`	registers and returns a lazily loaded plugin module.
`gopdf.recent_files([limit])`	returns recent document paths.
`gopdf.render_mode([mode])`	reads or changes the render mode. Valid modes are continuous and single.
`gopdf.rotation([degrees])`	reads or changes clockwise rotation in degrees.
`gopdf.schedule(callback)`	queues a callback on the main Lua thread after the current dispatch.
`gopdf.search(query[, backward])`	starts an asynchronous document search.
`gopdf.search_match_count()`	returns the number of discovered search matches.
`gopdf.search_match_index()`	returns the current search match index.
`gopdf.search_query()`	returns the active search query.
`gopdf.ui.create(spec)`	creates a searchable list view.
`gopdf.unbind(key)`	removes a key binding.
`gopdf.unbind_mouse(event)`	removes a mouse binding.
`gopdf.zoom([scale])`	reads or changes the zoom and clamps values to the configured range.

`gopdf.bind(key, action)`

binds a key sequence to an action or Lua callback.

Parameters

key: A printable key, special key name, modified key, or multi-key sequence, such as j, <PgDn>, <C-p>, or gg. See Key and mouse names.
action: A bindable action such as gopdf.next_page, or a Lua callback.

Returns

Nothing. A later binding replaces an earlier binding for the same key.

Errors

Raises an error when the key or action is invalid.

Example

gopdf.bind("<C-p>", function()
  gopdf.page(1)
end)

`gopdf.bind_mouse(event, action)`

binds a mouse event to an action or Lua callback.

Parameters

event: A mouse event such as wheel_down, left_down, or <C-wheel_up>. See Key and mouse names.
action: A bindable action or a Lua callback.

Returns

Nothing.

Errors

Raises an error when the event or action is invalid.

Example

gopdf.bind_mouse("<C-wheel_up>", gopdf.zoom_in)

`gopdf.cache.clear()`

drops all rendered tiles and thumbnails.

Returns

Nothing.

Example

gopdf.cache.clear()

`gopdf.cache.entries()`

returns the number of cached page tiles and thumbnails.

Returns

The number of rendered textures currently held in the render cache.

Example

gopdf.log("debug", tostring(gopdf.cache.entries()))

`gopdf.cache.limit([mib])`

reads or changes the render cache memory limit in MiB.

An omitted limit reads the current limit; supplying an integer changes it and returns the resulting limit. 0 removes the limit.

`gopdf.cache.pending()`

returns the number of queued tile renders.

Returns

The number of tile renders waiting to be processed.

Example

if gopdf.cache.pending() > 0 then gopdf.message("rendering") end

`gopdf.clear_pending_keys()`

clears pending key, mark, and numeric-count input.

Returns

Nothing.

Example

gopdf.clear_pending_keys()

`gopdf.clipboard.get_text()`

returns the current clipboard contents as UTF-8 text.

Returns

The current clipboard contents as UTF-8 text.

Errors

Raises an error when clipboard access is unavailable.

`gopdf.clipboard.set_text(text)`

replaces the clipboard with UTF-8 text.

Parameters

text: UTF-8 text to place on the clipboard.

Returns

Nothing.

`gopdf.command(command)`

executes a viewer command.

Parameters

command: A viewer command, with or without the leading colon.

Returns

Nothing.

Errors

Raises an error when the command is invalid or cannot be executed.

Example

gopdf.command(":fit width")

`gopdf.current_count()`

returns the pending numeric action count.

Returns

The pending numeric prefix as a string, or an empty string when no count is pending.

Example

gopdf.message("count: " .. gopdf.current_count())

`gopdf.fit_mode([mode])`

reads or changes the fit mode. Valid modes are manual, page, width, and height.

Parameters

mode: Optional manual, page, width, or height value. Omit it to read the current mode.

Returns

The active fit mode.

Errors

Raises an error for an invalid mode or when setting it without a viewer host.

Example

gopdf.fit_mode("width")

`gopdf.formats.extensions()`

returns extensions supported by the linked document engine.

Returns

An alphabetically sorted array of lower-case extensions without leading dots.

Example

for _, extension in ipairs(gopdf.formats.extensions()) do
  gopdf.log("debug", extension)
end

`gopdf.formats.supports(path)`

checks whether a path extension names a supported format.

Parameters

path: A path whose extension should be checked.

Returns

True when the extension names a format supported by the linked engine.

Behavior

This is an extension hint. Opening also sniffs content, so a missing or misleading extension may still open.

Example

if gopdf.formats.supports("book.epub") then gopdf.open("book.epub") end

`gopdf.fullscreen([enabled])`

reads or changes fullscreen state.

Parameters

enabled: Optional boolean. Omit it to read the current state.

Returns

The current fullscreen state.

Example

gopdf.fullscreen(true)

`gopdf.goto_document_point(spec)`

moves to a page coordinate in document space.

Parameters

spec: A table containing 1-based integer page and numeric x and y coordinates.

Returns

Nothing. Coordinates are measured from the page’s top-left corner in document points.

Example

gopdf.goto_document_point({ page = 3, x = 72, y = 144 })

`gopdf.log(level, message)`

writes a diagnostic without changing the user-facing message.

Parameters

level: debug, info, warn, or error.
message: Diagnostic text written to the application log, tagged with the plugin responsible, or config outside plugin code.

Returns

Nothing. The viewer’s user-facing message is unchanged.

Example

gopdf.log("info", "plugin loaded")

`gopdf.message([text])`

reads or replaces the viewer’s status message.

Parameters

text: Optional replacement status message.

Returns

The current message as a string.

Example

gopdf.message("ready")
local current = gopdf.message()

`gopdf.mode()`

returns the current viewer input mode.

Returns

The current input mode: normal, command, goto, or search; nil without a viewer host.

Example

if gopdf.mode() == "normal" then gopdf.message("ready") end

`gopdf.open(path)`

opens another document.

Parameters

path: A document path. Relative paths resolve from the current document directory.

Returns

Nothing. Opening is applied by the viewer after the current Lua dispatch.

Errors

Raises an error when the document cannot be opened.

Example

gopdf.open("appendix.pdf")

`gopdf.open_external(uri_or_path)`

asks the operating system to open a URI or path.

Parameters

uri_or_path: A URI or filesystem path for the operating system’s default application.

Returns

Nothing.

Errors

Raises an error when the operating-system opener cannot be started.

Example

gopdf.open_external("https://example.com")

`gopdf.page([page])`

reads or changes the current physical page.

Parameters

page: Optional 1-based physical page number to navigate to.

Returns

The current 1-based page number, or nil when no document is open.

Example

local page = gopdf.page()
gopdf.page(page + 1)

`gopdf.page_count()`

returns the current document’s page count.

Returns

The number of pages, or nil when no document is open.

Example

if (gopdf.page_count() or 0) > 100 then gopdf.message("long document") end

`gopdf.pending_keys()`

returns pending key-sequence tokens.

Returns

An array of pending key-sequence tokens.

Example

for _, key in ipairs(gopdf.pending_keys()) do gopdf.log("debug", key) end

`gopdf.pick_directory(callback)`

opens the native directory picker and invokes a callback with its result.

Parameters

callback: Receives { success, path, cancelled, error } after the native picker closes.

Returns

Nothing. The callback completes before this function returns.

Example

gopdf.pick_directory(function(result)
  if result.success then gopdf.message(result.path) end
end)

`gopdf.pick_file(callback)`

opens the native document picker, filtered to the formats this build can open, and invokes a callback with its result.

Parameters

callback: Receives { success, path, cancelled, error } after the native picker closes.

Returns

Nothing. The picker and callback complete before this function returns.

Errors

Raises an error when the callback fails.

Example

gopdf.pick_file(function(result)
  if result.success then gopdf.open(result.path) end
end)

`gopdf.plugin.register(id[, spec])`

registers and returns a lazily loaded plugin module.

Parameters

id: The plugin ID currently being loaded by require.
spec: Optional plugin option declarations.

Returns

The plugin module table.

Errors

Raises an error when the ID is invalid, undiscovered, disabled, or does not match the plugin currently being loaded.

Example

local plugin = gopdf.plugin.register("my-plugin")

`gopdf.recent_files([limit])`

returns recent document paths.

Parameters

limit: Optional maximum number of paths. Defaults to recent_files_max.

Returns

An array of document paths, or an empty array when session storage is disabled.

`gopdf.render_mode([mode])`

reads or changes the render mode. Valid modes are continuous and single.

Parameters

mode: Optional continuous or single value. Omit it to read the current mode.

Returns

The active render mode.

Errors

Raises an error for an invalid mode or when setting it without a viewer host.

Example

gopdf.render_mode("single")

`gopdf.rotation([degrees])`

reads or changes clockwise rotation in degrees.

Parameters

degrees: Optional clockwise rotation. Omit it to read the current rotation.

Returns

The normalized clockwise rotation, or nil without a viewer host.

Example

gopdf.rotation(90)

`gopdf.schedule(callback)`

queues a callback on the main Lua thread after the current dispatch.

Parameters

callback: A zero-argument callback to run on the main Lua thread after the current dispatch.

Returns

An operation handle with numeric id, cancel(), and active() members.

Example

local handle = gopdf.schedule(function() gopdf.message("later") end)

`gopdf.search(query[, backward])`

starts an asynchronous document search.

Parameters

query: Search text, optionally prefixed with -r, -i, -w, or -p flags.
backward: Optional boolean selecting backward search.

Returns

Nothing. Matching runs asynchronously.

Example

gopdf.search("-iw introduction")

`gopdf.search_match_count()`

returns the number of discovered search matches.

Returns

The number of matches discovered so far. Search may still be running.

Example

gopdf.message(gopdf.search_match_count() .. " matches")

`gopdf.search_match_index()`

returns the current search match index.

Returns

The current 1-based match index, or nil when no match is focused.

Example

local index = gopdf.search_match_index()

`gopdf.search_query()`

returns the active search query.

Returns

The active query without search flags, or an empty string when search is inactive.

Example

local query = gopdf.search_query()

`gopdf.ui.create(spec)`

creates a searchable list view.

The spec may contain id, title, rows, selected, scroll, query, searchable, on_select, and on_close. Rows may be strings or row tables with text, value, id, secondary, depth, and disabled fields.

Returns

A view object with show, close, visible, row/query setters, and state accessors.

Example

local view = gopdf.ui.create({
  title = "Recent files",
  rows = gopdf.recent_files(10),
  on_select = function(_, path) gopdf.open(path) end,
})
view:show()

`gopdf.unbind(key)`

removes a key binding.

Parameters

key: The key or key sequence to remove.

Returns

Nothing. Removing an unbound key is harmless.

Errors

Raises an error when the key is invalid.

Example

gopdf.unbind("<C-p>")

`gopdf.unbind_mouse(event)`

removes a mouse binding.

Parameters

event: The mouse event to remove.

Returns

Nothing. Removing an unbound event is harmless.

Errors

Raises an error when the event is invalid.

Example

gopdf.unbind_mouse("middle_down")

`gopdf.zoom([scale])`

reads or changes the zoom and clamps values to the configured range.

Parameters

scale: Optional manual zoom scale. Omit it to read the current scale.

Returns

The current zoom scale, or nil without a viewer host.

Errors

Raises an error when the scale is invalid or cannot be set.

Example

gopdf.zoom(1.5)

UI views

Create views with local view = gopdf.ui.create(spec), then call view:show(). The specification supports id, title, rows, selected, scroll, query, searchable, on_select, and on_close. A row may be a string or a table with text, value, id, secondary, depth, and disabled.

View methods are show(), close(), visible(), set_rows(rows), set_selected(index), set_scroll(scroll), set_query(query), selected(), scroll(), and query(). Selection indices are 1-based, with 0 meaning no selection. on_select receives (index, value, text, id), preserving the original row index and ID when the list is filtered. on_close runs for user, programmatic, replacement, and document-close paths.

Portable API

The gopdf tables below are available to configuration and plugin Lua code.

Module	Returns / fields	Description
`gopdf.platform`	table	Also available from `require("gopdf.platform")`. Fields: `os` (`linux`, `macos`, or `windows`), `arch`, `home_dir`, `config_dir`, `data_dir`, `cache_dir`, and `temp_dir`. Directory fields are absolute when the platform supplies a location and may be empty when it does not.
`gopdf.path`	table	Also available from `require("gopdf.path")`. Fields: `separator`, `list_separator`; functions: `join(...)`, `clean(path)`, `basename(path)`, `dirname(path)`, `extension(path)`, `is_absolute(path)`, `absolute(path)`, `relative(base, target)`, and `expand_home(path)`. Operations use native platform path rules; `expand_home` expands only `~`, `~/...`, and `~\...`.
`gopdf.json`	table	Also available from `require("gopdf.json")`. `encode(value)` returns compact JSON and `decode(text)` returns a Lua value. `null` is the stable module-local JSON null sentinel. Arrays require contiguous positive integer keys; objects require string keys. Cycles, sparse or mixed tables, non-finite numbers, unsupported Lua values, and trailing input are errors. Decoded empty arrays and objects retain their shape when re-encoded.

Document inspection

These read the open document. The gopdf.document fields path, name, extension, exists, size_bytes, and page_count remain available and are refreshed when the document changes. The functions below raise an error when no document is open. Rectangles are x0, y0, x1, y1 in unrotated PDF points.

Function	Returns / fields	Description
`gopdf.document.metadata()`	table	Return document metadata: `format`, `encryption`, `title`, `author`, `subject`, `keywords`, `creator`, `producer`, `creation_date`, and `modification_date`. Absent fields are empty strings.
`gopdf.document.outline()`	table[]	Return the outline as a tree. Each entry has `title`, `uri`, `external`, `page`, `children`, and optional `x` and `y` destination coordinates. `page` is 1-based, or 0 when the entry has no page destination.
`gopdf.document.page_info(page)`	table	Return `page`, `label`, `width`, `height`, and `bounds` for a 1-based page. Sizes are unrotated PDF points; an out-of-range page raises an error.
`gopdf.document.selection()`	table	Return the current selection: `active`, `text`, and `pages`, a list in page order of `{ page = n, quads = { ... } }` with quads as bounding rectangles. `pages` is empty when nothing is selected.
`plugin.document:page_text(page, callback)`	handle	Extract a page’s text asynchronously. The result adds `page` and `text`.
`plugin.document:page_links(page, callback)`	handle	Read a page’s links asynchronously. The result adds `page` and `links`; each link has `bounds`, `uri`, `external`, `page`, and optional `x` and `y`.

Plugins

Plugins are discovered without being executed. Enable one explicitly with local plugin = require("plugin-id"); only the required plugin and its declared dependencies execute. The entrypoint must call gopdf.plugin.register("plugin-id"[, spec]); require returns the registered module.

A plugin manifest is gopdf-plugin.json with id, version, module, and dependencies; only id is required, and unrecognised fields are ignored. module selects lua/<module>.lua or lua/<module>/init.lua. Plugin modules contain id, version, actions, fs, timer, storage, http, and document, plus register_action, register_command, on, off, and job. Registered actions use plugin-id.action; commands use :plugin-id-command, where the command name cannot contain -; options use plugin-id.option.

Function	Returns / fields	Description
`plugin.fs:read_dir(path[, options], callback)`	handle	Read one directory asynchronously. `options.follow_symlinks` defaults to false. Without following, a symlink supplied as `path` is rejected; entries themselves are reported as symlinks.
`plugin.fs:stat(path[, options], callback)`	handle	Stat a path asynchronously. `options.follow_symlinks` defaults to false.
`plugin.timer:after(ms, callback)`	handle	Call `callback()` once after `ms` milliseconds. `ms` may be zero.
`plugin.timer:every(ms, callback)`	handle	Call `callback()` repeatedly, waiting `ms` milliseconds between dispatches. `ms` must be greater than zero.
`plugin.storage:get(key)`	value or nil	Synchronously return the value stored for this plugin ID, or nil when absent or when no session database is available.
`plugin.storage:set(key, value)`	none	Synchronously persist a plugin-scoped value. Supports nil, booleans, finite numbers, strings, contiguous arrays, and string-keyed objects; tables cannot be cyclic or mix array and object keys. Raises an error when no session database is available; the value is not silently discarded.
`plugin.storage:delete(key)`	none	Synchronously delete a plugin-scoped value.
`plugin.storage:keys()`	string[]	Synchronously return this plugin’s keys in lexical order.
`plugin.http:request(spec, callback)`	handle	Make an asynchronous HTTP request. `spec` has required `url` (`http` or `https`) and optional `method` (default `GET`), string-to-string `headers`, `body`, and positive `timeout_ms`.
`plugin:job(spec, callback)`	handle	Start a subprocess without invoking a shell. `spec.command` is required; optional fields are string-array `args`, `cwd`, positive `timeout_ms`, string-to-string `env` additions, and `stdin`.

Handles and results

Every schedule, filesystem, timer, HTTP, document-extraction, and job call returns a handle with numeric id, cancel(), and active(). active() becomes false before a one-shot completion callback runs. Repeating timers remain active between callbacks until cancelled. cancel() is idempotent, removes the operation, and does not invoke its callback, so delivered result tables always have cancelled=false. Callbacks run serially on the main Lua thread, never on worker goroutines.

Result	Returns / fields	Description
`picker result`	`success`, `path`, `cancelled`, `error`	Cancellation is a normal result: `cancelled=true`, `success=false`, empty `path`, and empty `error`.
`fs.stat result`	`success`, `error`, `cancelled`, `timed_out`; on success: `name`, `path`, `type`, `size_bytes`, `modified_unix`	`type` is `file`, `directory`, `symlink`, or `other`. `modified_unix` is whole seconds since the Unix epoch.
`fs.read_dir result`	`success`, `error`, `cancelled`, `timed_out`, `entries`	On success, `entries` is an array of the same file-information fields returned by `stat`.
`http result`	`success`, `status`, `headers`, `body`, `error`, `timed_out`, `cancelled`	On transport failure, status is 0 and body and headers are empty. Response header values are arrays of strings. HTTP error status codes are completed responses and do not by themselves set `success=false`.
`job result`	`id`, `success`, `code`, `stdout`, `stderr`, `error`, `timed_out`, `cancelled`	`success` requires exit code 0, no launch/wait error, and no timeout. `code` is -1 when no process exit code is available.

Limits

Resource	Returns / fields	Description
`Storage value`	65,536 bytes	Limit applies to the encoded JSON value for each key.
`HTTP response body`	8 MiB	A larger response fails the operation; request bodies have no API-specific size limit.
`HTTP redirects`	10	Following a redirect after the tenth redirect fails the operation.
`Job stdout`	4 MiB	Captured independently; additional output is discarded.
`Job stderr`	4 MiB	Captured independently; additional output is discarded.

Lifecycle

Each plugin has an isolated local-module cache and search root. It may require another discovered plugin by ID only when that ID is declared in dependencies. Dependencies load first, and events are delivered in activation order, so dependencies receive an event before their dependents. Registration of actions, commands, and event subscriptions is allowed only while the plugin entrypoint is loading; off(id), storage calls, timers, filesystem and HTTP operations, and jobs remain available afterward.

A successful :reload-config replaces the Lua state and cancels all handles and jobs from the old generation without invoking their callbacks. If reload fails, the previous state and its operations remain active. A failed plugin load rolls back that plugin and cancels work it started. Viewer shutdown emits shutdown before runtime close; close then cancels remaining operations and jobs. Storage is keyed by plugin ID in the session database and survives reloads and application restarts.

Supported events are app_ready, document_open_pre, document_opened, document_close_pre, document_closed, document_reloaded, config_reloaded, mouse_button_pre, mouse_button, selection_changed, page_changed, zoom_changed, option_changed, and shutdown. page_changed carries page, label, previous_page, and page_count; zoom_changed carries scale, previous_scale, and percent. Both are emitted once per frame with the settled value, so a continuous gesture reports where it came to rest. Event callbacks run in subscription order within each plugin; returning true marks an event consumed where the host supports consumption but does not stop later callbacks.

Plugin search paths are the platform data/config plugin directories and are rescanned by :reload-config. Disable plugin discovery with --no-plugins, or start from built-in defaults with --no-config, which also skips the generated settings file.

Single instance

Instances are per document. Each window listens on a socket named after the document it is showing, and the address follows the document when the window opens another one. --unique hands the request to the window already showing that document and exits; with no such window, this process opens it. --goto PAGE opens at a page and --goto PAGE:X:Y at a point on it, overriding any remembered session position, whether the work is done here or by an existing window. --command TEXT runs a viewer command there, as typed after :, including any command registered by a plugin. An unrecognised command exits non-zero. X and Y are points measured from the page’s top-left corner, which is also SyncTeX’s convention. Sockets live under $XDG_RUNTIME_DIR/gopdf on Linux, the per-user temporary directory on macOS, and %LOCALAPPDATA%\gopdf on Windows. They are mode 0600 and named by a hash of the document path, which keeps them within the platform socket length limit. A socket left by a crashed process is reclaimed on the next start.

Key and mouse names

gopdf.bind and gopdf.unbind take a key sequence; gopdf.bind_mouse and gopdf.unbind_mouse take a mouse event. An unknown name is an error. To find the name of a key, bind it in :keybinds, which records the keys you press.

Keys

A sequence is one or more keys written one after another, such as gg, g? or <C-w>j. Each key must follow the one before within sequence_timeout_ms. Digits 1 to 9 start a count, as in 5j or 12g, and ' and " jump to and set marks, so binding a sequence that begins with any of them is an error.

Printable keys are written as the character they type with the current keyboard layout, so on a US keyboard Shift+1 is !. Letters are case-sensitive: J is Shift+j, or j with Caps Lock on. On layouts without Latin letters, letter keys are read as their QWERTY letters. Write < as <lt>.

Other keys are written by name in angle brackets. Names are case-insensitive.

Name	Key
`<CR>`	Enter, Return or keypad Enter; also `<Enter>` and `<Return>`.
`<Esc>`	Escape; also `<Escape>`.
`<Tab>`	Tab.
`<BS>`	Backspace; also `<Backspace>`.
`<Del>`	Delete; also `<Delete>`.
`<Ins>`	Insert; also `<Insert>`.
`<Space>`	Space.
`<Up>`, `<Down>`, `<Left>`, `<Right>`	Arrow keys.
`<PgUp>`	Page Up; also `<PageUp>`.
`<PgDn>`	Page Down; also `<PageDown>`.
`<Home>`	Home.
`<End>`	End.
`<F1>` to `<F24>`	Function keys.
`<k0>` to `<k9>`	Keypad digits.
`<kPlus>`, `<kMinus>`, `<kMultiply>`, `<kDivide>`, `<kPoint>`	Keypad operators.

Modifiers

Modifiers go inside the brackets before the key name, as in <C-p>, <C-S-Tab> or <D-c>.

Prefix	Modifier
`C-`	Ctrl.
`D-`	Cmd on macOS; the Super or Windows key elsewhere.
`S-`	Shift.

Ctrl and Cmd combine with any key: letters, digits, symbols and the names above, as in <C-a>, <C-=>, <C-Space> or <D-Up>. With them, a key is named by its unshifted character and Shift is written out: <C-S-r> is Ctrl+Shift+r, <C-S-1> is Ctrl+Shift+1, and <C-R> is Ctrl+r. Write > as <gt> after a modifier, as in <C-gt>. Without Ctrl or Cmd, Shift applies to named keys, as in <S-Tab> or <S-F5>, and <S-j> means J; for other printable keys, write the shifted character. Alt is not a modifier: a key pressed with Alt runs no binding.

Modifiers may be written in any order, so <C-S-Tab>, <s-c-tab> and <S-C-TAB> are the same key. Bindings are stored and shown in the first form.

Mouse events

Event	Fires on
`left_down`, `left_up`	Pressing or releasing the left button.
`middle_down`, `middle_up`	The middle button.
`right_down`, `right_up`	The right button.
`x1_down`, `x1_up`, `x2_down`, `x2_up`	The side buttons, usually back and forward.
`wheel_up`, `wheel_down`	Each step of the vertical wheel.
`wheel_left`, `wheel_right`	Each step of the horizontal wheel or a sideways tilt.
`<C-wheel_up>`, `<C-wheel_down>`	The vertical wheel with Ctrl held.

Button events take no modifiers, and the horizontal wheel does nothing while Ctrl is held. Event names are case-insensitive and may be written in angle brackets like keys: <middle_down> is middle_down. - may be written for _, and ctrl_wheel_up is the same as <C-wheel_up>.

A bound button event replaces that button’s built-in behaviour, such as text selection and following links on the left button. Wheel directions scroll smoothly only while they are bound to their default scroll actions.

Bindable actions

Every action is available as gopdf.<action>, can be passed to gopdf.bind, and can be called from a runtime Lua callback.

Action	Default keys	Countable
`next_page`	`J`, `<PgDn>`	true
`prev_page`	`K`, `<PgUp>`	true
`scroll_down`	`j`, `<Down>`	true
`scroll_up`	`k`, `<Up>`	true
`scroll_left`	`h`, `<Left>`	true
`scroll_right`	`l`, `<Right>`	true
`next_spread`		true
`prev_spread`		true
`first_page`	`gg`	false
`last_page`	`G`	false
`command_mode`	`:`	false
`search_prompt`	`/`	false
`search_prompt_backward`	`?`	false
`search_next`	`n`	true
`search_prev`	`N`	true
`toggle_dual_page`	`d`	false
`toggle_render_mode`	`m`	false
`toggle_alt_colors`	`<C-r>`	false
`toggle_first_page_offset`	`co`	false
`toggle_trim_margins`	`ct`	false
`toggle_status_bar`	`<C-n>`	false
`toggle_fullscreen`	`f`	false
`presentation`	`<F5>`	false
`follow_link`	`F`	false
`outline`	`o`	false
`overview`	`O`	false
`confirm`	`<CR>`	false
`zoom_in`	`+`, `=`	true
`zoom_out`	`-`	true
`reset_zoom`	`0`	false
`fit_width`	`a`	false
`fit_page`	`s`	false
`fit_height`	`S`	false
`reload_config`	`<C-S-r>`	false
`rotate_cw`	`r`	false
`rotate_ccw`	`R`	false
`goto_page_prompt`	`<C-g>`	false
`clear_search`		false
`highlight_selection`	`H`	false
`undo`	`u`	false
`redo`	`U`	false
`delete_annotation`	`x`	false
`search_matches`	`gm`	false
`show_completion`	`<Tab>`	false
`next_completion`		false
`prev_completion`	`<S-Tab>`	false
`copy`	`<C-c>`	false
`cut`	`<C-x>`	false
`paste`	`<C-v>`	false
`close`	`<Esc>`	false
`jump_forward`	`<C-i>`	false
`jump_backward`	`<C-o>`	false
`open_file_picker`	`<C-S-o>`	false
`show_recent_files`	`gr`	false
`help`	`<F1>`, `g?`	false
`keybinds`		false
`pan`	`<Space>`	false
`autoscroll`		false
`quit`	`q`	false

Lua tables

gopdf.document: path, name, extension, exists, size_bytes, and page_count.
gopdf.options (alias gopdf.o): all entries from the configuration-options table.
gopdf.cache, gopdf.ui, and gopdf.plugin: functions are listed above.

Status bar

Show or hide the status bar with gopdf.options.status_bar_visible. Configure horizontal spacing with gopdf.options.status_bar_padding and text size with gopdf.options.ui_font_size. The status_bar_left and status_bar_right options are templates with these substitutions:

Placeholder	Value
`{message}`	Status message or active input prompt.
`{page}`	Current physical page, or the page range for a dual-page spread.
`{label}`	PDF page label, or the label range for a dual-page spread.
`{total}`	Total physical page count.
`{mode}` / `{fit}`	Current render mode and fit mode.
`{rot}` / `{zoom}`	Clockwise rotation in degrees and zoom as a percentage.
`{dual}` / `{cover}`	`dual` or `single`, and `cover` or `flat`.
`{search}`	Current match counter, such as `[2/5]`, or empty when there is no current match.
`{document}`	Document filename.
`{modified}`	`[+]` while the document has unsaved edits, else empty.
`{input}` / `{prompt}`	Active input text and search prompt (`/` or `?`).
`$$`	A literal dollar sign.