Module nodetree

This file (nodetree.lua) is part of the LuaTeX package 'nodetree'.

nodetree uses the annotation system of the lua-language-server. Install the type definitions for LuaTeX or the Visual Studio Code Extension.

The LDoc support is deprecated.

Nodes in LuaTeX are connected. The nodetree view distinguishes between list and field connections.

  • list: Nodes that are doubly connected by next and previous fields.
  • field: Connections to nodes by other fields than next and previous fields, e.g., head, pre.

Tables

default_options The default options.
options The current options.
prev_options The previous options.
tree_state tree_state:

Fields

utf8 Lua 5.1 does not have the utf8 library (Lua 5.1 is the default version in LuajitTeX).
example_counter A counter for the compiled TeX examples.
have_output A flag to indicate that something has been emitted by nodetree.

Format functions

format.underscore (input)
format.escape (input)
format.function (input)
format.whitespace (count)
format.color_code (code)
format.color_tex (color, mode)
format.node_begin ()
format.node_end ()
format.new_line (count)
format.type_id (id)
nodetree_print (text) Print the output to stdout or write it into a file (output_file).

Template functions

template.color (color, mode, background) SGR (Select Graphic Rendition) parameters.
template.char (head) Format the char field of a node.
template.line (length)
template.branch (connection_type, connection_state, last)
template.fill (number, order, field)
template.colored_string (text, color, mode, background) Colorize a text string.
template.length (input) Format a scaled point input value into dimension string (12pt, 1cm)
get_all_table_data (data, previous_data) Get all data from a table including metatables.
template.table_inline (table) Convert a Lua table into a format string.
template.key_value (key, value, typ, color) Format a key-value pair (key: value, ).
template.type (type, id)
template.callback (callback_name, variables, where)
template.branches (level, connection_type) Format the branching tree for one output line.

Node library extensions

node_extended.node_id (n) Get the ID of a node.
get_node_subtypes () A table of all node subtype names.
node_extended.subtype (n)

Node tree building functions

tree.format_field (head, field)
tree.format_attributes (head) Attributes are key-value number pairs.
tree.set_state (level, connection_type, connection_state)
tree.analyze_fields (fields, level)
tree.analyze_node (head, level)
tree.analyze_list (head, level) Recurse over the current node list.
tree.analyze_callback (head) The top-level internal entry point.

Callback wrappers

callbacks.contribute_filter (extrainfo, where)
callbacks.buildpage_filter (extrainfo, where)
callbacks.build_page_insert (n, i)
callbacks.pre_linebreak_filter (head, groupcode, where)
callbacks.linebreak_filter (head, is_display)
callbacks.append_to_vlist_filter (box, locationcode, prevdepth, mirrored)
callbacks.post_linebreak_filter (head, groupcode, where)
callbacks.hpack_filter (head, groupcode, size, packtype, direction, attributelist, where)
callbacks.vpack_filter (head, groupcode, size, packtype, maxdepth, direction, attributelist, where)
callbacks.hpack_quality (incident, detail, head, first, last)
callbacks.vpack_quality (incident, detail, head, first, last)
callbacks.process_rule (head, width, height)
callbacks.pre_output_filter (head, groupcode, size, packtype, maxdepth, direction, where)
callbacks.hyphenate (head, tail, where)
callbacks.ligaturing (head, tail, where)
callbacks.kerning (head, tail, where)
callbacks.insert_local_par (local_par, location, where)
callbacks.mlist_to_hlist (head, display_type, need_penalties)

Messages, options

message (why, where, what, help) Emit a warning or error message.
set_option (key, value) Set a single-option key-value pair.
set_options (opts) Set multiple key-value option pairs using a table.

Callback management

template.get_print_position (what)
template.no_callback (name, internal)
check_callback_name (callback_name) Check whether the given callback name exists.
get_callback_name (alias) Get the real callback name from an alias string.
register_callback (cb) Register a callback.
unregister_callback (cb) Unregister a callback.

Exported functions

