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 | 1768 |
1 files changed, 1182 insertions, 586 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex index 517d9b6c8..34a2aebe8 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex @@ -1,16 +1,21 @@ % language=uk \environment luatex-style -\environment luatex-logos \startcomponent luatex-nodes \startchapter[reference=nodes,title={Nodes}] -\section{\LUA\ node representation} +\startsection[title={\LUA\ node representation}][library=node] -\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 +\topicindex {nodes} + +\libindex {fields} +\libindex {subtypes} +\libindex {values} + +\TEX's nodes are represented in \LUA\ as userdata objects with a variable set of +fields. In the following syntax tables, such as the type of such a userdata object is represented as \syntax {<node>}. The current return value of \type {node.types()} is: @@ -24,76 +29,43 @@ The current return value of \type {node.types()} is: \stopluacode . % period -The \type {\lastnodetype} primitive is \ETEX\ compliant. The valid range is still +The \prm {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). - -The \type {node.values} function reports some used values. Valid arguments are -\type {dir}, \type {direction}, \type {glue}, \type {pdf_literal}, \type -{pdf_action}, \type {pdf_window} and \type {color_stack}. Keep in mind that the -setters normally expect a number, but this helper gives you a list of what -numbers matter. For practical reason the \type {pagestate} values are also -reported with this helper. - -\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[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR -\NC \type{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. +You can ask for a list of fields with \type {node.fields} and for valid subtypes +with \type {node.subtypes}. The \type {node.values} function reports some used +values. Valid arguments are \nod {dir}, \type {direction}, \nod {glue}, \whs +{pdf_literal}, \whs {pdf_action}, \whs {pdf_window} and \whs {color_stack}. Keep +in mind that the setters normally expect a number, but this helper gives you a +list of what numbers matter. For practical reason the \type {pagestate} values +are also reported with this helper. -\starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR -\NC \type{next} \NC node \NC pointer to the next attribute \NC \NR -\NC \type{number} \NC number \NC the attribute type id \NC \NR -\NC \type{value} \NC number \NC the attribute value \NC \NR -\stoptabulate +\stopsection -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. +\startsection[title={Main text nodes}] -\subsection{Main text nodes} +\topicindex {nodes+text} These are the nodes that comprise actual typesetting commands. A few fields are present in all nodes regardless of their type, these are: \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{next} \NC node \NC the next node in a list, or nil \NC \NR \NC \type{id} \NC number \NC the node's type (\type {id}) number \NC \NR \NC \type{subtype} \NC number \NC the node \type {subtype} identifier \NC \NR +\LL \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. +The \type {subtype} is sometimes just a dummy entry because 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, @@ -101,25 +73,33 @@ 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. +internal magic uses a leading \nod {temp} nodes to temporarily store a state. -\subsubsection{hlist nodes} +\subsection{\nod {hlist} nodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{list} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width of the box \NC \NR \NC \type{height} \NC number \NC the height of the box \NC \NR \NC \type{depth} \NC number \NC the depth of the box \NC \NR -\NC \type{shift} \NC number \NC a displacement perpendicular to the character progression direction \NC \NR -\NC \type{glue_order} \NC number \NC a number in the range $[0,4]$, indicating the glue order \NC \NR +\NC \type{shift} \NC number \NC a displacement perpendicular to the character + progression direction \NC \NR +\NC \type{glue_order} \NC number \NC a number in the range $[0,4]$, indicating the + glue order \NC \NR \NC \type{glue_set} \NC number \NC the calculated glue ratio \NC \NR -\NC \type{glue_sign} \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 = \type {shrinking} \NC \NR +\NC \type{glue_sign} \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 = + \type {shrinking} \NC \NR \NC \type{head/list} \NC node \NC the first node of the body of this list \NC \NR -\NC \type{dir} \NC string \NC the direction of this box, see~\in[dirnodes] \NC \NR +\NC \type{dir} \NC string \NC the direction of this box, see~\in [dirnodes] \NC \NR +\LL \stoptabulate +\topicindex {nodes+lists} +\topicindex {lists} + 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. @@ -127,39 +107,72 @@ 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} +\subsection{\nod {vlist} nodes} + +\topicindex {nodes+lists} +\topicindex {lists} -This node is similar to \type {hlist}, except that \quote {shift} is a displacement +This node is similar to \nod {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} +\subsection{\nod {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. +\topicindex {nodes+rules} +\topicindex {rules} + +Contrary to traditional \TEX, \LUATEX\ has more \prm {rule} subtypes because we +also use rules to store reuseable objects and images. User nodes are invisible +and can be intercepted by a callback. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR -\NC \type{subtype} \NC number \NC \showsubtypes{rule} \NC \NR -\NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{width} \NC number \NC the width of the rule where the special value $-1073741824$ is used for \quote {running} glue dimensions \NC \NR -\NC \type{height} \NC number \NC the height of the rule (can be negative) \NC \NR -\NC \type{depth} \NC number \NC the depth of the rule (can be negative) \NC \NR -\NC \type{dir} \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR -\NC \type{index} \NC number \NC an optional index that can be referred to \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{subtype} \NC number \NC \showsubtypes {rule} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the width of the rule where the special value + $-1073741824$ is used for \quote {running} glue dimensions \NC \NR +\NC \type{height} \NC number \NC the height of the rule (can be negative) \NC \NR +\NC \type{depth} \NC number \NC the depth of the rule (can be negative) \NC \NR +\NC \type{left} \NC number \NC shift at the left end (also subtracted from width) \NC \NR +\NC \type{right} \NC number \NC (subtracted from width) \NC \NR +\NC \type{dir} \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR +\NC \type{index} \NC number \NC an optional index that can be referred to \NC \NR +\NC \type{transform} \NC number \NC an private variable (also used to specify outline width) \NC \NR +\LL \stoptabulate -\subsubsection{ins nodes} +The \type {left} and type {right} keys are somewhat special (and experimental). +When rules are auto adapting to the surrounding box width you can enforce a shift +to the right by setting \type {left}. The value is also subtracted from the width +which can be a value set by the engine itself and is not entirely under user +control. The \type {right} is also subtracted from the width. It all happens in +the backend so these are not affecting the calculations in the frontend (actually +the auto settings also happen in the backend). For a vertical rule \type {left} +affects the height and \type {right} affects the depth. There is no matching +interface at the \TEX\ end (although we can have more keywords for rules it would +complicate matters and introduce a speed penalty.) However, you can just +construct a rule node with \LUA\ and write it to the \TEX\ input. The \type +{outline} subtype is just a convenient variant and the \type {transform} field +specifies the width of the outline. + +\subsection{\nod {ins} nodes} + +\topicindex {nodes+insertions} +\topicindex {insertions} + +This node relates to the \prm {insert} primitive. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC the insertion class \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{cost} \NC number \NC the penalty associated with this insert \NC \NR \NC \type{height} \NC number \NC height of the insert \NC \NR \NC \type{depth} \NC number \NC depth of the insert \NC \NR \NC \type{head/list} \NC node \NC the first node of the body of this insert \NC \NR +\LL \stoptabulate There is a set of extra fields that concern the associated glue: \type {width}, @@ -167,53 +180,76 @@ There is a set of extra fields that concern the associated glue: \type {width}, 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 +its internal link structure is correct, otherwise an error may result. You can use +\type {list} instead (often in functions you want to use local variable with similar names and both names are equally sensible). -\subsubsection{mark nodes} +\subsection{\nod {mark} nodes} + +\topicindex {nodes+marks} +\topicindex {marks} + +This one relates to the \prm {mark} primitive. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC unused \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{class} \NC number \NC the mark class \NC \NR \NC \type{mark} \NC table \NC a table representing a token list \NC \NR +\LL \stoptabulate -\subsubsection{adjust nodes} +\subsection{\nod {adjust} nodes} + +\topicindex {nodes+adjust} +\topicindex {adjust} + +This node comes from \prm {vadjust} primitive. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{adjust} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{head/list} \NC node \NC adjusted material \NC \NR +\LL \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. +its internal link structure is correct, otherwise an error may be the result. + +\subsection{\nod {disc} nodes} + +\topicindex {nodes+discretionaries} +\topicindex {discretionaries} -\subsubsection{disc nodes} +The \prm {discretionary} and \prm {-}, the \type {-} character but also the +hyphenation mechanism produces these nodes. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{disc} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{pre} \NC node \NC pointer to the pre|-|break text \NC \NR \NC \type{post} \NC node \NC pointer to the post|-|break text \NC \NR \NC \type{replace} \NC node \NC pointer to the no|-|break text \NC \NR -\NC \type{penalty} \NC number \NC the penalty associated with the break, normally \type {\hyphenpenalty} or \type {\exhyphenpenalty} \NC \NR +\NC \type{penalty} \NC number \NC the penalty associated with the break, normally + \prm {hyphenpenalty} or \prm {exhyphenpenalty} \NC \NR +\LL \stoptabulate The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given -elsewhere. +elsewhere. These disc nodes are kind of special as at some point they also keep +information about breakpoints and nested ligatures. -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: +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 @@ -225,48 +261,64 @@ 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 +only because it is not really a node but part of the disc data structure (so freeing it again might crash \LUATEX). -\subsubsection{math nodes} +\subsection{\nod {math} nodes} + +\topicindex {nodes+math} +\topicindex {math+nodes} + +Math nodes represent the boundaries of a math formula, normally wrapped into +\type {$} signs. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{math} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{surround} \NC number \NC width of the \type {\mathsurround} kern \NC \NR +\NC \type{surround} \NC number \NC width of the \prm {mathsurround} kern \NC \NR +\LL \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} +\subsection{\nod {glue} nodes} + +\topicindex {nodes+glue} +\topicindex {glue} 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: +simple value. They are inserted when \TEX\ sees a space in the text flow but also +by \prm {hskip} and \prm {vskip}. The structure that represents the glue +components of a skip is called a \nod {glue_spec}, and it has the following +accessible fields: \starttabulate[|l|l|p|] -\BC key \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{width} \NC number \NC the horizontal or vertical displacement \NC \NR \NC \type{stretch} \NC number \NC extra (positive) displacement or stretch amount \NC \NR \NC \type{stretch_order} \NC number \NC factor applied to stretch amount \NC \NR \NC \type{shrink} \NC number \NC extra (negative) displacement or shrink amount\NC \NR \NC \type{shrink_order} \NC number \NC factor applied to shrink amount \NC \NR +\LL \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 +lines normally have glue representing spaces and these stretch or 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. +that glue item. When you pass \type {true} as third argument the value will be +rounded. -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. +A \nod {glue_spec} 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 @@ -281,10 +333,12 @@ 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[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{glue} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{leader} \NC node \NC pointer to a box or rule for leaders \NC \NR +\LL \stoptabulate In addition there are the \type {width}, \type {stretch} \type {stretch_order}, @@ -295,64 +349,90 @@ 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} +\subsection{\nod {kern} nodes} + +\topicindex {nodes+kerns} +\topicindex {kerns} + +The \prm {kern} command creates such nodes but for instance the font and math +machinery can also add them. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{kern} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{kern} \NC number \NC fixed horizontal or vertical advance \NC \NR +\LL \stoptabulate -\subsubsection{penalty nodes} +\subsection{\nod {penalty} nodes} + +\topicindex {nodes+penalty} +\topicindex {penalty} + +The \prm {penalty} command is one that generates these nodes. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{penalty} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{penalty} \NC number \NC the penalty value \NC \NR +\LL \stoptabulate The subtypes are just informative and \TEX\ itself doesn't use them. When you run into an \type {linebreakpenalty} you need to keep in mind that it's a accumulation of \type {club}, \type{widow} and other relevant penalties. -\subsubsection[glyphnodes]{glyph nodes} +\subsection[glyphnodes]{\nod {glyph} nodes} + +\topicindex {nodes+glyph} +\topicindex {glyphs} + +These are probably the mostly used nodes and although you can push them in the +current list with for instance \prm {char} \TEX\ will normally do it for you when +it considers some input to be text. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR -\NC \type{subtype} \NC number \NC bitfield \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{subtype} \NC number \NC bit field \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{char} \NC number \NC the chatacter index in the font \NC \NR +\NC \type{char} \NC number \NC the character index in the font \NC \NR \NC \type{font} \NC number \NC the font identifier \NC \NR \NC \type{lang} \NC number \NC the language identifier \NC \NR \NC \type{left} \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR \NC \type{right} \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR -\NC \type{uchyph} \NC boolean \NC the frozen \type {\uchyph} value \NC \NR +\NC \type{uchyph} \NC boolean \NC the frozen \prm {uchyph} value \NC \NR \NC \type{components} \NC node \NC pointer to ligature components \NC \NR \NC \type{xoffset} \NC number \NC a virtual displacement in horizontal direction \NC \NR \NC \type{yoffset} \NC number \NC a virtual displacement in vertical direction \NC \NR -%NC \type{xadvance} \NC number \NC an additional advance after the glyph (experimental) \NC \NR \NC \type{width} \NC number \NC the (original) width of the character \NC \NR \NC \type{height} \NC number \NC the (original) height of the character\NC \NR \NC \type{depth} \NC number \NC the (original) depth of the character\NC \NR \NC \type{expansion_factor} \NC number \NC the to be applied expansion_factor \NC \NR +\NC \type{data} \NC number \NC a general purpose field for users (we had room for it) \NC \NR +\LL \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. +\type {expansion_factor} is assigned in the par builder 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|] -\BC bit \BC meaning \NC \NR +\DB bit \BC meaning \NC \NR +\TB \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 +\LL \stoptabulate See \in {section} [charsandglyphs] for a detailed description of the \type @@ -378,87 +458,117 @@ helpers are not always faster than separate calls but they sometimes permit making more readable tests. The \type {uses_font} helpers takes a node and font id and returns true when a glyph or disc node references that font. -\subsubsection{boundary nodes} +\subsection{\nod {boundary} nodes} + +\topicindex {nodes+boundary} +\topicindex {boundary} + +This node relates to the \prm {noboundary}, \prm {boundary}, \prm +{protrusionboundary} and \prm {wordboundary} primitives. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{boundary} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{value} \NC number \NC values 0--255 are reserved \NC \NR +\LL \stoptabulate -This node relates to the \type {\noboundary}, \type {\boundary}, \type -{\protrusionboundary} and \type {\wordboundary} primitives. +\subsection{\nod {local_par} nodes} + +\topicindex {nodes+paragraphs} +\topicindex {paragraphs} -\subsubsection{local_par nodes} +This node is inserted at the start of a paragraph. You should not mess +too much with this one. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{pen_inter} \NC number \NC local interline penalty (from \type {\localinterlinepenalty}) \NC \NR -\NC \type{pen_broken} \NC number \NC local broken penalty (from \type {\localbrokenpenalty}) \NC \NR +\NC \type{pen_inter} \NC number \NC local interline penalty (from \lpr {localinterlinepenalty}) \NC \NR +\NC \type{pen_broken} \NC number \NC local broken penalty (from \lpr {localbrokenpenalty}) \NC \NR \NC \type{dir} \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR -\NC \type{box_left} \NC node \NC the \type {\localleftbox} \NC \NR -\NC \type{box_left_width} \NC number \NC width of the \type {\localleftbox} \NC \NR -\NC \type{box_right} \NC node \NC the \type {\localrightbox} \NC \NR -\NC \type{box_right_width} \NC number \NC width of the \type {\localrightbox} \NC \NR +\NC \type{box_left} \NC node \NC the \lpr {localleftbox} \NC \NR +\NC \type{box_left_width} \NC number \NC width of the \lpr {localleftbox} \NC \NR +\NC \type{box_right} \NC node \NC the \lpr {localrightbox} \NC \NR +\NC \type{box_right_width} \NC number \NC width of the \lpr {localrightbox} \NC \NR +\LL \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. +error may result. + +\subsection[dirnodes]{\nod {dir} nodes} -\subsubsection[dirnodes]{dir nodes} +\topicindex {nodes+direction} +\topicindex {directions} + +Direction nodes mark parts of the running text that need a change of direction and \ +the \prm {textdir} command generates them. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{dir} \NC string \NC the direction (but see below) \NC \NR \NC \type{level} \NC number \NC nesting level of this direction whatsit \NC \NR +\LL \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: +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. + the first is the direction of the \quote{top} of paragraphs \stopitem \startitem - the second is the direction of the \quote{start} of lines. + the second is the direction of the \quote{start} of lines \stopitem \startitem - the third is the direction of the \quote{top} of glyphs. + 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}. +{RTT}, and \type {LTL}. Inside actual \nod {dir} nodes, the representation of +\nod {dir} is not a three|-|letter but a combination of numbers. When printed the +direction is indicated by a \type {+} or \type {-}, indicating whether the value +is pushed or popped from the direction stack. -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. +\subsection{\nod {marginkern} nodes} -\subsubsection{margin_kern nodes} +\topicindex {nodes+paragraphs} +\topicindex {paragraphs} +\topicindex {protrusion} + +Margin kerns result from protrusion. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR -\NC \type{subtype} \NC number \NC \showsubtypes{margin_kern} \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{subtype} \NC number \NC \showsubtypes{marginkern} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the advance of the kern \NC \NR \NC \type{glyph} \NC node \NC the glyph to be used \NC \NR +\LL \stoptabulate -\subsection{Math nodes} +\stopsection + +\startsection[title={Math noads}] + +\topicindex {nodes+math} +\topicindex {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} +\subsection{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 @@ -467,58 +577,62 @@ these cases (in the following node descriptions these are indicated by the word The \type {next} and \type {prev} fields for these subnodes are unused. -\subsubsubsection{math_char and math_text_char subnodes} +\subsection{\nod {math_char} and \nod {math_text_char} subnodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{char} \NC number \NC the character index \NC \NR \NC \type{fam} \NC number \NC the family number \NC \NR +\LL \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 +The \nod {math_char} is the simplest subnode field, it contains the character +and family for a single glyph object. The \nod {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} +\subsection{\nod {sub_box} and \nod {sub_mlist} subnodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{head/list} \NC node \NC list of nodes \NC \NR +\LL \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}, +These two subnode types are used for subsidiary list items. For \nod {sub_box}, +the \type {head} points to a \quote {normal} vbox or hbox. For \nod {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. +its internal link structure is correct, otherwise an error is triggered. -\subsubsection{Math delimiter subnode} +\subsection{\nod {delim} subnodes} 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[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{small_char} \NC number \NC character index of base character \NC \NR \NC \type{small_fam} \NC number \NC family number of base character \NC \NR \NC \type{large_char} \NC number \NC character index of next larger character \NC \NR \NC \type{large_fam} \NC number \NC family number of next larger character \NC \NR +\LL \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 +font that is set for the \type {small_fam} is expected to provide the large version as an extension to the \type {small_char}. -\subsubsection{Math core nodes} +\subsection{Math core nodes} -First, there are the objects (the \TEX book calls then \quote {atoms}) that are +First, there are the objects (the \TEX book calls them \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. @@ -526,6 +640,8 @@ into a single node type with separate subtypes for differentiation. Some noads have an option field. The values in this bitset are common: \starttabulate[|l|r|] +\DB meaning \BC bits \NC \NR +\TB \NC set \NC \type{0x08} \NC \NR \NC internal \NC \type{0x00} + \type{0x08} \NC \NR \NC internal \NC \type{0x01} + \type{0x08} \NC \NR @@ -538,24 +654,28 @@ Some noads have an option field. The values in this bitset are common: \NC no sub script \NC \type{0x21} + \type{0x08} \NC \NR \NC no super script \NC \type{0x22} + \type{0x08} \NC \NR \NC no script \NC \type{0x23} + \type{0x08} \NC \NR +\LL \stoptabulate -\subsubsubsection{simple nodes} +\subsection{simple \nod {noad} nodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{noad} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{nucleus} \NC kernel node \NC base \NC \NR \NC \type{sub} \NC kernel node \NC subscript \NC \NR \NC \type{sup} \NC kernel node \NC superscript \NC \NR \NC \type{options} \NC number \NC bitset of rendering options \NC \NR +\LL \stoptabulate -\subsubsubsection{accent nodes} +\subsection{\nod {accent} nodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{accent} \NC \NR \NC \type{nucleus} \NC kernel node \NC base \NC \NR \NC \type{sub} \NC kernel node \NC subscript \NC \NR @@ -563,57 +683,65 @@ Some noads have an option field. The values in this bitset are common: \NC \type{accent} \NC kernel node \NC top accent \NC \NR \NC \type{bot_accent} \NC kernel node \NC bottom accent \NC \NR \NC \type{fraction} \NC number \NC larger step criterium (divided by 1000) \NC \NR +\LL \stoptabulate -\subsubsubsection{style nodes} +\subsection{\nod {style} nodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{style} \NC string \NC contains the style \NC \NR +\LL \stoptabulate There are eight possibilities for the string value: one of \type {display}, \type {text}, \type {script}, or \type {scriptscript}. Each of these can have be prefixed by \type {cramped}. -\subsubsubsection{choice nodes} +\subsection{\nod {choice} nodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{display} \NC node \NC list of display size alternatives \NC \NR \NC \type{text} \NC node \NC list of text size alternatives \NC \NR \NC \type{script} \NC node \NC list of scriptsize alternatives \NC \NR \NC \type{scriptscript} \NC node \NC list of scriptscriptsize alternatives \NC \NR +\LL \stoptabulate Warning: never assign a node list to the \type {display}, \type {text}, \type {script}, or \type {scriptscript} field unless you are sure its internal link -structure is correct, otherwise an error may be result. +structure is correct, otherwise an error can occur. -\subsubsubsection{radical nodes} +\subsection{\nod {radical} nodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{radical} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{nucleus} \NC kernel node \NC base \NC \NR \NC \type{sub} \NC kernel node \NC subscript \NC \NR \NC \type{sup} \NC kernel node \NC superscript \NC \NR \NC \type{left} \NC delimiter node \NC \NC \NR -\NC \type{degree} \NC kernel node \NC only set by \type {\Uroot} \NC \NR +\NC \type{degree} \NC kernel node \NC only set by \lpr {Uroot} \NC \NR \NC \type{width} \NC number \NC required width \NC \NR \NC \type{options} \NC number \NC bitset of rendering options \NC \NR +\LL \stoptabulate Warning: never assign a node list to the \type {nucleus}, \type {sub}, \type {sup}, \type {left}, or \type {degree} field unless you are sure its internal -link structure is correct, otherwise an error may be result. +link structure is correct, otherwise an error can be triggered. -\subsubsubsection{fraction nodes} +\subsection{\nod {fraction} nodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC (optional) width of the fraction \NC \NR \NC \type{num} \NC kernel node \NC numerator \NC \NR @@ -622,16 +750,18 @@ link structure is correct, otherwise an error may be result. \NC \type{right} \NC delimiter node \NC right side symbol \NC \NR \NC \type{middle} \NC delimiter node \NC middle symbol \NC \NR \NC \type{options} \NC number \NC bitset of rendering options \NC \NR +\LL \stoptabulate Warning: never assign a node list to the \type {num}, or \type {denom} field unless you are sure its internal link structure is correct, otherwise an error -may be result. +can result. -\subsubsubsection{fence nodes} +\subsection{\nod {fence} nodes} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{subtype} \NC number \NC \showsubtypes{fence} \NC \NR \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{delim} \NC delimiter node \NC delimiter specification \NC \NR @@ -640,15 +770,18 @@ may be result. \NC \type{depth} \NC number \NC required depth \NC \NR \NC \type{options} \NC number \NC bitset of rendering options \NC \NR \NC \type{class} \NC number \NC spacing related class \NC \NR +\LL \stoptabulate Warning: some of these fields are used by the renderer and might get adapted in the process. -\subsection{whatsit nodes} +\stopsection + +\startsection[title={Front|-|end whatsits}] -Whatsit nodes come in many subtypes that you can ask for by running -\type {node.whatsits()}: +Whatsit nodes come in many subtypes that you can ask for them by running +\type {node.whatsits}: \startluacode for id, name in table.sortedpairs(node.whatsits()) do context.type(name) @@ -659,44 +792,53 @@ Whatsit nodes come in many subtypes that you can ask for by running \stopluacode . % period -\subsubsection{front|-|end whatsits} +Some of them are generic and independent of the output mode and others are +specific to the chosen backend: \DVI\ or \PDF. Here we discuss the generic +font|-|end nodes nodes. -\subsubsubsection{open whatsits} +\subsection{\whs {open}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR \NC \type{name} \NC string \NC file name \NC \NR \NC \type{ext} \NC string \NC file extension \NC \NR \NC \type{area} \NC string \NC file area (this may become obsolete) \NC \NR +\LL \stoptabulate -\subsubsubsection{write whatsits} +\subsection{\whs {write}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR \NC \type{data} \NC table \NC a table representing the token list to be written \NC \NR +\LL \stoptabulate -\subsubsubsection{close whatsits} +\subsection{\whs {close}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR +\LL \stoptabulate -\subsubsubsection{user_defined whatsits} +\subsection{\whs {user_defined}} 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[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{user_id} \NC number \NC id number \NC \NR \NC \type{type} \NC number \NC type of the value \NC \NR @@ -704,103 +846,129 @@ will simply step over such whatsits without ever looking at the contents. \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 +\LL \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") +value if the first character of the type name (so you can use string.byte("l") instead of \type {108}). \starttabulate[|r|c|p|] -\BC value \BC meaning \BC explanation \NC \NR +\DB value \BC meaning \BC explanation \NC \NR +\TB \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 +\LL \stoptabulate -\subsubsubsection{save_pos whatsits} +\subsection{\whs {save_pos}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR +\LL \stoptabulate -\subsubsubsection{late_lua whatsits} +\subsection{\whs {late_lua}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR -\NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{data} \NC string \NC data to execute \NC \NR -\NC \type{string} \NC string \NC data to execute \NC \NR -\NC \type{name} \NC string \NC the name to use for \LUA\ error reporting \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{data} \NC string or function \NC the to be written information stored as \LUA\ value \NC \NR +\NC \type{token} \NC string \NC the to be written information stored as token list \NC \NR +\NC \type{name} \NC string \NC the name to use for \LUA\ error reporting \NC \NR +\LL \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 {data} field is converted to a token list, cf.\ use as \lpr {latelua}. The \type {string} version is treated as a literal string. -\subsubsection{\DVI\ backend whatsits} +\stopsection -\subsubsection{special whatsits} +\startsection[title={\DVI\ backend whatsits}] + +\subsection{\whs {special}} + +There is only one \DVI\ backend whatsit, and it just flushes its content to the +output file. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{data} \NC string \NC the \type {\special} information \NC \NR +\NC \type{data} \NC string \NC the \prm {special} information \NC \NR +\LL \stoptabulate -\subsubsection{\PDF\ backend whatsits} +\stopsection + +\startsection[title={\PDF\ backend whatsits}] -\subsubsubsection{pdf_literal whatsits} +\subsection{\whs {pdf_literal}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR -\NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{mode} \NC number \NC the \quote {mode} setting of this literal \NC \NR -\NC \type{data} \NC string \NC the \type {\pdfliteral} information \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{mode} \NC number \NC the \quote {mode} setting of this literal \NC \NR +\NC \type{data} \NC string \NC the to be written information stored as \LUA\ string \NC \NR +\NC \type{token} \NC string \NC the to be written information stored as token list \NC \NR +\LL \stoptabulate Possible mode values are: -\starttabulate[|l|p|] -\BC value \BC keyword \NC \NR +\starttabulate[|c|p|] +\DB value \BC keyword \NC \NR +\TB \NC 0 \NC \type{origin} \NC \NR \NC 1 \NC \type{page} \NC \NR \NC 2 \NC \type{direct} \NC \NR \NC 3 \NC \type{raw} \NC \NR \NC 4 \NC \type{text} \NC \NR +\LL \stoptabulate -The higher the number, the less checking and the more you can run into troubles. +The higher the number, the less checking and the more you can run into trouble. Especially the \type {raw} variant can produce bad \PDF\ so you can best check what you generate. -\subsubsubsection{pdf_refobj whatsits} +\subsection{\whs {pdf_refobj}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_annot whatsits} +\subsection{\whs {pdf_annot}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR \NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR \NC \type{data} \NC string \NC the annotation data \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_start_link whatsits} +\subsection{\whs {pdf_start_link}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR @@ -808,19 +976,23 @@ what you generate. \NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR \NC \type{link_attr} \NC table \NC the link attribute token list \NC \NR \NC \type{action} \NC node \NC the action to perform \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_end_link whatsits} +\subsection{\whs {pdf_end_link}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_dest whatsits} +\subsection{\whs {pdf_dest}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR @@ -831,45 +1003,54 @@ what you generate. \NC \type{dest_type} \NC number \NC type of destination \NC \NR \NC \type{xyz_zoom} \NC number \NC the zoom factor (times 1000) \NC \NR \NC \type{objnum} \NC number \NC the \PDF\ object number \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_action whatsits} +\subsection{\whs {pdf_action}} -These are a special kind of item that only appears inside \PDF\ start link +These are a special kind of items that only appear inside \PDF\ start link objects. \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{action_type} \NC number \NC the kind of action involved \NC \NR \NC \type{action_id} \NC number or string \NC token list reference or string \NC \NR \NC \type{named_id} \NC number \NC the index of the destination \NC \NR \NC \type{file} \NC string \NC the target filename \NC \NR \NC \type{new_window} \NC number \NC the window state of the target \NC \NR \NC \type{data} \NC string \NC the name of the destination \NC \NR +\LL \stoptabulate Valid action types are: \starttabulate[|l|l|] -\NC 0 \NC \type{page} \NC \NR -\NC 1 \NC \type{goto} \NC \NR -\NC 2 \NC \type{thread} \NC \NR -\NC 3 \NC \type{user} \NC \NR +\DB value \BC meaning \NC \NR +\TB +\NC 0 \NC \type{page} \NC \NR +\NC 1 \NC \type{goto} \NC \NR +\NC 2 \NC \type{thread} \NC \NR +\NC 3 \NC \type{user} \NC \NR +\LL \stoptabulate Valid window types are: \starttabulate[|l|l|] -\NC 0 \NC \type{notset} \NC \NR -\NC 1 \NC \type{new} \NC \NR -\NC 2 \NC \type{nonew} \NC \NR +\DB value \BC meaning \NC \NR +\TB +\NC 0 \NC \type{notset} \NC \NR +\NC 1 \NC \type{new} \NC \NR +\NC 2 \NC \type{nonew} \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_thread whatsits} +\subsection{\whs {pdf_thread}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR @@ -878,12 +1059,14 @@ Valid window types are: \NC \type{tread_id} \NC number \NC the thread id \NC \NR \NC \NC string \NC the thread name \NC \NR \NC \type{thread_attr} \NC number \NC extra thread information \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_start_thread whatsits} +\subsection{\whs {pdf_start_thread}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR \NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR @@ -892,48 +1075,63 @@ Valid window types are: \NC \type{tread_id} \NC number \NC the thread id \NC \NR \NC \NC string \NC the thread name \NC \NR \NC \type{thread_attr} \NC number \NC extra thread information \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_end_thread whatsits} +\subsection{\whs {pdf_end_thread}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_colorstack whatsits} +\subsection{\whs {pdf_colorstack}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{stack} \NC number \NC colorstack id number \NC \NR \NC \type{command} \NC number \NC command to execute \NC \NR \NC \type{data} \NC string \NC data \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_setmatrix whatsits} +\subsection{\whs {pdf_setmatrix}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{data} \NC string \NC data \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_save whatsits} +\subsection{\whs {pdf_save}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR +\LL \stoptabulate -\subsubsubsection{pdf_restore whatsits} +\subsection{\whs {pdf_restore}} \starttabulate[|l|l|p|] -\BC field \BC type \BC explanation \NC \NR +\DB field \BC type \BC explanation \NC \NR +\TB \NC \type{attr} \NC node \NC list of attributes \NC \NR +\LL \stoptabulate -\section{The \type {node} library} +\stopsection + +\startsection[title={The \type {node} library}][library=node] + +\subsection {Introduction} 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 @@ -943,8 +1141,7 @@ insert \LUATEX\ node objects, the core objects within the typesetter. \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}: +Each node has at least the three fields \type {next}, \type {id}, and \type {subtype}: \startitemize[intro] @@ -969,10 +1166,9 @@ Each node has at least the three fields \type {next}, \type {id}, and \type \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]. +the \type {subtype}) of the node. -Support for \type {unset} (alignment) nodes is partial: they can be queried and +Support for \nod {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 @@ -987,76 +1183,90 @@ call the node freeing functions yourself when you are no longer in need of a nod (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. +you did not create nodes that are referenced more than once. Normally the setters +and getters handle this for you. There are statistics available with regards to the allocated node memory, which can be handy for tracing. -\subsection{Node handling functions} +\subsection{\type {is_node}} -\subsubsection{\type {node.is_node}} +\topicindex {nodes+functions} + +\libindex {is_node} \startfunctioncall -<boolean> t = +<boolean|integer> t = node.is_node(<any> item) \stopfunctioncall -This function returns true if the argument is a userdata object of -type \type {<node>}. +This function returns a number (the internal index of the node) if the argument +is a userdata object of type \type {<node>} and false when no node is passed. -\subsubsection{\type {node.types}} +\subsection{\type {types} and \type {whatsits}} + +\libindex {types} +\libindex {whatsits} + +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. \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}} +\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 {types}, +except that it provides an array of \type {subtype} mappings. \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. +\subsection{\type {id}} -\subsubsection{\type {node.id}} +\libindex{id} + +This converts a single type name to its internal numeric representation. \startfunctioncall <number> id = node.id(<string> type) \stopfunctioncall -This converts a single type name to its internal numeric representation. +\subsection{\type {type} and \type {subtype}} -\subsubsection{\type {node.subtype}} +\libindex {type} +\libindex {subtype} + +In the argument is a number, then the next 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. \startfunctioncall -<number> subtype = - node.subtype(<string> type) +<string> type = + node.type(<any> n) \stopfunctioncall -This converts a single whatsit name to its internal numeric representation (\type -{subtype}). - -\subsubsection{\type {node.type}} +This next one converts a single whatsit name to its internal numeric +representation (\type {subtype}). \startfunctioncall -<string> type = - node.type(<any> n) +<number> subtype = + node.subtype(<string> type) \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. +\subsection{\type {fields}} + +\libindex {fields} -\subsubsection{\type {node.fields}} +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. \startfunctioncall <table> t = @@ -1065,24 +1275,29 @@ otherwise. 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. +The function accepts string \type {id} and \type {subtype} values as well. -This function accepts string \type {id} and \type {subtype} values as well. +\subsection{\type {has_field}} -\subsubsection{\type {node.has_field}} +\libindex {has_field} + +This function returns a boolean that is only true if \type {n} is +actually a node, and it has the 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. +\subsection{\type {new}} -\subsubsection{\type {node.new}} +\libindex{new} + +The \type {new} function creates a new node. All its fields are initialized to +either zero or \type {nil} except for \type {id} and \type {subtype}. Instead of +numbers you can also use strings (names). If you create a new \nod {whatsit} node +the second argument is required. As with all node functions, this function +creates a node at the \TEX\ level. \startfunctioncall <node> n = @@ -1091,15 +1306,16 @@ actually a node, and it has the field. 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. +\subsection{\type {free}, \type {flush_node} and \type {flush_list}} -This function accepts string \type {id} and \type {subtype} values as well. +\libindex{free} +\libindex{flush_node} +\libindex{flush_list} -\subsubsection{\type {node.free} and \type {node.flush_node}} +The next one 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. \startfunctioncall <node> next = @@ -1107,35 +1323,33 @@ This function accepts string \type {id} and \type {subtype} values as well. 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}} +A list starting with node \type {n} can be flushed from \TEX's memory too. 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. \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. +\subsection{\type {copy} and \type {copy_list}} -\subsubsection{\type {node.copy}} +\libindex{copy} +\libindex{copy_list} + +This 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. \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}} +A deep copy of the node list that starts at \type {n} can be created too. If +\type {m} is also given, the copy stops just before node \type {m}. \startfunctioncall <node> m = @@ -1144,42 +1358,37 @@ of a hlist or vlist node. Only the \type {next} field is not copied. 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. 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. + +\subsection{\type {prev} and \type{next}} -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. +\libindex{prev} +\libindex{next} -\subsubsection{\type {node.next}} +These returns the node preceding or following the given node, or \type {nil} if +there is no such node. \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. +\subsection{\type {current_attr}} + +\libindex{current_attr} -\subsubsection{\type {node.current_attr}} +This returns the currently active list of attributes, if there is one. \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 @@ -1209,7 +1418,16 @@ 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}} +\subsection{\type {hpack}} + +\libindex {hpack} + +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. \startfunctioncall <node> h, <number> b = @@ -1220,21 +1438,22 @@ list assigned to them. 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: there can be unexpected side|-|effects to this function, like updating +some of the \prm {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! -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! +\subsection{\type {vpack}} -\subsubsection{\type {node.vpack}} +\libindex {vpack} + +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. \startfunctioncall <node> h, <number> b = @@ -1245,17 +1464,26 @@ the \type {list} field to \type {nil} beforehand. And in a similar way, calling 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 {hpack} for a few memory allocation caveats. -The second return value is the badness of the generated box. +\subsection{\type {prepend_prevdepth}} -See the description of \type {node.hpack()} for a few memory allocation caveats. +\libindex {prepend_prevdepth} -\subsubsection{\type {node.dimensions}, \type {node.rangedimensions}} +This function is somewhat special in the sense that it is an experimental helper +that adds the interlinespace to a line keeping the baselineskip and lineskip into +account. + +\startfunctioncall +<node> n, <number> delta = + node.prepend_prevdepth(<node> n,<number> prevdepth) +\stopfunctioncall + +\subsection{\type {dimensions} and \type {rangedimensions}} + +\libindex{dimensions} +\libindex{rangedimensions} \startfunctioncall <number> w, <number> h, <number> d = @@ -1320,7 +1548,9 @@ cases: node.rangedimensions(<node> parent, <node> first, <node> last) \stopfunctioncall -\subsubsection{\type {node.mlist_to_hlist}} +\subsection{\type {mlist_to_hlist}} + +\libindex {mlist_to_hlist} \startfunctioncall <node> h = @@ -1329,9 +1559,9 @@ cases: 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}. +as for the callback \cbk {mlist_to_hlist}. -\subsubsection{\type {node.slide}} +\subsection{\type {slide}} \startfunctioncall <node> m = @@ -1342,7 +1572,9 @@ 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}} +\subsection{\type {tail}} + +\libindex {tail} \startfunctioncall <node> m = @@ -1351,7 +1583,10 @@ nodes. Returns the last node of the node list that starts at \type {n}. -\subsubsection{\type {node.length}} +\subsection{\type {length} and type {count}} + +\libindex {length} +\libindex {count} \startfunctioncall <number> i = @@ -1364,8 +1599,6 @@ 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) @@ -1376,14 +1609,29 @@ list. The node \type {m} is not counted. 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. +counted. This function also accept string \type {id}'s. + +\subsection{\type {is_char} and \type {is_glyph}} -This function also accept string \type {id}'s. +\libindex {is_char} +\libindex {is_glyph} -\subsubsection{\type {node.traverse}} +The subtype of a glyph node signals if the glyph is already turned into a character reference +or not. \startfunctioncall -<node> t = +<boolean> b = + node.is_char(<node> n) +<boolean> b = + node.is_glyph(<node> n) +\stopfunctioncall + +\subsection{\type {traverse}} + +\libindex {traverse} + +\startfunctioncall +<node> t, id, subtype = node.traverse(<node> n) \stopfunctioncall @@ -1426,10 +1674,12 @@ 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}} +\subsection{\type {traverse_id}} + +\libindex {traverse_id} \startfunctioncall -<node> t = +<node> t, subtype = node.traverse_id(<number> id, <node> n) \stopfunctioncall @@ -1454,17 +1704,45 @@ See the previous section for details. The change is in the local function \type end \stoptyping -\subsubsection{\type {node.traverse_char}} +\subsection{\type {traverse_char} and \type {traverse_glyph}} + +\libindex {traverse_char} +\libindex {traverse_glyph} -This iterators loops over the glyph nodes in a list. Only nodes with a subtype -less than 256 are seen. +The \type{traverse_char} iterator loops over the \nod {glyph} nodes in a list. +Only nodes with a subtype less than 256 are seen. \startfunctioncall -<node> n = +<node> n, font, char = node.traverse_char(<node> n) \stopfunctioncall -\subsubsection{\type {node.has_glyph}} +The \type{traverse_glyph} iterator loops over a list and returns the list and +filters all glyphs: + +\startfunctioncall +<node> n, font, char = + node.traverse_glyph(<node> n) +\stopfunctioncall + +\subsection{\type {traverse_list}} + +\libindex {traverse_list} + +This iterator loops over the \nod {hlist} and \nod {vlist} nodes in a list. + +\startfunctioncall +<node> n, id, subtype, list = + node.traverse_list(<node> n) +\stopfunctioncall + +The four return values can save some time compared to fetching these fields but +in practice you seldom need them all. So consider it a (side effect of +experimental) convenience. + +\subsection{\type {has_glyph}} + +\libindex {has_glyph} This function returns the first glyph or disc node in the given list: @@ -1473,7 +1751,9 @@ This function returns the first glyph or disc node in the given list: node.has_glyph(<node> n) \stopfunctioncall -\subsubsection{\type {node.end_of_math}} +\subsection{\type {end_of_math}} + +\libindex {end_of_math} \startfunctioncall <node> t = @@ -1481,11 +1761,13 @@ This function returns the first glyph or disc node in the given list: \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 +the given node is a math end node this helper returns that node, else it follows +the list and returns the next math endnote. If no such node is found nil is returned. -\subsubsection{\type {node.remove}} +\subsection{\type {remove}} + +\libindex {remove} \startfunctioncall <node> head, current = @@ -1501,7 +1783,9 @@ 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}} +\subsection{\type {insert_before}} + +\libindex {insert_before} \startfunctioncall <node> head, new = @@ -1515,7 +1799,9 @@ 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}} +\subsection{\type {insert_after}} + +\libindex {insert_after} \startfunctioncall <node> head, new = @@ -1528,7 +1814,9 @@ following \type {head}. It is your responsibility to make sure that \type 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}} +\subsection{\type {first_glyph}} + +\libindex {first_glyph} \startfunctioncall <node> n = @@ -1542,7 +1830,9 @@ 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}} +\subsection{\type {ligaturing}} + +\libindex {ligaturing} \startfunctioncall <node> h, <node> t, <boolean> success = @@ -1555,7 +1845,9 @@ Apply \TEX-style ligaturing to the specified nodelist. The tail node \type {m} i 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}} +\subsection{\type {kerning}} + +\libindex {kerning} \startfunctioncall <node> h, <node> t, <boolean> success = @@ -1569,7 +1861,10 @@ 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} and \type {node.unprotect_glyph}} +\subsection{\type {unprotect_glyph[s]}} + +\libindex {unprotect_glyphs} +\libindex {unprotect_glyph} \startfunctioncall node.unprotect_glyph(<node> n) @@ -1578,9 +1873,12 @@ node.unprotect_glyphs(<node> n,[<node> n]) 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. The second argument is option and indicates the end of a range. +processing. The second argument is optional and indicates the end of a range. -\subsubsection{\type {node.protect_glyphs} and \type {node.protect_glyph}} +\subsection{\type {protect_glyph[s]}} + +\libindex {protect_glyphs} +\libindex {protect_glyph} \startfunctioncall node.protect_glyph(<node> n) @@ -1591,9 +1889,11 @@ 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. The second argument is -option and indicates the end of a range. +optional and indicates the end of a range. + +\subsection{\type {last_node}} -\subsubsection{\type {node.last_node}} +\libindex {last_node} \startfunctioncall <node> n = @@ -1603,17 +1903,21 @@ option and indicates the end of a range. 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}} +\subsection{\type {write}} + +\libindex {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! +This 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! You mignt need +to enforce horizontal mode in order for this to work as expected. + +\subsection{\type {protrusion_skippable}} -\subsubsection{\type {node.protrusion_skippable}} +\libindex {protrusion_skippable} \startfunctioncall <boolean> skippable = @@ -1623,9 +1927,13 @@ either! Returns \type {true} if, for the purpose of line boundary discovery when character protrusion is active, this node can be skipped. -\subsection{Glue handling} +\stopsection + +\startsection[title={Glue handling}][library=node] -\subsubsection{\type {node.setglue}} +\subsection{\type {setglue}} + +\libindex {setglue} You can set the properties of a glue in one go. If you pass no values, the glue will become a zero glue. @@ -1645,9 +1953,11 @@ will only adapt the width and shrink. When a list node is passed, you set the glue, order and sign instead. -\subsubsection{\type {node.getglue}} +\subsection{\type {getglue}} + +\libindex {getglue} -The next call will return 5 values (or northing when no glue is passed). +The next call will return 5 values or nothing when no glue is passed. \startfunctioncall <integer> width, <integer> stretch, <integer> shrink, <integer> stretch_order, @@ -1660,7 +1970,9 @@ with \type {tex.get}). When a list node is passed, you get back the glue that is set, the order of that glue and the sign. -\subsubsection{\type {node.is_zero_glue}} +\subsection{\type {is_zero_glue}} + +\libindex {is_zero_glue} This function returns \type {true} when the width, stretch and shrink properties are zero. @@ -1670,13 +1982,61 @@ are zero. node.is_zero_glue(<node> n) \stopfunctioncall -\subsection{Attribute handling} +\stopsection + +\startsection[title={Attribute handling}][library=node] + +\subsection{Attributes} + +\topicindex {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. 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}} +\subsection{\nod {attribute_list} nodes} + +\topicindex {nodes+attributes} + +An \nod {attribute_list} item is used as a head pointer for a list of attribute +items. It has only one user-visible field: + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{next} \NC node \NC pointer to the first attribute \NC \NR +\LL +\stoptabulate + +\subsection{\nod {attr} nodes} + +A normal node's attribute field will point to an item of type \nod +{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[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{next} \NC node \NC pointer to the next attribute \NC \NR +\NC \type{number} \NC number \NC the attribute type id \NC \NR +\NC \type{value} \NC number \NC the attribute value \NC \NR +\LL +\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{\type {has_attribute}} + +\libindex {has_attribute} \startfunctioncall <number> v = @@ -1689,7 +2049,9 @@ 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}} +\subsection{\type {get_attribute}} + +\libindex {get_attribute} \startfunctioncall <number> v = @@ -1697,9 +2059,12 @@ or, if no match is found, \type {nil}. \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}. +value, or, if no match is found, \type {nil}. If no \type {id} is given then the +zero attributes is assumed. + +\subsection{\type {find_attribute}} -\subsubsection{\type {node.find_attribute}} +\libindex {find_attribute} \startfunctioncall <number> v, <node> n = @@ -1709,7 +2074,9 @@ value, or, if no match is found, \type {nil}. 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}} +\subsection{\type {set_attribute}} + +\libindex {set_attribute} \startfunctioncall node.set_attribute(<node> n, <number> id, <number> val) @@ -1718,7 +2085,9 @@ node.set_attribute(<node> n, <number> id, <number> val) Sets the attribute with number \type {id} to the value \type {val}. Duplicate assignments are ignored. -\subsubsection{\type {node.unset_attribute}} +\subsection{\type {unset_attribute}} + +\libindex {unset_attribute} \startfunctioncall <number> v = @@ -1734,7 +2103,9 @@ 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}} +\subsection{\type {slide}} + +\libindex {slide} This helper makes sure that the node lists is double linked and returns the found tail node. @@ -1751,13 +2122,16 @@ pointers but your other callbacks might expect proper \type {prev} pointers too. Future versions of \LUATEX\ can add more checking but this will not influence usage. -\subsubsection{\type {node.check_discretionary} and \type {node.check_discretionaries}} +\subsection{\type {check_discretionary}, \type {check_discretionaries}} + +\libindex{check_discretionary} +\libindex{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 +but when you add to list without reassigning you might end up in trouble when +the linebreak routine kicks in. You can call this function to check the list for issues with disc nodes. \startfunctioncall @@ -1768,7 +2142,9 @@ node.check_discretionaries(<node> head) 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.flatten_discretionaries}} +\subsection{\type {flatten_discretionaries}} + +\libindex {flatten_discretionaries} This function will remove the discretionaries in the list and inject the replace field when set. @@ -1777,45 +2153,51 @@ field when set. <node> head, count = node.flatten_discretionaries(<node> n) \stopfunctioncall -\subsubsection{\type {node.family_font}} +\subsection{\type {family_font}} + +\libindex {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. +When you pass 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 -\subsubsection{\type {node.set_synctex_fields} and \type {node.get_synctex_fields}} - -You can set and query the synctex fields, a file number aka tag and a line -number, for a glue, kern, hlist, vlist, rule and math nodes as well as glyph -nodes (although this last one are not used in native synctex). +\stopsection -\startfunctioncall -node.set_synctex_fields(<integer> f, <integer> l) -<integer> f, <integer> l = - node.get_synctex_fields(<node> n) -\stopfunctioncall +\startsection[title={Two access models}][library=node] -Of course you need to know what you're doing as no checking on sane values takes -place. Also, the synctex interpreter used in editors is rather peculiar and has -some assumptions (heuristics). +\topicindex{nodes+direct} +\topicindex{direct nodes} -\section{Two access models} +\libindex {todirect} +\libindex {tonode} +\libindex {tostring} -Deep down in \TEX\ a node has a number which is an numeric entry in a memory +Deep down in \TEX\ a node has a number which is a 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. +number often is reported when you print node related information. You go from +userdata nodes and there numeric references and back with: + +\startfunctioncall +<integer> d = node.todirect(<node> n)) +<node> n = node.tonode(<integer> d)) +\stopfunctioncall + +The userdata model is rather robust as it is a virtual interface with some +additional checking while the more direct access which uses the node numbers +directly. However, even with userdata you can get into troubles when you free +nodes that are no longer allocated or mess up lists. if you apply \type +{tostring} to a node you see its internal (direct) number and id. -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: +The first model provides key based access while the second always accesses fields +via functions: \starttyping nodeobject.char @@ -1823,19 +2205,19 @@ 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 +should not depend on that property but treat it as 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). +the direct one when speed might be a real issue. For that reason \LUATEX\ 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 nodes are accessed 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 @@ -1873,8 +2255,10 @@ end Some accessors are used frequently and for these we provide more efficient helpers: \starttabulate[|l|p|] +\DB function \BC explanation \NC \NR +\TB \NC \type{getnext} \NC parsing nodelist always involves this one \NC \NR -\NC \type{getprev} \NC used less but is logical companion to \type {getnext} \NC \NR +\NC \type{getprev} \NC used less but a logical companion to \type {getnext} \NC \NR \NC \type{getboth} \NC returns the next and prev pointer of a node \NC \NR \NC \type{getid} \NC consulted a lot \NC \NR \NC \type{getsubtype} \NC consulted less but also a topper \NC \NR @@ -1883,13 +2267,16 @@ Some accessors are used frequently and for these we provide more efficient helpe \NC \type{getwhd} \NC returns the \type {width}, \type {height} and \type {depth} of a list, rule or (unexpanded) glyph as well as glue (its spec is looked at) and unset nodes\NC \NR \NC \type{getdisc} \NC returns the \type {pre}, \type {post} and \type {replace} fields and - optionally when true is passed also the tail fields. \NC \NR + optionally when true is passed also the tail fields \NC \NR \NC \type{getlist} \NC we often parse nested lists so this is a convenient one too \NC \NR \NC \type{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 \type{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 \type{getbox} \NC gets the given box (a list node) \NC \NR +\NC \type{getoffsets} \NC gets the \type {xoffset} and \type {yoffset} of a glyph or + \type {left} and \type {right} values of a rule \NC \NR +\LL \stoptabulate In the direct namespace there are more such helpers and most of them are @@ -1910,145 +2297,157 @@ directmode setter \type {setlink} takes a list of nodes and will link them, thereby ignoring \type {nil} entries. The first valid node is returned (beware: for good reason it assumes single nodes). For rarely used fields no helpers are provided and there are a few that probably are used seldom too but were added for -consistency. You can of course always define additional accessor using \type -{getfield} and \type {setfield} with little overhead. - -% \startcolumns[balance=yes] +consistency. You can of course always define additional accessors using \type +{getfield} and \type {setfield} with little overhead. When the second argument of +\type {setattributelist} is \type {true} the current attribute list is assumed. \def\yes{$+$} \def\nop{$-$} +\def\supported#1#2#3% + {\NC \type{#1} + \NC \ifx#2\yes\libidx{node} {#1}\fi #2 + \NC \ifx#3\yes\libidx{node.direct}{#1}\fi #3 \NC + \NR} + \starttabulate[|l|c|c|] -\HL -\BC function \BC node \BC direct \NC \NR -\HL -%NC \type {do_ligature_n} \NC \yes \NC \yes \NC \NR % was never documented and experimental -\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 {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 {getattributelist} \NC \nop \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 {getcomponents} \NC \nop \NC \yes \NC \NR -\NC \type {getdepth} \NC \nop \NC \yes \NC \NR -\NC \type {getdir} \NC \nop \NC \yes \NC \NR -\NC \type {getdisc} \NC \yes \NC \yes \NC \NR -\NC \type {getfam} \NC \nop \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 {getheight} \NC \nop \NC \yes \NC \NR -\NC \type {getid} \NC \yes \NC \yes \NC \NR -\NC \type {getkern} \NC \nop \NC \yes \NC \NR -\NC \type {getlang} \NC \nop \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 {getnucleus} \NC \nop \NC \yes \NC \NR -\NC \type {getoffsets} \NC \nop \NC \yes \NC \NR -\NC \type {getpenalty} \NC \nop \NC \yes \NC \NR -\NC \type {getprev} \NC \yes \NC \yes \NC \NR -\NC \type {getproperty} \NC \yes \NC \yes \NC \NR -\NC \type {getshift} \NC \nop \NC \yes \NC \NR -\NC \type {getwidth} \NC \nop \NC \yes \NC \NR -\NC \type {getwhd} \NC \nop \NC \yes \NC \NR -\NC \type {getsub} \NC \nop \NC \yes \NC \NR -\NC \type {getsubtype} \NC \yes \NC \yes \NC \NR -\NC \type {getsup} \NC \nop \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 {rangedimensions} \NC \yes \NC \yes \NC \NR -\NC \type {remove} \NC \yes \NC \yes \NC \NR -\NC \type {set_attribute} \NC \nop \NC \yes \NC \NR -\NC \type {setattributelist} \NC \nop \NC \yes \NC \NR -\NC \type {setboth} \NC \nop \NC \yes \NC \NR -\NC \type {setbox} \NC \nop \NC \yes \NC \NR -\NC \type {setchar} \NC \nop \NC \yes \NC \NR -\NC \type {setcomponents} \NC \nop \NC \yes \NC \NR -\NC \type {setdepth} \NC \nop \NC \yes \NC \NR -\NC \type {setdir} \NC \nop \NC \yes \NC \NR -\NC \type {setdisc} \NC \nop \NC \yes \NC \NR -\NC \type {setfield} \NC \yes \NC \yes \NC \NR -\NC \type {setfont} \NC \nop \NC \yes \NC \NR -\NC \type {setglue} \NC \yes \NC \yes \NC \NR -\NC \type {setheight} \NC \nop \NC \yes \NC \NR -\NC \type {setid} \NC \nop \NC \yes \NC \NR -\NC \type {setkern} \NC \nop \NC \yes \NC \NR -\NC \type {setlang} \NC \nop \NC \yes \NC \NR -\NC \type {setleader} \NC \nop \NC \yes \NC \NR -\NC \type {setlist} \NC \nop \NC \yes \NC \NR -\NC \type {setnext} \NC \nop \NC \yes \NC \NR -\NC \type {setnucleus} \NC \nop \NC \yes \NC \NR -\NC \type {setoffsets} \NC \nop \NC \yes \NC \NR -\NC \type {setpenalty} \NC \nop \NC \yes \NC \NR -\NC \type {setprev} \NC \nop \NC \yes \NC \NR -\NC \type {setproperty} \NC \nop \NC \yes \NC \NR -\NC \type {setshift} \NC \nop \NC \yes \NC \NR -\NC \type {setwidth} \NC \nop \NC \yes \NC \NR -\NC \type {setwhd} \NC \nop \NC \yes \NC \NR -\NC \type {setsub} \NC \nop \NC \yes \NC \NR -\NC \type {setsubtype} \NC \nop \NC \yes \NC \NR -\NC \type {setsup} \NC \nop \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 {uses_font} \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 -\NC \type {set_synctex_fields} \NC \yes \NC \yes \NC \NR -\NC \type {get_synctex_fields} \NC \yes \NC \yes \NC \NR +\DB function \BC node \BC direct \NC \NR +\TB +\supported {check_discretionaries} \yes \yes +\supported {check_discretionary} \yes \yes +\supported {copy_list} \yes \yes +\supported {copy} \yes \yes +\supported {count} \yes \yes +\supported {current_attr} \yes \yes +\supported {dimensions} \yes \yes +\supported {effective_glue} \yes \yes +\supported {end_of_math} \yes \yes +\supported {family_font} \yes \nop +\supported {fields} \yes \nop +\supported {find_attribute} \yes \yes +\supported {first_glyph} \yes \yes +\supported {flatten_discretionaries} \yes \yes +\supported {flush_list} \yes \yes +\supported {flush_node} \yes \yes +\supported {free} \yes \yes +\supported {get_attribute} \yes \yes +\supported {get_synctex_fields} \nop \yes +\supported {getattributelist} \nop \yes +\supported {getboth} \yes \yes +\supported {getbox} \nop \yes +\supported {getchar} \yes \yes +\supported {getcomponents} \nop \yes +\supported {getdepth} \nop \yes +\supported {getdirection} \nop \yes +\supported {getdir} \nop \yes +\supported {getdisc} \yes \yes +\supported {getfam} \nop \yes +\supported {getfield} \yes \yes +\supported {getfont} \yes \yes +\supported {getglue} \yes \yes +\supported {getheight} \nop \yes +\supported {getid} \yes \yes +\supported {getkern} \nop \yes +\supported {getlang} \nop \yes +\supported {getleader} \yes \yes +\supported {getlist} \yes \yes +\supported {getnext} \yes \yes +\supported {getnucleus} \nop \yes +\supported {getoffsets} \nop \yes +\supported {getpenalty} \nop \yes +\supported {getprev} \yes \yes +\supported {getproperty} \yes \yes +\supported {getshift} \nop \yes +\supported {getsubtype} \yes \yes +\supported {getsub} \nop \yes +\supported {getsup} \nop \yes +\supported {getdata} \nop \yes +\supported {getwhd} \yes \yes +\supported {getwidth} \nop \yes +\supported {has_attribute} \yes \yes +\supported {has_field} \yes \yes +\supported {has_glyph} \yes \yes +\supported {hpack} \yes \yes +\supported {id} \yes \nop +\supported {insert_after} \yes \yes +\supported {insert_before} \yes \yes +\supported {is_char} \yes \yes +\supported {is_direct} \nop \yes +\supported {is_glyph} \yes \yes +\supported {is_node} \yes \yes +\supported {is_zero_glue} \yes \yes +\supported {kerning} \yes \yes +\supported {last_node} \yes \yes +\supported {length} \yes \yes +\supported {ligaturing} \yes \yes +\supported {mlist_to_hlist} \yes \nop +\supported {new} \yes \yes +\supported {next} \yes \nop +\supported {prepend_prevdepth} \nop \yes +\supported {prev} \yes \nop +\supported {protect_glyphs} \yes \yes +\supported {protect_glyph} \yes \yes +\supported {protrusion_skippable} \yes \yes +\supported {rangedimensions} \yes \yes +\supported {remove} \yes \yes +\supported {set_attribute} \yes \yes +\supported {set_synctex_fields} \nop \yes +\supported {setattributelist} \nop \yes +\supported {setboth} \nop \yes +\supported {setbox} \nop \yes +\supported {setchar} \nop \yes +\supported {setcomponents} \nop \yes +\supported {setdepth} \nop \yes +\supported {setdirection} \nop \yes +\supported {setdir} \nop \yes +\supported {setdisc} \nop \yes +\supported {setfam} \nop \yes +\supported {setfield} \yes \yes +\supported {setfont} \nop \yes +\supported {setexpansion} \nop \yes +\supported {setglue} \yes \yes +\supported {setheight} \nop \yes +\supported {setkern} \nop \yes +\supported {setlang} \nop \yes +\supported {setleader} \nop \yes +\supported {setlink} \nop \yes +\supported {setlist} \nop \yes +\supported {setnext} \nop \yes +\supported {setnucleus} \nop \yes +\supported {setoffsets} \nop \yes +\supported {setpenalty} \nop \yes +\supported {setprev} \nop \yes +\supported {setproperty} \yes \yes +\supported {setshift} \nop \yes +\supported {setsplit} \nop \yes +\supported {setsubtype} \nop \yes +\supported {setsub} \nop \yes +\supported {setsup} \nop \yes +\supported {setwhd} \nop \yes +\supported {setwidth} \nop \yes +\supported {slide} \yes \yes +\supported {subtypes} \yes \nop +\supported {subtype} \yes \nop +\supported {tail} \yes \yes +\supported {todirect} \yes \yes +\supported {tonode} \yes \yes +\supported {tostring} \yes \yes +\supported {traverse_char} \yes \yes +\supported {traverse_glyph} \yes \yes +\supported {traverse_id} \yes \yes +\supported {traverse} \yes \yes +\supported {types} \yes \nop +\supported {type} \yes \nop +\supported {unprotect_glyphs} \yes \yes +\supported {unprotect_glyph} \yes \yes +\supported {unset_attribute} \yes \yes +\supported {usedlist} \yes \yes +\supported {uses_font} \yes \yes +\supported {vpack} \yes \yes +\supported {whatsits} \yes \nop +\supported {write} \yes \yes +\LL \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 @@ -2056,6 +2455,13 @@ taken for providing meta information about nodes. Note: The getters do only basi checking for valid keys. You should just stick to the keys mentioned in the sections that describe node properties. +Some of the getters and setters handle multiple node types, given that the field +is relevant. In that case, some field names are considered similar (like \type +{kern} and \type {width}, or \type {data} and \type {value}. In retrospect we +could have normalized field names better but we decided to stick to the original +(internal) names as much as possible. After all, at the \LUA\ end one can easily +create synonyms. + 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 @@ -2063,6 +2469,196 @@ true for the \type {width}, \type {height} and \type {depth} of glue nodes. Thes actually access the spec node properties, and here we can set as well as get the values. +In some places \LUATEX\ can do a bit of extra checking for valid node lists and +you can enable that with: + +\startfunctioncall +node.fix_node_lists(<boolean> b) +\stopfunctioncall + +You can set and query the \SYNCTEX\ fields, a file number aka tag and a line +number, for a glue, kern, hlist, vlist, rule and math nodes as well as glyph +nodes (although this last one is not used in native \SYNCTEX). + +\startfunctioncall +node.set_synctex_fields(<integer> f, <integer> l) +<integer> f, <integer> l = + node.get_synctex_fields(<node> n) +\stopfunctioncall + +Of course you need to know what you're doing as no checking on sane values takes +place. Also, the synctex interpreter used in editors is rather peculiar and has +some assumptions (heuristics). + +\stopsection + +\startsection[title={Properties}][library=node] + +\topicindex {nodes+properties} +\topicindex {properties} + +\libindex{flush_properties_table} +\libindex{get_properties_table} +\libindex{set_properties_mode} + +Attributes are a convenient way to relate extra information to a node. You can +assign them at the \TEX\ end as well as at the \LUA\ end and and consult them at +the \LUA\ end. One big advantage is that they obey grouping. They are linked +lists and normally checking for them is pretty efficient, even if you use a lot +of them. A macro package has to provide some way to manage these attributes at the +\TEX\ end because otherwise clashes in their usage can occur. + +Each node also can have a properties table and you can assign values to this +table using the \type {setproperty} function and get properties using the \type +{getproperty} function. Managing properties is way more demanding than managing +attributes. + +Take the following example: + +\starttyping +\directlua { + local n = node.new("glyph") + + node.setproperty(n,"foo") + print(node.getproperty(n)) + + node.setproperty(n,"bar") + print(node.getproperty(n)) + + node.free(n) +} +\stoptyping + +This will print \type {foo} and \type {bar} which in itself is not that useful +when multiple mechanisms want to use this feature. A variant is: + +\starttyping +\directlua { + local n = node.new("glyph") + + node.setproperty(n,{ one = "foo", two = "bar" }) + print(node.getproperty(n).one) + print(node.getproperty(n).two) + + node.free(n) +} +\stoptyping + +This time we store two properties with the node. It really makes sense to have a +table as property because that way we can store more. But in order for that to +work well you need to do it this way: + +\starttyping +\directlua { + local n = node.new("glyph") + + local t = node.getproperty(n) + + if not t then + t = { } + node.setproperty(n,t) + end + t.one = "foo" + t.two = "bar" + + print(node.getproperty(n).one) + print(node.getproperty(n).two) + + node.free(n) +} +\stoptyping + +Here our own properties will not overwrite other users properties unless of +course they use the same keys. So, eventually you will end up with something: + +\starttyping +\directlua { + local n = node.new("glyph") + + local t = node.getproperty(n) + + if not t then + t = { } + node.setproperty(n,t) + end + t.myself = { one = "foo", two = "bar" } + + print(node.getproperty(n).myself.one) + print(node.getproperty(n).myself.two) + + node.free(n) +} +\stoptyping + +This assumes that only you use \type {myself} as subtable. The possibilities are +endless but care is needed. For instance, the generic font handler that ships +with \CONTEXT\ uses the \type {injections} subtable and you should not mess with +that one! + +There are a few helper functions that you normally should not touch as user: \typ +{flush_properties_table} will wipe the table (normally a bad idea), \typ +{get_properties_table} and will give the table that stores properties (using +direct entries) and you can best not mess too much with that one either because +\LUATEX\ itself will make sure that entries related to nodes will get wiped when +nodes get freed, so that the \LUA\ garbage collector can do its job. In fact, the +main reason why we have this mechanism is that it saves the user (or macro +package) some work. One can easily write a property mechanism in \LUA\ where +after a shipout properties gets cleaned up but it's not entirely trivial to make +sure that with each freed node also its properties get freed, due to the fact +that there can be nodes left over for a next page. And having a callback bound to +the node deallocator would add way to much overhead. + +Managing properties in the node (de)allocator functions is disabled by default +and is enabled by: + +\starttyping +node.set_properties_mode(true) +\stoptyping + +When we copy a node list that has a table as property, there are several possibilities: we do the same as +a new node, we copy the entry to the table in properties (a reference), we do +a deep copy of a table in the properties, we create a new table and give it +the original one as a metatable. After some experiments (that also included +timing) with these scenarios we decided that a deep copy made no sense, nor +did nilling. In the end both the shallow copy and the metatable variant were +both ok, although the second one is slower. The most important aspect to keep +in mind is that references to other nodes in properties no longer can be +valid for that copy. We could use two tables (one unique and one shared) or +metatables but that only complicates matters. + +When defining a new node, we could already allocate a table but it is rather easy +to do that at the lua end e.g.\ using a metatable \type {__index} method. That +way it is under macro package control. When deleting a node, we could keep the +slot (e.g. setting it to false) but it could make memory consumption raise +unneeded when we have temporary large node lists and after that only small lists. +Both are not done. + +So in the end this is what happens now: when a node is copied, and it has a table +as property, the new node will share that table. If the second argument of \typ +{set_properties_mode} is \type {true} then a metatable approach is chosen: the +copy gets its own table with the original table as metatable. If you use the +generic font loader the mode is enabled that way. + +A few more xperiments were done. For instance: copy attributes to the properties +so that we have fast access at the \LUA\ end. In the end the overhead is not +compensated by speed and convenience, in fact, attributes are not that slow when +it comes to accessing them. So this was rejected. + +Another experiment concerned a bitset in the node but again the gain compared to +attributes was neglectable and given the small amount of available bits it also +demands a pretty strong agreement over what bit represents what, and this is +unlikely to succeed in the \TEX\ community. It doesn't pay off. + +Just in case one wonders why properties make sense: it is not so much speed that +we gain, but more convenience: storing all kind of (temporary) data in attributes +is no fun and this mechanism makes sure that properties are cleaned up when a +node is freed. Also, the advantage of a more or less global properties table is +that we stay at the \LUA\ end. An alternative is to store a reference in the node +itself but that is complicated by the fact that the register has some limitations +(no numeric keys) and we also don't want to mess with it too much. + +\stopsection + \stopchapter \stopcomponent |