diff --git a/src/resources/lua-types/quarto/doc.lua b/src/resources/lua-types/quarto/doc.lua index 3da0e8e5eae..2642f9617dd 100644 --- a/src/resources/lua-types/quarto/doc.lua +++ b/src/resources/lua-types/quarto/doc.lua @@ -48,7 +48,25 @@ which must be copied into the LaTeX output directory. function quarto.doc.add_format_resource(file) end --[[ -Include text at the specified location (`in-header`, `before-body`, or `after-body`). +Add a resource file to the document. The file will be copied to the same +relative location in the output directory. + +The path should be relative to the Lua script calling this function. +]] +---@param path string Resource file path (relative to Lua script) +function quarto.doc.add_resource(path) end + +--[[ +Add a supporting file to the document. Supporting files are moved to the +output directory and may be cleaned up after rendering. + +The path should be relative to the Lua script calling this function. +]] +---@param path string Supporting file path (relative to Lua script) +function quarto.doc.add_supporting(path) end + +--[[ +Include text at the specified location (`in-header`, `before-body`, or `after-body`). ]] ---@param location 'in-header'|'before-body'|'after-body' Location for include ---@param text string Text to include @@ -101,6 +119,13 @@ Does the current output format include Bootstrap themed HTML ---@return boolean function quarto.doc.has_bootstrap() end +--[[ +Check whether a specific internal Quarto filter is currently active. +]] +---@param filter string Filter name to check +---@return boolean +function quarto.doc.is_filter_active(filter) end + --[[ Provides the project relative path to the current input if this render is in the context of a project (otherwise `nil`) diff --git a/src/resources/lua-types/quarto/utils.lua b/src/resources/lua-types/quarto/utils.lua index cd92c02fbf7..f1ebd4600f5 100644 --- a/src/resources/lua-types/quarto/utils.lua +++ b/src/resources/lua-types/quarto/utils.lua @@ -12,15 +12,60 @@ Note that you should use `quarto.log.output()` instead of this function. function quarto.utils.dump(value) end --[[ -Compute the absolute path to a file that is installed alongside the Lua script. +Extended type function that returns Pandoc types with Quarto custom node awareness. -This is useful for internal resources that your filter needs but should +Returns `"CustomBlock"` for Quarto custom block nodes and `"CustomInline"` for +custom inline nodes, otherwise delegates to `pandoc.utils.type()`. +]] +---@param value any Value to check +---@return string +function quarto.utils.type(value) end + +quarto.utils.table = {} + +--[[ +Return `true` if the table is a plain integer-indexed array. +]] +---@param t table Table to check +---@return boolean +function quarto.utils.table.isarray(t) end + +--[[ +Return `true` if the array-like table contains the given value. +]] +---@param t table Array-like table to search +---@param value any Value to find +---@return boolean +function quarto.utils.table.contains(t, value) end + +--[[ +Iterator that traverses table keys in sorted order. +]] +---@param t table Table to iterate +---@param f? function Optional comparison function for sorting +---@return function Iterator function +function quarto.utils.table.sortedPairs(t, f) end + +--[[ +Compute the absolute path to a file that is installed alongside the Lua script. + +This is useful for internal resources that your filter needs but should not be visible to the user. ]] ---@param path string Path of file relative to the Lua script ---@return string function quarto.utils.resolve_path(path) end +--[[ +Resolve a file path relative to the document's working directory. + +Unlike `resolve_path()` which resolves relative to the Lua script, +this resolves relative to the document being rendered. +]] +---@param path string File path to resolve +---@return string +function quarto.utils.resolve_path_relative_to_document(path) end + --[[ Converts a string to a list of Pandoc Inlines, processing any Quarto custom syntax in the string. @@ -38,6 +83,78 @@ syntax in the string. ---@return pandoc.Blocks function quarto.utils.string_to_blocks(path) end +--[[ +Coerce the given object into a `pandoc.Inlines` list. + +Handles Inline, Inlines, Block, Blocks, List, and table inputs. +More performant than `pandoc.Inlines()` as it avoids full marshal roundtrips. + +Note: The input object may be modified destructively. +]] +---@param obj any Object to coerce +---@return pandoc.Inlines +function quarto.utils.as_inlines(obj) end + +--[[ +Coerce the given object into a `pandoc.Blocks` list. + +Handles Block, Blocks, Inline, Inlines, List, Caption, and table inputs. +More performant than `pandoc.Blocks()` as it avoids full marshal roundtrips. + +Note: The input object may be modified destructively. +]] +---@param obj any Object to coerce +---@return pandoc.Blocks +function quarto.utils.as_blocks(obj) end + +--[[ +Return `true` if the given AST node is empty. + +A node is considered empty if it's an empty list/table, has empty `content`, +has empty `caption`, or has an empty `text` field. +]] +---@param node any AST node to check +---@return boolean +function quarto.utils.is_empty_node(node) end + +--[[ +Walk and render extended/custom AST nodes. + +Processes Quarto custom AST nodes (like Callout, Tabset, etc.) into their +final Pandoc representation. +]] +---@param node pandoc.Node AST node to render +---@return pandoc.Node +function quarto.utils.render(node) end + +--[[ +CSS-selector-like AST matcher for Pandoc nodes. + +Accepts string path selectors separated by `/` with support for: +- Element type selectors (e.g. `"Header"`, `"Para"`, `"Div"`) +- Child traversal via `/` separator +- `*` wildcard to match any child +- `{Type}` capture syntax to return matched nodes +- `:child` to search direct children +- `:descendant` to search all descendants +- `:nth-child(n)` to match a specific child index + +Returns a function that, when called with an AST node, returns the matched +node(s) or `false`/`nil` if no match. +]] +---@param ... string|function Selector path components +---@return function Matcher function +function quarto.utils.match(...) end + +--[[ +Append a Block, Blocks, or Inlines value to an existing Blocks list. + +Inlines are wrapped in a Plain block before appending. +]] +---@param blocks pandoc.Blocks Target Blocks list +---@param block pandoc.Block|pandoc.Blocks|pandoc.Inlines Value to append +function quarto.utils.add_to_blocks(blocks, block) end + --[[ Returns a filter that parses book metadata markers during document traversal.