Module SILE

The core SILE library

Fields

version Machine friendly short-form version.
features Status information about what options SILE was compiled with.
lua_version ABI version of Lua VM.
lua_isjit Whether or not Lua VM is a JIT compiler.
full_version User friendly long-form version string.

Modules

utilities Utilities module, typically accessed via SU alias.

Data tables

Commands Stash of all Lua functions used to power typesetter commands.
Help Short usage messages corresponding to typesetter commands.
debugFlags List of currently enabled debug flags.
scratch The wild-west of stash stuff.
documentState Data storage for typesetter, frame, and class information.
rawHandlers Callback functions for handling types of raw content.

User input

input All user-provided input collected before beginning document processing.

Core functions

init() Initialize a SILE instance.
use(module[, options[, reload=false]]) Multi-purpose loader to load and initialize modules.
process(ast) Process content.
processString(doc[, format[, filename[, options]]]) Process an input string.
processFile(filename[, format[, options]]) Process an input file Opens a file, converts the contents to an AST, then runs process on it.
resolveFile(filename[, pathprefix]) Resolve relative file paths to identify absolute resources locations.
call(command[, options={}[, content]]) Execute a registered SILE command.
registerCommand(name, func[, help[, pack]]) (Deprecated) Register a function as a SILE command.
setCommandDefaults(command, options) Wrap an existing command with new default options.
finish() Finalize document processing Signals that all the SILE.process() calls have been made and SILE should move on to finish up the output

1.



Fields

version
Machine friendly short-form version. Semver, prefixed with "v", possible postfixed with ".r" followed by VCS version information.
features
Status information about what options SILE was compiled with.

Fields:

  • appkit boolean
  • font_variations boolean
  • fontconfig boolean
  • harfbuzz boolean
  • icu boolean
lua_version
ABI version of Lua VM. For example may be "5.1" or "5.4" or others. Note that the ABI version for most LuaJIT implementations is 5.1.
lua_isjit
Whether or not Lua VM is a JIT compiler.
full_version
User friendly long-form version string. For example may be "SILE v0.14.17 (Lua 5.4)".

Modules

utilities
Utilities module, typically accessed via SU alias.

See also:

Data tables

Commands
Stash of all Lua functions used to power typesetter commands.
Help
Short usage messages corresponding to typesetter commands.
debugFlags
List of currently enabled debug flags. E.g. { typesetter = true, frames, true }.
scratch
The wild-west of stash stuff. No rules, just right (or usually wrong). Everything in here should be somewhere else, but lots of early SILE code relied on this as a global key/value store for various class, document, and package values. Since v0.14.0 with many core SILE components being instances of classes –and especially with each package having it's own variable namespace– there are almost always better places for things. This scratch space will eventually be completely deprecated, so don't put anything new in here and only use things in it if there are no other current alternatives.
documentState
Data storage for typesetter, frame, and class information. Current document class instances, node queues, and other "hot" data can be found here. As with SILE.scratch everything in here probably belongs elsewhere, but for now it is what it is.

Fields:

  • documentClass table The instantiated document processing class.
  • thisPageTemplate table The frameset used for the current page.
  • paperSize table The current paper size.
  • orgPaperSize table The original paper size if the current one is modified via packages.
rawHandlers
Callback functions for handling types of raw content. All registered handlers for raw content blocks have an entry in this table with the type as the key and the processing function as the value. @ table rawHandlers

User input

input
All user-provided input collected before beginning document processing. User input values, currently from CLI options, potentially all the inuts needed for a user to use a SILE-as-a-library version to produce documents programmatically.

Fields:

  • filenames table Path names of file(s) intended for processing. Files are processed in the order provided. File types may be mixed of any formaat for which SILE has an inputter module.
  • evaluates table List of strings to be evaluated as Lua code snippets before processing inputs.
  • evaluteAfters table List of strings to be evaluated as Lua code snippets after processing inputs.
  • uses table List of strings specifying module names (and optionally optionns) for modules to load before processing inputs. For example this accomodates loading inputter modules before any input of that type is encountered. Additionally it can be used to process a document using a document class other than the one specified in the document itself. Document class modules loaded here are instantiated after load, meaning the document will not be queried for a class at all.
  • options table Extra document class options to set or override in addition to ones found in the first input document.

Core functions