export.register_callbacks ()
export.unregister_callbacks ()
export.compile_include (tex_markup) Compile a TeX snippet.
export.check_shell_escape (what, is_command) Check for --shell-escape within a command or environment.
export.print (head, opts) Print a node tree.
export.format_dim (sp) Format a scaled point value as a formatted string.
export.get_default_option (key) Get a default option that is not changed.
export.push_options () Push current options.
export.pop_options () Pop previous options.
export.input (filename) Read a LaTeX input file and emit it immediately, obeying options firstline and lastline.
export.analyze Set to export.print.


Tables

default_options
The default options.

Fields:

  • callback
  • channel
  • color
  • decimalplaces
  • unit
  • verbosity
  • firstline
  • lastline
options
The current options.
prev_options
The previous options. We need this for functions push_options and pop_options so that the effects of the \setkeys commands in nodetree-embed.sty (which directly manipulates the options table) stay local.
tree_state
tree_state: * 1 (level): * list: continue * field: stop * 2: * list: continue * field: stop

...

Fields

utf8
Lua 5.1 does not have the utf8 library (Lua 5.1 is the default version in LuajitTeX). LuaJitTeX does include the slnunicode library.
example_counter
A counter for the compiled TeX examples. Some TeX code snippets a written into files, wrapped with some TeX boilerplate code. These written files are compiled later on.
have_output
A flag to indicate that something has been emitted by nodetree.

Format functions

Low-level template functions.
format.underscore (input)

Parameters:

  • input string

Returns:

    string
format.escape (input)

Parameters:

  • input string

Returns:

    string
format.function (input)

Parameters:

  • input number

Returns:

    number
format.whitespace (count)

Parameters:

  • count ? number # How many spaces should be output.

Returns:

    string
format.color_code (code)

Parameters:

  • code number

Returns:

    string
format.color_tex (color, mode)

Parameters:

  • color string
  • mode ? string

Returns:

    string
format.node_begin ()

Returns:

    string
format.node_end ()

Returns:

    string
format.new_line (count)

Parameters:

  • count ? number # How many new lines should be output.

Returns:

    string
format.type_id (id)

Parameters:

  • id number

Returns:

    string
nodetree_print (text)
Print the output to stdout or write it into a file (output_file). New text is appended.

Parameters:

  • text string # A text string.

Template functions

template.color (color, mode, background)
SGR (Select Graphic Rendition) parameters.

attributes

| color |code| |------------|----| | reset | 0 | | clear | 0 | | bright | 1 | | dim | 2 | | underscore | 4 | | blink | 5 | | reverse | 7 | | hidden | 8 |

foreground

| color |code| |------------|----| | black | 30 | | red | 31 | | green | 32 | | yellow | 33 | | blue | 34 | | magenta | 35 | | cyan | 36 | | white | 37 |

background

| color |code| |------------|----| | onblack | 40 | | onred | 41 | | ongreen | 42 | | onyellow | 43 | | onblue | 44 | | onmagenta | 45 | | oncyan | 46 | | onwhite | 47 |

Parameters:

  • color ColorName # A color name.
  • mode ? ColorMode
  • background ? boolean # If set, colorize the background instead of the text.

Returns:

    string
template.char (head)
Format the char field of a node. Try to find a textual representation that corresponds with the number stored in the char field.

LuaTeX’s node.char values are not really characters; they are font glyph indices which sometimes happen to match valid Unicode characters. HarfBuzz shapers differentiate between glyph IDs and characters by adding to 0x120000 to glyph IDs.

The code of this function is borrowed from the function get_glyph_info(n) of the luaotfload package. The harfbuzz mode in luaotfload uses this function to embed text in a PDF file and for messages that show textual representation of the nodes like over/underfull messages. It will not result in an error in other modes, but it might not give proper text representation, but that is a limitation of these modes.

It should be understood what the glyph nodes represent. Before processing by luaotfload they represent one-to-one mapping of the input characters. After processing, they represent font glyphs with potentially complicated relationship with input characters.

