Access document file path within Lua filter

[andrewpbray]

Description

I have a document, example.qmd inside a Quarto project that is running a lua filter called my_fil.lua. Within the filter, is there any way to access the path to that file relative to the project file?

In the following example, I'd like to have access to notes/example.qmd.

- _extensions
  - my-fil
    - _extension.yml
    - my-fil.lua
- _quarto.yml
- notes
  - example.qmd

[jimjam-slam]

@andrewpbray For pre- and post-render scripts Quarto makes ceertain environment variables available, but for a filter, maybe PANDOC_STATE.input_files will do the trick?

[mcanouil]

Indeed, there are a bunch of environment variables you can have access to (see https://github.com/mcanouil/quarto-lua-env).
Note that the environment variable mentioned is not Quarto input, but Pandoc input, you might prefer quarto.doc.input_file.

[cderv]

A few items for this purpose have been added in Quarto Lua api in version 1.2

quarto-cli/news/changelog-1.2.md

Lines 33 to 38 in b60509d

	- New `quarto.project.profile` which provides the list of currently active profiles (or an empty table if none are active)
	- New `quarto.project.directory` which provides the current project directory (if a project is active)
	- New `quarto.project.output_directory` which provides the current project output directory (if a project is active)
	- New `quarto.project.offset` which provides an offset from the current input document to the project directory.
	- New `quarto.doc.input_file` which provides the path to the input document
	- New `quarto.doc.output_file` which provides the path to the output file

quarto.doc.input_file mentioned above ( #6916 (reply in thread)) is one of them

We still need to document all of them - so sorry to make it hard to find

• Document all public functions from quarto Lua API #4499

For now, reading the source is the best doc

quarto-cli/src/resources/pandoc/datadir/init.lua

Lines 1916 to 2084 in b60509d

	-- The main exports of the quarto module
	quarto = {
	doc = {
	add_html_dependency = function(htmlDependency)
	-- validate the dependency
	if htmlDependency.name == nil then
	error("HTML dependencies must include a name")
	end
	if htmlDependency.meta == nil and
	htmlDependency.links == nil and
	htmlDependency.scripts == nil and
	htmlDependency.stylesheets == nil and
	htmlDependency.resources == nil and
	htmlDependency.serviceworkers == nil and
	htmlDependency.head == nil then
	error("HTML dependencies must include at least one of meta, links, scripts, stylesheets, serviceworkers, or resources. All appear empty.")
	end
	-- validate that the meta is as expected
	if htmlDependency.meta ~= nil then
	if type(htmlDependency.meta) ~= 'table' then
	error("Invalid HTML Dependency: meta value must be a table")
	elseif utils.table.isarray(htmlDependency.meta) then
	error("Invalid HTML Dependency: meta value must must not be an array")
	end
	end
	-- validate link tags
	if htmlDependency.links ~= nil then
	if type(htmlDependency.links) ~= 'table' or not utils.table.isarray(htmlDependency.links) then
	error("Invalid HTML Dependency: links must be an array")
	else
	for i, v in ipairs(htmlDependency.links) do
	if type(v) ~= "table" or (v.href == nil or v.rel == nil) then
	error("Invalid HTML Dependency: each link must be a table containing both rel and href properties.")
	end
	end
	end
	end
	-- resolve names so they aren't required
	htmlDependency.scripts = resolveFileDependencies("scripts", htmlDependency.scripts)
	htmlDependency.stylesheets = resolveFileDependencies("stylesheets", htmlDependency.stylesheets)
	htmlDependency.resources = resolveFileDependencies("resources", htmlDependency.resources)
	-- pass the dependency through to the file
	writeToDependencyFile(dependency("html", {
	name = htmlDependency.name,
	version = htmlDependency.version,
	external = true,
	meta = htmlDependency.meta,
	links = resolveDependencyLinkTags(htmlDependency.links),
	scripts = resolveDependencyFilePaths(htmlDependency.scripts),
	stylesheets = resolveDependencyFilePaths(htmlDependency.stylesheets),
	resources = resolveDependencyFilePaths(htmlDependency.resources),
	serviceworkers = resolveServiceWorkers(htmlDependency.serviceworkers),
	head = htmlDependency.head,
	}))
	end,
	attach_to_dependency = function(name, pathOrFileObj)
	if name == nil then
	fail("The target dependency name for an attachment cannot be nil. Please provide a valid dependency name.")
	end
	-- path can be a string or an obj { name, path }
	local resolvedFile = {}
	if type(pathOrFileObj) == "table" then
	-- validate that there is at least a path
	if pathOrFileObj.path == nil then
	fail("Error attaching to dependency '" .. name .. "'.\nYou must provide a 'path' when adding an attachment to a dependency.")
	end
	-- resolve a name, if one isn't provided
	local name = pathOrFileObj.name
	if name == nil then
	name = pandoc.path.filename(pathOrFileObj.path)
	end
	-- the full resolved file
	resolvedFile = {
	name = name,
	path = resolvePathExt(pathOrFileObj.path)
	}
	else
	resolvedFile = {
	name = pandoc.path.filename(pathOrFileObj),
	path = resolvePathExt(pathOrFileObj)
	}
	end
	writeToDependencyFile(dependency("html-attachment", {
	name = name,
	file = resolvedFile
	}))
	end,
	use_latex_package = function(package, options)
	writeToDependencyFile(dependency("usepackage", {package = package, options = options }))
	end,
	add_format_resource = function(path)
	writeToDependencyFile(dependency("format-resources", { file = resolvePathExt(path)}))
	end,
	add_resource = function(path)
	writeToDependencyFile(dependency("resources", { file = resolvePathExt(path)}))
	end,
	add_supporting = function(path)
	writeToDependencyFile(dependency("supporting", { file = resolvePathExt(path)}))
	end,
	include_text = function(location, text)
	writeToDependencyFile(dependency("text", { text = text, location = resolveLocation(location)}))
	end,
	include_file = function(location, path)
	writeToDependencyFile(dependency("file", { path = resolvePathExt(path), location = resolveLocation(location)}))
	end,
	is_format = format.isFormat,
	cite_method = function()
	local citeMethod = param('cite-method', 'citeproc')
	return citeMethod
	end,
	pdf_engine = function()
	local engine = param('pdf-engine', 'pdflatex')
	return engine
	end,
	has_bootstrap = function()
	local hasBootstrap = param('has-bootstrap', false)
	return hasBootstrap
	end,
	is_filter_active = function(filter)
	return quarto_global_state.active_filters[filter]
	end,
	output_file = outputFile(),
	input_file = inputFile()
	},
	project = {
	directory = projectDirectory(),
	offset = projectOffset(),
	profile = pandoc.List(projectProfiles()),
	output_directory = projectOutputDirectory()
	},
	utils = {
	dump = utils.dump,
	table = utils.table,
	type = utils.type,
	resolve_path = resolvePathExt,
	resolve_path_relative_to_document = resolvePath,
	as_inlines = utils.as_inlines,
	as_blocks = utils.as_blocks,
	string_to_blocks = utils.string_to_blocks,
	string_to_inlines = utils.string_to_inlines,
	render = utils.render,
	},
	json = json,
	base64 = base64,
	log = logging,
	version = version()
	}

[andrewpbray]

Hey, terrific: quarto.doc.input_file and quarto.project.directory get me exactly what I need.

Thanks!

[andrewpbray]

While working on a related project, I bumped into an issue that brought me back to this thread (and the source that you linked).

I'm trying to rename the output file (-o) within a lua filter. Based on looking at the source, I thought I'd try this:

PANDOC_STATE['output_file'] =  "foo.json"

Alas, it didn't work.

Error running filter /Applications/quarto/share/filters/main.lua:
'output_file' is a read-only property.

It may be that this simply isn't possible in this manner. If so I can brainstorm other ways to skin this cat.

[jimjam-slam]

Post-render project script to rename the output file? 🤔

[andrewpbray]

Indeed this is wrapped in a project, so that may work.... intriguing. Might work! I'd like this renaming to be subject to document-level metadata (effectively: add-suffix: true), and it'd like it to not overwrite the output that is under the original file name. I could conceivably do:

1. in pre-render script reach through docs and look for relevant metadata.
2. if add-suffix: true rename the file.
3. do all the renders.
4. in post-render script undo steps 2 and 1.

Thanks for the suggestion!

[cderv]

It may be that this simply isn't possible in this manner. If so I can brainstorm other ways to skin this cat.

Yes I don't think Pandoc will allow that. They cleary says PANDOC_STATE is read only (https://pandoc.org/lua-filters.html#global-variables)

The state shared by all readers and writers. It is used by pandoc to collect and pass information. The value of this variable is of type CommonState and is read-only.

To be able to do that at the document level, it would need to be a Quarto feature. A feature like allowing to tweak some post process Quarto behavior from within Lua filter (like renaming a file by setting output-file YAML config).

Personally I think that all path handling like this are best done with external processing like you are thinking off.