init()
Initialize a SILE instance. Presumes CLI args have already been processed and/or library inputs are set.

  1. If no backend has been loaded already (e.g. via --use) then assumes libtexpdf.
  2. Loads and instantiates a shaper and outputter module appropriate for the chosen backend.
  3. Instantiates a pagebuilder.
  4. Starts a Lua profiler if the profile debug flag is set.
  5. Instantiates a dependency tracker if we've been asked to write make dependencies.
  6. Runs any code snippents passed with --eval.

Does not move on to processing input document(s).

use(module[, options[, reload=false]])
Multi-purpose loader to load and initialize modules. This is used to load and intitialize core parts of SILE and also 3rd party modules. Module types supported bay be an inputter, outputer, shaper, typesetter, pagebuilder, or package.

Parameters:

  • module string or table The module spec name to load (dot-separated, e.g. "packages.lorem") or a table with a module that has already been loaded.
  • options table Startup options as key/value pairs passed to the module when initialized. (optional)
  • reload boolean whether or not to reload a module that has been loaded and initialized before. (default false)
process(ast)
Process content. This is the main 'action' SILE does. Once input files are parsed into an abstract syntax tree, then we recursively iterate through the tree handling each item in the order encountered.

Parameters:

  • ast table SILE content in abstract syntax tree format (a table of strings, functions, or more AST trees).
processString(doc[, format[, filename[, options]]])
Process an input string. First converts the string to an AST, then runs process on it.

Parameters:

  • doc string Input string to be coverted to SILE content.
  • format nil or string The name of the formatter. If nil, defaults to using each intputter's auto detection. (optional)
  • filename nil or string Pseudo filename to identify the content with, useful for error messages stack traces. (optional)
  • options nil or table Options to pass to the inputter instance when instantiated. (optional)
processFile(filename[, format[, options]])
Process an input file Opens a file, converts the contents to an AST, then runs process on it. Roughly equivalent to listing the file as an input, but easier to embed in code.

Parameters:

  • filename string Path of file to open string to be coverted to SILE content.
  • format nil or string The name of the formatter. If nil, defaults to using each intputter's auto detection. (optional)
  • options nil or table Options to pass to the inputter instance when instantiated. (optional)
resolveFile(filename[, pathprefix])
Resolve relative file paths to identify absolute resources locations. Makes it possible to load resources from relative paths, relative to a document or project or SILE itself.

Parameters:

  • filename string Name of file to find using the same order of precidence logic in require().
  • pathprefix nil or string Optional prefix in which to look for if the file isn't found otherwise. (optional)
call(command[, options={}[, content]])
Execute a registered SILE command. Uses a function previously registered by any modules explicitly loaded by the user at runtime via --use, the SILE core, the document class, or any loaded package.

Parameters:

  • command string Command name.
  • options nil or table Options to pass to the command. (default {})
  • content nil or table Any valid AST node to be processed by the command. (optional)
registerCommand(name, func[, help[, pack]])
(Deprecated) Register a function as a SILE command. Takes any Lua function and registers it for use as a SILE command (which will in turn be used to process any content nodes identified with the command name.

Note that alternative versions of this action are available as methods on document classes and packages. Those interfaces should be prefered to this global one.

Parameters:

  • name string Name of cammand to register.
  • func function Callback function to use as command handler.
  • help nil or string User friendly short usage string for use in error messages, documentation, etc. (optional)
  • pack nil or string Information identifying the module registering the command for use in error and usage messages. Usually auto-detected. (optional)

See also:

setCommandDefaults(command, options)
Wrap an existing command with new default options. Modifies an already registered SILE command with a new table of options to be used as default values any time it is called. Calling options still take precidence.

Parameters:

  • command string Name of command to overwride.
  • options table Options to set as updated defaults.
finish()

Finalize document processing Signals that all the SILE.process() calls have been made and SILE should move on to finish up the output

  1. Tells the document class to run its :finish() method. This method is typically responsible for calling the :finish() method of the outputter module in the appropriate sequence.
  2. Closes out anything in active memory we don't need like font instances.
  3. Evaluate any snippets in SILE.input.evalAfter table.
  4. Stops logging dependecies and writes them to a makedepends file if requested.
  5. Close out the Lua profiler if it was running.
  6. Output version information if versions debug flag is set.
generated by LDoc 1.5.0 Last updated 1980-01-01 00:00:00