diff options
Diffstat (limited to 'doc/context/sources/general/manuals/luatex/luatex-nodes.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/luatex/luatex-nodes.tex | 1915 |
1 files changed, 0 insertions, 1915 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex deleted file mode 100644 index 8d32ab287..000000000 --- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex +++ /dev/null @@ -1,1915 +0,0 @@ -% language=uk - -\environment luatex-style -\environment luatex-logos - -\startcomponent luatex-nodes - -\startchapter[reference=nodes,title={Nodes}] - -\section{\LUA\ node representation} - -\TEX's nodes are represented in \LUA\ as userdata object with a variable set of -fields. In the following syntax tables, such the type of such a userdata object -is represented as \syntax {<node>}. - -The current return value of \type {node.types()} is: -\startluacode - for id, name in table.sortedhash(node.types()) do - context.type(name) - context(" (%s), ",id) - end - context.removeunwantedspaces() - context.removepunctuation() -\stopluacode -. % period - -The \type {\lastnodetype} primitive is \ETEX\ compliant. The valid range is still -$[-1,15]$ and glyph nodes (formerly known as char nodes) have number~0 while -ligature nodes are mapped to~7. That way macro packages can use the same symbolic -names as in traditional \ETEX. Keep in mind that these \ETEX\ node numbers are -different from the real internal ones and that there are more \ETEX\ node types -than~15. - -You can ask for a list of fields with the \type {node.fields} (which takes an id) -and for valid subtypes with \type {node.subtypes} (which takes a string because -eventually we might support more used enumerations). - -\subsection{Attributes} - -The newly introduced attribute registers are non|-|trivial, because the value -that is attached to a node is essentially a sparse array of key|-|value pairs. It -is generally easiest to deal with attribute lists and attributes by using the -dedicated functions in the \type {node} library, but for completeness, here is -the low|-|level interface. - -\subsubsection{attribute_list nodes} - -An \type {attribute_list} item is used as a head pointer for a list of attribute -items. It has only one user-visible field: - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC node \NC pointer to the first attribute \NC \NR -\stoptabulate - -\subsubsection{attribute nodes} - -A normal node's attribute field will point to an item of type \type -{attribute_list}, and the \type {next} field in that item will point to the first -defined \quote {attribute} item, whose \type {next} will point to the second -\quote {attribute} item, etc. - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC node \NC pointer to the next attribute \NC \NR -\NC number \NC number \NC the attribute type id \NC \NR -\NC value \NC number \NC the attribute value \NC \NR -\stoptabulate - -As mentioned it's better to use the official helpers rather than edit these -fields directly. For instance the \type {prev} field is used for other purposes -and there is no double linked list. - -\subsection{Main text nodes} - -These are the nodes that comprise actual typesetting commands. A few fields are -present in all nodes regardless of their type, these are: - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC node \NC the next node in a list, or nil \NC \NR -\NC id \NC number \NC the node's type (\type {id}) number \NC \NR -\NC subtype \NC number \NC the node \type {subtype} identifier \NC \NR -\stoptabulate - -The \type {subtype} is sometimes just a stub entry. Not all nodes actually use -the \type {subtype}, but this way you can be sure that all nodes accept it as a -valid field name, and that is often handy in node list traversal. In the -following tables \type {next} and \type {id} are not explicitly mentioned. - -Besides these three fields, almost all nodes also have an \type {attr} field, and -there is a also a field called \type {prev}. That last field is always present, -but only initialized on explicit request: when the function \type {node.slide()} -is called, it will set up the \type {prev} fields to be a backwards pointer in -the argument node list. By now most of \TEX's node processing makes sure that the -\type {prev} nodes are valid but there can be exceptions, especially when the -internal magic uses a leading \type {temp} nodes to temporarily store a state. - -\subsubsection{hlist nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{list} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width of the box \NC \NR -\NC height \NC number \NC the height of the box \NC \NR -\NC depth \NC number \NC the depth of the box \NC \NR -\NC shift \NC number \NC a displacement perpendicular to the character progression direction \NC \NR -\NC glue_order \NC number \NC a number in the range $[0,4]$, indicating the glue order \NC \NR -\NC glue_set \NC number \NC the calculated glue ratio \NC \NR -\NC glue_sign \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 = \type {shrinking} \NC \NR -\NC head/list \NC node \NC the first node of the body of this list \NC \NR -\NC dir \NC string \NC the direction of this box, see~\in[dirnodes] \NC \NR -\stoptabulate - -A warning: never assign a node list to the \type {head} field unless you are sure -its internal link structure is correct, otherwise an error may result. - -Note: the field name \type {head} and \type {list} are both valid. Sometimes it -makes more sense to refer to a list by \type {head}, sometimes \type {list} makes -more sense. - -\subsubsection{vlist nodes} - -This node is similar to \type {hlist}, except that \quote {shift} is a displacement -perpendicular to the line progression direction, and \quote {subtype} only has -the values 0, 4, and~5. - -\subsubsection{rule nodes} - -Contrary to traditional \TEX, \LUATEX\ has more subtypes because we also use -rules to store reuseable objects and images. User nodes are invisible and can be -intercepted by a callback. - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{rule} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width of the rule where the special value $-1073741824$ is used for \quote {running} glue dimensions \NC \NR -\NC height \NC number \NC the height of the rule (can be negative) \NC \NR -\NC depth \NC number \NC the depth of the rule (can be negative) \NC \NR -\NC dir \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR -\NC index \NC number \NC an optional index that can be referred to \NC \NR -\stoptabulate - -\subsubsection{ins nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC the insertion class \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC cost \NC number \NC the penalty associated with this insert \NC \NR -\NC height \NC number \NC height of the insert \NC \NR -\NC depth \NC number \NC depth of the insert \NC \NR -\NC head/list \NC node \NC the first node of the body of this insert \NC \NR -\stoptabulate - -There is a set of extra fields that concern the associated glue: \type {width}, -\type {stretch}, \type {stretch_order}, \type {shrink} and \type {shrink_order}. -These are all numbers. - -A warning: never assign a node list to the \type {head} field unless you are sure -its internal link structure is correct, otherwise an error may be result. You can use -\type {list} instead (often in functions you want to use local variable swith similar -names and both names are equally sensible). - -\subsubsection{mark nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC unused \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC class \NC number \NC the mark class \NC \NR -\NC mark \NC table \NC a table representing a token list \NC \NR -\stoptabulate - -\subsubsection{adjust nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{adjust} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC head/list \NC node \NC adjusted material \NC \NR -\stoptabulate - -A warning: never assign a node list to the \type {head} field unless you are sure -its internal link structure is correct, otherwise an error may be result. - -\subsubsection{disc nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{disc} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC pre \NC node \NC pointer to the pre|-|break text \NC \NR -\NC post \NC node \NC pointer to the post|-|break text \NC \NR -\NC replace \NC node \NC pointer to the no|-|break text \NC \NR -\NC penalty \NC number \NC the penalty associated with the break, normally \type {\hyphenpenalty} or \type {\exhyphenpenalty} \NC \NR -\stoptabulate - -The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given -elsewhere. - -These disc nodes are kind of special as at some point they also keep information -about breakpoints and nested ligatures. The \type {pre}, \type {post} and \type -{replace} fields at the \LUA\ end are in fact indirectly accessed and have a -\type {prev} pointer that is not \type {nil}. This means that when you mess -around with the head of these (three) lists, you also need to reassign them -because that will restore the proper \type {prev} pointer, so: - -\starttyping -pre = d.pre --- change the list starting with pre -d.pre = pre -\stoptyping - -Otherwise you can end up with an invalid internal perception of reality and -\LUATEX\ might even decide to crash on you. It also means that running forward -over for instance \type {pre} is ok but backward you need to stop at \type {pre}. -And you definitely must not mess with the node that \type {prev} points to, if -only because it is not really an node but part of the disc data structure (so -freeing it again might crash \LUATEX). - -\subsubsection{math nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{math} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC surround \NC number \NC width of the \type {\mathsurround} kern \NC \NR -\stoptabulate - -There is a set of extra fields that concern the associated glue: \type {width}, -\type {stretch}, \type {stretch_order}, \type {shrink} and \type {shrink_order}. -These are all numbers. - -\subsubsection{glue nodes} - -Skips are about the only type of data objects in traditional \TEX\ that are not a -simple value. The structure that represents the glue components of a skip is -called a \type {glue_spec}, and it has the following accessible fields: - -\starttabulate[|lT|l|p|] -\NC \rmbf key \NC \bf type \NC \bf explanation \NC \NR -\NC width \NC number \NC the horizontal or vertical displacement \NC \NR -\NC stretch \NC number \NC extra (positive) displacement or stretch amount \NC \NR -\NC stretch_order \NC number \NC factor applied to stretch amount \NC \NR -\NC shrink \NC number \NC extra (negative) displacement or shrink amount\NC \NR -\NC shrink_order \NC number \NC factor applied to shrink amount \NC \NR -\stoptabulate - -The effective width of some glue subtypes depends on the stretch or shrink needed -to make the encapsulating box fit its dimensions. For instance, in a paragraph -lines normally have glue representing spaces and these stretch of shrink to make -the content fit in the available space. The \type {effective_glue} function that -takes a glue node and a parent (hlist or vlist) returns the effective width of -that glue item. - -A gluespec node is a special kind of node that is used for storing a set of glue -values in registers. Originally they were also used to store properties of glue -nodes (using a system of reference counts) but we now keep these properties in -the glue nodes themselves, which gives a cleaner interface to \LUA. - -The indirect spec approach was in fact an optimization in the original \TEX\ -code. First of all it can save quite some memory because all these spaces that -become glue now share the same specification (only the reference count is -incremented), and zero testing is also a bit faster because only the pointer has -to be checked (this is no longer true for engines that implement for instance -protrusion where we really need to ensure that zero is zero when we test for -bounds). Another side effect is that glue specifications are read|-|only, so in -the end copies need to be made when they are used from \LUA\ (each assignment to -a field can result in a new copy). So in the end the advantages of sharing are -not that high (and nowadays memory is less an issue, also given that a glue node -is only a few memory words larger than a spec). - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{glue} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC leader \NC node \NC pointer to a box or rule for leaders \NC \NR -\stoptabulate - -In addition there are the \type {width}, \type {stretch} \type {stretch_order}, -\type {shrink}, and \type {shrink_order} fields. Note that we use the key \type -{width} in both horizontal and vertical glue. This suits the \TEX\ internals well -so we decided to stick to that naming. - -A regular word space also results in a \type {spaceskip} subtype (this used to be -a \type {userskip} with subtype zero). - -\subsubsection{kern nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{kern} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC kern \NC number \NC fixed horizontal or vertical advance \NC \NR -\stoptabulate - -\subsubsection{penalty nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC not used \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC penalty \NC number \NC the penalty value \NC \NR -\stoptabulate - -\subsubsection[glyphnodes]{glyph nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \rmbf type \NC \rmbf explanation \NC \NR -\NC subtype \NC number \NC bitfield \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC char \NC number \NC the chatacter index in the font \NC \NR -\NC font \NC number \NC the font identifier \NC \NR -\NC lang \NC number \NC the language identifier \NC \NR -\NC left \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR -\NC right \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR -\NC uchyph \NC boolean \NC the frozen \type {\uchyph} value \NC \NR -\NC components \NC node \NC pointer to ligature components \NC \NR -\NC xoffset \NC number \NC a virtual displacement in horizontal direction \NC \NR -\NC yoffset \NC number \NC a virtual displacement in vertical direction \NC \NR -\NC xadvance \NC number \NC an additional advance after the glyph (experimental) \NC \NR -\NC width \NC number \NC the (original) width of the character \NC \NR -\NC height \NC number \NC the (original) height of the character\NC \NR -\NC depth \NC number \NC the (original) depth of the character\NC \NR -\NC expansion_factor \NC number \NC the to be applied expansion_factor \NC \NR -\stoptabulate - -The \type {width}, \type {height} and \type {depth} values are read|-|only. The -\type {expansion_factor} is assigned in the parbuilder and used in the backend. - -A warning: never assign a node list to the components field unless you are sure -its internal link structure is correct, otherwise an error may be result. Valid -bits for the \type {subtype} field are: - -\starttabulate[|c|l|] -\NC \rmbf bit \NC \bf meaning \NC \NR -\NC 0 \NC character \NC \NR -\NC 1 \NC ligature \NC \NR -\NC 2 \NC ghost \NC \NR -\NC 3 \NC left \NC \NR -\NC 4 \NC right \NC \NR -\stoptabulate - -See \in {section} [charsandglyphs] for a detailed description of the \type -{subtype} field. - -The \type {expansion_factor} has been introduced as part of the separation -between font- and backend. It is the result of extensive experiments with a more -efficient implementation of expansion. Early versions of \LUATEX\ already -replaced multiple instances of fonts in the backend by scaling but contrary to -\PDFTEX\ in \LUATEX\ we now also got rid of font copies in the frontend and -replaced them by expansion factors that travel with glyph nodes. Apart from a -cleaner approach this is also a step towards a better separation between front- -and backend. - -The \type {is_char} function checks if a node is a glyph node with a subtype still -less than 256. This function can be used to determine if applying font logic to a -glyph node makes sense. The value \type {nil} gets returned when the node is not -a glyph, a character number is returned if the node is still tagged as character -and \type {false} gets returned otherwise. When nil is returned, the id is also -returned. The \type {is_glyph} variant doesn't check for a subtype being less -than 256, so it returns either the character value or nil plus the id. These -helpers are not always faster than separate calls but they sometimes permit -making more readable tests. - -\subsubsection{boundary nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{boundary} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC value \NC number \NC values 0--255 are reserved \NC \NR -\stoptabulate - -This node relates to the \type {\noboundary}, \type {\boundary}, \type -{\protrusionboundary} and \type {\wordboundary} primitives. - -\subsubsection{local_par nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC pen_inter \NC number \NC local interline penalty (from \type {\localinterlinepenalty}) \NC \NR -\NC pen_broken \NC number \NC local broken penalty (from \type {\localbrokenpenalty}) \NC \NR -\NC dir \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR -\NC box_left \NC node \NC the \type {\localleftbox} \NC \NR -\NC box_left_width \NC number \NC width of the \type {\localleftbox} \NC \NR -\NC box_right \NC node \NC the \type {\localrightbox} \NC \NR -\NC box_right_width \NC number \NC width of the \type {\localrightbox} \NC \NR -\stoptabulate - -A warning: never assign a node list to the \type {box_left} or \type {box_right} -field unless you are sure its internal link structure is correct, otherwise an -error may be result. - -\subsubsection[dirnodes]{dir nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC dir \NC string \NC the direction (but see below) \NC \NR -\NC level \NC number \NC nesting level of this direction whatsit \NC \NR -\stoptabulate - -A note on \type {dir} strings. Direction specifiers are three|-|letter -combinations of \type {T}, \type {B}, \type {R}, and \type {L}. - -These are built up out of three separate items: - -\startitemize[packed] -\startitem - the first is the direction of the \quote{top} of paragraphs. -\stopitem -\startitem - the second is the direction of the \quote{start} of lines. -\stopitem -\startitem - the third is the direction of the \quote{top} of glyphs. -\stopitem -\stopitemize - -However, only four combinations are accepted: \type {TLT}, \type {TRT}, \type -{RTT}, and \type {LTL}. - -Inside actual \type {dir} whatsit nodes, the representation of \type {dir} is not -a three-letter but a four|-|letter combination. The first character in this case -is always either \type {+} or \type {-}, indicating whether the value is pushed -or popped from the direction stack. - -\subsubsection{margin_kern nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{margin_kern} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the advance of the kern \NC \NR -\NC glyph \NC node \NC the glyph to be used \NC \NR -\stoptabulate - -\subsection{Math nodes} - -These are the so||called \quote {noad}s and the nodes that are specifically -associated with math processing. Most of these nodes contain subnodes so that the -list of possible fields is actually quite small. First, the subnodes: - -\subsubsection{Math kernel subnodes} - -Many object fields in math mode are either simple characters in a specific family -or math lists or node lists. There are four associated subnodes that represent -these cases (in the following node descriptions these are indicated by the word -\type {<kernel>}). - -The \type {next} and \type {prev} fields for these subnodes are unused. - -\subsubsubsection{math_char and math_text_char subnodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC char \NC number \NC the character index \NC \NR -\NC fam \NC number \NC the family number \NC \NR -\stoptabulate - -The \type {math_char} is the simplest subnode field, it contains the character -and family for a single glyph object. The \type {math_text_char} is a special -case that you will not normally encounter, it arises temporarily during math list -conversion (its sole function is to suppress a following italic correction). - -\subsubsubsection{sub_box and sub_mlist subnodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC head/list \NC node \NC list of nodes \NC \NR -\stoptabulate - -These two subnode types are used for subsidiary list items. For \type {sub_box}, -the \type {head} points to a \quote {normal} vbox or hbox. For \type {sub_mlist}, -the \type {head} points to a math list that is yet to be converted. - -A warning: never assign a node list to the \type {head} field unless you are sure -its internal link structure is correct, otherwise an error may be result. - -\subsubsection{Math delimiter subnode} - -There is a fifth subnode type that is used exclusively for delimiter fields. As -before, the \type {next} and \type {prev} fields are unused. - -\subsubsubsection{delim subnodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC small_char \NC number \NC character index of base character \NC \NR -\NC small_fam \NC number \NC family number of base character \NC \NR -\NC large_char \NC number \NC character index of next larger character \NC \NR -\NC large_fam \NC number \NC family number of next larger character \NC \NR -\stoptabulate - -The fields \type {large_char} and \type {large_fam} can be zero, in that case the -font that is sed for the \type {small_fam} is expected to provide the large -version as an extension to the \type {small_char}. - -\subsubsection{Math core nodes} - -First, there are the objects (the \TEX book calls then \quote {atoms}) that are -associated with the simple math objects: ord, op, bin, rel, open, close, punct, -inner, over, under, vcent. These all have the same fields, and they are combined -into a single node type with separate subtypes for differentiation. - -\subsubsubsection{simple nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{noad} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC nucleus \NC kernel node \NC base \NC \NR -\NC sub \NC kernel node \NC subscript \NC \NR -\NC sup \NC kernel node \NC superscript \NC \NR -\stoptabulate - -\subsubsubsection{accent nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{accent} \NC \NR -\NC nucleus \NC kernel node \NC base \NC \NR -\NC sub \NC kernel node \NC subscript \NC \NR -\NC sup \NC kernel node \NC superscript \NC \NR -\NC accent \NC kernel node \NC top accent \NC \NR -\NC bot_accent \NC kernel node \NC bottom accent \NC \NR -\stoptabulate - -\subsubsubsection{style nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC style \NC string \NC contains the style \NC \NR -\stoptabulate - -There are eight possibilities for the string value: one of \quote {display}, -\quote {text}, \quote {script}, or \quote {scriptscript}. Each of these can have -a trailing \type {'} to signify \quote {cramped} styles. - -\subsubsubsection{choice nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC display \NC node \NC list of display size alternatives \NC \NR -\NC text \NC node \NC list of text size alternatives \NC \NR -\NC script \NC node \NC list of scriptsize alternatives \NC \NR -\NC scriptscript \NC node \NC list of scriptscriptsize alternatives \NC \NR -\stoptabulate - -A warning: never assign a node list to the display, text, script, or -scriptscript field unless you are sure its internal link structure is -correct, otherwise an error may be result. - -\subsubsubsection{radical nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{radical} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC nucleus \NC kernel node \NC base \NC \NR -\NC sub \NC kernel node \NC subscript \NC \NR -\NC sup \NC kernel node \NC superscript \NC \NR -\NC left \NC delimiter node \NC \NC \NR -\NC degree \NC kernel node \NC only set by \type {\Uroot} \NC \NR -\stoptabulate - -A warning: never assign a node list to the nucleus, sub, sup, left, or degree -field unless you are sure its internal link structure is correct, otherwise an -error may be result. - -\subsubsubsection{fraction nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC (optional) width of the fraction \NC \NR -\NC num \NC kernel node \NC numerator \NC \NR -\NC denom \NC kernel node \NC denominator \NC \NR -\NC left \NC delimiter node \NC left side symbol \NC \NR -\NC right \NC delimiter node \NC right side symbol\NC \NR -\stoptabulate - -A warning: never assign a node list to the num, or denom field unless you are -sure its internal link structure is correct, otherwise an error may be result. - -\subsubsubsection{fence nodes} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{fence} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC delim \NC delimiter node \NC delimiter specification \NC \NR -\stoptabulate - -\subsection{whatsit nodes} - -Whatsit nodes come in many subtypes that you can ask for by running -\type {node.whatsits()}: -\startluacode - for id, name in table.sortedpairs(node.whatsits()) do - context.type(name) - context(" (%s), ",id) - end - context.removeunwantedspaces() - context.removepunctuation() -\stopluacode -. % period - -\subsubsection{front|-|end whatsits} - -\subsubsubsection{open whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR -\NC name \NC string \NC file name \NC \NR -\NC ext \NC string \NC file extension \NC \NR -\NC area \NC string \NC file area (this may become obsolete) \NC \NR -\stoptabulate - -\subsubsubsection{write whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR -\NC data \NC table \NC a table representing the token list to be written \NC \NR -\stoptabulate - -\subsubsubsection{close whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR -\stoptabulate - -\subsubsubsection{user_defined whatsits} - -User|-|defined whatsit nodes can only be created and handled from \LUA\ code. In -effect, they are an extension to the extension mechanism. The \LUATEX\ engine -will simply step over such whatsits without ever looking at the contents. - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC user_id \NC number \NC id number \NC \NR -\NC type \NC number \NC type of the value \NC \NR -\NC value \NC number \NC a \LUA\ number \NC \NR -\NC \NC node \NC a node list \NC \NR -\NC \NC string \NC a \LUA\ string \NC \NR -\NC \NC table \NC a \LUA\ table \NC \NR -\stoptabulate - -The \type {type} can have one of six distinct values. The number is the \ASCII\ -value if the first character if the type name (so you can use string.byte("l") -instead of \type {108}). - -\starttabulate[|lT|lT|p|] -\NC \rmbf value \NC \bf meaning \NC \bf explanation \NC \NR -\NC 97 \NC a \NC list of attributes (a node list) \NC \NR -\NC 100 \NC d \NC a \LUA\ number \NC \NR -\NC 108 \NC l \NC a \LUA\ value (table, number, boolean, etc) \NC \NR -\NC 110 \NC n \NC a node list \NC \NR -\NC 115 \NC s \NC a \LUA\ string \NC \NR -\NC 116 \NC t \NC a \LUA\ token list in \LUA\ table form (a list of triplets) \NC \NR -\stoptabulate - -\subsubsubsection{save_pos whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\stoptabulate - -\subsubsubsection{late_lua whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC data \NC string \NC data to execute \NC \NR -\NC string \NC string \NC data to execute \NC \NR -\NC name \NC string \NC the name to use for \LUA\ error reporting \NC \NR -\stoptabulate - -The difference between \type {data} and \type {string} is that on assignment, the -\type {data} field is converted to a token list, cf. use as \type {\latelua}. The -\type {string} version is treated as a literal string. - -\subsubsection{\DVI\ backend whatsits} - -\subsubsection{special whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC data \NC string \NC the \type {\special} information \NC \NR -\stoptabulate - -\subsubsection{\PDF\ backend whatsits} - -\subsubsubsection{pdf_literal whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC mode \NC number \NC the \quote {mode} setting of this literal \NC \NR -\NC data \NC string \NC the \type {\pdfliteral} information \NC \NR -\stoptabulate - -Possible mode values are: - -\starttabulate[|lT|p|] -\NC \rmbf value \NC \rmbf \PDFTEX\ keyword \NC \NR -\NC 0 \NC setorigin \NC \NR -\NC 1 \NC page \NC \NR -\NC 2 \NC direct \NC \NR -\stoptabulate - -\subsubsubsection{pdf_refobj whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR -\stoptabulate - -\subsubsubsection{pdf_annot whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR -\NC data \NC string \NC the annotation data \NC \NR -\stoptabulate - -\subsubsubsection{pdf_start_link whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR -\NC link_attr \NC table \NC the link attribute token list \NC \NR -\NC action \NC node \NC the action to perform \NC \NR -\stoptabulate - -\subsubsubsection{pdf_end_link whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC \NC \NR -\stoptabulate - -\subsubsubsection{pdf_dest whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC named_id \NC number \NC is the \type {dest_id} a string value? \NC \NR -\NC dest_id \NC number \NC the destination id \NC \NR -\NC \NC string \NC the destination name \NC \NR -\NC dest_type \NC number \NC type of destination \NC \NR -\NC xyz_zoom \NC number \NC the zoom factor (times 1000) \NC \NR -\NC objnum \NC number \NC the \PDF\ object number \NC \NR -\stoptabulate - -\subsubsubsection{pdf_action whatsits} - -These are a special kind of item that only appears inside \PDF\ start link -objects. - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC action_type \NC number \NC the kind of action involved \NC \NR -\NC action_id \NC number or string \NC token list reference or string \NC \NR -\NC named_id \NC number \NC the index of the destination \NC \NR -\NC file \NC string \NC the target filename \NC \NR -\NC new_window \NC number \NC the window state of the target \NC \NR -\NC data \NC string \NC the name of the destination \NC \NR -\stoptabulate - -Valid action types are: - -\starttabulate[|lT|lT|] -\NC 0 \NC page \NC \NR -\NC 1 \NC goto \NC \NR -\NC 2 \NC thread \NC \NR -\NC 3 \NC user \NC \NR -\stoptabulate - -Valid window types are: - -\starttabulate[|lT|lT|] -\NC 0 \NC notset \NC \NR -\NC 1 \NC new \NC \NR -\NC 2 \NC nonew \NC \NR -\stoptabulate - -\subsubsubsection{pdf_thread whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC named_id \NC number \NC is \type {tread_id} a string value? \NC \NR -\NC tread_id \NC number \NC the thread id \NC \NR -\NC \NC string \NC the thread name \NC \NR -\NC thread_attr \NC number \NC extra thread information \NC \NR -\stoptabulate - -\subsubsubsection{pdf_start_thread whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC named_id \NC number \NC is \type {tread_id} a string value? \NC \NR -\NC tread_id \NC number \NC the thread id \NC \NR -\NC \NC string \NC the thread name \NC \NR -\NC thread_attr \NC number \NC extra thread information \NC \NR -\stoptabulate - -\subsubsubsection{pdf_end_thread whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC \NC \NR -\stoptabulate - -\subsubsubsection{pdf_colorstack whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC stack \NC number \NC colorstack id number \NC \NR -\NC command \NC number \NC command to execute \NC \NR -\NC data \NC string \NC data \NC \NR -\stoptabulate - -\subsubsubsection{pdf_setmatrix whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC data \NC string \NC data \NC \NR -\stoptabulate - -\subsubsubsection{pdf_save whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\stoptabulate - -\subsubsubsection{pdf_restore whatsits} - -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\stoptabulate - -\section{The \type {node} library} - -The \type {node} library contains functions that facilitate dealing with (lists -of) nodes and their values. They allow you to create, alter, copy, delete, and -insert \LUATEX\ node objects, the core objects within the typesetter. - -\LUATEX\ nodes are represented in \LUA\ as userdata with the metadata type -\type {luatex.node}. The various parts within a node can be accessed using -named fields. - -Each node has at least the three fields \type {next}, \type {id}, and \type -{subtype}: - -\startitemize[intro] - -\startitem - The \type {next} field returns the userdata object for the next node in a - linked list of nodes, or \type {nil}, if there is no next node. -\stopitem - -\startitem - The \type {id} indicates \TEX's \quote{node type}. The field \type {id} has a - numeric value for efficiency reasons, but some of the library functions also - accept a string value instead of \type {id}. -\stopitem - -\startitem - The \type {subtype} is another number. It often gives further information - about a node of a particular \type {id}, but it is most important when - dealing with \quote {whatsits}, because they are differentiated solely based - on their \type {subtype}. -\stopitem - -\stopitemize - -The other available fields depend on the \type {id} (and for \quote {whatsits}, -the \type {subtype}) of the node. Further details on the various fields and their -meanings are given in~\in{chapter}[nodes]. - -Support for \type {unset} (alignment) nodes is partial: they can be queried and -modified from \LUA\ code, but not created. - -Nodes can be compared to each other, but: you are actually comparing indices into -the node memory. This means that equality tests can only be trusted under very -limited conditions. It will not work correctly in any situation where one of the -two nodes has been freed and|/|or reallocated: in that case, there will be false -positives. - -At the moment, memory management of nodes should still be done explicitly by the -user. Nodes are not \quote {seen} by the \LUA\ garbage collector, so you have to -call the node freeing functions yourself when you are no longer in need of a node -(list). Nodes form linked lists without reference counting, so you have to be -careful that when control returns back to \LUATEX\ itself, you have not deleted -nodes that are still referenced from a \type {next} pointer elsewhere, and that -you did not create nodes that are referenced more than once. - -There are statistics available with regards to the allocated node memory, which -can be handy for tracing. - -\subsection{Node handling functions} - -\subsubsection{\type {node.is_node}} - -\startfunctioncall -<boolean> t = - node.is_node(<any> item) -\stopfunctioncall - -This function returns true if the argument is a userdata object of -type \type {<node>}. - -\subsubsection{\type {node.types}} - -\startfunctioncall -<table> t = - node.types() -\stopfunctioncall - -This function returns an array that maps node id numbers to node type strings, -providing an overview of the possible top|-|level \type {id} types. - -\subsubsection{\type {node.whatsits}} - -\startfunctioncall -<table> t = - node.whatsits() -\stopfunctioncall - -\TEX's \quote{whatsits} all have the same \type {id}. The various subtypes are -defined by their \type {subtype} fields. The function is much like \type -{node.types}, except that it provides an array of \type {subtype} mappings. - -\subsubsection{\type {node.id}} - -\startfunctioncall -<number> id = - node.id(<string> type) -\stopfunctioncall - -This converts a single type name to its internal numeric representation. - -\subsubsection{\type {node.subtype}} - -\startfunctioncall -<number> subtype = - node.subtype(<string> type) -\stopfunctioncall - -This converts a single whatsit name to its internal numeric representation (\type -{subtype}). - -\subsubsection{\type {node.type}} - -\startfunctioncall -<string> type = - node.type(<any> n) -\stopfunctioncall - -In the argument is a number, then this function converts an internal numeric -representation to an external string representation. Otherwise, it will return -the string \type {node} if the object represents a node, and \type {nil} -otherwise. - -\subsubsection{\type {node.fields}} - -\startfunctioncall -<table> t = - node.fields(<number> id) -<table> t = - node.fields(<number> id, <number> subtype) -\stopfunctioncall - -This function returns an array of valid field names for a particular type of -node. If you want to get the valid fields for a \quote {whatsit}, you have to -supply the second argument also. In other cases, any given second argument will -be silently ignored. - -This function accepts string \type {id} and \type {subtype} values as well. - -\subsubsection{\type {node.has_field}} - -\startfunctioncall -<boolean> t = - node.has_field(<node> n, <string> field) -\stopfunctioncall - -This function returns a boolean that is only true if \type {n} is -actually a node, and it has the field. - -\subsubsection{\type {node.new}} - -\startfunctioncall -<node> n = - node.new(<number> id) -<node> n = - node.new(<number> id, <number> subtype) -\stopfunctioncall - -Creates a new node. All of the new node's fields are initialized to either zero -or \type {nil} except for \type {id} and \type {subtype} (if supplied). If you -want to create a new whatsit, then the second argument is required, otherwise it -need not be present. As with all node functions, this function creates a node on -the \TEX\ level. - -This function accepts string \type {id} and \type {subtype} values as well. - -\subsubsection{\type {node.free} and \type {node.flush_node}} - -\startfunctioncall -<node> next = - node.free(<node> n) -flush_node(<node> n) -\stopfunctioncall - -Removes the node \type {n} from \TEX's memory. Be careful: no checks are done on -whether this node is still pointed to from a register or some \type {next} field: -it is up to you to make sure that the internal data structures remain correct. - -The \type {free} function returns the next field of the freed node, while the -\type {flush_node} alternative returns nothing. - -\subsubsection{\type {node.flush_list}} - -\startfunctioncall -node.flush_list(<node> n) -\stopfunctioncall - -Removes the node list \type {n} and the complete node list following \type {n} -from \TEX's memory. Be careful: no checks are done on whether any of these nodes -is still pointed to from a register or some \type {next} field: it is up to you -to make sure that the internal data structures remain correct. - -\subsubsection{\type {node.copy}} - -\startfunctioncall -<node> m = - node.copy(<node> n) -\stopfunctioncall - -Creates a deep copy of node \type {n}, including all nested lists as in the case -of a hlist or vlist node. Only the \type {next} field is not copied. - -\subsubsection{\type {node.copy_list}} - -\startfunctioncall -<node> m = - node.copy_list(<node> n) -<node> m = - node.copy_list(<node> n, <node> m) -\stopfunctioncall - -Creates a deep copy of the node list that starts at \type {n}. If \type {m} is -also given, the copy stops just before node \type {m}. - -Note that you cannot copy attribute lists this way, specialized functions for -dealing with attribute lists will be provided later but are not there yet. -However, there is normally no need to copy attribute lists as when you do -assignments to the \type {attr} field or make changes to specific attributes, the -needed copying and freeing takes place automatically. - -\subsubsection{\type {node.next}} - -\startfunctioncall -<node> m = - node.next(<node> n) -\stopfunctioncall - -Returns the node following this node, or \type {nil} if there is no such node. - -\subsubsection{\type {node.prev}} - -\startfunctioncall -<node> m = - node.prev(<node> n) -\stopfunctioncall - -Returns the node preceding this node, or \type {nil} if there is no such node. - -\subsubsection{\type {node.current_attr}} - -\startfunctioncall -<node> m = - node.current_attr() -\stopfunctioncall - -Returns the currently active list of attributes, if there is one. - -The intended usage of \type {current_attr} is as follows: - -\starttyping -local x1 = node.new("glyph") -x1.attr = node.current_attr() -local x2 = node.new("glyph") -x2.attr = node.current_attr() -\stoptyping - -or: - -\starttyping -local x1 = node.new("glyph") -local x2 = node.new("glyph") -local ca = node.current_attr() -x1.attr = ca -x2.attr = ca -\stoptyping - -The attribute lists are ref counted and the assignment takes care of incrementing -the refcount. You cannot expect the value \type {ca} to be valid any more when -you assign attributes (using \type {tex.setattribute}) or when control has been -passed back to \TEX. - -Note: this function is somewhat experimental, and it returns the {\it actual} -attribute list, not a copy thereof. Therefore, changing any of the attributes in -the list will change these values for all nodes that have the current attribute -list assigned to them. - -\subsubsection{\type {node.hpack}} - -\startfunctioncall -<node> h, <number> b = - node.hpack(<node> n) -<node> h, <number> b = - node.hpack(<node> n, <number> w, <string> info) -<node> h, <number> b = - node.hpack(<node> n, <number> w, <string> info, <string> dir) -\stopfunctioncall - -This function creates a new hlist by packaging the list that begins at node \type -{n} into a horizontal box. With only a single argument, this box is created using -the natural width of its components. In the three argument form, \type {info} -must be either \type {additional} or \type {exactly}, and \type {w} is the -additional (\type {\hbox spread}) or exact (\type {\hbox to}) width to be used. The -second return value is the badness of the generated box. - -Caveat: at this moment, there can be unexpected side|-|effects to this function, -like updating some of the \type {\marks} and \type {\inserts}. Also note that the -content of \type {h} is the original node list \type {n}: if you call \type -{node.free(h)} you will also free the node list itself, unless you explicitly set -the \type {list} field to \type {nil} beforehand. And in a similar way, calling -\type {node.free(n)} will invalidate \type {h} as well! - -\subsubsection{\type {node.vpack}} - -\startfunctioncall -<node> h, <number> b = - node.vpack(<node> n) -<node> h, <number> b = - node.vpack(<node> n, <number> w, <string> info) -<node> h, <number> b = - node.vpack(<node> n, <number> w, <string> info, <string> dir) -\stopfunctioncall - -This function creates a new vlist by packaging the list that begins at node \type -{n} into a vertical box. With only a single argument, this box is created using -the natural height of its components. In the three argument form, \type {info} -must be either \type {additional} or \type {exactly}, and \type {w} is the -additional (\type {\vbox spread}) or exact (\type {\vbox to}) height to be used. - -The second return value is the badness of the generated box. - -See the description of \type {node.hpack()} for a few memory allocation caveats. - -\subsubsection{\type {node.dimensions}} - -\startfunctioncall -<number> w, <number> h, <number> d = - node.dimensions(<node> n) -<number> w, <number> h, <number> d = - node.dimensions(<node> n, <string> dir) -<number> w, <number> h, <number> d = - node.dimensions(<node> n, <node> t) -<number> w, <number> h, <number> d = - node.dimensions(<node> n, <node> t, <string> dir) -\stopfunctioncall - -This function calculates the natural in|-|line dimensions of the node list starting -at node \type {n} and terminating just before node \type {t} (or the end of the -list, if there is no second argument). The return values are scaled points. An -alternative format that starts with glue parameters as the first three arguments -is also possible: - -\startfunctioncall -<number> w, <number> h, <number> d = - node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, - <node> n) -<number> w, <number> h, <number> d = - node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, - <node> n, <string> dir) -<number> w, <number> h, <number> d = - node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, - <node> n, <node> t) -<number> w, <number> h, <number> d = - node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, - <node> n, <node> t, <string> dir) -\stopfunctioncall - -This calling method takes glue settings into account and is especially useful for -finding the actual width of a sublist of nodes that are already boxed, for -example in code like this, which prints the width of the space in between the -\type {a} and \type {b} as it would be if \type {\box0} was used as-is: - -\starttyping -\setbox0 = \hbox to 20pt {a b} - -\directlua{print (node.dimensions( - tex.box[0].glue_set, - tex.box[0].glue_sign, - tex.box[0].glue_order, - tex.box[0].head.next, - node.tail(tex.box[0].head) -)) } -\stoptyping - -You need to keep in mind that this is one of the few places in \TEX\ where floats -are used, which means that you can get small differences in rounding when you -compare the width repported by \type {hpack} with \type {dimensions}. - -\subsubsection{\type {node.mlist_to_hlist}} - -\startfunctioncall -<node> h = - node.mlist_to_hlist(<node> n, <string> display_type, <boolean> penalties) -\stopfunctioncall - -This runs the internal mlist to hlist conversion, converting the math list in -\type {n} into the horizontal list \type {h}. The interface is exactly the same -as for the callback \type {mlist_to_hlist}. - -\subsubsection{\type {node.slide}} - -\startfunctioncall -<node> m = - node.slide(<node> n) -\stopfunctioncall - -Returns the last node of the node list that starts at \type {n}. As a -side|-|effect, it also creates a reverse chain of \type {prev} pointers between -nodes. - -\subsubsection{\type {node.tail}} - -\startfunctioncall -<node> m = - node.tail(<node> n) -\stopfunctioncall - -Returns the last node of the node list that starts at \type {n}. - -\subsubsection{\type {node.length}} - -\startfunctioncall -<number> i = - node.length(<node> n) -<number> i = - node.length(<node> n, <node> m) -\stopfunctioncall - -Returns the number of nodes contained in the node list that starts at \type {n}. -If \type {m} is also supplied it stops at \type {m} instead of at the end of the -list. The node \type {m} is not counted. - -\subsubsection{\type {node.count}} - -\startfunctioncall -<number> i = - node.count(<number> id, <node> n) -<number> i = - node.count(<number> id, <node> n, <node> m) -\stopfunctioncall - -Returns the number of nodes contained in the node list that starts at \type {n} -that have a matching \type {id} field. If \type {m} is also supplied, counting -stops at \type {m} instead of at the end of the list. The node \type {m} is not -counted. - -This function also accept string \type {id}'s. - -\subsubsection{\type {node.traverse}} - -\startfunctioncall -<node> t = - node.traverse(<node> n) -\stopfunctioncall - -This is a \LUA\ iterator that loops over the node list that starts at \type {n}. -Typically code looks like this: - -\starttyping -for n in node.traverse(head) do - ... -end -\stoptyping - -is functionally equivalent to: - -\starttyping -do - local n - local function f (head,var) - local t - if var == nil then - t = head - else - t = var.next - end - return t - end - while true do - n = f (head, n) - if n == nil then break end - ... - end -end -\stoptyping - -It should be clear from the definition of the function \type {f} that even though -it is possible to add or remove nodes from the node list while traversing, you -have to take great care to make sure all the \type {next} (and \type {prev}) -pointers remain valid. - -If the above is unclear to you, see the section \quote {For Statement} in the -\LUA\ Reference Manual. - -\subsubsection{\type {node.traverse_id}} - -\startfunctioncall -<node> t = - node.traverse_id(<number> id, <node> n) -\stopfunctioncall - -This is an iterator that loops over all the nodes in the list that starts at -\type {n} that have a matching \type {id} field. - -See the previous section for details. The change is in the local function \type -{f}, which now does an extra while loop checking against the upvalue \type {id}: - -\starttyping - local function f(head,var) - local t - if var == nil then - t = head - else - t = var.next - end - while not t.id == id do - t = t.next - end - return t - end -\stoptyping - -\subsubsection{\type {node.traverse_char}} - -This iterators loops over the glyph nodes in a list. Only nodes with a subtype -less than 256 are seen. - -\startfunctioncall -<node> n = - node.traverse_char(<node> n) -\stopfunctioncall - -\subsubsection{\type {node.has_glyph}} - -This function returns the first glyph or disc node in the given list: - -\startfunctioncall -<node> n = - node.has_glyph(<node> n) -\stopfunctioncall - -\subsubsection{\type {node.end_of_math}} - -\startfunctioncall -<node> t = - node.end_of_math(<node> start) -\stopfunctioncall - -Looks for and returns the next \type {math_node} following the \type {start}. If -the given node is a math endnode this helper return that node, else it follows -the list and return the next math endnote. If no such node is found nil is -returned. - -\subsubsection{\type {node.remove}} - -\startfunctioncall -<node> head, current = - node.remove(<node> head, <node> current) -\stopfunctioncall - -This function removes the node \type {current} from the list following \type -{head}. It is your responsibility to make sure it is really part of that list. -The return values are the new \type {head} and \type {current} nodes. The -returned \type {current} is the node following the \type {current} in the calling -argument, and is only passed back as a convenience (or \type {nil}, if there is -no such node). The returned \type {head} is more important, because if the -function is called with \type {current} equal to \type {head}, it will be -changed. - -\subsubsection{\type {node.insert_before}} - -\startfunctioncall -<node> head, new = - node.insert_before(<node> head, <node> current, <node> new) -\stopfunctioncall - -This function inserts the node \type {new} before \type {current} into the list -following \type {head}. It is your responsibility to make sure that \type -{current} is really part of that list. The return values are the (potentially -mutated) \type {head} and the node \type {new}, set up to be part of the list -(with correct \type {next} field). If \type {head} is initially \type {nil}, it -will become \type {new}. - -\subsubsection{\type {node.insert_after}} - -\startfunctioncall -<node> head, new = - node.insert_after(<node> head, <node> current, <node> new) -\stopfunctioncall - -This function inserts the node \type {new} after \type {current} into the list -following \type {head}. It is your responsibility to make sure that \type -{current} is really part of that list. The return values are the \type {head} and -the node \type {new}, set up to be part of the list (with correct \type {next} -field). If \type {head} is initially \type {nil}, it will become \type {new}. - -\subsubsection{\type {node.first_glyph}} - -\startfunctioncall -<node> n = - node.first_glyph(<node> n) -<node> n = - node.first_glyph(<node> n, <node> m) -\stopfunctioncall - -Returns the first node in the list starting at \type {n} that is a glyph node -with a subtype indicating it is a glyph, or \type {nil}. If \type {m} is given, -processing stops at (but including) that node, otherwise processing stops at the -end of the list. - -\subsubsection{\type {node.ligaturing}} - -\startfunctioncall -<node> h, <node> t, <boolean> success = - node.ligaturing(<node> n) -<node> h, <node> t, <boolean> success = - node.ligaturing(<node> n, <node> m) -\stopfunctioncall - -Apply \TEX-style ligaturing to the specified nodelist. The tail node \type {m} is -optional. The two returned nodes \type {h} and \type {t} are the new head and -tail (both \type {n} and \type {m} can change into a new ligature). - -\subsubsection{\type {node.kerning}} - -\startfunctioncall -<node> h, <node> t, <boolean> success = - node.kerning(<node> n) -<node> h, <node> t, <boolean> success = - node.kerning(<node> n, <node> m) -\stopfunctioncall - -Apply \TEX|-|style kerning to the specified node list. The tail node \type {m} is -optional. The two returned nodes \type {h} and \type {t} are the head and tail -(either one of these can be an inserted kern node, because special kernings with -word boundaries are possible). - -\subsubsection{\type {node.unprotect_glyphs}} - -\startfunctioncall -node.unprotect_glyphs(<node> n) -\stopfunctioncall - -Subtracts 256 from all glyph node subtypes. This and the next function are -helpers to convert from \type {characters} to \type {glyphs} during node -processing. - -\subsubsection{\type {node.protect_glyphs} and \type {node.protect_glyph}} - -\startfunctioncall -node.protect_glyphs(<node> n) -\stopfunctioncall - -Adds 256 to all glyph node subtypes in the node list starting at \type {n}, -except that if the value is 1, it adds only 255. The special handling of 1 means -that \type {characters} will become \type {glyphs} after subtraction of 256. A -single character can be marked by the singular call. - -\subsubsection{\type {node.last_node}} - -\startfunctioncall -<node> n = - node.last_node() -\stopfunctioncall - -This function pops the last node from \TEX's \quote{current list}. It returns -that node, or \type {nil} if the current list is empty. - -\subsubsection{\type {node.write}} - -\startfunctioncall -node.write(<node> n) -\stopfunctioncall - -This is an experimental function that will append a node list to \TEX's \quote -{current list} The node list is not deep|-|copied! There is no error checking -either! - -\subsubsection{\type {node.protrusion_skippable}} - -\startfunctioncall -<boolean> skippable = - node.protrusion_skippable(<node> n) -\stopfunctioncall - -Returns \type {true} if, for the purpose of line boundary discovery when -character protrusion is active, this node can be skipped. - -\subsection{Glue handling} - -\subsubsection{\type {node.setglue}} - -You can set the properties of a glue in one go. If you pass no values, the glue -will become a zero glue. - -\startfunctioncall -node.setglue(<node> n) -node.setglue(<node> n,width,stretch,shrink,stretch_order,shrink_order) -\stopfunctioncall - -When you pass values, only arguments that are numbers -are assigned so - -\starttyping -node.setglue(n,655360,false,65536) -\stoptyping - -will only adapt the width and shrink. - -\subsubsection{\type {node.getglue}} - -The next call will return 5 values (or northing when no glue is passed). - -\startfunctioncall -<integer> width, <integer> stretch, <integer> shrink, <integer> stretch_order, - <integer> shrink_order = node.getglue(<node> n) -\stopfunctioncall - -\subsubsection{\type {node.is_zero_glue}} - -This function returns \type {true} when the width, stretch and shrink properties -are zero. - -\startfunctioncall -<boolean> isglue = - node.is_zero_glue(<node> n) -\stopfunctioncall - -\subsection{Attribute handling} - -Attributes appear as linked list of userdata objects in the \type {attr} field of -individual nodes. They can be handled individually, but it is much safer and more -efficient to use the dedicated functions associated with them. - -\subsubsection{\type {node.has_attribute}} - -\startfunctioncall -<number> v = - node.has_attribute(<node> n, <number> id) -<number> v = - node.has_attribute(<node> n, <number> id, <number> val) -\stopfunctioncall - -Tests if a node has the attribute with number \type {id} set. If \type {val} is -also supplied, also tests if the value matches \type {val}. It returns the value, -or, if no match is found, \type {nil}. - -\subsubsection{\type {node.get_attribute}} - -\startfunctioncall -<number> v = - node.get_attribute(<node> n, <number> id) -\stopfunctioncall - -Tests if a node has an attribute with number \type {id} set. It returns the -value, or, if no match is found, \type {nil}. - -\subsubsection{\type {node.find_attribute}} - -\startfunctioncall -<number> v, <node> n = - node.find_attribute(<node> n, <number> id) -\stopfunctioncall - -Finds the first node that has attribute with number \type {id} set. It returns -the value and the node if there is a match and otherwise nothing. - -\subsubsection{\type {node.set_attribute}} - -\startfunctioncall -node.set_attribute(<node> n, <number> id, <number> val) -\stopfunctioncall - -Sets the attribute with number \type {id} to the value \type {val}. Duplicate -assignments are ignored. {\em [needs explanation]} - -\subsubsection{\type {node.unset_attribute}} - -\startfunctioncall -<number> v = - node.unset_attribute(<node> n, <number> id) -<number> v = - node.unset_attribute(<node> n, <number> id, <number> val) -\stopfunctioncall - -Unsets the attribute with number \type {id}. If \type {val} is also supplied, it -will only perform this operation if the value matches \type {val}. Missing -attributes or attribute|-|value pairs are ignored. - -If the attribute was actually deleted, returns its old value. Otherwise, returns -\type {nil}. - -\subsubsection{\type {node.slide}} - -This helper makes sure that the node lists is double linked and returns the found -tail node. - -\startfunctioncall -<node> tail = - node.slide(<node> n) -\stopfunctioncall - -\subsubsection{\type {node.check_discretionary} and \type {node.check_discretionaries}} - -When you fool around with disc nodes you need to be aware of the fact that they -have a special internal data structure. As long as you reassign the fields when -you have extended the lists it's ok because then the tail pointers get updated, -but when you add to list without reassigning you might end up in troubles when -the linebreak routien kicks in. You can call this function to check the list for -issues with disc nodes. - -\startfunctioncall -node.check_discretionary(<node> n) -node.check_discretionaries(<node> head) -\stopfunctioncall - -The plural variant runs over all disc nodes in a list, the singular variant -checks one node only (it also checks if the node is a disc node). - -\subsubsection{\type {node.family_font}} - -When you pass it a proper family identifier the next helper will return the font -currently associated with it. You can normally also access the font with the normal -font field or getter because it will resolve the family automatically for noads. - -\startfunctioncall -<integer> id = - node.family_font(<integer> fam) -\stopfunctioncall - -\section{Two access models} - -Deep down in \TEX\ a node has a number which is an numeric entry in a memory -table. In fact, this model, where \TEX\ manages memory is real fast and one of -the reasons why plugging in callbacks that operate on nodes is quite fast too. -Each node gets a number that is in fact an index in the memory table and that -number often gets reported when you print node related information. - -There are two access models, a robust one using a so called user data object that -provides a virtual interface to the internal nodes, and a more direct access which -uses the node numbers directly. The first model provide key based access while -the second always accesses fields via functions: - -\starttyping -nodeobject.char -getfield(nodenumber,"char") -\stoptyping - -If you use the direct model, even if you know that you deal with numbers, you -should not depend on that property but treat it an abstraction just like -traditional nodes. In fact, the fact that we use a simple basic datatype has the -penalty that less checking can be done, but less checking is also the reason why -it's somewhat faster. An important aspect is that one cannot mix both methods, -but you can cast both models. So, multiplying a node number makes no sense. - -So our advice is: use the indexed (table) approach when possible and investigate -the direct one when speed might be an real issue. For that reason we also provide -the \type {get*} and \type {set*} functions in the top level node namespace. -There is a limited set of getters. When implementing this direct approach the -regular index by key variant was also optimized, so direct access only makes -sense when we're accessing nodes millions of times (which happens in some font -processing for instance). - -We're talking mostly of getters because setters are less important. Documents -have not that many content related nodes and setting many thousands of properties -is hardly a burden contrary to millions of consultations. - -Normally you will access nodes like this: - -\starttyping -local next = current.next -if next then - -- do something -end -\stoptyping - -Here \type {next} is not a real field, but a virtual one. Accessing it results in -a metatable method being called. In practice it boils down to looking up the node -type and based on the node type checking for the field name. In a worst case you -have a node type that sits at the end of the lookup list and a field that is last -in the lookup chain. However, in successive versions of \LUATEX\ these lookups -have been optimized and the most frequently accessed nodes and fields have a -higher priority. - -Because in practice the \type {next} accessor results in a function call, there -is some overhead involved. The next code does the same and performs a tiny bit -faster (but not that much because it is still a function call but one that knows -what to look up). - -\starttyping -local next = node.next(current) -if next then - -- do something -end -\stoptyping - -If performance matters you can use an function instead: - -\starttabulate[|T|p|] -\NC getnext \NC parsing nodelist always involves this one \NC \NR -\NC getprev \NC used less but is logical companion to \type {getnext} \NC \NR -\NC getboth \NC returns the next and prev pointer of a node \NC \NR -\NC getid \NC consulted a lot \NC \NR -\NC getsubtype \NC consulted less but also a topper \NC \NR -\NC getfont \NC used a lot in \OPENTYPE\ handling (glyph nodes are consulted a lot) \NC \NR -\NC getchar \NC idem and also in other places \NC \NR -\NC getdisc \NC returns the \type {pre}, \type {post} and \type {replace} fields and - optionally when true is passed also the tail fields. \NC \NR -\NC getlist \NC we often parse nested lists so this is a convenient one too - (only works for hlist and vlist!) \NC \NR -\NC getleader \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting - like lists; leaders could have been made a dedicated node type) \NC \NR -\NC getfield \NC generic getter, sufficient for the rest (other field names are - often shared so a specific getter makes no sense then) \NC \NR -\NC getbox \NC gets the given box (a list node) \NC \NR -\stoptabulate - -The direct variants also have setters, where the discretionary setter takes three -(optional) arguments plus an optional fourth indicating the subtype. An additional -setter is \type {setlink} which will link two nodes. - -It doesn't make sense to add getters for all fields, also because some are not -unique to one node type. Profiling demonstrated that these fields can get -accesses way more times than other fields. Even in complex documents, many node -and fields types never get seen, or seen only a few times. Most functions in the -\type {node} namespace have a companion in \type {node.direct}, but of course not -the ones that don't deal with nodes themselves. The following table summarized -this: - -% \startcolumns[balance=yes] - -\def\yes{$+$} \def\nop{$-$} - -\starttabulate[|T|c|c|] -\HL -\NC \bf function \NC \bf node \NC \bf direct \NC \NR -\HL -\NC \type {check_discretionaries}\NC \yes \NC \yes \NC \NR -\NC \type {copy_list} \NC \yes \NC \yes \NC \NR -\NC \type {copy} \NC \yes \NC \yes \NC \NR -\NC \type {count} \NC \yes \NC \yes \NC \NR -\NC \type {current_attr} \NC \yes \NC \yes \NC \NR -\NC \type {dimensions} \NC \yes \NC \yes \NC \NR -%NC \type {do_ligature_n} \NC \yes \NC \yes \NC \NR % was never documented and experimental -\NC \type {effective_glue} \NC \yes \NC \yes \NC \NR -\NC \type {end_of_math} \NC \yes \NC \yes \NC \NR -\NC \type {family_font} \NC \yes \NC \nop \NC \NR -\NC \type {fields} \NC \yes \NC \nop \NC \NR -\NC \type {find_attribute} \NC \yes \NC \yes \NC \NR -\NC \type {first_glyph} \NC \yes \NC \yes \NC \NR -\NC \type {flush_list} \NC \yes \NC \yes \NC \NR -\NC \type {flush_node} \NC \yes \NC \yes \NC \NR -\NC \type {free} \NC \yes \NC \yes \NC \NR -\NC \type {get_attribute} \NC \yes \NC \yes \NC \NR -\NC \type {getboth} \NC \yes \NC \yes \NC \NR -\NC \type {getbox} \NC \nop \NC \yes \NC \NR -\NC \type {getchar} \NC \yes \NC \yes \NC \NR -\NC \type {getdisc} \NC \yes \NC \yes \NC \NR -\NC \type {getfield} \NC \yes \NC \yes \NC \NR -\NC \type {getfont} \NC \yes \NC \yes \NC \NR -\NC \type {getglue} \NC \yes \NC \yes \NC \NR -\NC \type {getid} \NC \yes \NC \yes \NC \NR -\NC \type {getleader} \NC \yes \NC \yes \NC \NR -\NC \type {getlist} \NC \yes \NC \yes \NC \NR -\NC \type {getnext} \NC \yes \NC \yes \NC \NR -\NC \type {getprev} \NC \yes \NC \yes \NC \NR -\NC \type {getsubtype} \NC \yes \NC \yes \NC \NR -\NC \type {has_attribute} \NC \yes \NC \yes \NC \NR -\NC \type {has_field} \NC \yes \NC \yes \NC \NR -\NC \type {has_glyph} \NC \yes \NC \yes \NC \NR -\NC \type {hpack} \NC \yes \NC \yes \NC \NR -\NC \type {id} \NC \yes \NC \nop \NC \NR -\NC \type {insert_after} \NC \yes \NC \yes \NC \NR -\NC \type {insert_before} \NC \yes \NC \yes \NC \NR -\NC \type {is_char} \NC \yes \NC \yes \NC \NR -\NC \type {is_direct} \NC \nop \NC \yes \NC \NR -\NC \type {is_glue_zero} \NC \yes \NC \yes \NC \NR -\NC \type {is_glyph} \NC \yes \NC \yes \NC \NR -\NC \type {is_node} \NC \yes \NC \yes \NC \NR -\NC \type {kerning} \NC \yes \NC \yes \NC \NR -\NC \type {last_node} \NC \yes \NC \yes \NC \NR -\NC \type {length} \NC \yes \NC \yes \NC \NR -\NC \type {ligaturing} \NC \yes \NC \yes \NC \NR -\NC \type {mlist_to_hlist} \NC \yes \NC \nop \NC \NR -\NC \type {new} \NC \yes \NC \yes \NC \NR -\NC \type {next} \NC \yes \NC \nop \NC \NR -\NC \type {prev} \NC \yes \NC \nop \NC \NR -\NC \type {protect_glyphs} \NC \yes \NC \yes \NC \NR -\NC \type {protect_glyph} \NC \yes \NC \yes \NC \NR -\NC \type {protrusion_skippable} \NC \yes \NC \yes \NC \NR -\NC \type {remove} \NC \yes \NC \yes \NC \NR -\NC \type {set_attribute} \NC \yes \NC \yes \NC \NR -\NC \type {setboth} \NC \yes \NC \yes \NC \NR -\NC \type {setbox} \NC \nop \NC \yes \NC \NR -\NC \type {setbox} \NC \yes \NC \yes \NC \NR -\NC \type {setchar} \NC \yes \NC \yes \NC \NR -\NC \type {setdisc} \NC \yes \NC \yes \NC \NR -\NC \type {setfield} \NC \yes \NC \yes \NC \NR -\NC \type {setglue} \NC \yes \NC \yes \NC \NR -\NC \type {setlink} \NC \yes \NC \yes \NC \NR -\NC \type {setnext} \NC \yes \NC \yes \NC \NR -\NC \type {setprev} \NC \yes \NC \yes \NC \NR -\NC \type {slide} \NC \yes \NC \yes \NC \NR -\NC \type {subtypes} \NC \yes \NC \nop \NC \NR -\NC \type {subtype} \NC \yes \NC \nop \NC \NR -\NC \type {tail} \NC \yes \NC \yes \NC \NR -\NC \type {todirect} \NC \yes \NC \yes \NC \NR -\NC \type {tonode} \NC \yes \NC \yes \NC \NR -\NC \type {tostring} \NC \yes \NC \yes \NC \NR -\NC \type {traverse_char} \NC \yes \NC \yes \NC \NR -\NC \type {traverse_id} \NC \yes \NC \yes \NC \NR -\NC \type {traverse} \NC \yes \NC \yes \NC \NR -\NC \type {types} \NC \yes \NC \nop \NC \NR -\NC \type {type} \NC \yes \NC \nop \NC \NR -\NC \type {unprotect_glyphs} \NC \yes \NC \yes \NC \NR -\NC \type {unset_attribute} \NC \yes \NC \yes \NC \NR -\NC \type {usedlist} \NC \yes \NC \yes \NC \NR -\NC \type {vpack} \NC \yes \NC \yes \NC \NR -\NC \type {whatsitsubtypes} \NC \yes \NC \nop \NC \NR -\NC \type {whatsits} \NC \yes \NC \nop \NC \NR -\NC \type {write} \NC \yes \NC \yes \NC \NR -\stoptabulate - -% \stopcolumns - -The \type {node.next} and \type {node.prev} functions will stay but for -consistency there are variants called \type {getnext} and \type {getprev}. We had -to use \type {get} because \type {node.id} and \type {node.subtype} are already -taken for providing meta information about nodes. Note: The getters do only basic -checking for valid keys. You should just stick to the keys mentioned in the -sections that describe node properties. - -Some nodes have indirect references. For instance a math character refers to a -family instead of a font. In that case we provide a virtual font field as -accessor. So, \type {getfont} and \type {.font} can be used on them. The same is -true for the \type {width}, \type {height} and \type {depth} of glue nodes. These -actually access the spec node properties, and here we can set as well as get the -values. - -\stopchapter - -\stopcomponent |