Relation between input characters and output glyphs are many-to-many. An input character may be represented by one or more glyphs, and output glyph might represent one or more input characters, and in some cases (e.g. when there is reordering) a group of input characters are represented by a group of output glyphs. In the 2nd and 3rd cases, the first glyph node will have a glyph_info property with all the characters of the group, and subsequent glyph nodes in the group will have empty glyph_info properties.

It should also noted that this mapping is not unique, the same glyph can represent different characters in different context.

Parameters:

  • head Node # The head node of a node list.

Returns:

    string # A textual representation of the char number.
template.line (length)

Parameters:

  • length string # If long, emit a longer line.

Returns:

    string
template.branch (connection_type, connection_state, last)

Parameters:

  • connection_type ConnectionType
  • connection_state ConnectionState
  • last boolean

Returns:

    string
template.fill (number, order, field)

Parameters:

  • number number
  • order number
  • field string

Returns:

    string
template.colored_string (text, color, mode, background)
Colorize a text string.

Parameters:

  • text string # A text string.
  • color ColorName # A color name.
  • mode ? ColorMode
  • background ? boolean # If set, colorize the background instead of the text.

Returns:

    string
template.length (input)
Format a scaled point input value into dimension string (12pt, 1cm)

Parameters:

  • input number

Returns:

    string
get_all_table_data (data, previous_data)
Get all data from a table including metatables.

Properties will reside in a metatable if nodes were copied using an operation like box copy: (\copy). The LuaTeX manual states this: “If the second argument of set_properties_mode is true, then a metatable approach is chosen: the copy gets its own table with the original table as metatable.”

Source: StackOverflow – this works if __index returns a table, which it should as per LuaTeX manual.

Parameters:

  • data table # A Lua table.
  • previous_data ? table # The data of a Lua table of a previous recursive call.

Returns:

    table # A merged table.
template.table_inline (table)
Convert a Lua table into a format string.

Parameters:

  • table table # A table to generate an inline view of.

Returns:

    string
template.key_value (key, value, typ, color)
Format a key-value pair (key: value, ).

Parameters:

  • key string # A key.
  • value string|number # A value.
  • typ ? string # A node type. Had to be named typ to avoid conflict with the type() function.
  • color ? ColorName # A color name.

Returns:

    string
template.type (type, id)

Parameters:

  • type string
  • id number

Returns:

    string
template.callback (callback_name, variables, where)

Parameters:

  • callback_name string
  • variables table|nil
  • where 'before'|'after' # 'before' or 'after'
template.branches (level, connection_type)
Format the branching tree for one output line.

Parameters:

  • level number
  • connection_type ConnectionType

Returns:

    string

Node library extensions

node_extended.node_id (n)
Get the ID of a node.

We have to convert the node into a string and then to extract the ID from this string using a regular expression. If you convert a node into a string it looks like: <node nil < 172 > nil : hlist 2>.

Parameters:

  • n Node # A node.

Returns:

    string
get_node_subtypes ()

A table of all node subtype names.

Nodes without subtypes:

  • ins (3)
  • local_par (9)
  • penalty (14)
  • unset (15)
  • style (16)
  • choice (17)
  • fraction (20)
  • math_char (23)
  • sub_box (24)
  • sub_mlist (25)
  • math_text_char (26)
  • delim (27)
  • margin_kern (28)
  • align_record (30)
  • pseudo_file (31)
  • pseudo_line (32)
  • page_insert (33)
  • split_insert (34)
  • expr_stack (35)
  • nested_list (36)
  • span (37)
  • attribute (38)
  • glue_spec (39)
  • attribute_list (40)
  • temp (41)
  • align_stack (42)
  • movement_stack (43)
  • if_stack (44)
  • unhyphenated (45)
  • hyphenated (46)
  • delta (47)
  • passive (48)
  • shape (49)

Returns:

    table
node_extended.subtype (n)

Parameters:

  • n Node

Returns:

    string

Node tree building functions

tree.format_field (head, field)

Parameters:

  • head Node # The head node of a node list.
  • field string

Returns:

    string
