nodetree

Contents

• Tables
• Fields
• Format functions
• Template functions
• Node library extensions
• Node tree building functions
• Callback wrappers
• Messages, options
• Callback management
• Exported functions

Modules

• nodetree

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

Fields

Format functions

Template functions

Node library extensions

Node tree building functions

Callback wrappers

Messages, options

Callback management

Exported functions

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

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 (tbl)

Convert a Lua table into a format string.

Parameters:

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

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.