--- This file (`nodetree.lua`) is part of the LuaTeX package
--- 'nodetree'.
---
---`nodetree` uses the annotation system of the
---[lua-language-server](https://github.com/LuaLS/lua-language-server/wiki/Annotations).
---Install the [type definitions for LuaTeX](https://github.com/Josef-Friedrich/LuaTeX_Lua-API)
---or the [Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=JosefFriedrich.luatex).
---
---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`.
---@module nodetree
---luacheck: globals node lang tex luatexbase lfs
---luacheck: globals callback os unicode status modules
---
---@alias ColorName 'black'|'red' |'green'|'yellow'|'blue'|'magenta'|'cyan'|'white'|'reset'
---@alias ColorMode 'bright'|'dim'|''
---
---@alias ConnectionType 'list'|'field' # A string literal,
--- which can be either 'list' or 'field'.
---@alias ConnectionState 'stop'|'continue' # A literal, which can
--- be either `continue` or `stop`.
if not modules then modules = {} end modules ['nodetree'] = {
version = '2.4.0',
comment = 'nodetree',
author = 'Josef Friedrich',
copyright = 'Josef Friedrich',
license = 'The LaTeX Project Public License Version 1.3c 2008-05-04'
}
local direct = node.direct
local todirect = direct.todirect
local getchar = direct.getchar
---Lua 5.1 does not have the utf8 library (Lua 5.1 is the default
---version in LuajitTeX). LuaJitTeX does include the slnunicode library.
local utf8 = utf8 or unicode.utf8
local utfchar = utf8.char
local properties = direct.get_properties_table()
---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.
local example_counter = 0
---A flag to indicate that something has been emitted by nodetree.
local have_output = false
--- The default options.
local default_options = {
callback = 'post_linebreak_filter',
channel = 'term',
color = 'colored',
decimalplaces = 2,
unit = 'pt',
verbosity = 0,
firstline = 1,
lastline = -1,
}
--- The current options.
local options = {}
for key, value in pairs(default_options) do
options[key] = value
end
--- 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.
local prev_options = {}
local option_level = 0
---File descriptor.
local output_file
--- The state values of the current tree item.
---
---`tree_state`:
---
---* `1` (level):
--- * `list`: `continue`
--- * `field`: `stop`
---* `2`:
--- * `list`: `continue`
--- * `field`: `stop`
---
---...
local tree_state = {}
--- Format functions.
---
---Low-level template functions.
---
---@section format
local format = {
---@function format.underscore
---
---@param input string
---
---@return string
underscore = function(input)
if options.channel == 'tex' then
local result = input.gsub(input, '_', '\\_')
return result
else
return input
end
end,
---@function format.escape
---
---@param input string
---
---@return string
escape = function(input)
if options.channel == 'tex' then
local result = input.gsub(input, [[\]], [[\string\]])
return result
else
return input
end
end,
---@function format.function
---
---@param input number
---
---@return number
number = function(input)
local mult = 10^(options.decimalplaces or 0)
return math.floor(input * mult + 0.5) / mult
end,
---@function format.whitespace
---
---@param count? number # How many spaces should be output.
---
---@return string
whitespace = function(count)
local whitespace
local output = ''
if options.channel == 'tex' then
whitespace = '\\hspace{0.5em}'
else
whitespace = ' '
end
if not count then
count = 1
end
for _ = 1, count do
output = output .. whitespace
end
return output
end,
---@function format.color_code
---
---@param code number
---
---@return string
color_code = function(code)
return string.char(27) .. '[' .. tostring(code) .. 'm'
end,
---@function format.color_tex
---
---@param color string
---@param mode? string
---
---@return string
color_tex = function(color, mode)
if not mode then mode = '' end
return 'NTE' .. color .. mode
end,
---@function format.node_begin
---
---@return string
node_begin = function()
if options.channel == 'tex' then
return '\\mbox{'
else
return ''
end
end,
---@function format.node_end
---
---@return string
node_end = function()
if options.channel == 'tex' then
return '}'
else
return ''
end
end,
---@function format.new_line
---
---@param count? number # How many new lines should be output.
---
---@return string
new_line = function(count)
local output = ''
if not count then
count = 1
end
local new_line
if options.channel == 'tex' then
new_line = '\\par\n'
else
new_line = '\n'
end
for _ = 1, count do
output = output .. new_line
end
return output
end,
---@function format.type_id
---
---@param id number
---
---@return string
type_id = function(id)
return '[' .. tostring(id) .. ']'
end
}
--- Print the output to stdout or write it into a file (`output_file`).
---New text is appended.
---
---@param text string # A text string.
local function nodetree_print(text)
if options.channel == 'log' or options.channel == 'tex' then
output_file:write(text)
else
io.write(text)
end
end
--- Template functions.
---
---@section template
local template = {
node_colors = {
hlist = {'red', 'bright'},
vlist = {'green', 'bright'},
rule = {'blue', 'bright'},
ins = {'blue'},
mark = {'magenta'},
adjust = {'cyan'},
boundary = {'red', 'bright'},
disc = {'green', 'bright'},
whatsit = {'yellow', 'bright'},
local_par = {'blue', 'bright'},
dir = {'magenta', 'bright'},
math = {'cyan', 'bright'},
glue = {'magenta', 'bright'},
kern = {'green', 'bright'},
penalty = {'yellow', 'bright'},
unset = {'blue'},
style = {'magenta'},
choice = {'cyan'},
noad = {'red'},
radical = {'green'},
fraction = {'yellow'},
accent = {'blue'},
fence = {'magenta'},
math_char = {'cyan'},
sub_box = {'red', 'bright'},
sub_mlist = {'green', 'bright'},
math_text_char = {'yellow', 'bright'},
delim = {'blue', 'bright'},
margin_kern = {'magenta', 'bright'},
glyph = {'cyan', 'bright'},
align_record = {'red'},
pseudo_file = {'green'},
pseudo_line = {'yellow'},
page_insert = {'blue'},
split_insert = {'magenta'},
expr_stack = {'cyan'},
nested_list = {'red'},
span = {'green'},
attribute = {'yellow'},
glue_spec = {'magenta'},
attribute_list = {'cyan'},
temp = {'magenta'},
align_stack = {'red', 'bright'},
movement_stack = {'green', 'bright'},
if_stack = {'yellow', 'bright'},
unhyphenated = {'magenta', 'bright'},
hyphenated = {'cyan', 'bright'},
delta = {'red'},
passive = {'green'},
shape = {'yellow'},
},
-- Field name abbreviations for verbosity level 0. A second field
-- limits the abbreviation to this node type.
--
-- Entry '' means to omit the key, printing only the value. Entry
-- '()' means the same, but the value gets printed in parentheses.
field_abbrevs = {
char = {''},
depth = {'dp'},
dir = {'()', 'dir'},
height = {'ht'},
kern = {''},
mark = {''},
penalty = {'', 'penalty'},
shrink = {'minus'},
stretch = {'plus'},
style = {''},
subtype = {'()'},
width = {'wd'},
},
--- [SGR (Select Graphic Rendition)
-- parameters](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_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 |
--
---@function template.color
---
---@param color ColorName # A color name.
---@param mode? ColorMode
---@param background? boolean # If set, colorize the background instead of the text.
---
---@return string
color = function(color, mode, background)
if options.color ~= 'colored' then
return ''
end
local output = ''
local code
if mode == 'bright' then
output = format.color_code(1)
elseif mode == 'dim' then
output = format.color_code(2)
end
if not background then
if color == 'reset' then code = 0
elseif color == 'red' then code = 31
elseif color == 'green' then code = 32
elseif color == 'yellow' then code = 33
elseif color == 'blue' then code = 34
elseif color == 'magenta' then code = 35
elseif color == 'cyan' then code = 36
else code = 37 end
else
if color == 'black' then code = 40
elseif color == 'red' then code = 41
elseif color == 'green' then code = 42
elseif color == 'yellow' then code = 43
elseif color == 'blue' then code = 44
elseif color == 'magenta' then code = 45
elseif color == 'cyan' then code = 46
elseif color == 'white' then code = 47
else code = 40 end
end
return output .. format.color_code(code)
end,
--- 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)`](https://github.com/latex3/luaotfload/blob/4c09fe264c1644792d95182280be259449e7da02/src/luaotfload-harf-plug.lua#L1018-L1031)
-- 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.
--
---@function template.char
--
---@param head Node # The head node of a node list.
---
---@return string # A textual representation of the `char` number.
char = function(head)
local node_id = todirect(head) -- Convert to node id.
local props = properties[node_id]
local info = props and props.glyph_info
local textual
local character_index = getchar(node_id)
if info then
textual = info
elseif character_index == 0 then
textual = '^^@'
elseif character_index <= 31 or (character_index >= 127 and character_index <= 159) then
-- The C0 range [c-zero] contains characters from U+0000 to U+001F
-- (decimal 0-31) and U+007F (decimal 127), the C1 range covers
-- characters from U+0080 to U+009F (decimal 128-159).
textual = '???'
elseif character_index ~= nil and character_index < 0x110000 then
textual = utfchar(character_index)
else
textual = string.format('^^^^^^%06X', character_index)
end
if options.verbosity == 0 then
if textual == '???' then
return character_index
else
return "'" .. textual .. "'"
end
elseif options.verbosity <= 2 then
return character_index .. " ('" .. textual .. "')"
else
return character_index
.. ' ('
.. string.format('0x%x', character_index)
.. ", '"
.. textual
.. "')"
end
end,
---@function template.line
---
---@param length string # If `long`, emit a longer line.
---
---@return string
line = function(length)
local output
if length == 'long' then
output = '------------------------------------------'
else
output = '-----------------------'
end
return output .. format.new_line()
end,
---@function template.branch
---
---@param connection_type ConnectionType
---@param connection_state ConnectionState
---@param last boolean
---
---@return string
branch = function(connection_type, connection_state, last)
local c = connection_type
local s = connection_state
local l = last
if c == 'list' and s == 'stop' and l == false then
return format.whitespace(2)
elseif c == 'field' and s == 'stop' and l == false then
return format.whitespace(2)
elseif c == 'list' and s == 'continue' and l == false then
return '���' .. format.whitespace()
elseif c == 'field' and s == 'continue' and l == false then
return '���' .. format.whitespace()
elseif c == 'list' and s == 'continue' and l == true then
return '������'
elseif c == 'field' and s == 'continue' and l == true then
return '������'
elseif c == 'list' and s == 'stop' and l == true then
return '������'
elseif c == 'field' and s == 'stop' and l == true then
return '������'
end
return ''
end,
}
---@param number number
---@param order number
---@param field string
---
---@return string
function template.fill(number, order, field)
local output
if order ~= nil and order ~= 0 then
if field == 'stretch' then
output = '+'
else
output = '-'
end
return output .. string.format(
'%g%s', number / 2^16,
template.colored_string(
'fi' .. string.rep('l', order - 1),
'white',
'dim'
)
)
else
return template.length(number)
end
end
--- Colorize a text string.
---
---@param text string # A text string.
---@param color ColorName # A color name.
---@param mode? ColorMode
---@param background? boolean # If set, colorize the background instead of the text.
---
---@return string
function template.colored_string(text, color, mode, background)
if options.channel == 'tex' then
if mode == 'dim' then
mode = ''
end
return '\\textcolor{' ..
format.color_tex(color, mode) ..
'}{' ..
text ..
'}'
else
return template.color(color, mode, background) .. text .. template.color('reset')
end
end
--- Format a scaled point input value into dimension string (`12pt`,
--- `1cm`)
---
---@param input number
---
---@return string
function template.length(input)
local i = tonumber(input)
if i ~= nil then
input = i / tex.sp('1' .. options.unit)
end
return string.format(
'%g%s',
format.number(input),
template.colored_string(options.unit, 'white', 'dim')
)
end
--- 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](https://stackoverflow.com/a/5639667) ��� this
---works if `__index` returns a table, which it should as per LuaTeX
---manual.
---
---@param data table # A Lua table.
---@param previous_data? table # The data of a Lua table of a previous recursive call.
---
---@return table # A merged table.
local function get_all_table_data(data, previous_data)
-- If previous_data is nil, start empty, otherwise start with previous_data.
local output = previous_data or {}
-- Copy all the attributes from the table.
for key, value in pairs(data) do
output[key] = output[key] or value
end
-- Get table���s metatable, or exit if not existing.
local metatable = getmetatable(data)
if type(metatable) ~= 'table' then
return output
end
-- Get the `__index` from metatable, or exit if not table.
local index = metatable.__index
if type(index) ~= 'table' then
return output
end
-- Include the data from index into data recursively and return.
return get_all_table_data(index, output)
end
--- Convert a Lua table into a format string.
---
---@param tbl table # A table to generate an inline view of.
---
---@return string
function template.table_inline(tbl)
local tex_escape = ''
if options.channel == 'tex' then
tex_escape = '\\'
end
if type(tbl) == 'table' then
tbl = get_all_table_data(tbl)
local output = tex_escape .. '{'
local kv_list = ''
local keys = {}
for key in pairs(tbl) do
keys[#keys + 1] = key
end
table.sort(keys)
for i = 1, #keys do
local key = keys[i]
local value = tbl[key]
if type(key) ~= 'numbers' then
key = '\'' ..
template.colored_string(key, 'cyan', 'dim') .. '\''
end
kv_list = kv_list .. '[' .. key .. '] = ' ..
template.table_inline(value) .. ', '
end
output = output .. kv_list:gsub(', $', '')
return output .. tex_escape .. '}'
else
return tostring(tbl)
end
end
--- Format a key-value pair (`key: value, `).
---
---@param key string # A key.
---@param value string|number # A value.
---@param typ? string # A node type. Had to be named typ to avoid conflict with the type() function.
---@param color? ColorName # A color name.
---
---@return string
function template.key_value(key, value, typ, color)
if type(color) ~= 'string' then
color = 'yellow'
end
key = format.underscore(key)
local output = ''
local abbrev = nil
local separator = ':'
if options.verbosity == 0 then
if template.field_abbrevs[key] then
local only_this_type = template.field_abbrevs[key][2]
if not only_this_type or not typ or only_this_type == typ then
abbrev = template.field_abbrevs[key][1]
end
end
separator = ''
end
if abbrev == nil then
output = template.colored_string(key .. separator, color)
elseif abbrev ~= '' and abbrev ~= '()' then
output = template.colored_string(abbrev, color)
end
if value then
if abbrev == '()' then
-- Printing '(unused)' is confusing.
if value ~= 'unused' then
output = output .. '(' .. value .. ') '
end
elseif abbrev == '' then
output = output .. value .. ', '
else
output = output .. ' ' .. value .. ', '
end
end
return output
end
---@param type string
---@param id number
---
---@return string
function template.type(type, id)
local output
output = format.underscore(type)
output = string.upper(output)
if options.verbosity > 1 then
output = output .. format.type_id(id)
end
return template.colored_string(
output,
template.node_colors[type][1],
template.node_colors[type][2]
)
end
---@param callback_name string
---@param variables table|nil
---@param where 'before'|'after' # `'before'` or `'after'`
function template.callback(callback_name, variables, where)
if options.channel == 'term' or have_output == true then
nodetree_print(format.new_line(2))
end
have_output = true
nodetree_print(
where .. ' callback ' ..
template.colored_string(format.underscore(callback_name), 'red', '', true) ..
format.new_line()
)
if variables then
for name, value in pairs(variables) do
if value ~= nil and value ~= '' then
nodetree_print(
'- ' ..
format.underscore(name) ..
': ' ..
format.underscore(tostring(value)) ..
format.new_line()
)
end
end
end
nodetree_print(template.line('long'))
end
--- Format the branching tree for one output line.
---
---@param level number
---@param connection_type ConnectionType
---
---@return string
function template.branches(level, connection_type)
local output = ''
for i = 1, level - 1 do
output = output .. template.branch('list', tree_state[i]['list'], false)
output = output .. template.branch('field', tree_state[i]['field'], false)
end
---Format the last branches
if connection_type == 'list' then
output = output .. template.branch('list', tree_state[level]['list'], true)
else
output = output .. template.branch('list', tree_state[level]['list'], false)
output = output .. template.branch('field', tree_state[level]['field'], true)
end
return output
end
--- Node library extensions.
---
---@section node_extended
local node_extended = {}
--- 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>`.
---
---@param n Node # A node.
---
---@return string
function node_extended.node_id(n)
local result = string.gsub(tostring(n), '^<node%s+%S+%s+<%s+(%d+).*', '%1')
return result
end
--- 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)
---
---@return table
local function get_node_subtypes()
local subtypes = {
-- hlist (0)
hlist = {
[0] = 'unknown',
[1] = 'line',
[2] = 'box',
[3] = 'indent',
[4] = 'alignment',
[5] = 'cell',
[6] = 'equation',
[7] = 'equationnumber',
[8] = 'math',
[9] = 'mathchar',
[10] = 'hextensible',
[11] = 'vextensible',
[12] = 'hdelimiter',
[13] = 'vdelimiter',
[14] = 'overdelimiter',
[15] = 'underdelimiter',
[16] = 'numerator',
[17] = 'denominator',
[18] = 'limits',
[19] = 'fraction',
[20] = 'nucleus',
[21] = 'sup',
[22] = 'sub',
[23] = 'degree',
[24] = 'scripts',
[25] = 'over',
[26] = 'under',
[27] = 'accent',
[28] = 'radical',
},
-- vlist (1)
vlist = {
[0] = 'unknown',
[4] = 'alignment',
[5] = 'cell',
},
-- rule (2)
rule = {
[0] = 'normal',
[1] = 'box',
[2] = 'image',
[3] = 'empty',
[4] = 'user',
[5] = 'over',
[6] = 'under',
[7] = 'fraction',
[8] = 'radical',
[9] = 'outline',
},
-- mark (4)
-- The subtype is not used.
mark = {
[0] = 'unused',
},
-- adjust (5)
adjust = {
[0] = 'normal',
[1] = 'pre',
},
-- boundary (6)
boundary = {
[0] = 'cancel',
[1] = 'user',
[2] = 'protrusion',
[3] = 'word',
},
-- disc (7)
disc = {
[0] = 'discretionary',
[1] = 'explicit',
[2] = 'automatic',
[3] = 'regular',
[4] = 'first',
[5] = 'second',
},
-- dir (10)
-- This is an internal detail, see luatex source code file
-- `texnodes.h`.
-- dir = {
-- [0] = 'normal_dir',
-- [1] = 'cancel_dir',
-- },
-- math (11)
math = {
[0] = 'beginmath',
[1] = 'endmath',
},
-- glue (12)
glue = {
[0] = 'userskip',
[1] = 'lineskip',
[2] = 'baselineskip',
[3] = 'parskip',
[4] = 'abovedisplayskip',
[5] = 'belowdisplayskip',
[6] = 'abovedisplayshortskip',
[7] = 'belowdisplayshortskip',
[8] = 'leftskip',
[9] = 'rightskip',
[10] = 'topskip',
[11] = 'splittopskip',
[12] = 'tabskip',
[13] = 'spaceskip',
[14] = 'xspaceskip',
[15] = 'parfillskip',
[16] = 'mathskip',
[17] = 'thinmuskip',
[18] = 'medmuskip',
[19] = 'thickmuskip',
[98] = 'conditionalmathskip',
[99] = 'muglue',
[100] = 'leaders',
[101] = 'cleaders',
[102] = 'xleaders',
[103] = 'gleaders',
},
-- kern (13)
kern = {
[0] = 'fontkern',
[1] = 'userkern',
[2] = 'accentkern',
[3] = 'italiccorrection',
},
-- penalty (14)
penalty = {
[0] = 'userpenalty',
[1] = 'linebreakpenalty',
[2] = 'linepenalty',
[3] = 'wordpenalty',
[4] = 'finalpenalty',
[5] = 'noadpenalty',
[6] = 'beforedisplaypenalty',
[7] = 'afterdisplaypenalty',
[8] = 'equationnumberpenalty',
},
noad = {
[0] = 'ord',
[1] = 'opdisplaylimits',
[2] = 'oplimits',
[3] = 'opnolimits',
[4] = 'bin',
[5] = 'rel',
[6] = 'open',
[7] = 'close',
[8] = 'punct',
[9] = 'inner',
[10] = 'under',
[11] = 'over',
[12] = 'vcenter',
},
-- radical (19)
radical = {
[0] = 'radical',
[1] = 'uradical',
[2] = 'uroot',
[3] = 'uunderdelimiter',
[4] = 'uoverdelimiter',
[5] = 'udelimiterunder',
[6] = 'udelimiterover',
},
-- accent (21)
accent = {
[0] = 'bothflexible',
[1] = 'fixedtop',
[2] = 'fixedbottom',
[3] = 'fixedboth',
},
-- fence (22)
fence = {
[0] = 'unset',
[1] = 'left',
[2] = 'middle',
[3] = 'right',
[4] = 'no',
},
-- margin_kern (28)
margin_kern = {
[0] = 'left',
[1] = 'right',
},
-- glyph (29)
-- The subtype for this node is a bit field, not an enumeration;
-- bit 0 gets handled separately.
glyph = {
[1] = 'ligature',
[2] = 'ghost',
[3] = 'left',
[4] = 'right',
},
}
subtypes.whatsit = node.whatsits()
return subtypes
end
---@param n Node
---
---@return string
function node_extended.subtype(n)
local typ = node.type(n.id)
local subtypes = get_node_subtypes()
local output = ''
if subtypes[typ] then
if typ == 'glyph' then
-- Only handle the lowest five bits.
if n.subtype & 1 == 0 then
output = output .. 'glyph'
else
output = output .. 'character'
end
local mask = 2
for i = 1,4,1 do
if n.subtype & mask ~= 0 then
output = output .. ' ' .. subtypes[typ][i]
end
mask = mask << 1
end
else
if subtypes[typ][n.subtype] then
output = subtypes[typ][n.subtype]
else
return tostring(n.subtype)
end
end
if options.verbosity > 1 then
output = output .. format.type_id(n.subtype)
end
return output
else
return tostring(n.subtype)
end
end
--- Node tree building functions.
---
---@section tree
local tree = {}
---
---@param head Node # The head node of a node list.
---@param field string
---
---@return string
function tree.format_field(head, field)
local output
local typ = node.type(head.id)
-- Print subtypes also for nodes with ID=0. However, suppress the
-- internal 'subtype' field for 'dir' nodes.
if field == 'subtype' then
if typ == 'dir' then
return ''
elseif head[field] ~= nil then
return template.key_value(field,
format.underscore(node_extended.subtype(head)))
end
end
-- Character 0 should be printed in a tree because the corresponding slot
-- zero in a TeX font usually contains a symbol.
if head[field] == nil or (head[field] == 0 and field ~= 'char') then
return ''
end
if options.verbosity < 2 and
-- glyph
field == 'left' or
field == 'right' or
field == 'uchyph' or
-- hlist
-- Don't drop the 'dir' field of the 'dir' node.
(field == 'dir' and typ ~= 'dir') or
field == 'glue_order' or
field == 'glue_sign' or
field == 'glue_set' or
-- glue
field == 'stretch_order' then
return ''
elseif options.verbosity < 3 and
field == 'prev' or
field == 'next' or
field == 'id' then
return ''
end
if field == 'prev' or field == 'next' then
output = node_extended.node_id(head[field])
elseif
field == 'width' or
field == 'height' or
field == 'depth' or
field == 'kern' or
field == 'shift' then
output = template.length(head[field])
elseif field == 'char' then
output = template.char(head)
elseif field == 'glue_set' then
output = format.number(head[field])
elseif field == 'stretch' or field == 'shrink' then
output = template.fill(head[field], head[field .. '_order'], field)
else
-- Surround strings with single quotes except values of fields
-- that get potentially abbreviated (and thus don't really need
-- quotes).
if type(head[field]) == 'string' and not template.field_abbrevs[field] then
output = template.colored_string("'", 'yellow') ..
head[field] ..
template.colored_string("'", 'yellow')
elseif type(head[field]) == 'table' then
output = '<table>'
else
output = tostring(head[field])
end
end
return template.key_value(field, output, node.type(head.id))
end
---
---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.
---
---@param head Node # The head node of a node list.
---
---@return string
function tree.format_attributes(head)
if not head then
return ''
end
local space = ''
local output = ''
local attr = head.next --[[@as AttributeNode]]
while attr do
if attr.number ~= 0 or (attr.number == 0 and attr.value ~= 0) then
output = output .. space .. tostring(attr.number) .. '=' .. tostring(attr.value)
space = ' '
end
attr = attr.next --[[@as AttributeNode]]
end
return output
end
---
---@param level number # `level` is an integer beginning with 1.
---@param connection_type ConnectionType
---@param connection_state ConnectionState
function tree.set_state(level, connection_type, connection_state)
if not tree_state[level] then
tree_state[level] = {}
end
tree_state[level][connection_type] = connection_state
end
---
---@param fields table
---@param level number # The current recursion level.
function tree.analyze_fields(fields, level)
local max = 0
local connection_state
for _ in pairs(fields) do
max = max + 1
end
local count = 0
for field_name, recursion_node in pairs(fields) do
count = count + 1
if count == max then
connection_state = 'stop'
else
connection_state = 'continue'
end
tree.set_state(level, 'field', connection_state)
nodetree_print(
format.node_begin() ..
template.branches(level, 'field') ..
template.key_value(field_name) ..
format.node_end() ..
format.new_line()
)
tree.analyze_list(recursion_node, level + 1)
end
end
---
---@param head Node # The head node of a node list.
---@param level number # The current recursion level.
function tree.analyze_node(head, level)
local connection_state
local output
local need_whitespace = true
if head.next then
connection_state = 'continue'
else
connection_state = 'stop'
end
tree.set_state(level, 'list', connection_state)
output = template.branches(level, 'list')
.. template.type(node.type(head.id), head.id)
if options.verbosity > 1 then
output = output ..
format.whitespace() ..
template.key_value('no', node_extended.node_id(head))
need_whitespace = false
end
-- We store the attributes output so that we can append it to the field
-- list later on.
local attributes
-- We store fields which are nodes for later treatment.
local fields = {}
-- Inline fields, for example: char: 'm', width: 25pt, height: 13.33pt.
local output_fields = ''
for _, field_name in pairs(node.fields(head.id, head.subtype)) do
if field_name == 'attr' then
attributes = tree.format_attributes(head.attr)
elseif field_name ~= 'next' and field_name ~= 'prev' and
node.is_node(head[field_name]) then
fields[field_name] = head[field_name]
else
output_fields = output_fields .. tree.format_field(head, field_name)
end
end
if output_fields ~= '' then
if need_whitespace == true then
output = output .. format.whitespace()
need_whitespace = false
end
output = output .. output_fields
end
-- Append the attributes output if available.
if attributes and attributes ~= '' then
if need_whitespace == true then
output = output .. format.whitespace()
end
output = output .. template.key_value('attr', attributes, nil, 'blue')
end
output = output:gsub(', $', '')
nodetree_print(
format.node_begin() ..
output ..
format.node_end() ..
format.new_line()
)
local property = node.getproperty(head)
if property then
local props
if options.verbosity == 0 then
props = 'props'
else
props = 'properties:'
end
-- Print attributes in a separate line.
nodetree_print(
format.node_begin() ..
template.branches(level, 'field') ..
' ' ..
template.colored_string(props, 'blue') .. ' ' ..
template.table_inline(property) ..
format.node_end() ..
format.new_line()
)
end
tree.analyze_fields(fields, level)
end
--- Recurse over the current node list.
---
---@param head Node # The head node of a node list.
---@param level number # The current recursion level.
function tree.analyze_list(head, level)
while head do
tree.analyze_node(head, level)
head = head.next
end
end
--- The top-level internal entry point.
---
---@param head Node # The head node of a node list.
function tree.analyze_callback(head)
tree.analyze_list(head, 1)
nodetree_print(template.line('short'))
end
local orig_callbacks = {}
local orig_descriptions = {}
local print_positions = {}
local callback_has_default_action = {
hyphenate = true,
ligaturing = true,
kerning = true,
mlist_to_hlist = true
}
--- 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.
---
---@section callbacks
local callback_wrappers = {
---@function callbacks.contribute_filter
---
---@param extrainfo string
---@param where string
contribute_filter = function(extrainfo, where)
local cb = 'contribute_filter'
local before, after = template.get_print_position(where)
if before then
template.callback(cb, {extrainfo = extrainfo}, before)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
orig_callbacks[cb](extrainfo)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {extrainfo = extrainfo}, after)
end
end,
---@function callbacks.buildpage_filter
---
---@param extrainfo string
---@param where string
buildpage_filter = function(extrainfo, where)
local cb = 'buildpage_filter'
local before, after = template.get_print_position(where)
if before then
template.callback(cb, {extrainfo = extrainfo}, before)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
orig_callbacks[cb](extrainfo)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {extrainfo = extrainfo}, after)
end
end,
---@function callbacks.build_page_insert
---
---@param n string
---@param i string
---
---@return number
build_page_insert = function(n, i)
local cb = 'build_page_insert'
local before, after = template.get_print_position(cb)
local retval = 0
if before then
template.callback(cb, {n = n, i = i}, before)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](n, i)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {n = n, i = i}, after)
end
return retval
end,
---@function callbacks.pre_linebreak_filter
---
---@param head Node # The head node of a node list.
---@param groupcode string
---@param where string
---
---@return boolean
pre_linebreak_filter = function(head, groupcode, where)
local cb = 'pre_linebreak_filter'
local before, after = template.get_print_position(where)
local retval = true
if before then
template.callback(cb, {groupcode = groupcode}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](head, groupcode)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {groupcode = groupcode}, after)
tree.analyze_callback(head)
end
return retval
end,
---@function callbacks.linebreak_filter
---
---@param head Node # The head node of a node list.
---@param is_display boolean
---
---@return boolean
linebreak_filter = function(head, is_display)
local cb = 'linebreak_filter'
local before, after = template.get_print_position(cb)
local retval = true
if before then
template.callback(cb, {is_display = is_display}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](head, is_display)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {is_display = is_display}, after)
tree.analyze_callback(head)
end
return retval
end,
---@function callbacks.append_to_vlist_filter
---
---@param box Node
---@param locationcode string
---@param prevdepth number
---@param mirrored boolean
---
---@return Node
---@return number
append_to_vlist_filter = function(box, locationcode, prevdepth, mirrored)
local cb = 'append_to_vlist_filter'
local before, after = template.get_print_position(cb)
if before then
template.callback(cb, {locationcode = locationcode,
prevdepth = prevdepth,
mirrored = mirrored}, before)
tree.analyze_callback(box)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
box, prevdepth = orig_callbacks[cb](box, locationcode,
prevdepth, mirrored)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {locationcode = locationcode,
prevdepth = prevdepth,
mirrored = mirrored}, after)
tree.analyze_callback(box)
end
return box, prevdepth
end,
---@function callbacks.post_linebreak_filter
---
---@param head Node # The head node of a node list.
---@param groupcode string
---@param where string
---
---@return boolean
post_linebreak_filter = function(head, groupcode, where)
local cb = 'post_linebreak_filter'
local before, after = template.get_print_position(where)
local retval = true
if before then
template.callback(cb, {groupcode = groupcode}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](head, groupcode)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {groupcode = groupcode}, after)
tree.analyze_callback(head)
end
return retval
end,
---@function callbacks.hpack_filter
---
---@param head Node # The head node of a node list.
---@param groupcode string
---@param size number
---@param packtype string
---@param direction string
---@param attributelist Node
---@param where string
---
---@return boolean
hpack_filter = function(head, groupcode, size, packtype,
direction, attributelist, where)
local cb = 'hpack_filter'
local before, after = template.get_print_position(where)
local retval = true
if before then
template.callback(cb, {groupcode = groupcode,
size = size,
packtype = packtype,
direction = direction,
attributelist = attributelist}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](head, groupcode, size,
packtype, direction,
attributelist)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {groupcode = groupcode,
size = size,
packtype = packtype,
direction = direction,
attributelist = attributelist}, after)
tree.analyze_callback(head)
end
return retval
end,
---@function callbacks.vpack_filter
---
---@param head Node # The head node of a node list.
---@param groupcode string
---@param size number
---@param packtype string
---@param maxdepth number
---@param direction string
---@param attributelist Node
---@param where string
---
---@return boolean
vpack_filter = function(head, groupcode, size, packtype,
maxdepth, direction, attributelist, where)
local cb = 'vpack_filter'
local before, after = template.get_print_position(where)
local retval = true
if before then
template.callback(cb, {groupcode = groupcode,
size = size,
packtype = packtype,
maxdepth = template.length(maxdepth),
direction = direction,
attributelist = attributelist}, before)
tree.analyze_callback(head)
tree.analyze_callback(attributelist)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](head, groupcode, size, packtype,
maxdepth, direction,
attributelist)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {groupcode = groupcode,
size = size,
packtype = packtype,
maxdepth = template.length(maxdepth),
direction = direction,
attributelist = attributelist}, after)
tree.analyze_callback(head)
tree.analyze_callback(attributelist)
end
return retval
end,
---@function callbacks.hpack_quality
---
---@param incident string
---@param detail number
---@param head Node # The head node of a node list.
---@param first number
---@param last number
---
---@return Node
hpack_quality = function(incident, detail, head, first, last)
local cb = 'hpack_quality'
local before, after = template.get_print_position(cb)
local retval = nil
if before then
template.callback(cb, {incident = incident,
detail = detail,
first = first,
last = last}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](incident, detail, head, first, last)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {incident = incident,
detail = detail,
first = first,
last = last}, after)
tree.analyze_callback(head)
end
return retval
end,
---@function callbacks.vpack_quality
---
---@param incident string
---@param detail number
---@param head Node # The head node of a node list.
---@param first number
---@param last number
vpack_quality = function(incident, detail, head, first, last)
local cb = 'vpack_quality'
local before, after = template.get_print_position(cb)
if before then
template.callback(cb, {incident = incident,
detail = detail,
first = first,
last = last}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
orig_callbacks[cb](incident, detail, head, first, last)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {incident = incident,
detail = detail,
first = first,
last = last}, after)
tree.analyze_callback(head)
end
end,
---@function callbacks.process_rule
---
---@param head Node # The head node of a node list.
---@param width number
---@param height number
process_rule = function(head, width, height)
local cb = 'process_rule'
local before, after = template.get_print_position(cb)
if before then
template.callback(cb, {width = width, height = height}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
orig_callbacks[cb](head, width, height)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {width = width, height = height}, after)
tree.analyze_callback(head)
end
end,
---@function callbacks.pre_output_filter
---
---@param head Node # The head node of a node list.
---@param groupcode string
---@param size number
---@param packtype string
---@param maxdepth number
---@param direction string
---@param where string
---
---@return boolean
pre_output_filter = function(head, groupcode, size, packtype,
maxdepth, direction, where)
local cb = 'pre_output_filter'
local before, after = template.get_print_position(where)
local retval = true
if before then
template.callback(cb, {groupcode = groupcode,
size = size,
packtype = packtype,
maxdepth = maxdepth,
direction = direction}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](head, groupcode, size,
packtype, maxdepth,
direction)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {groupcode = groupcode,
size = size,
packtype = packtype,
maxdepth = maxdepth,
direction = direction}, after)
tree.analyze_callback(head)
end
return retval
end,
---@function callbacks.hyphenate
---
---@param head Node # The head node of a node list.
---@param tail Node
---@param where string
hyphenate = function(head, tail, where)
local cb = 'hyphenate'
local before, after = template.get_print_position(where)
if before then
template.callback(cb, nil, before)
nodetree_print('head:' .. format.new_line())
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
orig_callbacks[cb](head, tail)
end
else
template.no_callback(cb, true)
lang.hyphenate(head, tail)
end
if after then
template.callback(cb, nil, after)
nodetree_print('head:' .. format.new_line())
tree.analyze_callback(head)
end
end,
---@function callbacks.ligaturing
---
---@param head Node # The head node of a node list.
---@param tail Node
---@param where string
ligaturing = function(head, tail, where)
local cb = 'ligaturing'
local before, after = template.get_print_position(where)
if before then
template.callback(cb, nil, before)
nodetree_print('head:' .. format.new_line())
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
orig_callbacks[cb](head, tail)
end
else
template.no_callback(cb, true)
node.ligaturing(head, tail)
end
if after then
template.callback(cb, nil, after)
nodetree_print('head:' .. format.new_line())
tree.analyze_callback(head)
end
end,
---@function callbacks.kerning
---
---@param head Node # The head node of a node list.
---@param tail Node
---@param where string
kerning = function(head, tail, where)
local cb = 'kerning'
local before, after = template.get_print_position(where)
if before then
template.callback(cb, nil, before)
nodetree_print('head:' .. format.new_line())
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
orig_callbacks[cb](head, tail)
end
else
template.no_callback(cb, true)
node.kerning(head, tail)
end
if after then
template.callback(cb, nil, after)
nodetree_print('head:' .. format.new_line())
tree.analyze_callback(head)
end
end,
---@function callbacks.insert_local_par
---
---@param local_par Node
---@param location string
---@param where string
insert_local_par = function(local_par, location, where)
local cb = 'insert_local_par'
local before, after = template.get_print_position(where)
if before then
template.callback(cb, {location = location}, before)
tree.analyze_callback(local_par)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
orig_callbacks[cb](local_par, location)
end
else
template.no_callback(cb)
end
if after then
template.callback(cb, {location = location}, after)
tree.analyze_callback(local_par)
end
end,
---@function callbacks.mlist_to_hlist
---
---@param head Node # The head node of a node list.
---@param display_type string
---@param need_penalties boolean
---
---@return Node
mlist_to_hlist = function(head, display_type, need_penalties)
local cb = 'mlist_to_hlist'
local before, after = template.get_print_position(cb)
local retval
if before then
template.callback(cb, {display_type = display_type,
need_penalties = need_penalties}, before)
tree.analyze_callback(head)
end
if orig_callbacks[cb] then
if orig_callbacks[cb] ~= '' then
retval = orig_callbacks[cb](head, display_type, need_penalties)
end
else
template.no_callback(cb, true)
retval = node.mlist_to_hlist(head, display_type, need_penalties)
end
if after then
template.callback(cb, {display_type = display_type,
need_penalties = need_penalties}, after)
tree.analyze_callback(head)
end
return retval
end
}
-- The actual callback functions. The `*_before` and `*_after`
-- variants are needed for luatexbase. For 'exclusive' callbacks we
-- directly use the corresponding functions from the
-- `callback_wrappers` table.
local callbacks = {
contribute_filter = function(extrainfo)
callback_wrappers.contribute_filter(extrainfo, 'contribute_filter')
end,
contribute_filter_before = function(extrainfo)
callback_wrappers.contribute_filter(extrainfo, 'before')
end,
contribute_filter_after = function(extrainfo)
callback_wrappers.contribute_filter(extrainfo, 'after')
end,
buildpage_filter = function(extrainfo)
callback_wrappers.buildpage_filter(extrainfo, 'buildpage_filter')
end,
buildpage_filter_before = function(extrainfo)
callback_wrappers.buildpage_filter(extrainfo, 'before')
end,
buildpage_filter_after = function(extrainfo)
callback_wrappers.buildpage_filter(extrainfo, 'after')
end,
build_page_insert = callback_wrappers.build_page_insert,
pre_linebreak_filter = function(head, groupcode)
return callback_wrappers.pre_linebreak_filter(head, groupcode,
'pre_linebreak_filter')
end,
pre_linebreak_filter_before = function(head, groupcode)
return callback_wrappers.pre_linebreak_filter(head, groupcode, 'before')
end,
pre_linebreak_filter_after = function(head, groupcode)
return callback_wrappers.pre_linebreak_filter(head, groupcode, 'after')
end,
linebreak_filter = callback_wrappers.linebreak_filter,
append_to_vlist_filter = callback_wrappers.append_to_vlist_filter,
post_linebreak_filter = function(head, groupcode)
return callback_wrappers.post_linebreak_filter(head, groupcode,
'post_linebreak_filter')
end,
post_linebreak_filter_before = function(head, groupcode)
return callback_wrappers.post_linebreak_filter(head, groupcode, 'before')
end,
post_linebreak_filter_after = function(head, groupcode)
return callback_wrappers.post_linebreak_filter(head, groupcode, 'after')
end,
hpack_filter = function(head, groupcode, size, packtype,
direction, attributelist)
return callback_wrappers.hpack_filter(head, groupcode, size, packtype,
direction, attributelist,
'hpack_filter')
end,
hpack_filter_before = function(head, groupcode, size, packtype,
direction, attributelist)
return callback_wrappers.hpack_filter(head, groupcode, size, packtype,
direction, attributelist, 'before')
end,
hpack_filter_after = function(head, groupcode, size, packtype,
direction, attributelist)
return callback_wrappers.hpack_filter(head, groupcode, size, packtype,
direction, attributelist, 'after')
end,
vpack_filter = function(head, groupcode, size, packtype,
maxdepth, direction, attributelist)
return callback_wrappers.vpack_filter(head, groupcode, size, packtype,
maxdepth, direction, attributelist,
'vpack_filter')
end,
vpack_filter_before = function(head, groupcode, size, packtype,
maxdepth, direction, attributelist)
return callback_wrappers.vpack_filter(head, groupcode, size, packtype,
maxdepth, direction, attributelist,
'before')
end,
vpack_filter_after = function(head, groupcode, size, packtype,
maxdepth, direction, attributelist)
callback_wrappers.vpack_filter(head, groupcode, size, packtype,
maxdepth, direction, attributelist,
'after')
end,
hpack_quality = callback_wrappers.hpack_quality,
vpack_quality = callback_wrappers.vpack_quality,
process_rule = callback_wrappers.process_rule,
pre_output_filter = function(head, groupcode, size, packtype,
maxdepth, direction)
return callback_wrappers.pre_output_filter(head, groupcode, size,
packtype, maxdepth, direction,
'pre_output_filter')
end,
pre_output_filter_before = function(head, groupcode, size, packtype,
maxdepth, direction)
return callback_wrappers.pre_output_filter(head, groupcode, size,
packtype, maxdepth, direction,
'before')
end,
pre_output_filter_after = function(head, groupcode, size, packtype,
maxdepth, direction)
return callback_wrappers.pre_output_filter(head, groupcode, size,
packtype, maxdepth, direction,
'after')
end,
hyphenate = function(head, tail)
callback_wrappers.hyphenate(head, tail, 'hyphenate')
end,
hyphenate_before = function(head, tail)
callback_wrappers.hyphenate(head, tail, 'before')
end,
hyphenate_after = function(head, tail)
callback_wrappers.hyphenate(head, tail, 'after')
end,
ligaturing = function(head, tail)
callback_wrappers.ligaturing(head, tail, 'ligaturing')
end,
ligaturing_before = function(head, tail)
callback_wrappers.ligaturing(head, tail, 'before')
end,
ligaturing_after = function(head, tail)
callback_wrappers.ligaturing(head, tail, 'after')
end,
kerning = function(head, tail)
callback_wrappers.kerning(head, tail, 'kerning')
end,
kerning_before = function(head, tail)
callback_wrappers.kerning(head, tail, 'before')
end,
kerning_after = function(head, tail)
callback_wrappers.kerning(head, tail, 'after')
end,
insert_local_par = function(head, tail)
callback_wrappers.insert_local_par(head, tail, 'insert_local_par')
end,
insert_local_par_before = function(head, tail)
callback_wrappers.insert_local_par(head, tail, 'before')
end,
insert_local_par_after = function(head, tail)
callback_wrappers.insert_local_par(head, tail, 'after')
end,
mlist_to_hlist = callback_wrappers.mlist_to_hlist
}
--- Messages, options
---
---@section messages
--- 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`.
---
---@param why string # `'error'` or `'warning'`.
---@param where string # In which package the error happened.
---@param what string # The warning message to emit.
---@param help? string # Additional help text for errors.
local function message(why, where, what, help)
local msg
what = string.gsub(what, '\n', '\\MessageBreak ')
if why == 'error' then
if not help then
help = ''
end
msg = {
'\\ifx\\mbox\\undefined',
' \\errhelp{' .. help .. '}%',
' \\begingroup',
' \\newlinechar`\\^^J%',
' \\def\\MessageBreak{^^J(' .. where .. ')' .. string.rep('\\space', 16) .. '}%',
' \\errmessage{Package ' .. where .. ' Error: ' .. what .. '}%',
' \\endgroup',
'\\else',
' \\PackageError{' .. where .. '}{' .. what .. '}{' .. help .. '}%',
'\\fi'
}
else
msg = {
'\\ifx\\mbox\\undefined',
' \\begingroup',
' \\newlinechar`\\^^J%',
' \\def\\MessageBreak{^^J(' .. where .. ')' .. string.rep('\\space', 16) .. '}%',
' \\message{Package ' .. where .. ' Warning: ' .. what .. '}%',
' \\endgroup',
'\\else',
' \\PackageWarning{' .. where .. '}{' .. what .. '}%',
'\\fi'
}
end
if tex.escapechar == utf8.codepoint('@') then
table.insert(msg, 1, '@tex')
table.insert(msg, '@end tex')
end
tex.print(msg)
end
--- Set a single-option key-value pair.
---
---@param key string # The key of the option pair.
---@param value number|string # The value of the option pair.
local function set_option(key, value)
if not default_options[key] then
message(
'warning',
'nodetree',
"Ignoring unknown option '" .. key .. "'"
)
return
end
if not options then
options = {}
end
if key == 'verbosity' then
options[key] = tonumber(value) or default_options.verbosity
elseif key == 'decimalplaces' then
options[key] = tonumber(value) or default_options.decimalplaces
elseif key == 'firstline' then
options[key] = tonumber(value) or default_options.firstline
elseif key == 'lastline' then
options[key] = tonumber(value) or default_options.lastline
else
options[key] = value
end
end
--- Set multiple key-value option pairs using a table.
---
---@param opts table # Options.
local function set_options(opts)
if not options then
options = {}
end
for key, value in pairs(opts) do
set_option(key, value)
end
end
--- Callback management
---
---@section callback_management
---
---@param what? string|'before'|'after' # The name of a callback, or either the string `before` or `after`.
---
---@return 'before'|nil # 'before'` or `nil`.
---@return 'after'|nil # `'after'` or `nil`.
function template.get_print_position(what)
local before, after
if what == 'before' then
before = what
after = nil
elseif what == 'after' then
before = nil
after = what
else
before = print_positions[what][1]
after = print_positions[what][2]
end
return before, after
end
---
---@param name string
---@param internal? string|boolean
function template.no_callback(name, internal)
local more = ''
if internal == true then
more = ',' .. format.new_line() ..
' LuaTeX uses internal function instead'
end
nodetree_print(
format.new_line() ..
"<no registered function for '" ..
format.underscore(name) .. "' callback" .. more .. ">")
end
--- Check whether the given callback name exists.
---
---Throw an error if it doesn���t.
---
---@param callback_name string # The name of a callback to check.
---
---@return string # The unchanged input of the function.
local function check_callback_name(callback_name)
local info = callback.list()
if info[callback_name] == nil then
message(
'error',
'nodetree',
'Unknown callback name or callback alias\n'
.. "'" .. callback_name .. "'"
)
end
return callback_name
end
--- Get the real callback name from an alias string.
---
---@param alias string # The alias of a callback name or the callback name itself.
---
---@return string # The real callback name.
local function get_callback_name(alias)
local callback_name
if alias == 'contribute' or alias == 'contributefilter' then
callback_name = 'contribute_filter'
-- Formerly called buildpage, now there is a build_page_insert.
elseif alias == 'buildfilter' or alias == 'buildpagefilter' then
callback_name = 'buildpage_filter'
-- Untested: I don���t know how to invoke this filter.
elseif alias == 'buildinsert' or alias == 'buildpageinsert' then
callback_name = 'build_page_insert'
elseif alias == 'preline' or alias == 'prelinebreakfilter' then
callback_name = 'pre_linebreak_filter'
elseif alias == 'line' or alias == 'linebreakfilter' then
callback_name = 'linebreak_filter'
elseif alias == 'append' or alias == 'appendtovlistfilter' then
callback_name = 'append_to_vlist_filter'
elseif alias == 'postline' or alias == 'postlinebreak' or alias == 'postlinebreakfilter' then
callback_name = 'post_linebreak_filter'
elseif alias == 'hpack' or alias == 'hpackfilter' then
callback_name = 'hpack_filter'
elseif alias == 'vpack' or alias == 'vpackfilter' then
callback_name = 'vpack_filter'
elseif alias == 'hpackq' or alias == 'hpackquality' then
callback_name = 'hpack_quality'
elseif alias == 'vpackq' or alias == 'vpackquality' then
callback_name = 'vpack_quality'
elseif alias == 'process' or alias == 'processrule' then
callback_name = 'process_rule'
elseif alias == 'preout' or alias == 'preoutputfilter' then
callback_name = 'pre_output_filter'
elseif alias == 'hyph' or alias == 'hyphenate' then
callback_name = 'hyphenate'
elseif alias == 'liga' or alias == 'ligaturing' then
callback_name = 'ligaturing'
elseif alias == 'kern' or alias == 'kerning' then
callback_name = 'kerning'
elseif alias == 'insert' or alias == 'insertlocalpar' then
callback_name = 'insert_local_par'
elseif alias == 'mhlist' or alias == 'mlisttohlist' then
callback_name = 'mlist_to_hlist'
else
callback_name = alias
end
return check_callback_name(callback_name)
end
--- 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.
---
---@param cb string # The name of a callback.
local function register_callback(cb)
if luatexbase then
local descriptions = luatexbase.callback_descriptions(cb)
if #descriptions == 0 then
-- No callback installed. If there is no default action
-- (according to the LuaTeX manual), use only `before`, ignoring
-- the position requested by the user.
if not callback_has_default_action[cb] then
print_positions[cb] = { 'before', nil }
end
luatexbase.add_to_callback(cb, callbacks[cb], 'nodetree')
elseif luatexbase.callbacktypes[cb] == 3 then
-- A single, 'exclusive' callback.
orig_callbacks[cb], orig_descriptions[cb] =
luatexbase.remove_from_callback(cb, descriptions[1])
luatexbase.add_to_callback(cb, callbacks[cb], 'nodetree')
else
-- All other callback types.
local funcs = {}
local descr = {}
local before, after = template.get_print_position(cb)
-- XXX Is this correct for 'reverselist' callback type?
-- This makes the callback wrapper call neither the old nor the
-- new function.
orig_callbacks[cb] = ''
for i, description in ipairs(descriptions) do
funcs[i], descr[i] = luatexbase.remove_from_callback(cb, description)
end
if before then
luatexbase.add_to_callback(cb, callbacks[cb .. '_before'],
'nodetree before')
end
for i, _ in ipairs(funcs) do
luatexbase.add_to_callback(cb, funcs[i], descr[i])
end
if after then
luatexbase.add_to_callback(cb, callbacks[cb .. '_after'],
'nodetree after')
end
end
else
orig_callbacks[cb] = callback.find(cb)
callback.register(cb, callbacks[cb])
end
end
--- Unregister a callback.
---
--- We follow the same logic as with `register_callback`.
---
---@param cb string # The name of a callback.
local function unregister_callback(cb)
if luatexbase then
local descriptions = luatexbase.callback_descriptions(cb)
if #descriptions == 0 then
return
elseif #descriptions == 1 then
luatexbase.remove_from_callback(cb, 'nodetree')
if orig_callbacks[cb] then
luatexbase.add_to_callback(cb,
orig_callbacks[cb],
orig_descriptions[cb])
end
orig_callbacks[cb] = nil
orig_descriptions[cb] = nil
else
local funcs = {}
local descr = {}
local i = 1
for _, description in ipairs(descriptions) do
if description == 'nodetree before' or
description == 'nodetree after' then
luatexbase.remove_from_callback(cb, description)
else
funcs[i], descr[i] = luatexbase.remove_from_callback(cb,
description)
i = i + 1
end
end
for n, _ in ipairs(funcs) do
luatexbase.add_to_callback(cb, funcs[n], descr[n])
end
end
else
callback.register(cb, nil)
callback.register(cb, orig_callbacks[cb])
end
end
--- Exported functions.
---
---@section export
local export = {
set_option = set_option,
set_options = set_options,
---@function export.register_callbacks
register_callbacks = function()
if options.channel == 'log' or options.channel == 'tex' then
-- nt = nodetree
-- jobname.nttex
-- jobname.ntlog
local file_name = tex.jobname .. '.nt' .. options.channel
io.open(file_name, 'w'):close() -- Clear former content.
output_file = io.open(file_name, 'a')
end
-- Split string at ','.
for alias in string.gmatch(options.callback, '([^,]+)') do
-- Trim whitespace.
alias = string.gsub(alias, '^%s*(.-)%s*$', '%1')
-- Check where to position nodetree's inspection callback(s).
local before, after
if string.sub(alias, 1, 1) == ':' then
before = 'before'
alias = string.sub(alias, 2, -1)
end
if string.sub(alias, -1, -1) == ':' then
after = 'after'
alias = string.sub(alias, 1, -2)
end
if not before and not after then
before = 'before'
end
local name = get_callback_name(alias)
print_positions[name] = {before, after}
register_callback(name)
end
end,
---@function export.unregister_callbacks
unregister_callbacks = function()
for alias in string.gmatch(options.callback, '([^,]+)') do
-- Split string at ',', then trim whitespace. For symmetry with
-- `register_callbacks`, also remove a leading and/or trailing
-- ':' character.
unregister_callback(
get_callback_name(string.gsub(alias, '^%s*:?(.-):?%s*$', '%1'))
)
end
end,
--- 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.
--
---@function export.compile_include
--
---@param tex_markup string
compile_include = function(tex_markup)
-- Generate a subfolder for all tempory files: _nodetree-jobname.
local parent_path = lfs.currentdir() .. '/' .. '_nodetree-' .. tex.jobname
lfs.mkdir(parent_path)
-- Generate the temporary LuaTeX or LuaLaTeX file.
example_counter = example_counter + 1
local filename_tex = example_counter .. '.tex'
local absolute_path_tex = parent_path .. '/' .. filename_tex
output_file = io.open(absolute_path_tex, 'w')
local format_option = function(key, value)
return '\\NodetreeSetOption[' .. key .. ']{' .. value .. '}' .. '\n'
end
-- Process the options.
local option_lines =
format_option('channel', 'tex') ..
format_option('verbosity', options.verbosity) ..
format_option('unit', options.unit) ..
format_option('decimalplaces', options.decimalplaces) ..
'\\NodetreeUnregisterCallback{post_linebreak_filter}' .. '\n' ..
'\\NodetreeRegisterCallback{' .. options.callback .. '}'
local prefix = '%!TEX program = lualatex\n' ..
'\\documentclass{article}\n' ..
'\\usepackage{nodetree}\n' ..
option_lines .. '\n' ..
'\\begin{document}\n'
local suffix = '\n\\end{document}'
if output_file ~= nil then
output_file:write(prefix .. tex_markup .. suffix)
output_file:close()
end
-- Compile the temporary LuaTeX or LuaLaTeX file.
os.spawn({ 'latexmk', '-cd', '-pdflua', absolute_path_tex })
local include_file = assert(io.open(parent_path .. '/' .. example_counter .. '.nttex', 'r'))
local include_content = include_file:read('*all')
include_file:close()
-- To make the newline character be handled properly by the TeX engine
-- it would be necessary to set up its correct catcode. However, it is
-- simpler to just replace all newlines with '{}'.
include_content = include_content:gsub('[\r\n]', '{}')
tex.print(include_content)
end,
--- Check for `\--shell-escape` within a command or environment.
---
---@function export.check_shell_escape
---
---@param what string # The name of the command or environment.
---@param is_command boolean # Set if `what` is a command.
check_shell_escape = function(what, is_command)
local info = status.list()
if info ~= nil and info.shell_escape ~= 1 then
local typ, stuff
if is_command == true then
typ = 'command'
stuff = 'argument'
else
typ = 'environment'
stuff = 'contents'
end
message(
'error',
'nodetree-embed',
what .. ' needs option --shell-escape',
"You must process this document with 'lualatex --shell-escape ...'\n"
.. "so that 'latexmk' can be executed to generate the nodetree view\n"
.. 'for the ' .. stuff .. ' of this ' .. typ .. '.'
)
end
end,
--- Print a node tree.
---
---@function export.print
---
---@param head Node # The head node of a node list.
---@param opts table # Options as a table.
print = function(head, opts)
if opts and type(opts) == 'table' then
set_options(opts)
end
nodetree_print(format.new_line())
tree.analyze_list(head, 1)
end,
--- Format a scaled point value as a formatted string.
--
---@function export.format_dim
---
---@param sp number # A scaled point value.
--
---@return string
format_dim = function(sp)
return template.length(sp)
end,
--- Get a default option that is not changed.
---
---@function export.get_default_option
---
---@param key string # The key of the option.
--
---@return string|number|boolean
get_default_option = function(key)
return default_options[key]
end,
--- Push current options.
---
---@function export.push_options
push_options = function()
prev_options[option_level] = {}
for k, v in pairs(options) do
prev_options[option_level][k] = v
end
option_level = option_level + 1
end,
--- Pop previous options.
---
---@function export.pop_options
pop_options = function()
if option_level > 0 then
prev_options[option_level] = nil
option_level = option_level - 1
for k, v in pairs(prev_options[option_level]) do
options[k] = v
end
end
end,
--- Read a LaTeX input file and emit it immediately, obeying options
--- `firstline` and `lastline`.
---
---@function export.input
---
---@param filename string
input = function(filename)
local file = assert(io.open(filename, 'r'))
local lines_in = {}
for line in file:lines() do
table.insert(lines_in, line)
end
local firstline = options.firstline
local lastline = options.lastline
-- Handle negative line numbers.
if firstline < 0 then
firstline = #lines_in + 1 + firstline
elseif firstline == 0 then
firstline = 1
end
if lastline < 0 then
lastline = #lines_in + 1 + lastline
elseif lastline == 0 then
lastline = 1
end
-- Clamp values.
if firstline < 1 then
firstline = 1
elseif firstline > #lines_in then
firstline = #lines_in
end
if lastline < 1 then
lastline = 1
elseif lastline > #lines_in then
lastline = #lines_in
end
if firstline > lastline then
local tmp = firstline
firstline = lastline
lastline = tmp
end
local lines_out = {}
for i, line in ipairs(lines_in) do
if firstline <= i and i <= lastline then
table.insert(lines_out, line)
end
end
tex.print(lines_out)
end
}
--- Set to `export.print`.
export.analyze = export.print
return export