tree.format_attributes (head)
Attributes are key-value number pairs. They are printed as an inline list. The attribute 0 with the value 0 is skipped because this attribute is in every node by default.

Parameters:

  • head Node # The head node of a node list.

Returns:

    string
tree.set_state (level, connection_type, connection_state)

Parameters:

  • level number # level is an integer beginning with 1.
  • connection_type ConnectionType
  • connection_state ConnectionState
tree.analyze_fields (fields, level)

Parameters:

  • fields table
  • level number # The current recursion level.
tree.analyze_node (head, level)

Parameters:

  • head Node # The head node of a node list.
  • level number # The current recursion level.
tree.analyze_list (head, level)
Recurse over the current node list.

Parameters:

  • head Node # The head node of a node list.
  • level number # The current recursion level.
tree.analyze_callback (head)
The top-level internal entry point.

Parameters:

  • head Node # The head node of a node list.

Callback wrappers

Nodetree uses luatexbase's functions to manage callbacks if available. Otherwise a simplistic approach is taken by prepending or appending nodetree's diagnostic callbacks to the existing ones (and also removing them again if requested).

Each function in the callback_wrappers table consists of three parts:

  • before-callback inspection
  • original callback or default function call
  • after-callback inspection

The actual callback functions are stored in the callbacks table.

callbacks.contribute_filter (extrainfo, where)

Parameters:

  • extrainfo string
  • where string
callbacks.buildpage_filter (extrainfo, where)

Parameters:

  • extrainfo string
  • where string
callbacks.build_page_insert (n, i)

Parameters:

  • n string
  • i string

Returns:

    number
callbacks.pre_linebreak_filter (head, groupcode, where)

Parameters:

  • head Node # The head node of a node list.
  • groupcode string
  • where string

Returns:

    boolean
callbacks.linebreak_filter (head, is_display)

Parameters:

  • head Node # The head node of a node list.
  • is_display boolean

Returns:

    boolean
callbacks.append_to_vlist_filter (box, locationcode, prevdepth, mirrored)

Parameters:

  • box Node
  • locationcode string
  • prevdepth number
  • mirrored boolean

Returns:

  1. Node
  2. number
callbacks.post_linebreak_filter (head, groupcode, where)

Parameters:

  • head Node # The head node of a node list.
  • groupcode string
  • where string

Returns:

    boolean
callbacks.hpack_filter (head, groupcode, size, packtype, direction, attributelist, where)

Parameters:

  • head Node # The head node of a node list.
  • groupcode string
  • size number
  • packtype string
  • direction string
  • attributelist Node
  • where string

Returns:

    boolean
callbacks.vpack_filter (head, groupcode, size, packtype, maxdepth, direction, attributelist, where)

Parameters:

  • head Node # The head node of a node list.
  • groupcode string
  • size number
  • packtype string
  • maxdepth number
  • direction string
  • attributelist Node
  • where string

Returns:

    boolean
callbacks.hpack_quality (incident, detail, head, first, last)

Parameters:

  • incident string
  • detail number
  • head Node # The head node of a node list.
  • first number
  • last number

Returns:

    Node
callbacks.vpack_quality (incident, detail, head, first, last)

Parameters:

  • incident string
  • detail number
  • head Node # The head node of a node list.
  • first number
  • last number
callbacks.process_rule (head, width, height)

Parameters:

  • head Node # The head node of a node list.
  • width number
  • height number
callbacks.pre_output_filter (head, groupcode, size, packtype, maxdepth, direction, where)

Parameters:

  • head Node # The head node of a node list.
  • groupcode string
  • size number
  • packtype string
  • maxdepth number
  • direction string
  • where string

Returns:

    boolean
callbacks.hyphenate (head, tail, where)

Parameters:

  • head Node # The head node of a node list.
  • tail Node
  • where string
callbacks.ligaturing (head, tail, where)

Parameters:

  • head Node # The head node of a node list.
  • tail Node
  • where string
callbacks.kerning (head, tail, where)

Parameters:

  • head Node # The head node of a node list.
  • tail Node
  • where string
