Module nodetree

The nodetree package.

Nodetree uses LDoc for the source code documentation. The supported tags are described on in the wiki.

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

  • list: Nodes, which are double 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 They are changed very often.

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.

Format functions

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

Template functions

color (color, mode, background) SGR (Select Graphic Rendition) Parameters
char (head) Format the char field of a node.
line (length)
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 (table, 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, color) Format a key value pair (key: value, ).
template.type (type, id)
template.callback (callback_name, variables)
template.branches (level, connection_type)

Extend the node library

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)

Build the node tree

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)
tree.analyze_callback (head)

Callback wrapper

contribute_filter (extrainfo)
buildpage_filter (extrainfo)
build_page_insert (n, i)
pre_linebreak_filter (head, groupcode)
linebreak_filter (head, is_display)
append_to_vlist_filter (box, locationcode, prevdepth, mirrored)
post_linebreak_filter (head, groupcode)
hpack_filter (head, groupcode, size, packtype, direction, attributelist)
vpack_filter (head, groupcode, size, packtype, maxdepth, direction, attributelist)
hpack_quality (incident, detail, head, first, last)
vpack_quality (incident, detail, head, first, last)
process_rule (head, width, height)
pre_output_filter (head, groupcode, size, packtype, maxdepth, direction)
hyphenate (head, tail)
ligaturing (head, tail)
kerning (head, tail)
insert_local_par (local_par, location)
mlist_to_hlist (head, display_type, need_penalties)
set_option (key, value) Set a single option key value pair.
set_options (opts) Set multiple key value pairs using a table.
check_callback_name (callback_name) Check if 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

compile_include (tex_markup) Compile a TeX snippet.
check_shell_escape () Check for –shell-escape
print (head, opts) Print a node tree.
format_dim (sp) Format a scaled point value into a formated string.
get_default_option (key) Get a default option that is not changed.
export.analyze Use export.print


Tables

default_options
The default options

Fields:

  • callback
  • channel
  • color
  • decimalplaces
  • unit
  • verbosity
options
The current options They are changed very often.

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 file, wrapped with some TeX boilerplate code. This written files are compiled.

Format functions

Low level template functions.
underscore (string)

Parameters:

  • string

Returns:

    string
escape (string)

Parameters:

  • string

Returns:

    string
whitespace (count)

Parameters:

  • count

Returns:

    string
color_code (code)

Parameters:

  • code

Returns:

    string
color_tex (color, mode)

Parameters:

  • color
  • mode

Returns:

    string
node_begin ()

Returns:

    string
node_end ()

Returns:

    string
new_line (count)

Parameters:

  • count

Returns:

    string
type_id (id)

Parameters:

  • id

Returns:

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

Parameters:

Template functions

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 string A color name (black, red, green, yellow, blue, magenta, cyan, white).
  • mode string bright or dim.
  • background boolean Colorize the background not the text.

Returns:

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

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

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. In verbosity level 2 or great suffixed with [char number]
line (length)

Parameters:

  • length

Returns:

    string
branch (connection_type, connection_state, last)

Parameters:

  • connection_type
  • connection_state
  • last

Returns:

    string
template.fill (number, order, field)

Parameters:

  • number
  • order
  • field

Returns:

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

Parameters:

  • text string A text string.
  • color string A color name (black, red, green, yellow, blue, magenta, cyan, white).
  • mode string bright or dim.
  • background boolean Colorize the background not 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 (table, 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: https://stackoverflow.com/a/5639667 Works if __index returns table, which it should as per luatex manual

Parameters:

  • table table A Lua table.
  • previous_data table table The of 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 a inline view of.

Returns:

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

Parameters:

  • key string A key
  • value string or number A value
  • color string A color name (black, red, green, yellow, blue, magenta, cyan, white).

Returns:

    string
template.type (type, id)

Parameters:

  • type
  • id

Returns:

    string
template.callback (callback_name, variables)

Parameters:

  • callback_name
  • variables

Returns:

    string
template.branches (level, connection_type)

Parameters:

  • level
  • connection_type

Returns:

    string

Extend the node library

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

We have to convert the node into a string and than have 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)
  • mark (4)
  • whatsit (8)
  • local_par (9)
  • dir (10)
  • 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

Returns:

    string

Build the node tree

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 a integer beginning with 1.
  • connection_type number The variable connection_type is a string, which can be either list or field.
  • connection_state connection_state is a string, which can be either continue or stop`.
tree.analyze_fields (fields, level)

Parameters:

  • fields table
  • level number
tree.analyze_node (head, level)

Parameters:

  • head node The head node of a node list.
  • level number
tree.analyze_list (head, level)

Parameters:

  • head node The head node of a node list.
  • level number
tree.analyze_callback (head)

Parameters:

  • head node The head node of a node list.

Callback wrapper

contribute_filter (extrainfo)

Parameters:

buildpage_filter (extrainfo)

Parameters:

build_page_insert (n, i)

Parameters:

pre_linebreak_filter (head, groupcode)

Parameters:

  • head node The head node of a node list.
  • groupcode string
linebreak_filter (head, is_display)

Parameters:

  • head node The head node of a node list.
  • is_display boolean
append_to_vlist_filter (box, locationcode, prevdepth, mirrored)

Parameters:

  • box node
  • locationcode string
  • prevdepth number
  • mirrored boolean
post_linebreak_filter (head, groupcode)

Parameters:

  • head node The head node of a node list.
  • groupcode string
hpack_filter (head, groupcode, size, packtype, direction, attributelist)

Parameters:

  • head node The head node of a node list.
  • groupcode string
  • size number
  • packtype string
  • direction string
  • attributelist node
vpack_filter (head, groupcode, size, packtype, maxdepth, direction, attributelist)

Parameters:

  • head node The head node of a node list.
  • groupcode string
  • size number
  • packtype string
  • maxdepth number
  • direction string
  • attributelist node
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
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
process_rule (head, width, height)

Parameters:

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

Parameters:

  • head node The head node of a node list.
  • groupcode string
  • size number
  • packtype string
  • maxdepth number
  • direction string
hyphenate (head, tail)

Parameters:

  • head node The head node of a node list.
  • tail node
ligaturing (head, tail)

Parameters:

  • head node The head node of a node list.
  • tail node
kerning (head, tail)

Parameters:

  • head node The head node of a node list.
  • tail node
insert_local_par (local_par, location)

Parameters:

  • local_par node
  • location string
mlist_to_hlist (head, display_type, need_penalties)

Parameters:

  • head node The head node of a node list.
  • display_type string
  • need_penalties boolean
set_option (key, value)
Set a single option key value pair.

Parameters:

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

Parameters:

check_callback_name (callback_name)
Check if the given callback name exists.

Throw an error if it doen’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.

Parameters:

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

Parameters:

  • cb string The name of a callback.

Exported functions

compile_include (tex_markup)
Compile a TeX snippet.

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

Parameters:

Returns:

    string
check_shell_escape ()
Check for –shell-escape
print (head, opts)
Print a node tree.

Parameters:

  • head node The head node of a node list.
  • opts table Options as a table.
format_dim (sp)
Format a scaled point value into a formated string.

Parameters:

  • sp number A scaled point value

Returns:

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

Parameters:

  • key string The key of the option.

Returns:

    string, number or boolean
export.analyze
Use export.print
  • head node The head node of a node list.
generated by LDoc 1.4.6 Last updated 2020-10-23 14:49:25