sile-typesetter / sile / 10616097075

--- The core SILE library.

-- Depending on how SILE was loaded, everything in here will probably be available under a top level `SILE` global. Note

-- that an additional global `SU` is typically available as an alias to `SILE.utilities`. Also some 3rd party Lua

-- libraries are always made available in the global scope, see `globals`.

-- @module SILE

-- Placeholder for 3rd party Lua libraries SILE always provides as globals

-- Reserve scope placeholder for profiler (developer tooling)

local ProFi

-- Placeholder for SILE internals table

--- Fields

-- @section fields

--- Machine friendly short-form version.

-- Semver, prefixed with "v", possible postfixed with ".r" followed by VCS version information.

-- @string version

--- Status information about what options SILE was compiled with.

-- @table SILE.features

-- @tfield boolean appkit

-- @tfield boolean font_variations

-- @tfield boolean fontconfig

-- @tfield boolean harfbuzz

-- @tfield boolean icu

-- Initialize Lua environment and global utilities

--- 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.

-- @string lua_version

--- Whether or not Lua VM is a JIT compiler.

-- @boolean lua_isjit

-- luacheck: ignore jit

--- User friendly long-form version string.

-- For example may be "SILE v0.14.17 (Lua 5.4)".

-- @string full_version

--- Default to verbose mode, can be changed from the CLI or by libraries

--- @boolean quiet

-- Backport of lots of Lua 5.3 features to Lua 5.[12]

end

--- Modules

-- @section modules

--- Utilities module, typically accessed via `SU` alias.

-- @see SU

-- For warnings and shims scheduled for removal that are easier to keep track

-- of when they are not spread across so many locations...

-- Loaded early to make it easier to manage migrations in core code.

-- On demand loader, allows modules to be loaded into a specific scope but

-- only when/if accessed.

local function core_loader (scope)

      __index = function (self, key)

         -- local var = rawget(self, key)

      end,

end

--- Data tables

--- @section data

--- Stash of all Lua functions used to power typesetter commands.

-- @table Commands

--- Short usage messages corresponding to typesetter commands.

-- @table Help

--- List of currently enabled debug flags.

-- E.g. `{ typesetter = true, frames, true }`.

-- @table debugFlags

--- 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.

-- @table scratch

--- 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.

-- @table documentState

-- @tfield table documentClass The instantiated document processing class.

-- @tfield table thisPageTemplate The frameset used for the current page.

-- @tfield table paperSize The current paper size.

-- @tfield table orgPaperSize The original paper size if the current one is modified via packages.

--- 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

-- @section 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.

-- @table input

-- @tfield table filenames 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.

-- @tfield table evaluates List of strings to be evaluated as Lua code snippets *before* processing inputs.

-- @tfield table evaluteAfters List of strings to be evaluated as Lua code snippets *after* processing inputs.

-- @tfield table uses 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.

-- @tfield table options Extra document class options to set or override in addition to ones found in the first input

-- document.

-- Internal libraries that are idempotent and return classes that need instantiation

-- Internal libraries that don't try to use anything on load, only provide something

-- NOTE:

-- See remainaing internal libraries loaded at the end of this file because

-- they run core SILE functions on load instead of waiting to be called (or

-- depend on others that do).

local function runEvals (evals, arg)

      else

      end

   end

end

--- Core functions

-- @section functions

--- 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).

   end

   end

   end

   end

end

local function suggest_luarocks (module)

    If the expected module is a 3rd party extension you may need to install it

    using LuaRocks. The details of how to do this are highly dependent on

    your system and preferred installation method, but as an example installing

    a 3rd party SILE module to a project-local tree where might look like this:

        luarocks --lua-version %s --tree lua_modules install %s

    This will install the LuaRocks to your project, then you need to tell your

    shell to pass along that info about available LuaRocks paths to SILE. This

    only needs to be done once in each shell.

        eval $(luarocks --lua-version %s --tree lua_modules path)

    Thereafter running SILE again should work as expected:

       sile %s

end

--- 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*.

-- @tparam string|table module The module spec name to load (dot-separated, e.g. `"packages.lorem"`) or a table with

--   a module that has already been loaded.

-- @tparam[opt] table options Startup options as key/value pairs passed to the module when initialized.

-- @tparam[opt=false] boolean reload whether or not to reload a module that has been loaded and initialized before.

   local status, pack

               module,

            )

         )

      end

   end

      end

      else

      end

   end

end

-- --- Content loader like Lua's `require()` but whith special path handling for loading SILE resource files.

