diff options
Diffstat (limited to 'Master/texmf-dist/doc/luatex/base/luatex-tex.tex')
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatex-tex.tex | 316 |
1 files changed, 196 insertions, 120 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/luatex-tex.tex b/Master/texmf-dist/doc/luatex/base/luatex-tex.tex index edf86870c6a..6096b1e77ec 100644 --- a/Master/texmf-dist/doc/luatex/base/luatex-tex.tex +++ b/Master/texmf-dist/doc/luatex/base/luatex-tex.tex @@ -99,70 +99,81 @@ The current list is: \starttabulate[|lT|p|] \NC \rmbf key \NC \bf explanation \NC \NR -\NC pdf_gone \NC written \PDF\ bytes \NC \NR -\NC pdf_ptr \NC not yet written \PDF\ bytes \NC \NR +\NC banner \NC terminal display banner \NC \NR +\NC best_page_break \NC the current best break (a node) \NR \NR +\NC buf_size \NC current allocated size of the line buffer \NC \NR +\NC callbacks \NC total number of executed callbacks so far \NC \NR +\NC cs_count \NC number of control sequences \NC \NR +\NC dest_names_size \NC \PDF\ destination table size \NC \NR \NC dvi_gone \NC written \DVI\ bytes \NC \NR \NC dvi_ptr \NC not yet written \DVI\ bytes \NC \NR -\NC total_pages \NC number of written pages \NC \NR -\NC output_file_name \NC name of the \PDF\ or \DVI\ file \NC \NR -\NC log_name \NC name of the log file \NC \NR -\NC banner \NC terminal display banner \NC \NR -\NC var_used \NC variable (one|-|word) memory in use \NC \NR \NC dyn_used \NC token (multi|-|word) memory in use \NC \NR -\NC str_ptr \NC number of strings \NC \NR -\NC init_str_ptr \NC number of \INITEX\ strings \NC \NR -\NC max_strings \NC maximum allowed strings \NC \NR -\NC pool_ptr \NC string pool index \NC \NR -\NC init_pool_ptr \NC \INITEX\ string pool index \NC \NR -\NC pool_size \NC current size allocated for string characters \NC \NR -\NC node_mem_usage \NC a string giving insight into currently used nodes \NC \NR -\NC var_mem_max \NC number of allocated words for nodes \NC \NR -\NC fix_mem_max \NC number of allocated words for tokens \NC \NR +\NC filename \NC name of the current input file \NC \NR \NC fix_mem_end \NC maximum number of used tokens \NC \NR -\NC cs_count \NC number of control sequences \NC \NR -\NC hash_size \NC size of hash \NC \NR -\NC hash_extra \NC extra allowed hash \NC \NR +\NC fix_mem_min \NC minimum number of allocated words for tokens \NC \NR +\NC fix_mem_max \NC maximum number of allocated words for tokens \NC \NR \NC font_ptr \NC number of active fonts \NC \NR +\NC hash_extra \NC extra allowed hash \NC \NR +\NC hash_size \NC size of hash \NC \NR +\NC indirect_callbacks \NC number of those that were themselves a result of other callbacks (e.g. file readers) \NC \NR +\NC ini_version \NC \type {true} if this is an \INITEX\ run \NC \NR +\NC init_pool_ptr \NC \INITEX\ string pool index \NC \NR +\NC init_str_ptr \NC number of \INITEX\ strings \NC \NR \NC input_ptr \NC th elevel of input we're at \NC \NR +\NC inputid \NC numeric id of the current input \NC \NR +\NC largest_used_mark \NC max referenced marks class \NC \NR +\NC lasterrorcontext \NC last error context string (with newlines) \NC \NR +\NC lasterrorstring \NC last \TEX\ error string \NC \NR +\NC lastluaerrorstring \NC last \LUA\ error string \NC \NR +\NC lastwarningstring \NC last warning tag, normally an indication of in what part\NC \NR +\NC lastwarningtag \NC last warning string\NC \NR +\NC linenumber \NC location in the current input file \NC \NR +\NC log_name \NC name of the log file \NC \NR +\NC luabytecode_bytes \NC number of bytes in \LUA\ bytecode registers \NC \NR +\NC luabytecodes \NC number of active \LUA\ bytecode registers \NC \NR +\NC luastate_bytes \NC number of bytes in use by \LUA\ interpreters \NC \NR +\NC luatex_engine \NC the \LUATEX\ engine identifier \NC \NR +\NC luatex_hashchars \NC length to which \LUA\ hashes strings ($2^n$) \NC \NR +\NC luatex_hashtype \NC the hash method used (in \LUAJITTEX) \NC \NR +\NC luatex_revision \NC the \LUATEX\ revision string \NC \NR +\NC luatex_revision \NC the \LUATEX\ revision string \NC \NR +\NC luatex_version \NC the \LUATEX\ version number \NC \NR +\NC max_buf_stack \NC max used buffer position \NC \NR \NC max_in_stack \NC max used input stack entries \NC \NR \NC max_nest_stack \NC max used nesting stack entries \NC \NR \NC max_param_stack \NC max used parameter stack entries \NC \NR -\NC max_buf_stack \NC max used buffer position \NC \NR \NC max_save_stack \NC max used save stack entries \NC \NR -\NC stack_size \NC input stack size \NC \NR +\NC max_strings \NC maximum allowed strings \NC \NR \NC nest_size \NC nesting stack size \NC \NR -\NC param_size \NC parameter stack size \NC \NR -\NC buf_size \NC current allocated size of the line buffer \NC \NR -\NC save_size \NC save stack size \NC \NR +\NC node_mem_usage \NC a string giving insight into currently used nodes \NC \NR \NC obj_ptr \NC max \PDF\ object pointer \NC \NR \NC obj_tab_size \NC \PDF\ object table size \NC \NR -\NC pdf_os_cntr \NC max \PDF\ object stream pointer \NC \NR -\NC pdf_os_objidx \NC \PDF\ object stream index \NC \NR +\NC output_active \NC \type {true} if the \type {\output} routine is active \NC \NR +\NC output_file_name \NC name of the \PDF\ or \DVI\ file \NC \NR +\NC param_size \NC parameter stack size \NC \NR \NC pdf_dest_names_ptr \NC max \PDF\ destination pointer \NC \NR -\NC dest_names_size \NC \PDF\ destination table size \NC \NR +\NC pdf_gone \NC written \PDF\ bytes \NC \NR \NC pdf_mem_ptr \NC max \PDF\ memory used \NC \NR \NC pdf_mem_size \NC \PDF\ memory size \NC \NR -\NC largest_used_mark \NC max referenced marks class \NC \NR -\NC filename \NC name of the current input file \NC \NR -\NC inputid \NC numeric id of the current input \NC \NR -\NC linenumber \NC location in the current input file \NC \NR -\NC lasterrorstring \NC last \TEX\ error string \NC \NR -\NC lastluaerrorstring \NC last \LUA\ error string \NC \NR -\NC lastwarningtag \NC last warning string\NC \NR -\NC lastwarningstring \NC last warning tag, normally an indication of in what part\NC \NR -\NC lasterrorcontext \NC last error context string (with newlines) \NC \NR -\NC luabytecodes \NC number of active \LUA\ bytecode registers \NC \NR -\NC luabytecode_bytes \NC number of bytes in \LUA\ bytecode registers \NC \NR -\NC luastate_bytes \NC number of bytes in use by \LUA\ interpreters \NC \NR -\NC output_active \NC \type {true} if the \type {\output} routine is active \NC \NR -\NC callbacks \NC total number of executed callbacks so far \NC \NR -\NC indirect_callbacks \NC number of those that were themselves - a result of other callbacks (e.g. file readers) \NC \NR -\NC luatex_version \NC the \LUATEX\ version number \NC \NR -\NC luatex_revision \NC the \LUATEX\ revision string \NC \NR -\NC ini_version \NC \type {true} if this is an \INITEX\ run \NC \NR -\NC shell_escape \NC \type {0} means disabled, \type {1} is restricted and - \type {2} means anything is permitted \NC \NR +\NC pdf_os_cntr \NC max \PDF\ object stream pointer \NC \NR +\NC pdf_os_objidx \NC \PDF\ object stream index \NC \NR +\NC pdf_ptr \NC not yet written \PDF\ bytes \NC \NR +\NC pool_ptr \NC string pool index \NC \NR +\NC pool_size \NC current size allocated for string characters \NC \NR +\NC save_size \NC save stack size \NC \NR +\NC shell_escape \NC \type {0} means disabled, \type {1} is restricted and \type {2} means anything is permitted \NC \NR +\NC safer_option \NC \type {1} means safer is enforced \NC \NR +\NC kpse_used \NC \type {1} means that kpse is used \NC \NR +\NC stack_size \NC input stack size \NC \NR +\NC str_ptr \NC number of strings \NC \NR +\NC total_pages \NC number of written pages \NC \NR +\NC var_mem_max \NC number of allocated words for nodes \NC \NR +\NC var_used \NC variable (one|-|word) memory in use \NC \NR +\NC lc_collate \NC the value of \type {LC_COLLATE} at startup time (becomes \type {C} at startup) \NC \NR +\NC lc_ctype \NC the value of \type {LC_CTYPE} at startup time (becomes \type {C} at startup) \NC \NR +%NC lc_monetary \NC the value of \type {LC_MONETARY} at startup time \NC \NR +\NC lc_numeric \NC the value of \type {LC_NUMERIC} at startup time \NC \NR +%NC lc_time \NC the value of \type {LC_TIME} at startup time (becomes \type {C} at startup) \NC \NR \stoptabulate The error and warning messages can be wiped with the \type {resetmessages} @@ -197,9 +208,7 @@ writable as well as readable (stuff like \type {\tracingcommands} and For all the parameters in this section, it is possible to access them directly using their names as index in the \type {tex} table, or by using one of the -functions \type {tex.get} and \type {tex.set}. If you created aliasses, -you can use accessors like \type {tex.getdimen} as these also understand -names of built|-|in variables. +functions \type {tex.get} and \type {tex.set}. The exact parameters and return values differ depending on the actual parameter, and so does whether \type {tex.set} has any effect. For the parameters that {\it @@ -211,6 +220,16 @@ tex.set (["global",] <string> n, ...) ... = tex.get (<string> n) \stopfunctioncall +Glue is kind of special because there are five values involved. The return value +is a \type {glue_spec} node btu when you pass \type {false} as last argument to +\type {tex.get} you get the width of the glue and when you pass \type {true} you +get all five values. Otherwise you get a node which is a copy of the internal +value so you are responsible for its freeing at the \LUA\ end. When you set a +glue quantity you can either pass a \type {glue_spec} or upto five numbers. + +For the registers you can use \type {getskip} (node), \type {getglue} (numbers) +\type {setskip} (node) and \type {setglue} (numbers). + There are also dedicated setters, getters and checkers: \startfunctioncall @@ -474,10 +493,6 @@ tex.everymath tex.everypar tex.everyvbox tex.output -tex.pdfpageattr -tex.pdfpageresources -tex.pdfpagesattr -tex.pdfpkmode \stoptyping \stopthreecolumns @@ -494,16 +509,10 @@ tex.formatname tex.jobname tex.luatexbanner tex.luatexrevision -tex.pdfnormaldeviate tex.fontname(number) -tex.pdffontname(number) -tex.pdffontobjnum(number) -tex.pdffontsize(number) tex.uniformdeviate(number) tex.number(number) tex.romannumeral(number) -tex.pdfpageref(number) -tex.pdfxformname(number) tex.fontidentifier(number) \stoptyping \stoptwocolumns @@ -530,15 +539,9 @@ tex.lastkern tex.lastskip tex.lastnodetype tex.inputlineno -tex.pdflastobj -tex.pdflastxform -tex.pdflastximage -tex.pdflastximagepages -tex.pdflastannot -tex.pdflastxpos -tex.pdflastypos -tex.pdfrandomseed -tex.pdflastlink +tex.lastxpos +tex.lastypos +tex.randomseed tex.luatexversion tex.eTeXminorversion tex.eTeXversion @@ -547,7 +550,6 @@ tex.currentgrouptype tex.currentiflevel tex.currentiftype tex.currentifbranch -tex.pdflastximagecolordepth \stoptyping \stopthreecolumns @@ -697,7 +699,7 @@ Where the table for \type {mathcode} is an array of 3 numbers, like this: \starttyping { - <number> mathclass, + <number> class, <number> family, <number> character } @@ -717,8 +719,12 @@ And the table for \type {delcode} is an array with 4 numbers, like this: You can also avoid the table: \startfunctioncall +tex.setmathcode (["global"], <number> n, <number> class, + <number> family, <number> character) class, family, char = tex.getmathcodes (<number> n) +tex.setdelcode (["global"], <number> n, <number> smallfam, + <number> smallchar, <number> largefam, <number> largechar) smallfam, smallchar, largefam, largechar = tex.getdelcodes (<number> n) \stopfunctioncall @@ -770,10 +776,13 @@ called xforms in \PDF). You can (re)use the box with \type {\useboxresource} or by creating a rule node with subtype~2. \starttyping -local index = tex.saveboxresource(n,attributes,resources,immediate) +local index = tex.saveboxresource(n,attributes,resources,immediate,type) \stoptyping -The optional second and third arguments are strings, the fourth is a boolean. +The optional second and third arguments are strings, the fourth is a boolean. The +fifth argument is a type. When set to non|-|zero the \type {/Type} entry is +omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3 will write +a \type {/Matrix}. You can generate the reference (a rule type) with: @@ -912,8 +921,7 @@ The known fields are: \NC head \NC node \NC all \NC the head of the current list \NC \NR \NC tail \NC node \NC all \NC the tail of the current list \NC \NR \NC prevgraf \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR -\NC prevdepth \NC number \NC vmode \NC depth of the previous paragraph (equal to \type {\pdfignoreddimen} - when it is to be ignored) \NC \NR +\NC prevdepth \NC number \NC vmode \NC depth of the previous paragraph \NC \NR \NC spacefactor \NC number \NC hmode \NC the current space factor \NC \NR \NC dirs \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR \NC noad \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator, @@ -1157,11 +1165,12 @@ line of error help. for i,v in pairs (tex.hashtokens()) do ... end \stopfunctioncall -Returns a name and token table pair (see~\in {section} [luatokens] about token -tables) iterator for every non-zero entry in the hash table. This can be useful -for debugging, but note that this also reports control sequences that may be -unreachable at this moment due to local redefinitions: it is strictly a dump of -the hash table. +Returns a list of names. This can be useful for debugging, but note that this +also reports control sequences that may be unreachable at this moment due to +local redefinitions: it is strictly a dump of the hash table. You can use \type +{token.create} to inspect properties, for instance when the \type {command} key +in a created table equals \type {123}, you have the \type {cmdname} value \type +{undefined_cs}. \subsection[luaprimitives]{Functions for dealing with primitives } @@ -1250,7 +1259,7 @@ end \NC luatex \NC \ctxlua{document.showprimitives('luatex') } \NC \NR \stoptabulate -Note that \type {'luatex'} does not contain \type {directlua}, as that is +Note that \type {luatex} does not contain \type {directlua}, as that is considered to be a core primitive, along with all the \TEX82 primitives, so it is part of the list that is returned from \type {'core'}. @@ -1260,7 +1269,7 @@ part of the list that is returned from \type {'core'}. Running \type {tex.extraprimitives()} will give you the complete list of primitives \type {-ini} startup. It is exactly equivalent to \type -{tex.extraprimitives('etex' and 'luatex')}. +{tex.extraprimitives("etex","luatex")}. \subsubsection{\type {tex.primitives}} @@ -1268,16 +1277,7 @@ primitives \type {-ini} startup. It is exactly equivalent to \type <table> t = tex.primitives() \stopfunctioncall -This function returns a hash table listing all primitives that \LUATEX\ knows -about. The keys in the hash are primitives names, the values are tables -representing tokens (see~\in{section }[luatokens]). The third value is always -zero. - -{\em In the beginning we had \type {omega} and \type {pdftex} subsets but in the -meantime relevant primitives ave been promoted (either or not adapted) to the -\type {luatex} set when found useful, or removed when considered to be of no use. -Originally we had two sets of math definition primitives but the \OMEGA\ ones -have been removed, so we no longer have a subset for math either.} +This function returns a list of all primitives that \LUATEX\ knows about. \subsection{Core functionality interfaces} @@ -1468,11 +1468,10 @@ values from \type {texmf.cnf} are used. \section{The \type {texio} library} -This library takes care of the low|-|level I/O interface. +This library takes care of the low|-|level I/O interface: writing to the log file +and|/|or console. -\subsection{Printing functions} - -\subsubsection{\type {texio.write}} +\subsection{\type {texio.write}} \startfunctioncall texio.write(<string> target, <string> s, ...) @@ -1489,7 +1488,7 @@ Note: If several strings are given, and if the first of these strings is or migh be one of the targets above, the \type {target} must be specified explicitly to prevent \LUA\ from interpreting the first string as the target. -\subsubsection{\type {texio.write_nl}} +\subsection{\type {texio.write_nl}} \startfunctioncall texio.write_nl(<string> target, <string> s, ...) @@ -1500,32 +1499,23 @@ This function behaves like \type {texio.write}, but make sure that the given strings will appear at the beginning of a new line. You can pass a single empty string if you only want to move to the next line. -\subsubsection{\type {texio.setescape}} +\subsection{\type {texio.setescape}} You can disable \type {^^} escaping of control characters by passing a value of zero. -\section{The \type {token} libray} +\section{The \type {token} library} -The current \type {token} library will be replaced by a new one that is more -flexible and powerful. The transition takes place in steps. In version 0.80 we -have \type {token} and in version 0.85 the old lib will be replaced -completely. So if you use this new mechanism in production code you need to be -aware of incompatible updates between 0.80 and 0.90. Because the related in- and -output code will also be cleaned up and rewritten you should be aware of -incompatible logging and error reporting too. +\subsection{The scanner} -The old library presents tokens as triplets or numbers, the new library presents -a userdata object. The old library used a callback to intercept tokens in the -input but the new library provides a basic scanner infrastructure that can be -used to write macros that accept a wide range of arguments. This interface is on +The token library provides means to intercept the input and deal with it at the +\LUA\ level. The library provides a basic scanner infrastructure that can be used +to write macros that accept a wide range of arguments. This interface is on purpose kept general and as performance is quite ok one can build additional parsers without too much overhead. It's up to macro package writers to see how they can benefit from this as the main principle behind \LUATEX\ is to provide a -minimal set of tools and no solutions. - -The current functions in the \type {token} namespace are given in the next -table: +minimal set of tools and no solutions. The functions provided in the \type +{token} namespace are given in the next table: \starttabulate[|lT|lT|p|] \NC \bf function \NC \bf argument \NC \bf result \NC \NR @@ -1673,11 +1663,7 @@ do) this effect should not be overestimated. For numbers and dimensions it saves bit but for passing strings conversion to and from tokens has to be done anyway (although we can probably speed up the process in later versions if needed). -When the interface is stable and has replaced the old one completely we will add -some more information here. By that time the internals have been cleaned up a bit -more so we know then what will stay and go. A positive side effect of this -transition is that we can simplify the input part because we no longer need to -intercept using callbacks. +\subsection{Macros} The \type {set_macro} function can get upto 4 arguments: @@ -1703,6 +1689,8 @@ The results are like: \def\csname{} \stoptyping +\subsection{Pushing back} + There is a (for now) experimental putter: \starttyping @@ -1719,6 +1707,94 @@ token.put_next ( t3, t4 ) When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a table with tokens or a list of tokens. +\subsection{Nota bene} + +When scanning for the next token you need to keep in mind that we're not scanning +like \TEX\ does: expanding, changing modes and doing things as it goes. When we +scan with \LUA\ we just pick up tokens. Say that we have: + +\starttyping +\bar +\stoptyping + +but \type {\bar} is undefined. Normally \TEX\ will then issue an error message. +However, when we have: + +\starttyping +\def\foo{\bar} +\stoptyping + +We get no error, unless we expand \type {\foo} while \type {\bar} is still +undefined. What happens is that as soon as \TEX\ sees an undefined macro it will +create a hash entry and when later it gets defined that entry will be reused. So, +\type {\bar} really exists but can be in an undefined state. + +\startbuffer[demo] +bar : \directlua{tex.print(token.scan_csname())}\bar +foo : \directlua{tex.print(token.scan_csname())}\foo +myfirstbar : \directlua{tex.print(token.scan_csname())}\myfirstbar +\stopbuffer + +\startlines +\getbuffer[demo] +\stoplines + +This was entered as: + +\typebuffer[demo] + +The reason that you see \type {bar} reported and not \type {myfirstbar} is that +\type {\bar} was already used in a previous paragraph. + +If we now say: + +\startbuffer +\def\foo{} +\stopbuffer + +\typebuffer \getbuffer + +we get: + +\startlines +\getbuffer[demo] +\stoplines + +And if we say + +\startbuffer +\def\foo{\bar} +\stopbuffer + +\typebuffer \getbuffer + +we get: + +\startlines +\getbuffer[demo] +\stoplines + +When scanning from \LUA\ we are not in a mode that defines (undefined) macros at +all. There we just get the real primitive undefined macro token. + +\startbuffer +\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\myfirstbar +\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mysecondbar +\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mythirdbar +\stopbuffer + +\startlines +\getbuffer +\stoplines + +This was generated with: + +\typebuffer + +So, we do get a unique token because after all we need some kind of \LUA\ object +that can be used and garbage collected, but it is basically the same one, +representing an undefined control sequence. + \section{The \type {kpse} library} This library provides two separate, but nearly identical interfaces to the |