callbacks.insert_local_par (local_par, location, where)

Parameters:

  • local_par Node
  • location string
  • where string
callbacks.mlist_to_hlist (head, display_type, need_penalties)

Parameters:

  • head Node # The head node of a node list.
  • display_type string
  • need_penalties boolean

Returns:

    Node

Messages, options

message (why, where, what, help)
Emit a warning or error message.

This works for plain TeX, Texinfo, and LaTeX (for plain TeX and Texinfo we make the message look identical to the LaTeX case). Note that a full stop gets appended to what.

Parameters:

  • why string # 'error' or 'warning'.
  • where string # In which package the error happened.
  • what string # The warning message to emit.
  • help ? string # Additional help text for errors.
set_option (key, value)
Set a single-option key-value pair.

Parameters:

  • key string # The key of the option pair.
  • value number|string # The value of the option pair.
set_options (opts)
Set multiple key-value option pairs using a table.

Parameters:

  • opts table # Options.

Callback management

template.get_print_position (what)

Parameters:

  • what ? string|'before'|'after' # The name of a callback, or either the string before or after.

Returns:

  1. 'before'|nil # 'before' or nil`.
  2. 'after'|nil # 'after' or nil.
template.no_callback (name, internal)

Parameters:

  • name string
  • internal ? string|boolean
check_callback_name (callback_name)
Check whether the given callback name exists.

Throw an error if it doesn’t.

Parameters:

  • callback_name string # The name of a callback to check.

Returns:

    string # The unchanged input of the function.
get_callback_name (alias)
Get the real callback name from an alias string.

Parameters:

  • alias string # The alias of a callback name or the callback name itself.

Returns:

    string # The real callback name.
register_callback (cb)

Register a callback.

Doing this for plain TeX is simple; we have access to LuaTeX's base function callback.register and thus can easily add our callback wrapper, which in turn calls nodetree's functions at the very beginning and/or at the very end.

Enter LaTeX. It comes with its own callback management that can register multiple callbacks, also taking care of the calling order. Unfortunately, however, it is also more restrictive: for example, some callbacks like linebreak_filter are tagged as 'exclusive', only accepting a single callback. While this makes sense for the end user, it complicates the situation for nodetree to install its non-intrusive, observing-only callbacks.

We thus take the following route.

  • If there is no function for callback <foo> installed, register callbacks.<foo>.

  • If there is a (single) function for callback <foo> of type three ('exclusive'), remove it, wrap it into callbacks.<foo> (via orig_callbacks) and install callbacks.<foo>.

  • Otherwise register callbacks.<foo>_{before,after} as necessary.

Parameters:

  • cb string # The name of a callback.
unregister_callback (cb)
Unregister a callback.

We follow the same logic as with register_callback.

Parameters:

  • cb string # The name of a callback.

Exported functions

export.register_callbacks ()
export.unregister_callbacks ()
export.compile_include (tex_markup)
Compile a TeX snippet.

Write some TeX snippets into a temporary LaTeX file, compile this file using latexmk, read the generated *.nttex file, and return its content.

Parameters:

  • tex_markup string
export.check_shell_escape (what, is_command)
Check for --shell-escape within a command or environment.

Parameters:

  • what string # The name of the command or environment.
  • is_command boolean # Set if what is a command.
export.print (head, opts)
Print a node tree.

Parameters:

  • head Node # The head node of a node list.
  • opts table # Options as a table.
export.format_dim (sp)
Format a scaled point value as a formatted string.

Parameters:

  • sp number # A scaled point value.

Returns:

    string
export.get_default_option (key)
Get a default option that is not changed.

Parameters:

  • key string # The key of the option.

Returns:

    string|number|boolean
export.push_options ()
Push current options.
export.pop_options ()
Pop previous options.
export.input (filename)
Read a LaTeX input file and emit it immediately, obeying options firstline and lastline.

Parameters:

  • filename string
export.analyze
Set to export.print.
generated by LDoc 1.4.6 Last updated 2023-09-10 21:47:44