-- -- Used for example by commands that load data via a `src=file.name` option.

-- -- @tparam string dependency Lua spec

  Please don't use the path prefix mechanism; it was intended to provide

  alternate paths to override core components but never worked well and is

  causing portability problems. Just use Lua idiomatic module loading:

      SILE.require("%s", "%s") → SILE.require("%s.%s")]],

         dependency,

         pathprefix,

         pathprefix,

         dependency

      )

   end

   local status, lib

      -- Note this is not a *path*, it is a module identifier:

      -- https://github.com/sile-typesetter/sile/issues/1861

   end

               dependency,

            )

         )

      end

   end

  Use of SILE.require() is only supported in documents, packages, or class

  init functions. It will not function fully before the class is instantiated.

  Please just use the Lua require() function directly:

      SILE.require("%s") → require("%s")]],

         dependency,

         dependency

      ))

   end

      else

      end

   end

end

--- 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.

-- @tparam table ast SILE content in abstract syntax tree format (a table of strings, functions, or more AST trees).

   end

   end

   end

      end

   end

end

local function detectFormat (doc, filename)

   -- Preload default reader types so content detection has something to work with

      end

   end

      end

   end

   end)

         end

      end

   end

end

--- Process an input string.

-- First converts the string to an AST, then runs `process` on it.

-- @tparam string doc Input string to be coverted to SILE content.

-- @tparam[opt] nil|string format The name of the formatter. If nil, defaults to using each intputter's auto detection.

-- @tparam[opt] nil|string filename Pseudo filename to identify the content with, useful for error messages stack traces.

-- @tparam[opt] nil|table options Options to pass to the inputter instance when instantiated.

   local cpf

   end

   -- In the event we're processing the master file *and* the user gave us

   -- a specific inputter to use, use it at the exclusion of all content type

   -- detection

   local inputter

   if

      filename

   then

   else

      end

      -- If we did content detection *and* this is the master file, save the

      -- inputter for posterity and postambles

      end

   end

   end

end

--- 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.

-- @tparam string filename Path of file to open string to be coverted to SILE content.

-- @tparam[opt] nil|string format The name of the formatter. If nil, defaults to using each intputter's auto detection.

-- @tparam[opt] nil|table options Options to pass to the inputter instance when instantiated.

   local doc

   else

      -- Turn slashes around in the event we get passed a path from a Windows shell

      end

      end

      end

      end

      end

      end

   end

end

-- TODO: this probably needs deprecating, moved here just to get out of the way so

-- typesetters classing works as expected

   end

   end

end

--- 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.

-- @tparam string filename Name of file to find using the same order of precidence logic in `require()`.

-- @tparam[opt] nil|string pathprefix Optional prefix in which to look for if the file isn't found otherwise.

   -- Start with the raw file name as given prefixed with a path if requested

   end

   -- Also check the raw file name without a path

   -- Iterate through the directory of the master file, the SILE_PATH variable, and the current directory

   -- Check for prefixed paths first, then the plain path in that fails

            end

         end

      end

   end

   -- Return the first candidate that exists, also checking the .sil suffix

      end

   end

end

--- 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.

-- @tparam string command Command name.

-- @tparam[opt={}] nil|table options Options to pass to the command.

-- @tparam[opt] nil|table content Any valid AST node to be processed by the command.

      -- This call is from code (no content.lno) and we want to spend the time

      -- to determine everything we need about the caller

   end

   end

end

--- (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.

-- @tparam string name Name of cammand to register.

-- @tparam function func Callback function to use as command handler.

-- @tparam[opt] nil|string help User friendly short usage string for use in error messages, documentation, etc.

-- @tparam[opt] nil|string pack Information identifying the module registering the command for use in error and usage

-- messages. Usually auto-detected.

-- @see SILE.classes:registerCommand

-- @see SILE.packages:registerCommand

         [[Commands are being scoped to the document classes they are loaded into rather than being globals.]]

   end

   -- Shimming until we have all scope cheating removed from core

   end

end

--- 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.

-- @tparam string command Name of command to overwride.

-- @tparam table options Options to set as updated defaults.

      end

   end

end

-- TODO: Move to new table entry handler in types.unit

   -- If a unit exists already, clear it first so we get fresh meta table entries, see #1607

   end

end

end

--- 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.

   end

   end

   end

   end

end

-- Internal libraries that return classes, but we only ever use one instantiation

-- Internal libraries that run core SILE functions on load