3 \environment luatex-style
4 \environment luatex-logos
6 \startcomponent luatex-tex
8 \startchapter[reference=tex,title=
{The
\TEX\ related libraries
}]
10 \section{The
\type {lua
} library
}
12 \subsection{\LUA\ version
}
14 This library contains one read|-|only item:
17 <string> s = lua.version
20 This returns the
\LUA\ version identifier string. The value is currently
21 \directlua {tex
.print(lua
.version
)}.
23 \subsection{\LUA\ bytecode registers
}
25 \LUA\ registers can be used to communicate
\LUA\ functions across
\LUA\ chunks.
26 The accepted values for assignments are functions and
\type {nil
}. Likewise, the
27 retrieved value is either a function or
\type {nil
}.
30 lua.bytecode
[<number> n
] = <function> f
31 lua.bytecode
[<number> n
]()
34 The contents of the
\type {lua.bytecode
} array is stored inside the format file
35 as actual
\LUA\ bytecode, so it can also be used to preload
\LUA\ code.
37 Note: The function must not contain any upvalues. Currently, functions containing
38 upvalues can be stored (and their upvalues are set to
\type {nil
}), but this is
39 an artifact of the current
\LUA\ implementation and thus subject to change.
41 The associated function calls are
44 <function> f = lua.getbytecode(<number> n)
45 lua.setbytecode(<number> n, <function> f)
48 Note: Since a
\LUA\ file loaded using
\type {loadfile(filename)
} is essentially
49 an anonymous function, a complete file can be stored in a bytecode register like
53 lua.bytecode
[n
] = loadfile(filename)
56 Now all definitions (functions, variables) contained in the file can be
57 created by executing this bytecode register:
63 Note that the path of the file is stored in the
\LUA\ bytecode to be used in
64 stack backtraces and therefore dumped into the format file if the above code is
65 used in
\INITEX. If it contains private information, i.e. the user name, this
66 information is then contained in the format file as well. This should be kept in
67 mind when preloading files into a bytecode register in
\INITEX.
69 \subsection{\LUA\ chunk name registers
}
71 There is an array of
65536 (
0--
65535) potential chunk names for use with the
72 \type {\directlua} and
\type {\latelua
} primitives.
75 lua.name
[<number> n
] = <string> s
76 <string> s = lua.name
[<number> n
]
79 If you want to unset a
\LUA\ name, you can assign
\type {nil
} to it.
81 \section{The
\type {status
} library
}
83 This contains a number of run|-|time configuration items that you may find useful
84 in message reporting, as well as an iterator function that gets all of the names
85 and values as a table.
88 <table> info = status.list()
91 The keys in the table are the known items, the value is the current value. Almost
92 all of the values in
\type {status
} are fetched through a metatable at run|-|time
93 whenever they are accessed, so you cannot use
\type {pairs
} on
\type {status
},
94 but you
{\it can\/
} use
\type {pairs
} on
\type {info
}, of course. If you do not
95 need the full list, you can also ask for a single item by using its name as an
96 index into
\type {status
}.
100 \starttabulate[|lT|p|
]
101 \NC \rmbf key
\NC \bf explanation
\NC \NR
102 \NC pdf_gone
\NC written
\PDF\ bytes
\NC \NR
103 \NC pdf_ptr
\NC not yet written
\PDF\ bytes
\NC \NR
104 \NC dvi_gone
\NC written
\DVI\ bytes
\NC \NR
105 \NC dvi_ptr
\NC not yet written
\DVI\ bytes
\NC \NR
106 \NC total_pages
\NC number of written pages
\NC \NR
107 \NC output_file_name
\NC name of the
\PDF\ or
\DVI\ file
\NC \NR
108 \NC log_name
\NC name of the log file
\NC \NR
109 \NC banner
\NC terminal display banner
\NC \NR
110 \NC var_used
\NC variable (one|-|word) memory in use
\NC \NR
111 \NC dyn_used
\NC token (multi|-|word) memory in use
\NC \NR
112 \NC str_ptr
\NC number of strings
\NC \NR
113 \NC init_str_ptr
\NC number of
\INITEX\ strings
\NC \NR
114 \NC max_strings
\NC maximum allowed strings
\NC \NR
115 \NC pool_ptr
\NC string pool index
\NC \NR
116 \NC init_pool_ptr
\NC \INITEX\ string pool index
\NC \NR
117 \NC pool_size
\NC current size allocated for string characters
\NC \NR
118 \NC node_mem_usage
\NC a string giving insight into currently used nodes
\NC \NR
119 \NC var_mem_max
\NC number of allocated words for nodes
\NC \NR
120 \NC fix_mem_max
\NC number of allocated words for tokens
\NC \NR
121 \NC fix_mem_end
\NC maximum number of used tokens
\NC \NR
122 \NC cs_count
\NC number of control sequences
\NC \NR
123 \NC hash_size
\NC size of hash
\NC \NR
124 \NC hash_extra
\NC extra allowed hash
\NC \NR
125 \NC font_ptr
\NC number of active fonts
\NC \NR
126 \NC input_ptr
\NC th elevel of input we're at
\NC \NR
127 \NC max_in_stack
\NC max used input stack entries
\NC \NR
128 \NC max_nest_stack
\NC max used nesting stack entries
\NC \NR
129 \NC max_param_stack
\NC max used parameter stack entries
\NC \NR
130 \NC max_buf_stack
\NC max used buffer position
\NC \NR
131 \NC max_save_stack
\NC max used save stack entries
\NC \NR
132 \NC stack_size
\NC input stack size
\NC \NR
133 \NC nest_size
\NC nesting stack size
\NC \NR
134 \NC param_size
\NC parameter stack size
\NC \NR
135 \NC buf_size
\NC current allocated size of the line buffer
\NC \NR
136 \NC save_size
\NC save stack size
\NC \NR
137 \NC obj_ptr
\NC max
\PDF\ object pointer
\NC \NR
138 \NC obj_tab_size
\NC \PDF\ object table size
\NC \NR
139 \NC pdf_os_cntr
\NC max
\PDF\ object stream pointer
\NC \NR
140 \NC pdf_os_objidx
\NC \PDF\ object stream index
\NC \NR
141 \NC pdf_dest_names_ptr
\NC max
\PDF\ destination pointer
\NC \NR
142 \NC dest_names_size
\NC \PDF\ destination table size
\NC \NR
143 \NC pdf_mem_ptr
\NC max
\PDF\ memory used
\NC \NR
144 \NC pdf_mem_size
\NC \PDF\ memory size
\NC \NR
145 \NC largest_used_mark
\NC max referenced marks class
\NC \NR
146 \NC filename
\NC name of the current input file
\NC \NR
147 \NC inputid
\NC numeric id of the current input
\NC \NR
148 \NC linenumber
\NC location in the current input file
\NC \NR
149 \NC lasterrorstring
\NC last
\TEX\ error string
\NC \NR
150 \NC lastluaerrorstring
\NC last
\LUA\ error string
\NC \NR
151 \NC lastwarningtag
\NC last warning string
\NC \NR
152 \NC lastwarningstring
\NC last warning tag, normally an indication of in what part
\NC \NR
153 \NC lasterrorcontext
\NC last error context string (with newlines)
\NC \NR
154 \NC luabytecodes
\NC number of active
\LUA\ bytecode registers
\NC \NR
155 \NC luabytecode_bytes
\NC number of bytes in
\LUA\ bytecode registers
\NC \NR
156 \NC luastate_bytes
\NC number of bytes in use by
\LUA\ interpreters
\NC \NR
157 \NC output_active
\NC \type {true
} if the
\type {\output} routine is active
\NC \NR
158 \NC callbacks
\NC total number of executed callbacks so far
\NC \NR
159 \NC indirect_callbacks
\NC number of those that were themselves
160 a result of other callbacks (e.g. file readers)
\NC \NR
161 \NC luatex_version
\NC the
\LUATEX\ version number
\NC \NR
162 \NC luatex_revision
\NC the
\LUATEX\ revision string
\NC \NR
163 \NC ini_version
\NC \type {true
} if this is an
\INITEX\ run
\NC \NR
164 \NC shell_escape
\NC \type {0} means disabled,
\type {1} is restricted and
165 \type {2} means anything is permitted
\NC \NR
168 The error and warning messages can be wiped with the
\type {resetmessages
}
171 \section{The
\type {tex
} library
}
173 The
\type {tex
} table contains a large list of virtual internal
\TEX\
174 parameters that are partially writable.
176 The designation
\quote {virtual
} means that these items are not properly defined
177 in
\LUA, but are only front\-ends that are handled by a metatable that operates
178 on the actual
\TEX\ values. As a result, most of the
\LUA\ table operators (like
179 \type {pairs
} and
\type {#
}) do not work on such items.
181 At the moment, it is possible to access almost every parameter that has these
184 \startitemize[packed
]
185 \item You can use it after
\type {\the}
186 \item It is a single token.
187 \item Some special others, see the list below
190 This excludes parameters that need extra arguments, like
\type {\the\scriptfont}.
192 The subset comprising simple integer and dimension registers are
193 writable as well as readable (stuff like
\type {\tracingcommands} and
196 \subsection{Internal parameter values
}
198 For all the parameters in this section, it is possible to access them directly
199 using their names as index in the
\type {tex
} table, or by using one of the
200 functions
\type {tex.get
} and
\type {tex.set
}. If you created aliasses,
201 you can use accessors like
\type {tex.getdimen
} as these also understand
202 names of built|-|in variables.
204 The exact parameters and return values differ depending on the actual parameter,
205 and so does whether
\type {tex.set
} has any effect. For the parameters that
{\it
206 can\/
} be set, it is possible to use
\type {global
} as the first argument to
207 \type {tex.set
}; this makes the assignment global instead of local.
210 tex.set (<string> n, ...)
211 tex.set ("global", <string> n, ...)
212 ... = tex.get (<string> n)
215 There are also dedicated setters, getters and checkers:
218 local d = tex.getdimen("foo")
219 if tex.isdimen("bar") then
220 tex.setdimen("bar",d)
224 There are such helpers for
\type {dimen
},
\type {count
},
\type {skip
},
\type
225 {box
} and
\type {attribute
} registers.
227 \subsubsection{Integer parameters
}
229 The integer parameters accept and return
\LUA\ numbers.
241 tex.defaulthyphenchar
244 tex.displaywidowpenalty
245 tex.doublehyphendemerits
247 tex.errorcontextlines
251 tex.finalhyphendemerits
263 tex.localbrokenpenalty
264 tex.localinterlinepenalty
272 tex.postdisplaypenalty
273 tex.predisplaydirection
274 tex.predisplaypenalty
294 tex.tracingparagraphs
296 tex.tracingscantokens
317 \subsubsection{Dimension parameters
}
319 The dimension parameters accept
\LUA\ numbers (signifying scaled points) or
320 strings (with included dimension). The result is always a number in scaled
328 tex.delimitershortfall
339 tex.nulldelimiterspace
375 Beware: as with all
\LUA\ tables you can add values to them. So, the following is valid:
381 When you access a
\TEX\ parameter a look up takes place. For read||only variables
382 that means that you will get something back, but when you set them you create a
383 new entry in the table thereby making the original invisible.
385 There are a few special cases that we make an exception for:
\type {prevdepth
},
386 \type {prevgraf
} and
\type {spacefactor
}. These normally are accessed via the
387 \type {tex.nest
} table:
390 tex.nest
[tex.nest.ptr
].prevdepth = p
391 tex.nest
[tex.nest.ptr
].spacefactor = s
394 However, the following also works:
401 Keep in mind that when you mess with node lists directly at the
\LUA\ end you
402 might need to update the top of the nesting stack's
\type {prevdepth
} explicitly
403 as there is no way
\LUATEX\ can guess your intentions. By using the accessor in
404 the
\type {tex
} tables, you get and set the values atthe top of the nest stack.
406 \subsubsection{Direction parameters
}
408 The direction parameters are read|-|only and return a
\LUA\ string.
420 \subsubsection{Glue parameters
}
422 The glue parameters accept and return a userdata object that represents a
\type
427 tex.abovedisplayshortskip
430 tex.belowdisplayshortskip
445 \subsubsection{Muglue parameters
}
447 All muglue parameters are to be used read|-|only and return a
\LUA\ string.
457 \subsubsection{Tokenlist parameters
}
459 The tokenlist parameters accept and return
\LUA\ strings.
\LUA\ strings are
460 converted to and from token lists using
\type {\the} \type {\toks} style expansion:
461 all category codes are either space (
10) or other (
12). It follows that assigning
462 to some of these, like
\quote {tex.output
}, is actually useless, but it feels bad
463 to make exceptions in view of a coming extension that will accept full|-|blown
485 \subsection{Convert commands
}
487 All
\quote {convert
} commands are read|-|only and return a
\LUA\ string. The
488 supported commands at this moment are:
500 tex.pdffontname(number)
501 tex.pdffontobjnum(number)
502 tex.pdffontsize(number)
503 tex.uniformdeviate(number)
505 tex.romannumeral(number)
506 tex.pdfpageref(number)
507 tex.pdfxformname(number)
508 tex.fontidentifier(number)
512 If you are wondering why this list looks haphazard; these are all the cases of
513 the
\quote {convert
} internal command that do not require an argument, as well as
514 the ones that require only a simple numeric value.
516 The special (lua-only) case of
\type {tex.fontidentifier
} returns the
\type
517 {csname
} string that matches a font id number (if there is one).
519 if these are really needed in a macro package.
521 \subsection{Last item commands
}
523 All
\quote {last item
} commands are read|-|only and return a number.
525 The supported commands at this moment are:
537 tex.pdflastximagepages
546 tex.currentgrouplevel
551 tex.pdflastximagecolordepth
555 \subsection{Attribute, count, dimension, skip and token registers
}
557 \TEX's attributes (
\type {\attribute}), counters (
\type {\count}), dimensions (
\type
558 {\dimen}), skips (
\type {\skip}) and token (
\type {\toks}) registers can be accessed
559 and written to using two times five virtual sub|-|tables of the
\type {tex
}
572 It is possible to use the names of relevant
\type {\attributedef},
\type {\countdef},
573 \type {\dimendef},
\type {\skipdef}, or
\type {\toksdef} control sequences as indices
577 tex.count.scratchcounter =
0
578 enormous = tex.dimen
['maxdimen'
]
581 In this case,
\LUATEX\ looks up the value for you on the fly. You have to use a
582 valid
\type {\countdef} (or
\type {\attributedef}, or
\type {\dimendef}, or
\type
583 {\skipdef}, or
\type {\toksdef}), anything else will generate an error (the intent
584 is to eventually also allow
\type {<chardef tokens>
} and even macros that expand
587 The attribute and count registers accept and return
\LUA\ numbers.
589 The dimension registers accept
\LUA\ numbers (in scaled points) or strings (with
590 an included absolute dimension;
\type {em
} and
\type {ex
} and
\type {px
} are
591 forbidden). The result is always a number in scaled points.
593 The token registers accept and return
\LUA\ strings.
\LUA\ strings are converted
594 to and from token lists using
\type {\the} \type {\toks} style expansion: all
595 category codes are either space (
10) or other (
12).
597 The skip registers accept and return
\type {glue_spec
} userdata node objects (see
598 the description of the node interface elsewhere in this manual).
600 As an alternative to array addressing, there are also accessor functions defined
601 for all cases, for example, here is the set of possibilities for
\type {\skip}
605 tex.setskip (<number> n, <node> s)
606 tex.setskip (<string> s, <node> s)
607 tex.setskip ("global",<number> n, <node> s)
608 tex.setskip ("global",<string> s, <node> s)
609 <node> s = tex.getskip (<number> n)
610 <node> s = tex.getskip (<string> s)
613 We have similar setters for
\type {count
},
\type {dimen
},
\type {muskip
}, and
614 \type {toks
}. Counters and dimen are represented by numbers, skips and muskips by
615 nodes, and toks by strings. For tokens registers we have an alternative where a
616 catcode table is specified:
619 tex.scantoks(
0,
3,"$e=mc^
2$")
620 tex.scantoks("global",
0,"$
\int\limits^
1_2$")
623 In the function-based interface, it is possible to define values globally by
624 using the string
\type {global
} as the first function argument.
626 There are four extra skip related helpers:
629 tex.setglue (<number> n, width, stretch, shrink, stretch_order, shrink_order)
630 tex.setglue (<string> s, width, stretch, shrink, stretch_order, shrink_order)
631 tex.setglue ("global",<number> n, width, stretch, shrink, stretch_order, shrink_order)
632 tex.setglue ("global",<string> s, width, stretch, shrink, stretch_order, shrink_order)
633 width, stretch, shrink, stretch_order, shrink_order = tex.getglue (<number> n)
634 width, stretch, shrink, stretch_order, shrink_order = tex.getglue (<string> s)
637 The other two are
\type {tex.setmuglue
} and
\type {tex.getmuglue
}.
639 \subsection{Character code registers
}
641 \TEX's character code tables (
\type {\lccode},
\type {\uccode},
\type {\sfcode},
\type
642 {\catcode},
\type {\mathcode},
\type {\delcode}) can be accessed and written to using
643 six virtual subtables of the
\type {tex
} table
656 The function call interfaces are roughly as above, but there are a few twists.
657 \type {sfcode
}s are the simple ones:
660 tex.setsfcode (<number> n, <number> s)
661 tex.setsfcode ('global', <number> n, <number> s)
662 <number> s = tex.getsfcode (<number> n)
665 The function call interface for
\type {lccode
} and
\type {uccode
} additionally
666 allows you to set the associated sibling at the same time:
669 tex.setlccode (
['global'
], <number> n, <number> lc)
670 tex.setlccode (
['global'
], <number> n, <number> lc, <number> uc)
671 <number> lc = tex.getlccode (<number> n)
672 tex.setuccode (
['global'
], <number> n, <number> uc)
673 tex.setuccode (
['global'
], <number> n, <number> uc, <number> lc)
674 <number> uc = tex.getuccode (<number> n)
677 The function call interface for
\type {catcode
} also allows you to specify a
678 category table to use on assignment or on query (default in both cases is the
682 tex.setcatcode (
['global'
], <number> n, <number> c)
683 tex.setcatcode (
['global'
], <number> cattable, <number> n, <number> c)
684 <number> lc = tex.getcatcode (<number> n)
685 <number> lc = tex.getcatcode (<number> cattable, <number> n)
688 The interfaces for
\type {delcode
} and
\type {mathcode
} use small array tables to
689 set and retrieve values:
692 tex.setmathcode (
['global'
], <number> n, <table> mval )
693 <table> mval = tex.getmathcode (<number> n)
694 tex.setdelcode (
['global'
], <number> n, <table> dval )
695 <table> dval = tex.getdelcode (<number> n)
698 Where the table for
\type {mathcode
} is an array of
3 numbers, like this:
701 {<number> mathclass, <number> family, <number> character
}
704 And the table for
\type {delcode
} is an array with
4 numbers, like this:
707 {<number> small_fam, <number> small_char, <number> large_fam, <number> large_char
}
710 You can also avoid the table:
713 class, family, char = tex.getmathcodes (<number> n)
714 smallfam, smallchar, largefam, largechar = tex.getdelcodes (<number> n)
717 Normally, the third and fourth values in a delimiter code assignment will be zero
718 according to
\type {\Udelcode} usage, but the returned table can have values there
719 (if the delimiter code was set using
\type {\delcode}, for example). Unset
\type
720 {delcode
}'s can be recognized because
\type {dval
[1]} is $-
1$.
722 \subsection{Box registers
}
724 It is possible to set and query actual boxes, using the node interface as defined
725 in the
\type {node
} library:
734 tex.setbox(<number> n, <node> s)
735 tex.setbox(<string> cs, <node> s)
736 tex.setbox('global', <number> n, <node> s)
737 tex.setbox('global', <string> cs, <node> s)
738 <node> n = tex.getbox(<number> n)
739 <node> n = tex.getbox(<string> cs)
742 for function|-|based access. In the function-based interface, it is possible to
743 define values globally by using the string
\type {global
} as the first function
746 Be warned that an assignment like
749 tex.box
[0] = tex.box
[2]
752 does not copy the node list, it just duplicates a node pointer. If
\type {\box2}
753 will be cleared by
\TEX\ commands later on, the contents of
\type {\box0} becomes
754 invalid as well. To prevent this from happening, always use
\type
755 {node.copy_list()
} unless you are assigning to a temporary variable:
758 tex.box
[0] = node.copy_list(tex.box
[2])
761 The following function will register a box for reuse (this is modelled after so
762 called xforms in
\PDF). You can (re)use the box with
\type {\useboxresource} or
763 by creating a rule node with subtype~
2.
766 local index = tex.saveboxresource(n,attributes,resources,immediate)
769 The optional second and third arguments are strings, the fourth is a boolean.
771 You can generate the reference (a rule type) with:
774 local reused = tex.useboxresource(n,wd,ht,dp)
777 The dimensions are optional and the final ones are returned as extra values. The
778 following is just a bonus (no dimensions returned means that the resource is
782 local w, h, d = tex.getboxresourcedimensions(n)
788 local vlist = tex.splitbox(n,height,mode)
791 The remainder is kept in the original box and a packaged vlist is returned. This
792 operation is comparable to the
\type {\vsplit} operation. The mode can be
\type
793 {additional
} or
\type {exactly
} and concerns the split off box.
795 \subsection{Math parameters
}
797 It is possible to set and query the internal math parameters using:
800 tex.setmath(<string> n, <string> t, <number> n)
801 tex.setmath('global', <string> n, <string> t, <number> n)
802 <number> n = tex.getmath(<string> n, <string> t)
805 As before an optional first parameter
\type {global
} indicates a global
808 The first string is the parameter name minus the leading
\quote {Umath
}, and the
809 second string is the style name minus the trailing
\quote {style
}.
811 Just to be complete, the values for the math parameter name are:
814 quad axis operatorsize
815 overbarkern overbarrule overbarvgap
816 underbarkern underbarrule underbarvgap
817 radicalkern radicalrule radicalvgap
818 radicaldegreebefore radicaldegreeafter radicaldegreeraise
819 stackvgap stacknumup stackdenomdown
820 fractionrule fractionnumvgap fractionnumup
821 fractiondenomvgap fractiondenomdown fractiondelsize
822 limitabovevgap limitabovebgap limitabovekern
823 limitbelowvgap limitbelowbgap limitbelowkern
824 underdelimitervgap underdelimiterbgap
825 overdelimitervgap overdelimiterbgap
826 subshiftdrop supshiftdrop subshiftdown
827 subsupshiftdown subtopmax supshiftup
828 supbottommin supsubbottommax subsupvgap
829 spaceafterscript connectoroverlapmin
830 ordordspacing ordopspacing ordbinspacing ordrelspacing
831 ordopenspacing ordclosespacing ordpunctspacing ordinnerspacing
832 opordspacing opopspacing opbinspacing oprelspacing
833 opopenspacing opclosespacing oppunctspacing opinnerspacing
834 binordspacing binopspacing binbinspacing binrelspacing
835 binopenspacing binclosespacing binpunctspacing bininnerspacing
836 relordspacing relopspacing relbinspacing relrelspacing
837 relopenspacing relclosespacing relpunctspacing relinnerspacing
838 openordspacing openopspacing openbinspacing openrelspacing
839 openopenspacing openclosespacing openpunctspacing openinnerspacing
840 closeordspacing closeopspacing closebinspacing closerelspacing
841 closeopenspacing closeclosespacing closepunctspacing closeinnerspacing
842 punctordspacing punctopspacing punctbinspacing punctrelspacing
843 punctopenspacing punctclosespacing punctpunctspacing punctinnerspacing
844 innerordspacing inneropspacing innerbinspacing innerrelspacing
845 inneropenspacing innerclosespacing innerpunctspacing innerinnerspacing
848 The values for the style parameter name are:
851 display crampeddisplay
854 scriptscript crampedscriptscript
857 The value is either a number (representing a dimension or number) or a glue spec
858 node representing a muskip for
\type {ordordspacing
} and similar spacing
861 \subsection{Special list heads
}
863 The virtual table
\type {tex.lists
} contains the set of internal registers that
864 keep track of building page lists.
866 \starttabulate[|lT|p|
]
867 \NC \bf field
\NC \bf description
\NC \NR
868 \NC page_ins_head
\NC circular list of pending insertions
\NC \NR
869 \NC contrib_head
\NC the recent contributions
\NC \NR
870 \NC page_head
\NC the current page content
\NC \NR
871 %NC temp_head \NC \NC \NR
872 \NC hold_head
\NC used for held-over items for next page
\NC \NR
873 \NC adjust_head
\NC head of the current
\type {\vadjust} list
\NC \NR
874 \NC pre_adjust_head
\NC head of the current
\type {\vadjust pre
} list
\NC \NR
875 %NC align_head \NC \NC \NR
876 \NC page_discards_head
\NC head of the discarded items of a page break
\NC \NR
877 \NC split_discards_head
\NC head of the discarded items in a vsplit
\NC \NR
880 \subsection{Semantic nest levels
}
882 The virtual table
\type {tex.nest
} contains the currently active
883 semantic nesting state. It has two main parts: a zero-based array of userdata for
884 the semantic nest itself, and the numerical value
\type {tex.nest.ptr
}, which
885 gives the highest available index. Neither the array items in
\type {tex.nest
[]}
886 nor
\type {tex.nest.ptr
} can be assigned to (as this would confuse the
887 typesetting engine beyond repair), but you can assign to the individual values
888 inside the array items, e.g.\
\type {tex.nest
[tex.nest.ptr
].prevdepth
}.
890 \type {tex.nest
[tex.nest.ptr
]} is the current nest state,
\type {tex.nest
[0]} the
891 outermost (main vertical list) level.
893 The known fields are:
895 \starttabulate[|lT|l|l|p|
]
896 \NC \rmbf key
\NC \bf type
\NC \bf modes
\NC \bf explanation
\NC \NR
897 \NC mode
\NC number
\NC all
\NC a number representing the main mode at this level:
898 \type {0} = no mode (this happens during
\type {\write}),
899 \type {1} = vertical,
900 \type {127} = horizontal,
901 \type {253} = display math,
902 \type {-
1} = internal vertical,
903 \type {-
127} = restricted horizontal,
904 \type {-
253} = inline math
\NC \NR
905 \NC modeline
\NC number
\NC all
\NC source input line where this mode was entered in,
906 negative inside the output routine
\NC \NR
907 \NC head
\NC node
\NC all
\NC the head of the current list
\NC \NR
908 \NC tail
\NC node
\NC all
\NC the tail of the current list
\NC \NR
909 \NC prevgraf
\NC number
\NC vmode
\NC number of lines in the previous paragraph
\NC \NR
910 \NC prevdepth
\NC number
\NC vmode
\NC depth of the previous paragraph (equal to
\type {\pdfignoreddimen}
911 when it is to be ignored)
\NC \NR
912 \NC spacefactor
\NC number
\NC hmode
\NC the current space factor
\NC \NR
913 \NC dirs
\NC node
\NC hmode
\NC used for temporary storage by the line break algorithm
\NC \NR
914 \NC noad
\NC node
\NC mmode
\NC used for temporary storage of a pending fraction numerator,
915 for
\type {\over} etc.
\NC \NR
916 \NC delimptr
\NC node
\NC mmode
\NC used for temporary storage of the previous math delimiter,
917 for
\type {\middle} \NC \NR
918 \NC mathdir
\NC boolean
\NC mmode
\NC true when during math processing the
\type {\mathdir} is not
919 the same as the surrounding
\type {\textdir} \NC \NR
920 \NC mathstyle
\NC number
\NC mmode
\NC the current
\type {\mathstyle} \NC \NR
923 \subsection[sec:luaprint
]{Print functions
}
925 The
\type {tex
} table also contains the three print functions that are the
926 major interface from
\LUA\ scripting to
\TEX.
928 The arguments to these three functions are all stored in an in|-|memory virtual
929 file that is fed to the
\TEX\ scanner as the result of the expansion of
932 The total amount of returnable text from a
\type {\directlua} command is only
933 limited by available system
\RAM. However, each separate printed string has to
934 fit completely in
\TEX's input buffer.
936 The result of using these functions from inside callbacks is undefined
939 \subsubsection{\type {tex.print
}}
942 tex.print(<string> s, ...)
943 tex.print(<number> n, <string> s, ...)
945 tex.print(<number> n, <table> t)
948 Each string argument is treated by
\TEX\ as a separate input line. If there is a
949 table argument instead of a list of strings, this has to be a consecutive array
950 of strings to print (the first non-string value will stop the printing process).
952 The optional parameter can be used to print the strings using the catcode regime
953 defined by
\type {\catcodetable}~
\type {n
}. If
\type {n
} is $-
1$, the currently
954 active catcode regime is used. If
\type {n
} is $-
2$, the resulting catcodes are
955 the result of
\type {\the} \type {\toks}: all category codes are
12 (other) except for
956 the space character, that has category code
10 (space). Otherwise, if
\type {n
}
957 is not a valid catcode table, then it is ignored, and the currently active
958 catcode regime is used instead.
960 The very last string of the very last
\type {tex.print()
} command in a
\type
961 {\directlua} will not have the
\type {\endlinechar
} appended, all others do.
963 \subsubsection{\type {tex.sprint
}}
966 tex.sprint(<string> s, ...)
967 tex.sprint(<number> n, <string> s, ...)
968 tex.sprint(<table> t)
969 tex.sprint(<number> n, <table> t)
972 Each string argument is treated by
\TEX\ as a special kind of input line that
973 makes it suitable for use as a partial line input mechanism:
975 \startitemize[packed
]
977 \TEX\ does not switch to the
\quote {new line
} state, so that leading spaces
981 No
\type {\endlinechar} is inserted.
984 Trailing spaces are not removed.
986 Note that this does not prevent
\TEX\ itself from eating spaces as result of
987 interpreting the line. For example, in
990 before
\directlua{tex
.sprint("\\relax")tex
.sprint(" inbetween")}after
992 the space before
\type {in between
} will be gobbled as a result of the
\quote
993 {normal
} scanning of
\type {\relax}.
997 If there is a table argument instead of a list of strings, this has to
998 be a consecutive array of strings to print (the first non-string value
999 will stop the printing process).
1001 The optional argument sets the catcode regime, as with
\type {tex.print()
}.
1003 \subsubsection{\type {tex.tprint
}}
1006 tex.tprint(
{<number> n, <string> s, ...
},
{...
})
1009 This function is basically a shortcut for repeated calls to
\type
1010 {tex.sprint(<number> n, <string> s, ...)
}, once for each of the supplied argument
1013 \subsubsection{\type {tex.cprint
}}
1015 This function takes a number indicating the to be used catcode, plus either a
1016 table of strings or an argument list of strings that will be pushed into the
1020 tex.cprint(
1,"
1: $&
{\
\foo}") tex.print("\
\par") -- a lot of
\bgroup s
1021 tex.cprint(
2,"
2: $&
{\
\foo}") tex.print("\
\par") -- matching
\egroup s
1022 tex.cprint(
9,"
9: $&
{\
\foo}") tex.print("\
\par") -- all get ignored
1023 tex.cprint(
10,"
10: $&
{\
\foo}") tex.print("\
\par") -- all become spaces
1024 tex.cprint(
11,"
11: $&
{\
\foo}") tex.print("\
\par") -- letters
1025 tex.cprint(
12,"
12: $&
{\
\foo}") tex.print("\
\par") -- other characters
1026 tex.cprint(
14,"
12: $&
{\
\foo}") tex.print("\
\par") -- comment triggers
1029 \subsubsection{\type {tex.write
}}
1032 tex.write(<string> s, ...)
1033 tex.write(<table> t)
1036 Each string argument is treated by
\TEX\ as a special kind of input line that
1037 makes it suitable for use as a quick way to dump information:
1040 \item All catcodes on that line are either
\quote{space
} (for '~') or
1041 \quote{character
} (for all others).
1042 \item There is no
\type {\endlinechar} appended.
1045 If there is a table argument instead of a list of strings, this has to be a
1046 consecutive array of strings to print (the first non-string value will stop the
1049 \subsection{Helper functions
}
1051 \subsubsection{\type {tex.round
}}
1054 <number> n = tex.round(<number> o)
1057 Rounds
\LUA\ number
\type {o
}, and returns a number that is in the range of a
1058 valid
\TEX\ register value. If the number starts out of range, it generates a
1059 \quote {number to big
} error as well.
1061 \subsubsection{\type {tex.scale
}}
1064 <number> n = tex.scale(<number> o, <number> delta)
1065 <table> n = tex.scale(table o, <number> delta)
1068 Multiplies the
\LUA\ numbers
\type {o
} and
\type {delta
}, and returns a rounded
1069 number that is in the range of a valid
\TEX\ register value. In the table
1070 version, it creates a copy of the table with all numeric top||level values scaled
1071 in that manner. If the multiplied number(s) are of range, it generates
1072 \quote{number to big
} error(s) as well.
1074 Note: the precision of the output of this function will depend on your computer's
1075 architecture and operating system, so use with care! An interface to
\LUATEX's
1076 internal,
100\% portable scale function will be added at a later date.
1078 \subsubsection{\type {tex.sp
}}
1081 <number> n = tex.sp(<number> o)
1082 <number> n = tex.sp(<string> s)
1085 Converts the number
\type {o
} or a string
\type {s
} that represents an explicit
1086 dimension into an integer number of scaled points.
1088 For parsing the string, the same scanning and conversion rules are used that
1089 \LUATEX\ would use if it was scanning a dimension specifier in its
\TEX|-|like
1090 input language (this includes generating errors for bad values), expect for the
1095 only explicit values are allowed, control sequences are not handled
1098 infinite dimension units (
\type {fil...
}) are forbidden
1101 \type {mu
} units do not generate an error (but may not be useful either)
1105 \subsubsection{\type {tex.definefont
}}
1108 tex.definefont(<string> csname, <number> fontid)
1109 tex.definefont(<boolean> global, <string> csname, <number> fontid)
1112 Associates
\type {csname
} with the internal font number
\type {fontid
}. The
1113 definition is global if (and only if)
\type {global
} is specified and true (the
1114 setting of
\type {globaldefs
} is not taken into account).
1116 \subsubsection{\type {tex.getlinenumber
} and
\type {tex.setlinenumber
}}
1118 You can mess with the current line number:
1121 local n = tex.getlinenumber()
1122 tex.setlinenumber(n+
10)
1125 which can be shortcut to:
1128 tex.setlinenumber(
10,true)
1131 This might be handy when you have a callback that read numbers from a file and
1132 combines them in one line (in which case an error message probably has to refer
1133 to the original line). Interference with
\TEX's internal handling of numbers is
1136 \subsubsection{\type {tex.error
}}
1139 tex.error(<string> s)
1140 tex.error(<string> s, <table> help)
1143 This creates an error somewhat like the combination of
\type {\errhelp} and
\type
1144 {\errmessage} would. During this error, deletions are disabled.
1146 The array part of the
\type {help
} table has to contain strings, one for each
1149 \subsubsection{\type {tex.hashtokens
}}
1152 for i,v in pairs (tex.hashtokens()) do ... end
1155 Returns a name and token table pair (see~
\in {section
} [luatokens
] about token
1156 tables) iterator for every non-zero entry in the hash table. This can be useful
1157 for debugging, but note that this also reports control sequences that may be
1158 unreachable at this moment due to local redefinitions: it is strictly a dump of
1161 \subsection[luaprimitives
]{Functions for dealing with primitives
}
1163 \subsubsection{\type {tex.enableprimitives
}}
1166 tex.enableprimitives(<string> prefix, <table> primitive names)
1169 This function accepts a prefix string and an array of primitive names.
1171 For each combination of
\quote {prefix
} and
\quote {name
}, the
\type
1172 {tex.enableprimitives
} first verifies that
\quote {name
} is an actual primitive
1173 (it must be returned by one of the
\type {tex.extraprimitives()
} calls explained
1174 below, or part of
\TEX82, or
\type {\directlua}). If it is not,
\type
1175 {tex.enableprimitives
} does nothing and skips to the next pair.
1177 But if it is, then it will construct a csname variable by concatenating the
1178 \quote {prefix
} and
\quote {name
}, unless the
\quote {prefix
} is already the
1179 actual prefix of
\quote {name
}. In the latter case, it will discard the
\quote
1180 {prefix
}, and just use
\quote {name
}.
1182 Then it will check for the existence of the constructed csname. If the csname is
1183 currently undefined (note: that is not the same as
\type {\relax}), it will
1184 globally define the csname to have the meaning: run code belonging to the
1185 primitive
\quote {name
}. If for some reason the csname is already defined, it
1186 does nothing and tries the next pair.
1191 tex.enableprimitives('LuaTeX',
{'formatname'
})
1194 will define
\type {\LuaTeXformatname} with the same intrinsic meaning as the
1195 documented primitive
\type {\formatname}, provided that the control sequences
\type
1196 {\LuaTeXformatname} is currently undefined.
1198 When
\LUATEX\ is run with
\type {--ini
} only the
\TEX82 primitives and
\type
1199 {\directlua} are available, so no extra primitives
{\bf at all
}.
1201 If you want to have all the new functionality available using their default
1202 names, as it is now, you will have to add
1205 \ifx\directlua\undefined \else
1206 \directlua {tex
.enableprimitives('',tex
.extraprimitives ())}
1210 near the beginning of your format generation file. Or you can choose different
1211 prefixes for different subsets, as you see fit.
1213 Calling some form of
\type {tex.enableprimitives()
} is highly important though,
1214 because if you do not, you will end up with a
\TEX82-lookalike that can run
\LUA\
1215 code but not do much else. The defined csnames are (of course) saved in the
1216 format and will be available at runtime.
1218 \subsubsection{\type {tex.extraprimitives
}}
1221 <table> t = tex.extraprimitives(<string> s, ...)
1224 This function returns a list of the primitives that originate from the engine(s)
1225 given by the requested string value(s). The possible values and their (current)
1229 function
document.showprimitives(tag)
1230 for k, v in table.sortedpairs(tex.extraprimitives(tag)) do
1232 v = '\
\normalcontrolspace'
1240 \starttabulate[|l|pl|
]
1241 \NC \bf name
\NC \bf values
\NC \NR
1242 \NC tex
\NC \ctxlua{document.showprimitives('tex')
} \NC \NR
1243 \NC core
\NC \ctxlua{document.showprimitives('core')
} \NC \NR
1244 \NC etex
\NC \ctxlua{document.showprimitives('etex')
} \NC \NR
1245 \NC luatex
\NC \ctxlua{document.showprimitives('luatex')
} \NC \NR
1248 Note that
\type {'luatex'
} does not contain
\type {directlua
}, as that is
1249 considered to be a core primitive, along with all the
\TEX82 primitives, so it is
1250 part of the list that is returned from
\type {'core'
}.
1252 % \type {'umath'} is a subset of \type {'luatex'} that covers the Unicode math
1253 % primitives as it might be desired to handle the prefixing of that subset
1256 Running
\type {tex.extraprimitives()
} will give you the complete list of
1257 primitives
\type {-ini
} startup. It is exactly equivalent to
\type
1258 {tex.extraprimitives('etex' and 'luatex')
}.
1260 \subsubsection{\type {tex.primitives
}}
1263 <table> t = tex.primitives()
1266 This function returns a hash table listing all primitives that
\LUATEX\ knows
1267 about. The keys in the hash are primitives names, the values are tables
1268 representing tokens (see~
\in{section
}[luatokens
]). The third value is always
1271 {\em In the beginning we had
\type {omega
} and
\type {pdftex
} subsets but in the
1272 meantime relevant primitives ave been promoted (either or not adapted) to the
1273 \type {luatex
} set when found useful, or removed when considered to be of no use.
1274 Originally we had two sets of math definition primitives but the
\OMEGA\ ones
1275 have been removed, so we no longer have a subset for math either.
}
1277 \subsection{Core functionality interfaces
}
1279 \subsubsection{\type {tex.badness
}}
1282 <number> b = tex.badness(<number> t, <number> s)
1285 This helper function is useful during linebreak calculations.
\type {t
} and
\type
1286 {s
} are scaled values; the function returns the badness for when total
\type {t
}
1287 is supposed to be made from amounts that sum to
\type {s
}. The returned number is
1288 a reasonable approximation of $
100(t/s)^
3$;
1290 \subsubsection{\type {tex.resetparagraph
}}
1292 This function resets the parameters that
\TEX\ normally resets when a new paragraph
1295 \subsubsection{\type {tex.linebreak
}}
1298 local <node> nodelist, <table> info =
1299 tex.linebreak(<node> listhead, <table> parameters)
1302 The understood parameters are as follows:
1304 \starttabulate[|l|l|p|
]
1305 \NC \bf name
\NC \bf type
\NC \bf description
\NC \NR
1306 \NC pardir
\NC string
\NC \NC \NR
1307 \NC pretolerance
\NC number
\NC \NC \NR
1308 \NC tracingparagraphs
\NC number
\NC \NC \NR
1309 \NC tolerance
\NC number
\NC \NC \NR
1310 \NC looseness
\NC number
\NC \NC \NR
1311 \NC hyphenpenalty
\NC number
\NC \NC \NR
1312 \NC exhyphenpenalty
\NC number
\NC \NC \NR
1313 \NC pdfadjustspacing
\NC number
\NC \NC \NR
1314 \NC adjdemerits
\NC number
\NC \NC \NR
1315 \NC pdfprotrudechars
\NC number
\NC \NC \NR
1316 \NC linepenalty
\NC number
\NC \NC \NR
1317 \NC lastlinefit
\NC number
\NC \NC \NR
1318 \NC doublehyphendemerits
\NC number
\NC \NC \NR
1319 \NC finalhyphendemerits
\NC number
\NC \NC \NR
1320 \NC hangafter
\NC number
\NC \NC \NR
1321 \NC interlinepenalty
\NC number or table
\NC if a table, then it is an array like
\type {\interlinepenalties} \NC \NR
1322 \NC clubpenalty
\NC number or table
\NC if a table, then it is an array like
\type {\clubpenalties} \NC \NR
1323 \NC widowpenalty
\NC number or table
\NC if a table, then it is an array like
\type {\widowpenalties} \NC \NR
1324 \NC brokenpenalty
\NC number
\NC \NC \NR
1325 \NC emergencystretch
\NC number
\NC in scaled points
\NC \NR
1326 \NC hangindent
\NC number
\NC in scaled points
\NC \NR
1327 \NC hsize
\NC number
\NC in scaled points
\NC \NR
1328 \NC leftskip
\NC glue_spec node
\NC \NC \NR
1329 \NC rightskip
\NC glue_spec node
\NC \NC \NR
1330 \NC pdfignoreddimen
\NC number
\NC in scaled points
\NC \NR
1331 \NC parshape
\NC table
\NC \NC \NR
1334 Note that there is no interface for
\type {\displaywidowpenalties}, you have to
1335 pass the right choice for
\type {widowpenalties
} yourself.
1337 The meaning of the various keys should be fairly obvious from the table (the
1338 names match the
\TEX\ and
\PDFTEX\ primitives) except for the last
5 entries. The
1339 four
\type {pdf...line...
} keys are ignored if their value equals
\type
1342 It is your own job to make sure that
\type {listhead
} is a proper paragraph list:
1343 this function does not add any nodes to it. To be exact, if you want to replace
1344 the core line breaking, you may have to do the following (when you are not
1345 actually working in the
\type {pre_linebreak_filter
} or
\type {linebreak_filter
}
1346 callbacks, or when the original list starting at listhead was generated in
1351 add an
\quote {indent box
} and perhaps a
\type {local_par
} node at the start
1352 (only if you need them)
1355 replace any found final glue by an infinite penalty (or add such a penalty,
1356 if the last node is not a glue)
1359 add a glue node for the
\type {\parfillskip} after that penalty node
1362 make sure all the
\type {prev
} pointers are OK
1366 The result is a node list, it still needs to be vpacked if you want to assign it
1369 The returned
\type {info
} table contains four values that are all numbers:
1371 \starttabulate[|l|p|
]
1372 \NC prevdepth
\NC depth of the last line in the broken paragraph
\NC \NR
1373 \NC prevgraf
\NC number of lines in the broken paragraph
\NC \NR
1374 \NC looseness
\NC the actual looseness value in the broken paragraph
\NC \NR
1375 \NC demerits
\NC the total demerits of the chosen solution
\NC \NR
1378 Note there are a few things you cannot interface using this function: You cannot
1379 influence font expansion other than via
\type {pdfadjustspacing
}, because the
1380 settings for that take place elsewhere. The same is true for hbadness and hfuzz
1381 etc. All these are in the
\type {hpack()
} routine, and that fetches its own
1382 variables via globals.
1384 \subsubsection{\type {tex.shipout
}}
1387 tex.shipout(<number> n)
1390 Ships out box number
\type {n
} to the output file, and clears the box register.
1392 \section[texconfig
]{The
\type {texconfig
} table
}
1394 This is a table that is created empty. A startup
\LUA\ script could
1395 fill this table with a number of settings that are read out by
1396 the executable after loading and executing the startup file.
1398 \starttabulate[|lT|l|l|p|
]
1399 \NC \rmbf key
\NC \bf type
\NC \bf default
\NC \bf explanation
\NC \NR
1400 \NC kpse_init
\NC boolean
\NC true
1402 \type {false
} totally disables
\KPATHSEA\ initialisation, and enables
1403 interpretation of the following numeric key--value pairs. (only ever unset
1404 this if you implement
{\it all\/
} file find callbacks!)
1407 shell_escape
\NC string
\NC \type {'f'
} \NC
1408 Use
\type {'y'
} or
\type {'t'
} or
\type {'
1'
} to enable
\type {\write18}
1409 unconditionally,
\type {'p'
} to enable the commands that are listed in
\type
1410 {shell_escape_commands
}
1413 shell_escape_commands
\NC string
\NC \NC Comma-separated list of command
1414 names that may be executed by
\type {\write18} even if
\type {shell_escape
}
1415 is set to
\type {'p'
}. Do
{\it not\/
} use spaces around commas, separate any
1416 required command arguments by using a space, and use the
\ASCII\ double quote
1417 (
\type {"
}) for any needed argument or path quoting
1420 \NC string_vacancies
\NC number
\NC 75000 \NC cf.\ web2c docs
\NC \NR
1421 \NC pool_free
\NC number
\NC 5000 \NC cf.\ web2c docs
\NC \NR
1422 \NC max_strings
\NC number
\NC 15000 \NC cf.\ web2c docs
\NC \NR
1423 \NC strings_free
\NC number
\NC 100 \NC cf.\ web2c docs
\NC \NR
1424 \NC nest_size
\NC number
\NC 50 \NC cf.\ web2c docs
\NC \NR
1425 \NC max_in_open
\NC number
\NC 15 \NC cf.\ web2c docs
\NC \NR
1426 \NC param_size
\NC number
\NC 60 \NC cf.\ web2c docs
\NC \NR
1427 \NC save_size
\NC number
\NC 4000 \NC cf.\ web2c docs
\NC \NR
1428 \NC stack_size
\NC number
\NC 300 \NC cf.\ web2c docs
\NC \NR
1429 \NC dvi_buf_size
\NC number
\NC 16384 \NC cf.\ web2c docs
\NC \NR
1430 \NC error_line
\NC number
\NC 79 \NC cf.\ web2c docs
\NC \NR
1431 \NC half_error_line
\NC number
\NC 50 \NC cf.\ web2c docs
\NC \NR
1432 \NC max_print_line
\NC number
\NC 79 \NC cf.\ web2c docs
\NC \NR
1433 \NC hash_extra
\NC number
\NC 0 \NC cf.\ web2c docs
\NC \NR
1434 \NC pk_dpi
\NC number
\NC 72 \NC cf.\ web2c docs
\NC \NR
1435 \NC trace_file_names
\NC boolean
\NC true
1437 \type {false
} disables
\TEX's normal file open|-|close feedback (the
1438 assumption is that callbacks will take care of that)
1440 \NC file_line_error
\NC boolean
\NC false
1442 do
\type {file:line
} style error messages
1444 \NC halt_on_error
\NC boolean
\NC false
1446 abort run on the first encountered error
1448 \NC formatname
\NC string
\NC
1450 if no format name was given on the command line, this key will be tested first
1451 instead of simply quitting
1453 \NC jobname
\NC string
\NC
1455 if no input file name was given on the command line, this key will be tested
1456 first instead of simply giving up
1460 Note: the numeric values that match web2c parameters are only used if
\type
1461 {kpse_init
} is explicitly set to
\type {false
}. In all other cases, the normal
1462 values from
\type {texmf.cnf
} are used.
1464 \section{The
\type {texio
} library
}
1466 This library takes care of the low|-|level I/O interface.
1468 \subsection{Printing functions
}
1470 \subsubsection{\type {texio.write
}}
1473 texio.write(<string> target, <string> s, ...)
1474 texio.write(<string> s, ...)
1477 Without the
\type {target
} argument, writes all given strings to the same
1478 location(s)
\TEX\ writes messages to at this moment. If
\type {\batchmode} is in
1479 effect, it writes only to the log, otherwise it writes to the log and the
1480 terminal. The optional
\type {target
} can be one of three possibilities:
\type
1481 {term
},
\type {log
} or
\type {term and log
}.
1483 Note: If several strings are given, and if the first of these strings is or might
1484 be one of the targets above, the
\type {target
} must be specified explicitly to
1485 prevent
\LUA\ from interpreting the first string as the target.
1487 \subsubsection{\type {texio.write_nl
}}
1490 texio.write_nl(<string> target, <string> s, ...)
1491 texio.write_nl(<string> s, ...)
1494 This function behaves like
\type {texio.write
}, but make sure that the given
1495 strings will appear at the beginning of a new line. You can pass a single empty
1496 string if you only want to move to the next line.
1498 \subsubsection{\type {texio.setescape
}}
1500 You can disable
\type {^^
} escaping of control characters by passing a value of
1503 \section{The
\type {token
} libray
}
1505 The current
\type {token
} library will be replaced by a new one that is more
1506 flexible and powerful. The transition takes place in steps. In version
0.80 we
1507 have
\type {token
} and in version
0.85 the old lib will be replaced
1508 completely. So if you use this new mechanism in production code you need to be
1509 aware of incompatible updates between
0.80 and
0.90. Because the related in- and
1510 output code will also be cleaned up and rewritten you should be aware of
1511 incompatible logging and error reporting too.
1513 The old library presents tokens as triplets or numbers, the new library presents
1514 a userdata object. The old library used a callback to intercept tokens in the
1515 input but the new library provides a basic scanner infrastructure that can be
1516 used to write macros that accept a wide range of arguments. This interface is on
1517 purpose kept general and as performance is quite ok one can build additional
1518 parsers without too much overhead. It's up to macro package writers to see how
1519 they can benefit from this as the main principle behind
\LUATEX\ is to provide a
1520 minimal set of tools and no solutions.
1522 The current functions in the
\type {token
} namespace are given in the next
1525 \starttabulate[|lT|lT|p|
]
1526 \NC \bf function
\NC \bf argument
\NC \bf result
\NC \NR
1528 \NC is_token
\NC token
\NC checks if the given argument is a token userdatum
\NC \NR
1529 \NC get_next
\NC \NC returns the next token in the input
\NC \NR
1530 \NC scan_keyword
\NC string
\NC returns true if the given keyword is gobbled
\NC \NR
1531 \NC scan_int
\NC \NC returns a number
\NC \NR
1532 \NC scan_dimen
\NC infinity, mu-units
\NC returns a number representing a dimension and or two numbers being the filler and order
\NC \NR
1533 \NC scan_glue
\NC mu-units
\NC returns a glue spec node
\NC \NR
1534 \NC scan_toks
\NC definer, expand
\NC returns a table of tokens token list (this can become a linked list in later releases)
\NC \NR
1535 \NC scan_code
\NC bitset
\NC returns a character if its category is in the given bitset (representing catcodes)
\NC \NR
1536 \NC scan_string
\NC \NC returns a string given between
\type {{}}, as
\type {\macro} or as sequence of characters with catcode
11 or
12 \NC \NR
1537 \NC scan_word
\NC \NC returns a sequence of characters with catcode
11 or
12 as string
\NC \NR
1538 \NC scan_csname
\NC \NC returns
\type {foo
} after scanning
\type {\foo} \NC \NR
1539 \NC set_macro
\NC see below
\NC assign a macro
\NC \NR
1540 \NC create
\NC \NC returns a userdata token object of the given control sequence name (or character); this interface can change
\NC \NR
1543 The scanners can be considered stable apart from the one scanning for a token.
1544 This is because futures releases can return a linked list instead of a table (as
1545 with nodes). The
\type {scan_code
} function takes an optional number, the
\type
1546 {keyword
} function a normal
\LUA\ string. The
\type {infinity
} boolean signals
1547 that we also permit
\type {fill
} as dimension and the
\type {mu-units
} flags the
1548 scanner that we expect math units. When scanning tokens we can indicate that we
1549 are defining a macro, in which case the result will also provide information
1550 about what arguments are expected and in the result this is separated from the
1551 meaning by a separator token. The
\type {expand
} flag determines if the list will
1554 The string scanner scans for something between curly braces and expands on the
1555 way, or when it sees a control sequence it will return its meaning. Otherwise it
1556 will scan characters with catcode
\type {letter
} or
\type {other
}. So, given the
1557 following definition:
1564 \typebuffer \getbuffer
1568 \starttabulate[|l|Tl|l|
]
1569 \NC \type {\directlua{token
.scan_string()}{foo
}} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
} {foo
} \NC full expansion
\NR
1570 \NC \type {\directlua{token
.scan_string()}foo
} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
} foo
\NC letters and others
\NR
1571 \NC \type {\directlua{token
.scan_string()}\foo} \NC \directlua{context("
{\
\red\
\type {"..token.scan_string().."
}}")
}\foo \NC meaning
\NR
1574 The
\type {\foo} case only gives the meaning, but one can pass an already
1575 expanded definition (
\type {\edef}'d). In the case of the braced variant one can of
1576 course use the
\type {\detokenize} and
\type {\unexpanded} primitives as there we
1579 The
\type {scan_word
} scanner can be used to implement for instance a number scanner:
1582 function token.scan_number(base)
1583 return tonumber(token.scan_word(),base)
1587 This scanner accepts any valid
\LUA\ number so it is a way to pick up floats
1590 The creator function can be used as follows:
1593 local t = token.create("relax")
1596 This gives back a token object that has the properties of the
\type {\relax}
1597 primitive. The possible properties of tokens are:
1599 \starttabulate[|lT|p|
]
1600 \NC command
\NC a number representing the internal command number
\NC \NR
1601 \NC cmdname
\NC the type of the command (for instance the catcode in case of a
1602 character or the classifier that determines the internal
1604 \NC csname
\NC the associated control sequence (if applicable)
\NC \NR
1605 \NC id
\NC the unique id of the token
\NC \NR
1606 %NC tok \NC \NC \NR % might change
1607 \NC active
\NC a boolean indicating the active state of the token
\NC \NR
1608 \NC expandable
\NC a boolean indicating if the token (macro) is expandable
\NC \NR
1609 \NC protected
\NC a boolean indicating if the token (macro) is protected
\NC \NR
1612 The numbers that represent a catcode are the same as in
\TEX\ itself, so using
1613 this information assumes that you know a bit about
\TEX's internals. The other
1614 numbers and names are used consistently but are not frozen. So, when you use them
1615 for comparing you can best query a known primitive or character first to see the
1618 More interesting are the scanners. You can use the
\LUA\ interface as follows:
1629 mymacro(\number
\dimexpr
#1)
1637 You can also do this:
1642 local d
= token
.scan_dimen()
1657 It is quite clear from looking at the code what the first method needs as
1658 argument(s). For the second method you need to look at the
\LUA\ code to see what
1659 gets picked up. Instead of passing from
\TEX\ to
\LUA\ we let
\LUA\ fetch from
1662 In the first case the input is tokenized and then turned into a string when it's
1663 passed to
\LUA\ where it gets interpreted. In the second case only a function
1664 call gets interpreted but then the input is picked up by explicitly calling the
1665 scanner functions. These return proper
\LUA\ variables so no further conversion
1666 has to be done. This is more efficient but in practice (given what
\TEX\ has to
1667 do) this effect should not be overestimated. For numbers and dimensions it saves a
1668 bit but for passing strings conversion to and from tokens has to be done anyway
1669 (although we can probably speed up the process in later versions if needed).
1671 When the interface is stable and has replaced the old one completely we will add
1672 some more information here. By that time the internals have been cleaned up a bit
1673 more so we know then what will stay and go. A positive side effect of this
1674 transition is that we can simplify the input part because we no longer need to
1675 intercept using callbacks.
1677 The
\type {set_macro
} function can get upto
4 arguments:
1680 setmacro("csname","content")
1681 setmacro("csname","content","global")
1685 You can pass a catcodetable identifier as first argument:
1688 setmacro(catcodetable,"csname","content")
1689 setmacro(catcodetable,"csname","content","global")
1690 setmacro(catcodetable,"csname")
1693 The results are like:
1696 \def\csname{content
}
1697 \gdef\csname{content
}
1701 There is a (for now) experimental putter:
1704 local t1 = token.get_next()
1705 local t2 = token.get_next()
1706 local t3 = token.get_next()
1707 local t4 = token.get_next()
1708 -- watch out, we flush in sequence
1709 token.put_next
{ t1, t2
}
1710 -- but this one gets pushed in front
1711 token.put_next ( t3, t4 )
1714 When we scan
\type {wxyz!
} we get
\type {yzwx!
} back. The argument is either a table
1715 with tokens or a list of tokens.
1717 \section{The
\type {kpse
} library
}
1719 This library provides two separate, but nearly identical interfaces to the
1720 \KPATHSEA\ file search functionality: there is a
\quote {normal
} procedural
1721 interface that shares its kpathsea instance with
\LUATEX\ itself, and an object
1722 oriented interface that is completely on its own.
1724 \subsection{\type {kpse.set_program_name
} and
\type {kpse.new
}}
1726 Before the search library can be used at all, its database has to be initialized.
1727 There are three possibilities, two of which belong to the procedural interface.
1729 First, when
\LUATEX\ is used to typeset documents, this initialization happens
1730 automatically and the
\KPATHSEA\ executable and program names are set to
\type
1731 {luatex
} (that is, unless explicitly prohibited by the user's startup script.
1732 See~
\in {section
} [init
] for more details).
1734 Second, in
\TEXLUA\ mode, the initialization has to be done explicitly via the
1735 \type {kpse.set_program_name
} function, which sets the
\KPATHSEA\ executable
1736 (and optionally program) name.
1739 kpse.set_program_name(<string> name)
1740 kpse.set_program_name(<string> name, <string> progname)
1743 The second argument controls the use of the
\quote {dotted
} values in the
\type
1744 {texmf.cnf
} configuration file, and defaults to the first argument.
1746 Third, if you prefer the object oriented interface, you have to call a different
1747 function. It has the same arguments, but it returns a userdata variable.
1750 local kpathsea = kpse.new(<string> name)
1751 local kpathsea = kpse.new(<string> name, <string> progname)
1754 Apart from these two functions, the calling conventions of the interfaces are
1755 identical. Depending on the chosen interface, you either call
\type
1756 {kpse.find_file()
} or
\type {kpathsea:find_file()
}, with identical arguments and
1759 \subsection{\type {find_file
}}
1761 The most often used function in the library is
\type {find_file
}:
1764 <string> f = kpse.find_file(<string> filename)
1765 <string> f = kpse.find_file(<string> filename, <string> ftype)
1766 <string> f = kpse.find_file(<string> filename, <boolean> mustexist)
1767 <string> f = kpse.find_file(<string> filename, <string> ftype, <boolean> mustexist)
1768 <string> f = kpse.find_file(<string> filename, <string> ftype, <number> dpi)
1773 \startitemize[intro
]
1777 the name of the file you want to find, with or without extension.
1781 maps to the
\type {-format
} argument of
\KPSEWHICH. The supported
\type {ftype
}
1782 values are the same as the ones supported by the standalone
\type {kpsewhich
}
1783 program:
\startluacode
1798 "font feature files",
1820 "other binary files",
1827 "PostScript header",
1828 "subfont definition files",
1830 "TeX system documentation",
1831 "TeX system sources",
1844 context("
{\
\tttf \letterpercent, t
}",list)
1847 The default type is
\type {tex
}. Note: this is different from
\KPSEWHICH, which
1848 tries to deduce the file type itself from looking at the supplied extension.
1852 is similar to
\KPSEWHICH's
\type {-must-exist
}, and the default is
\type {false
}.
1853 If you specify
\type {true
} (or a non|-|zero integer), then the
\KPSE\ library
1854 will search the disk as well as the
\type {ls-R
} databases.
1858 This is used for the size argument of the formats
\type {pk
},
\type {gf
}, and
1859 \type {bitmap font
}.
\stopitemize
1862 \subsection{\type {lookup
}}
1864 A more powerful (but slower) generic method for finding files is also available.
1865 It returns a string for each found file.
1868 <string> f, ... = kpse.lookup(<string> filename, <table> options)
1871 The options match commandline arguments from
\type {kpsewhich
}:
1873 \starttabulate[|l|l|p|
]
1874 \NC \rmbf key
\NC \rmbf type
\NC \rmbf description
\NC \NR
1875 \NC debug
\NC number
\NC set debugging flags for this lookup
\NC \NR
1876 \NC format
\NC string
\NC use specific file type (see list above)
\NC \NR
1877 \NC dpi
\NC number
\NC use this resolution for this lookup; default
600\NC \NR
1878 \NC path
\NC string
\NC search in the given path
\NC \NR
1879 \NC all
\NC boolean
\NC output all matches, not just the first
\NC \NR
1880 \NC mustexist
\NC boolean
\NC search the disk as well as ls-R if necessary
\NC \NR
1881 \NC mktexpk
\NC boolean
\NC disable/enable mktexpk generation for this lookup
\NC \NR
1882 \NC mktextex
\NC boolean
\NC disable/enable mktextex generation for this lookup
\NC \NR
1883 \NC mktexmf
\NC boolean
\NC disable/enable mktexmf generation for this lookup
\NC \NR
1884 \NC mktextfm
\NC boolean
\NC disable/enable mktextfm generation for this lookup
\NC \NR
1885 \NC subdir
\NC string
1886 or table
\NC only output matches whose directory part
1887 ends with the given string(s)
\NC \NR
1890 \subsection{\type {init_prog
}}
1892 Extra initialization for programs that need to generate bitmap fonts.
1895 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode)
1896 kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode, <string> fallback)
1899 \subsection{\type {readable_file
}}
1901 Test if an (absolute) file name is a readable file.
1904 <string> f = kpse.readable_file(<string> name)
1907 The return value is the actual absolute filename you should use, because the disk
1908 name is not always the same as the requested name, due to aliases and
1909 system|-|specific handling under e.g.\
\MSDOS. Returns
\type {nil
} if the file
1910 does not exist or is not readable.
1912 \subsection{\type {expand_path
}}
1914 Like kpsewhich's
\type {-expand-path
}:
1917 <string> r = kpse.expand_path(<string> s)
1920 \subsection{\type {expand_var
}}
1922 Like kpsewhich's
\type {-expand-var
}:
1925 <string> r = kpse.expand_var(<string> s)
1928 \subsection{\type {expand_braces
}}
1930 Like kpsewhich's
\type {-expand-braces
}:
1933 <string> r = kpse.expand_braces(<string> s)
1936 \subsection{\type {show_path
}}
1938 Like kpsewhich's
\type {-show-path
}:
1941 <string> r = kpse.show_path(<string> ftype)
1945 \subsection{\type {var_value
}}
1947 Like kpsewhich's
\type {-var-value
}:
1950 <string> r = kpse.var_value(<string> s)
1953 \subsection{\type {version
}}
1955 Returns the kpathsea version string.
1958 <string> r = kpse.version()