| 1 |
% engine=luatex language=uk |
| 2 |
|
| 3 |
% lua.newtable |
| 4 |
|
| 5 |
\environment luatex-style |
| 6 |
|
| 7 |
\startcomponent luatex-tex |
| 8 |
|
| 9 |
\startchapter[reference=tex,title={The \TEX\ related libraries}] |
| 10 |
|
| 11 |
\startsection[title={The \type {lua} library}][library=lua] |
| 12 |
|
| 13 |
\startsubsection[title={Version information}] |
| 14 |
|
| 15 |
\topicindex{libraries+\type{lua}} |
| 16 |
\topicindex{version} |
| 17 |
|
| 18 |
\libindex{version} |
| 19 |
|
| 20 |
This library contains one read|-|only item: |
| 21 |
|
| 22 |
\starttyping |
| 23 |
<string> s = lua.version |
| 24 |
\stoptyping |
| 25 |
|
| 26 |
This returns the \LUA\ version identifier string. The value is currently |
| 27 |
\directlua {tex.print(lua.version)}. |
| 28 |
|
| 29 |
\stopsubsection |
| 30 |
|
| 31 |
\startsubsection[title={Bytecode registers}] |
| 32 |
|
| 33 |
\topicindex{bytecodes} |
| 34 |
\topicindex{registers+bytecodes} |
| 35 |
|
| 36 |
\libindex{bytecode} |
| 37 |
\libindex{setbytecode} |
| 38 |
\libindex{getbytecode} |
| 39 |
|
| 40 |
\LUA\ registers can be used to store \LUA\ code chunks. The accepted values for |
| 41 |
assignments are functions and \type {nil}. Likewise, the retrieved value is |
| 42 |
either a function or \type {nil}. |
| 43 |
|
| 44 |
\starttyping |
| 45 |
lua.bytecode[<number> n] = <function> f |
| 46 |
lua.bytecode[<number> n]() |
| 47 |
\stoptyping |
| 48 |
|
| 49 |
The contents of the \type {lua.bytecode} array is stored inside the format file |
| 50 |
as actual \LUA\ bytecode, so it can also be used to preload \LUA\ code. The |
| 51 |
function must not contain any upvalues. The associated function calls are: |
| 52 |
|
| 53 |
\startfunctioncall |
| 54 |
<function> f = lua.getbytecode(<number> n) |
| 55 |
lua.setbytecode(<number> n, <function> f) |
| 56 |
\stopfunctioncall |
| 57 |
|
| 58 |
Note: Since a \LUA\ file loaded using \type {loadfile(filename)} is essentially |
| 59 |
an anonymous function, a complete file can be stored in a bytecode register like |
| 60 |
this: |
| 61 |
|
| 62 |
\startfunctioncall |
| 63 |
lua.bytecode[n] = loadfile(filename) |
| 64 |
\stopfunctioncall |
| 65 |
|
| 66 |
Now all definitions (functions, variables) contained in the file can be |
| 67 |
created by executing this bytecode register: |
| 68 |
|
| 69 |
\startfunctioncall |
| 70 |
lua.bytecode[n]() |
| 71 |
\stopfunctioncall |
| 72 |
|
| 73 |
Note that the path of the file is stored in the \LUA\ bytecode to be used in |
| 74 |
stack backtraces and therefore dumped into the format file if the above code is |
| 75 |
used in \INITEX. If it contains private information, i.e. the user name, this |
| 76 |
information is then contained in the format file as well. This should be kept in |
| 77 |
mind when preloading files into a bytecode register in \INITEX. |
| 78 |
|
| 79 |
\stopsubsection |
| 80 |
|
| 81 |
\startsubsection[title={Chunk name registers}] |
| 82 |
|
| 83 |
\libindex{name} |
| 84 |
\libindex{setluaname} |
| 85 |
\libindex{getluaname} |
| 86 |
|
| 87 |
There is an array of 65536 (0--65535) potential chunk names for use with the |
| 88 |
\prm {directlua} and \lpr {latelua} primitives. |
| 89 |
|
| 90 |
\startfunctioncall |
| 91 |
lua.name[<number> n] = <string> s |
| 92 |
<string> s = lua.name[<number> n] |
| 93 |
\stopfunctioncall |
| 94 |
|
| 95 |
If you want to unset a \LUA\ name, you can assign \type {nil} to it. The function |
| 96 |
accessors are: |
| 97 |
|
| 98 |
\startfunctioncall |
| 99 |
lua.setluaname(<number> n, <string> s) |
| 100 |
<string> s = lua.getluaname(<number> n) |
| 101 |
\stopfunctioncall |
| 102 |
|
| 103 |
\stopsubsection |
| 104 |
|
| 105 |
\startsubsection[title={Introspection}] |
| 106 |
|
| 107 |
\libindex{getstacktop} |
| 108 |
\libindex{getcalllevel} |
| 109 |
|
| 110 |
The \type {getstacktop} and\type {getcalllevel} functions return numbers |
| 111 |
indicating how much nesting is going on. They are only of use as breakpoints when |
| 112 |
checking some mechanism going haywire. |
| 113 |
|
| 114 |
\stopsubsection |
| 115 |
|
| 116 |
\stopsection |
| 117 |
|
| 118 |
\startsection[title={The \type {status} library}][library=status] |
| 119 |
|
| 120 |
\topicindex{libraries+\type{status}} |
| 121 |
|
| 122 |
\libindex{list} |
| 123 |
\libindex{resetmessages} |
| 124 |
\libindex{setexitcode} |
| 125 |
|
| 126 |
This contains a number of run|-|time configuration items that you may find useful |
| 127 |
in message reporting, as well as an iterator function that gets all of the names |
| 128 |
and values as a table. |
| 129 |
|
| 130 |
\startfunctioncall |
| 131 |
<table> info = status.list() |
| 132 |
\stopfunctioncall |
| 133 |
|
| 134 |
The keys in the table are the known items, the value is the current value. Almost |
| 135 |
all of the values in \type {status} are fetched through a metatable at run|-|time |
| 136 |
whenever they are accessed, so you cannot use \type {pairs} on \type {status}, |
| 137 |
but you {\it can\/} use \type {pairs} on \type {info}, of course. If you do not |
| 138 |
need the full list, you can also ask for a single item by using its name as an |
| 139 |
index into \type {status}. The current list is: |
| 140 |
|
| 141 |
\starttabulate[|l|p|] |
| 142 |
\DB key \BC explanation \NC \NR |
| 143 |
\TB |
| 144 |
\NC \type{banner} \NC terminal display banner \NC \NR |
| 145 |
\NC \type{best_page_break} \NC the current best break (a node) \NC \NR |
| 146 |
\NC \type{buf_size} \NC current allocated size of the line buffer \NC \NR |
| 147 |
\NC \type{callbacks} \NC total number of executed callbacks so far \NC \NR |
| 148 |
\NC \type{cs_count} \NC number of control sequences \NC \NR |
| 149 |
\NC \type{dest_names_size} \NC \PDF\ destination table size \NC \NR |
| 150 |
\NC \type{dvi_gone} \NC written \DVI\ bytes \NC \NR |
| 151 |
\NC \type{dvi_ptr} \NC not yet written \DVI\ bytes \NC \NR |
| 152 |
\NC \type{dyn_used} \NC token (multi|-|word) memory in use \NC \NR |
| 153 |
\NC \type{filename} \NC name of the current input file \NC \NR |
| 154 |
\NC \type{fix_mem_end} \NC maximum number of used tokens \NC \NR |
| 155 |
\NC \type{fix_mem_min} \NC minimum number of allocated words for tokens \NC \NR |
| 156 |
\NC \type{fix_mem_max} \NC maximum number of allocated words for tokens \NC \NR |
| 157 |
\NC \type{font_ptr} \NC number of active fonts \NC \NR |
| 158 |
\NC \type{hash_extra} \NC extra allowed hash \NC \NR |
| 159 |
\NC \type{hash_size} \NC size of hash \NC \NR |
| 160 |
\NC \type{indirect_callbacks} \NC number of those that were themselves a result of other callbacks (e.g. file readers) \NC \NR |
| 161 |
\NC \type{ini_version} \NC \type {true} if this is an \INITEX\ run \NC \NR |
| 162 |
\NC \type{init_pool_ptr} \NC \INITEX\ string pool index \NC \NR |
| 163 |
\NC \type{init_str_ptr} \NC number of \INITEX\ strings \NC \NR |
| 164 |
\NC \type{input_ptr} \NC the level of input we're at \NC \NR |
| 165 |
\NC \type{inputid} \NC numeric id of the current input \NC \NR |
| 166 |
\NC \type{largest_used_mark} \NC max referenced marks class \NC \NR |
| 167 |
\NC \type{lasterrorcontext} \NC last error context string (with newlines) \NC \NR |
| 168 |
\NC \type{lasterrorstring} \NC last \TEX\ error string \NC \NR |
| 169 |
\NC \type{lastluaerrorstring} \NC last \LUA\ error string \NC \NR |
| 170 |
\NC \type{lastwarningstring} \NC last warning tag, normally an indication of in what part\NC \NR |
| 171 |
\NC \type{lastwarningtag} \NC last warning string\NC \NR |
| 172 |
\NC \type{linenumber} \NC location in the current input file \NC \NR |
| 173 |
\NC \type{log_name} \NC name of the log file \NC \NR |
| 174 |
\NC \type{luabytecode_bytes} \NC number of bytes in \LUA\ bytecode registers \NC \NR |
| 175 |
\NC \type{luabytecodes} \NC number of active \LUA\ bytecode registers \NC \NR |
| 176 |
\NC \type{luastate_bytes} \NC number of bytes in use by \LUA\ interpreters \NC \NR |
| 177 |
\NC \type{luatex_engine} \NC the \LUATEX\ engine identifier \NC \NR |
| 178 |
\NC \type{luatex_hashchars} \NC length to which \LUA\ hashes strings ($2^n$) \NC \NR |
| 179 |
\NC \type{luatex_hashtype} \NC the hash method used (in \LUAJITTEX) \NC \NR |
| 180 |
\NC \type{luatex_version} \NC the \LUATEX\ version number \NC \NR |
| 181 |
\NC \type{luatex_revision} \NC the \LUATEX\ revision string \NC \NR |
| 182 |
\NC \type{max_buf_stack} \NC max used buffer position \NC \NR |
| 183 |
\NC \type{max_in_stack} \NC max used input stack entries \NC \NR |
| 184 |
\NC \type{max_nest_stack} \NC max used nesting stack entries \NC \NR |
| 185 |
\NC \type{max_param_stack} \NC max used parameter stack entries \NC \NR |
| 186 |
\NC \type{max_save_stack} \NC max used save stack entries \NC \NR |
| 187 |
\NC \type{max_strings} \NC maximum allowed strings \NC \NR |
| 188 |
\NC \type{nest_size} \NC nesting stack size \NC \NR |
| 189 |
\NC \type{node_mem_usage} \NC a string giving insight into currently used nodes \NC \NR |
| 190 |
\NC \type{obj_ptr} \NC max \PDF\ object pointer \NC \NR |
| 191 |
\NC \type{obj_tab_size} \NC \PDF\ object table size \NC \NR |
| 192 |
\NC \type{output_active} \NC \type {true} if the \prm {output} routine is active \NC \NR |
| 193 |
\NC \type{output_file_name} \NC name of the \PDF\ or \DVI\ file \NC \NR |
| 194 |
\NC \type{param_size} \NC parameter stack size \NC \NR |
| 195 |
\NC \type{pdf_dest_names_ptr} \NC max \PDF\ destination pointer \NC \NR |
| 196 |
\NC \type{pdf_gone} \NC written \PDF\ bytes \NC \NR |
| 197 |
\NC \type{pdf_mem_ptr} \NC max \PDF\ memory used \NC \NR |
| 198 |
\NC \type{pdf_mem_size} \NC \PDF\ memory size \NC \NR |
| 199 |
\NC \type{pdf_os_cntr} \NC max \PDF\ object stream pointer \NC \NR |
| 200 |
\NC \type{pdf_os_objidx} \NC \PDF\ object stream index \NC \NR |
| 201 |
\NC \type{pdf_ptr} \NC not yet written \PDF\ bytes \NC \NR |
| 202 |
\NC \type{pool_ptr} \NC string pool index \NC \NR |
| 203 |
\NC \type{pool_size} \NC current size allocated for string characters \NC \NR |
| 204 |
\NC \type{save_size} \NC save stack size \NC \NR |
| 205 |
\NC \type{shell_escape} \NC \type {0} means disabled, \type {1} means anything is permitted, and \type {2} is restricted \NC \NR |
| 206 |
\NC \type{safer_option} \NC \type {1} means safer is enforced \NC \NR |
| 207 |
\NC \type{luadebug_option} \NC true if the \type{debug} library is enabled at command line \NC\NR |
| 208 |
\NC \type{output_directory} \NC the value of the output directory \NC \NR |
| 209 |
\NC \type{kpse_used} \NC \type {1} means that kpse is used \NC \NR |
| 210 |
\NC \type{stack_size} \NC input stack size \NC \NR |
| 211 |
\NC \type{str_ptr} \NC number of strings \NC \NR |
| 212 |
\NC \type{total_pages} \NC number of written pages \NC \NR |
| 213 |
\NC \type{var_mem_max} \NC number of allocated words for nodes \NC \NR |
| 214 |
\NC \type{var_used} \NC variable (one|-|word) memory in use \NC \NR |
| 215 |
\NC \type{lc_collate} \NC the value of \type {LC_COLLATE} at startup time (becomes \type {C} at startup) \NC \NR |
| 216 |
\NC \type{lc_ctype} \NC the value of \type {LC_CTYPE} at startup time (becomes \type {C} at startup) \NC \NR |
| 217 |
%NC \type{lc_monetary} \NC the value of \type {LC_MONETARY} at startup time \NC \NR |
| 218 |
\NC \type{lc_numeric} \NC the value of \type {LC_NUMERIC} at startup time \NC \NR |
| 219 |
%NC \type{lc_time} \NC the value of \type {LC_TIME} at startup time (becomes \type {C} at startup) \NC \NR |
| 220 |
\LL |
| 221 |
\stoptabulate |
| 222 |
|
| 223 |
The error and warning messages can be wiped with the \type {resetmessages} |
| 224 |
function. A return value can be set with \type {setexitcode}. |
| 225 |
|
| 226 |
\stopsection |
| 227 |
|
| 228 |
\startsection[title={The \type {tex} library}][library=tex] |
| 229 |
|
| 230 |
\startsubsection[title={Introduction}] |
| 231 |
|
| 232 |
\topicindex{libraries+\type{tex}} |
| 233 |
|
| 234 |
The \type {tex} table contains a large list of virtual internal \TEX\ |
| 235 |
parameters that are partially writable. |
| 236 |
|
| 237 |
The designation \quote {virtual} means that these items are not properly defined |
| 238 |
in \LUA, but are only front\-ends that are handled by a metatable that operates |
| 239 |
on the actual \TEX\ values. As a result, most of the \LUA\ table operators (like |
| 240 |
\type {pairs} and \type {#}) do not work on such items. |
| 241 |
|
| 242 |
At the moment, it is possible to access almost every parameter that you can use |
| 243 |
after \prm {the}, is a single tokens or is sort of special in \TEX. This excludes |
| 244 |
parameters that need extra arguments, like \type {\the\scriptfont}. The subset |
| 245 |
comprising simple integer and dimension registers are writable as well as |
| 246 |
readable (like \prm {tracingcommands} and \prm {parindent}). |
| 247 |
|
| 248 |
\stopsubsection |
| 249 |
|
| 250 |
\startsubsection[title={Internal parameter values, \type {set} and \type {get}}] |
| 251 |
|
| 252 |
\topicindex{parameters+internal} |
| 253 |
|
| 254 |
\libindex{set} |
| 255 |
\libindex{get} |
| 256 |
|
| 257 |
For all the parameters in this section, it is possible to access them directly |
| 258 |
using their names as index in the \type {tex} table, or by using one of the |
| 259 |
functions \type {tex.get} and \type {tex.set}. |
| 260 |
|
| 261 |
The exact parameters and return values differ depending on the actual parameter, |
| 262 |
and so does whether \type {tex.set} has any effect. For the parameters that {\em |
| 263 |
can} be set, it is possible to use \type {global} as the first argument to \type |
| 264 |
{tex.set}; this makes the assignment global instead of local. |
| 265 |
|
| 266 |
\startfunctioncall |
| 267 |
tex.set (["global",] <string> n, ...) |
| 268 |
... = tex.get (<string> n) |
| 269 |
\stopfunctioncall |
| 270 |
|
| 271 |
Glue is kind of special because there are five values involved. The return value |
| 272 |
is a \nod {glue_spec} node but when you pass \type {false} as last argument to |
| 273 |
\type {tex.get} you get the width of the glue and when you pass \type {true} you |
| 274 |
get all five values. Otherwise you get a node which is a copy of the internal |
| 275 |
value so you are responsible for its freeing at the \LUA\ end. When you set a |
| 276 |
glue quantity you can either pass a \nod {glue_spec} or upto five numbers. If |
| 277 |
you pass \type {true} to \type {get} you get 5 values returned for a glue and |
| 278 |
when you pass \type {false} you only get the width returned. |
| 279 |
|
| 280 |
\subsubsection{Integer parameters} |
| 281 |
|
| 282 |
The integer parameters accept and return \LUA\ numbers. These are read|-|write: |
| 283 |
|
| 284 |
\starttwocolumns |
| 285 |
\starttyping |
| 286 |
tex.adjdemerits |
| 287 |
tex.binoppenalty |
| 288 |
tex.brokenpenalty |
| 289 |
tex.catcodetable |
| 290 |
tex.clubpenalty |
| 291 |
tex.day |
| 292 |
tex.defaulthyphenchar |
| 293 |
tex.defaultskewchar |
| 294 |
tex.delimiterfactor |
| 295 |
tex.displaywidowpenalty |
| 296 |
tex.doublehyphendemerits |
| 297 |
tex.endlinechar |
| 298 |
tex.errorcontextlines |
| 299 |
tex.escapechar |
| 300 |
tex.exhyphenpenalty |
| 301 |
tex.fam |
| 302 |
tex.finalhyphendemerits |
| 303 |
tex.floatingpenalty |
| 304 |
tex.globaldefs |
| 305 |
tex.hangafter |
| 306 |
tex.hbadness |
| 307 |
tex.holdinginserts |
| 308 |
tex.hyphenpenalty |
| 309 |
tex.interlinepenalty |
| 310 |
tex.language |
| 311 |
tex.lastlinefit |
| 312 |
tex.lefthyphenmin |
| 313 |
tex.linepenalty |
| 314 |
tex.localbrokenpenalty |
| 315 |
tex.localinterlinepenalty |
| 316 |
tex.looseness |
| 317 |
tex.mag |
| 318 |
tex.maxdeadcycles |
| 319 |
tex.month |
| 320 |
tex.newlinechar |
| 321 |
tex.outputpenalty |
| 322 |
tex.pausing |
| 323 |
tex.postdisplaypenalty |
| 324 |
tex.predisplaydirection |
| 325 |
tex.predisplaypenalty |
| 326 |
tex.pretolerance |
| 327 |
tex.relpenalty |
| 328 |
tex.righthyphenmin |
| 329 |
tex.savinghyphcodes |
| 330 |
tex.savingvdiscards |
| 331 |
tex.showboxbreadth |
| 332 |
tex.showboxdepth |
| 333 |
tex.time |
| 334 |
tex.tolerance |
| 335 |
tex.tracingassigns |
| 336 |
tex.tracingcommands |
| 337 |
tex.tracinggroups |
| 338 |
tex.tracingifs |
| 339 |
tex.tracinglostchars |
| 340 |
tex.tracingmacros |
| 341 |
tex.tracingnesting |
| 342 |
tex.tracingonline |
| 343 |
tex.tracingoutput |
| 344 |
tex.tracingpages |
| 345 |
tex.tracingparagraphs |
| 346 |
tex.tracingrestores |
| 347 |
tex.tracingscantokens |
| 348 |
tex.tracingstats |
| 349 |
tex.uchyph |
| 350 |
tex.vbadness |
| 351 |
tex.widowpenalty |
| 352 |
tex.year |
| 353 |
\stoptyping |
| 354 |
\stoptwocolumns |
| 355 |
|
| 356 |
These are read|-|only: |
| 357 |
|
| 358 |
\startthreecolumns |
| 359 |
\starttyping |
| 360 |
tex.deadcycles |
| 361 |
tex.insertpenalties |
| 362 |
tex.parshape |
| 363 |
tex.interlinepenalties |
| 364 |
tex.clubpenalties |
| 365 |
tex.widowpenalties |
| 366 |
tex.displaywidowpenalties |
| 367 |
tex.prevgraf |
| 368 |
tex.spacefactor |
| 369 |
\stoptyping |
| 370 |
\stopthreecolumns |
| 371 |
|
| 372 |
\subsubsection{Dimension parameters} |
| 373 |
|
| 374 |
The dimension parameters accept \LUA\ numbers (signifying scaled points) or |
| 375 |
strings (with included dimension). The result is always a number in scaled |
| 376 |
points. These are read|-|write: |
| 377 |
|
| 378 |
\startthreecolumns |
| 379 |
\starttyping |
| 380 |
tex.boxmaxdepth |
| 381 |
tex.delimitershortfall |
| 382 |
tex.displayindent |
| 383 |
tex.displaywidth |
| 384 |
tex.emergencystretch |
| 385 |
tex.hangindent |
| 386 |
tex.hfuzz |
| 387 |
tex.hoffset |
| 388 |
tex.hsize |
| 389 |
tex.lineskiplimit |
| 390 |
tex.mathsurround |
| 391 |
tex.maxdepth |
| 392 |
tex.nulldelimiterspace |
| 393 |
tex.overfullrule |
| 394 |
tex.pagebottomoffset |
| 395 |
tex.pageheight |
| 396 |
tex.pageleftoffset |
| 397 |
tex.pagerightoffset |
| 398 |
tex.pagetopoffset |
| 399 |
tex.pagewidth |
| 400 |
tex.parindent |
| 401 |
tex.predisplaysize |
| 402 |
tex.scriptspace |
| 403 |
tex.splitmaxdepth |
| 404 |
tex.vfuzz |
| 405 |
tex.voffset |
| 406 |
tex.vsize |
| 407 |
tex.prevdepth |
| 408 |
tex.prevgraf |
| 409 |
tex.spacefactor |
| 410 |
\stoptyping |
| 411 |
\stopthreecolumns |
| 412 |
|
| 413 |
These are read|-|only: |
| 414 |
|
| 415 |
\startthreecolumns |
| 416 |
\starttyping |
| 417 |
tex.pagedepth |
| 418 |
tex.pagefilllstretch |
| 419 |
tex.pagefillstretch |
| 420 |
tex.pagefilstretch |
| 421 |
tex.pagegoal |
| 422 |
tex.pageshrink |
| 423 |
tex.pagestretch |
| 424 |
tex.pagetotal |
| 425 |
\stoptyping |
| 426 |
\stopthreecolumns |
| 427 |
|
| 428 |
Beware: as with all \LUA\ tables you can add values to them. So, the following is |
| 429 |
valid: |
| 430 |
|
| 431 |
\starttyping |
| 432 |
tex.foo = 123 |
| 433 |
\stoptyping |
| 434 |
|
| 435 |
When you access a \TEX\ parameter a look up takes place. For read||only variables |
| 436 |
that means that you will get something back, but when you set them you create a |
| 437 |
new entry in the table thereby making the original invisible. |
| 438 |
|
| 439 |
There are a few special cases that we make an exception for: \type {prevdepth}, |
| 440 |
\type {prevgraf} and \type {spacefactor}. These normally are accessed via the |
| 441 |
\type {tex.nest} table: |
| 442 |
|
| 443 |
\starttyping |
| 444 |
tex.nest[tex.nest.ptr].prevdepth = p |
| 445 |
tex.nest[tex.nest.ptr].spacefactor = s |
| 446 |
\stoptyping |
| 447 |
|
| 448 |
However, the following also works: |
| 449 |
|
| 450 |
\starttyping |
| 451 |
tex.prevdepth = p |
| 452 |
tex.spacefactor = s |
| 453 |
\stoptyping |
| 454 |
|
| 455 |
Keep in mind that when you mess with node lists directly at the \LUA\ end you |
| 456 |
might need to update the top of the nesting stack's \type {prevdepth} explicitly |
| 457 |
as there is no way \LUATEX\ can guess your intentions. By using the accessor in |
| 458 |
the \type {tex} tables, you get and set the values at the top of the nesting |
| 459 |
stack. |
| 460 |
|
| 461 |
\subsubsection{Direction parameters} |
| 462 |
|
| 463 |
The direction parameters are read|-|only and return a \LUA\ string. |
| 464 |
|
| 465 |
\startthreecolumns |
| 466 |
\starttyping |
| 467 |
tex.bodydir |
| 468 |
tex.mathdir |
| 469 |
tex.pagedir |
| 470 |
tex.pardir |
| 471 |
tex.textdir |
| 472 |
\stoptyping |
| 473 |
\stopthreecolumns |
| 474 |
|
| 475 |
\subsubsection{Glue parameters} |
| 476 |
|
| 477 |
The glue parameters accept and return a userdata object that represents a \nod {glue_spec} node. |
| 478 |
|
| 479 |
\startthreecolumns |
| 480 |
\starttyping |
| 481 |
tex.abovedisplayshortskip |
| 482 |
tex.abovedisplayskip |
| 483 |
tex.baselineskip |
| 484 |
tex.belowdisplayshortskip |
| 485 |
tex.belowdisplayskip |
| 486 |
tex.leftskip |
| 487 |
tex.lineskip |
| 488 |
tex.parfillskip |
| 489 |
tex.parskip |
| 490 |
tex.rightskip |
| 491 |
tex.spaceskip |
| 492 |
tex.splittopskip |
| 493 |
tex.tabskip |
| 494 |
tex.topskip |
| 495 |
tex.xspaceskip |
| 496 |
\stoptyping |
| 497 |
\stopthreecolumns |
| 498 |
|
| 499 |
\subsubsection{Muglue parameters} |
| 500 |
|
| 501 |
All muglue parameters are to be used read|-|only and return a \LUA\ string. |
| 502 |
|
| 503 |
\startthreecolumns |
| 504 |
\starttyping |
| 505 |
tex.medmuskip |
| 506 |
tex.thickmuskip |
| 507 |
tex.thinmuskip |
| 508 |
\stoptyping |
| 509 |
\stopthreecolumns |
| 510 |
|
| 511 |
\subsubsection{Tokenlist parameters} |
| 512 |
|
| 513 |
The tokenlist parameters accept and return \LUA\ strings. \LUA\ strings are |
| 514 |
converted to and from token lists using \prm {the} \prm {toks} style expansion: |
| 515 |
all category codes are either space (10) or other (12). It follows that assigning |
| 516 |
to some of these, like \quote {tex.output}, is actually useless, but it feels bad |
| 517 |
to make exceptions in view of a coming extension that will accept full|-|blown |
| 518 |
token strings. |
| 519 |
|
| 520 |
\startthreecolumns |
| 521 |
\starttyping |
| 522 |
tex.errhelp |
| 523 |
tex.everycr |
| 524 |
tex.everydisplay |
| 525 |
tex.everyeof |
| 526 |
tex.everyhbox |
| 527 |
tex.everyjob |
| 528 |
tex.everymath |
| 529 |
tex.everypar |
| 530 |
tex.everyvbox |
| 531 |
tex.output |
| 532 |
\stoptyping |
| 533 |
\stopthreecolumns |
| 534 |
|
| 535 |
\stopsubsection |
| 536 |
|
| 537 |
\startsubsection[title={Convert commands}] |
| 538 |
|
| 539 |
\topicindex{convert commands} |
| 540 |
|
| 541 |
All \quote {convert} commands are read|-|only and return a \LUA\ string. The |
| 542 |
supported commands at this moment are: |
| 543 |
|
| 544 |
\starttwocolumns |
| 545 |
\starttyping |
| 546 |
tex.eTeXVersion |
| 547 |
tex.eTeXrevision |
| 548 |
tex.formatname |
| 549 |
tex.jobname |
| 550 |
tex.luatexbanner |
| 551 |
tex.luatexrevision |
| 552 |
tex.fontname(number) |
| 553 |
tex.uniformdeviate(number) |
| 554 |
tex.number(number) |
| 555 |
tex.romannumeral(number) |
| 556 |
tex.fontidentifier(number) |
| 557 |
\stoptyping |
| 558 |
\stoptwocolumns |
| 559 |
|
| 560 |
If you are wondering why this list looks haphazard; these are all the cases of |
| 561 |
the \quote {convert} internal command that do not require an argument, as well as |
| 562 |
the ones that require only a simple numeric value. The special (\LUA|-|only) case |
| 563 |
of \type {tex.fontidentifier} returns the \type {csname} string that matches a |
| 564 |
font id number (if there is one). |
| 565 |
|
| 566 |
\stopsubsection |
| 567 |
|
| 568 |
\startsubsection[title={Last item commands}] |
| 569 |
|
| 570 |
\topicindex{last items} |
| 571 |
|
| 572 |
All \quote {last item} commands are read|-|only and return a number. The |
| 573 |
supported commands at this moment are: |
| 574 |
|
| 575 |
\startthreecolumns |
| 576 |
\starttyping |
| 577 |
tex.lastpenalty |
| 578 |
tex.lastkern |
| 579 |
tex.lastskip |
| 580 |
tex.lastnodetype |
| 581 |
tex.inputlineno |
| 582 |
tex.lastxpos |
| 583 |
tex.lastypos |
| 584 |
tex.randomseed |
| 585 |
tex.luatexversion |
| 586 |
tex.eTeXminorversion |
| 587 |
tex.eTeXversion |
| 588 |
tex.currentgrouplevel |
| 589 |
tex.currentgrouptype |
| 590 |
tex.currentiflevel |
| 591 |
tex.currentiftype |
| 592 |
tex.currentifbranch |
| 593 |
\stoptyping |
| 594 |
\stopthreecolumns |
| 595 |
|
| 596 |
\stopsubsection |
| 597 |
|
| 598 |
\startsubsection[title={Accessing registers: \type {set*}, \type {get*} and \type {is*}}] |
| 599 |
|
| 600 |
\topicindex{attributes} |
| 601 |
\topicindex{registers} |
| 602 |
|
| 603 |
\libindex{attribute} \libindex{setattribute} \libindex{getattribute} \libindex{isattribute} |
| 604 |
\libindex{count} \libindex{setcount} \libindex{getcount} \libindex{iscount} |
| 605 |
\libindex{dimen} \libindex{setdimen} \libindex{getdimen} \libindex{isdimen} |
| 606 |
\libindex{skip} \libindex{setskip} \libindex{getskip} \libindex{isskip} |
| 607 |
\libindex{muskip} \libindex{setmuskip} \libindex{getmuskip} \libindex{ismuskip} |
| 608 |
\libindex{glue} \libindex{setglue} \libindex{getglue} \libindex{isglue} |
| 609 |
\libindex{muglue} \libindex{setmuglue} \libindex{getmuglue} \libindex{ismuglue} |
| 610 |
\libindex{toks} \libindex{settoks} \libindex{gettoks} \libindex{istoks} |
| 611 |
\libindex{box} \libindex{setbox} \libindex{getbox} \libindex{isbox} |
| 612 |
|
| 613 |
\libindex{scantoks} |
| 614 |
|
| 615 |
\libindex{getmark} |
| 616 |
|
| 617 |
\TEX's attributes (\lpr {attribute}), counters (\prm {count}), dimensions (\prm |
| 618 |
{dimen}), skips (\prm {skip}, \prm {muskip}) and token (\prm {toks}) registers |
| 619 |
can be accessed and written to using two times five virtual sub|-|tables of the |
| 620 |
\type {tex} table: |
| 621 |
|
| 622 |
\startthreecolumns |
| 623 |
\starttyping |
| 624 |
tex.attribute |
| 625 |
tex.count |
| 626 |
tex.dimen |
| 627 |
tex.skip |
| 628 |
tex.glue |
| 629 |
tex.muskip |
| 630 |
tex.muglue |
| 631 |
tex.toks |
| 632 |
\stoptyping |
| 633 |
\stopthreecolumns |
| 634 |
|
| 635 |
It is possible to use the names of relevant \lpr {attributedef}, \prm {countdef}, |
| 636 |
\prm {dimendef}, \prm {skipdef}, or \prm {toksdef} control sequences as indices |
| 637 |
to these tables: |
| 638 |
|
| 639 |
\starttyping |
| 640 |
tex.count.scratchcounter = 0 |
| 641 |
enormous = tex.dimen['maxdimen'] |
| 642 |
\stoptyping |
| 643 |
|
| 644 |
In this case, \LUATEX\ looks up the value for you on the fly. You have to use a |
| 645 |
valid \prm {countdef} (or \lpr {attributedef}, or \prm {dimendef}, or \prm |
| 646 |
{skipdef}, or \prm {toksdef}), anything else will generate an error (the intent |
| 647 |
is to eventually also allow \type {<chardef tokens>} and even macros that expand |
| 648 |
into a number). |
| 649 |
|
| 650 |
\startitemize |
| 651 |
|
| 652 |
\startitem |
| 653 |
The count registers accept and return \LUA\ numbers. |
| 654 |
\stopitem |
| 655 |
|
| 656 |
\startitem |
| 657 |
The dimension registers accept \LUA\ numbers (in scaled points) or |
| 658 |
strings (with an included absolute dimension; \type {em} and \type {ex} |
| 659 |
and \type {px} are forbidden). The result is always a number in scaled |
| 660 |
points. |
| 661 |
\stopitem |
| 662 |
|
| 663 |
\startitem |
| 664 |
The token registers accept and return \LUA\ strings. \LUA\ strings are |
| 665 |
converted to and from token lists using \prm {the} \prm {toks} style |
| 666 |
expansion: all category codes are either space (10) or other (12). |
| 667 |
\stopitem |
| 668 |
|
| 669 |
\startitem |
| 670 |
The skip registers accept and return \nod {glue_spec} userdata node |
| 671 |
objects (see the description of the node interface elsewhere in this |
| 672 |
manual). |
| 673 |
\stopitem |
| 674 |
|
| 675 |
\startitem |
| 676 |
The glue registers are just skip registers but instead of userdata |
| 677 |
are verbose. |
| 678 |
\stopitem |
| 679 |
|
| 680 |
\startitem |
| 681 |
Like the counts, the attribute registers accept and return \LUA\ numbers. |
| 682 |
\stopitem |
| 683 |
|
| 684 |
\stopitemize |
| 685 |
|
| 686 |
As an alternative to array addressing, there are also accessor functions defined |
| 687 |
for all cases, for example, here is the set of possibilities for \prm {skip} |
| 688 |
registers: |
| 689 |
|
| 690 |
\startfunctioncall |
| 691 |
tex.setskip (["global",] <number> n, <node> s) |
| 692 |
tex.setskip (["global",] <string> s, <node> s) |
| 693 |
<node> s = tex.getskip (<number> n) |
| 694 |
<node> s = tex.getskip (<string> s) |
| 695 |
\stopfunctioncall |
| 696 |
|
| 697 |
We have similar setters for \type {count}, \type {dimen}, \type {muskip}, and |
| 698 |
\type {toks}. Counters and dimen are represented by numbers, skips and muskips by |
| 699 |
nodes, and toks by strings. |
| 700 |
|
| 701 |
Again the glue variants are not using the \nod {glue_spec} userdata nodes. The |
| 702 |
\type {setglue} function accepts upto 5 arguments: width, stretch, shrink, |
| 703 |
stretch order and shrink order. If you pass no values or if a value is not a |
| 704 |
number the corresponding property will become a zero. The \type {getglue} |
| 705 |
function reports all properties, unless the second argument is \type {false} in |
| 706 |
which care only the width is returned. |
| 707 |
|
| 708 |
Here is an example using a threesome: |
| 709 |
|
| 710 |
\startfunctioncall |
| 711 |
local d = tex.getdimen("foo") |
| 712 |
if tex.isdimen("bar") then |
| 713 |
tex.setdimen("bar",d) |
| 714 |
end |
| 715 |
\stopfunctioncall |
| 716 |
|
| 717 |
There are six extra skip (glue) related helpers: |
| 718 |
|
| 719 |
\startfunctioncall |
| 720 |
tex.setglue (["global"], <number> n, |
| 721 |
width, stretch, shrink, stretch_order, shrink_order) |
| 722 |
tex.setglue (["global"], <string> s, |
| 723 |
width, stretch, shrink, stretch_order, shrink_order) |
| 724 |
width, stretch, shrink, stretch_order, shrink_order = |
| 725 |
tex.getglue (<number> n) |
| 726 |
width, stretch, shrink, stretch_order, shrink_order = |
| 727 |
tex.getglue (<string> s) |
| 728 |
\stopfunctioncall |
| 729 |
|
| 730 |
The other two are \type {tex.setmuglue} and \type {tex.getmuglue}. |
| 731 |
|
| 732 |
There are such helpers for \type {dimen}, \type {count}, \type {skip}, \type |
| 733 |
{muskip}, \type {box} and \type {attribute} registers but the glue ones |
| 734 |
are special because they have to deal with more properties. |
| 735 |
|
| 736 |
As with the general \type {get} and \type {set} function discussed before, for |
| 737 |
the skip registers \type {getskip} returns a node and \type {getglue} returns |
| 738 |
numbers, while \type {setskip} accepts a node and \type {setglue} expects upto five |
| 739 |
numbers. Again, when you pass \type {false} as second argument to \type {getglue} |
| 740 |
you only get the width returned. The same is true for the \type {mu} variants |
| 741 |
\type {getmuskip}, \type {setmuskip}, \type {getmuskip} and\type {setmuskip}. |
| 742 |
|
| 743 |
For tokens registers we have an alternative where a catcode table is specified: |
| 744 |
|
| 745 |
\startfunctioncall |
| 746 |
tex.scantoks(0,3,"$e=mc^2$") |
| 747 |
tex.scantoks("global",0,"$\int\limits^1_2$") |
| 748 |
\stopfunctioncall |
| 749 |
|
| 750 |
In the function|-|based interface, it is possible to define values globally by |
| 751 |
using the string \type {global} as the first function argument. |
| 752 |
|
| 753 |
There is a dedicated getter for marks: \type {getmark} that takes two arguments. |
| 754 |
The first argument is one of \type {top}, \type {bottom}, \type {first}, \type |
| 755 |
{splitbottom} or \type {splitfirst}, and the second argument is a marks class |
| 756 |
number. When no arguments are given the current maximum number of classes is |
| 757 |
returned. |
| 758 |
|
| 759 |
\stopsubsection |
| 760 |
|
| 761 |
\startsubsection[title={Character code registers: \type {[get|set]*code[s]}}] |
| 762 |
|
| 763 |
\topicindex{characters+codes} |
| 764 |
|
| 765 |
\libindex{lccode} \libindex{setlccode} \libindex{getlccode} |
| 766 |
\libindex{uccode} \libindex{setuccode} \libindex{getuccode} |
| 767 |
\libindex{sfcode} \libindex{setsfcode} \libindex{getsfcode} |
| 768 |
\libindex{catcode} \libindex{setcatcode} \libindex{getcatcode} |
| 769 |
\libindex{mathcode} \libindex{setmathcode} \libindex{getmathcode} |
| 770 |
\libindex{delcode} \libindex{setdelcode} \libindex{getdelcode} |
| 771 |
|
| 772 |
\libindex{setdelcodes} \libindex{getdelcodes} |
| 773 |
\libindex{setmathcodes} \libindex{getmathcodes} |
| 774 |
|
| 775 |
\TEX's character code tables (\prm {lccode}, \prm {uccode}, \prm {sfcode}, \prm |
| 776 |
{catcode}, \prm {mathcode}, \prm {delcode}) can be accessed and written to using |
| 777 |
six virtual subtables of the \type {tex} table |
| 778 |
|
| 779 |
\startthreecolumns |
| 780 |
\starttyping |
| 781 |
tex.lccode |
| 782 |
tex.uccode |
| 783 |
tex.sfcode |
| 784 |
tex.catcode |
| 785 |
tex.mathcode |
| 786 |
tex.delcode |
| 787 |
\stoptyping |
| 788 |
\stopthreecolumns |
| 789 |
|
| 790 |
The function call interfaces are roughly as above, but there are a few twists. |
| 791 |
\type {sfcode}s are the simple ones: |
| 792 |
|
| 793 |
\startfunctioncall |
| 794 |
tex.setsfcode (["global",] <number> n, <number> s) |
| 795 |
<number> s = tex.getsfcode (<number> n) |
| 796 |
\stopfunctioncall |
| 797 |
|
| 798 |
The function call interface for \type {lccode} and \type {uccode} additionally |
| 799 |
allows you to set the associated sibling at the same time: |
| 800 |
|
| 801 |
\startfunctioncall |
| 802 |
tex.setlccode (["global"], <number> n, <number> lc) |
| 803 |
tex.setlccode (["global"], <number> n, <number> lc, <number> uc) |
| 804 |
<number> lc = tex.getlccode (<number> n) |
| 805 |
tex.setuccode (["global"], <number> n, <number> uc) |
| 806 |
tex.setuccode (["global"], <number> n, <number> uc, <number> lc) |
| 807 |
<number> uc = tex.getuccode (<number> n) |
| 808 |
\stopfunctioncall |
| 809 |
|
| 810 |
The function call interface for \type {catcode} also allows you to specify a |
| 811 |
category table to use on assignment or on query (default in both cases is the |
| 812 |
current one): |
| 813 |
|
| 814 |
\startfunctioncall |
| 815 |
tex.setcatcode (["global"], <number> n, <number> c) |
| 816 |
tex.setcatcode (["global"], <number> cattable, <number> n, <number> c) |
| 817 |
<number> lc = tex.getcatcode (<number> n) |
| 818 |
<number> lc = tex.getcatcode (<number> cattable, <number> n) |
| 819 |
\stopfunctioncall |
| 820 |
|
| 821 |
The interfaces for \type {delcode} and \type {mathcode} use small array tables to |
| 822 |
set and retrieve values: |
| 823 |
|
| 824 |
\startfunctioncall |
| 825 |
tex.setmathcode (["global"], <number> n, <table> mval ) |
| 826 |
<table> mval = tex.getmathcode (<number> n) |
| 827 |
tex.setdelcode (["global"], <number> n, <table> dval ) |
| 828 |
<table> dval = tex.getdelcode (<number> n) |
| 829 |
\stopfunctioncall |
| 830 |
|
| 831 |
Where the table for \type {mathcode} is an array of 3 numbers, like this: |
| 832 |
|
| 833 |
\starttyping |
| 834 |
{ |
| 835 |
<number> class, |
| 836 |
<number> family, |
| 837 |
<number> character |
| 838 |
} |
| 839 |
\stoptyping |
| 840 |
|
| 841 |
And the table for \type {delcode} is an array with 4 numbers, like this: |
| 842 |
|
| 843 |
\starttyping |
| 844 |
{ |
| 845 |
<number> small_fam, |
| 846 |
<number> small_char, |
| 847 |
<number> large_fam, |
| 848 |
<number> large_char |
| 849 |
} |
| 850 |
\stoptyping |
| 851 |
|
| 852 |
You can also avoid the table: |
| 853 |
|
| 854 |
\startfunctioncall |
| 855 |
tex.setmathcode (["global"], <number> n, <number> class, |
| 856 |
<number> family, <number> character) |
| 857 |
class, family, char = |
| 858 |
tex.getmathcodes (<number> n) |
| 859 |
tex.setdelcode (["global"], <number> n, <number> smallfam, |
| 860 |
<number> smallchar, <number> largefam, <number> largechar) |
| 861 |
smallfam, smallchar, largefam, largechar = |
| 862 |
tex.getdelcodes (<number> n) |
| 863 |
\stopfunctioncall |
| 864 |
|
| 865 |
Normally, the third and fourth values in a delimiter code assignment will be zero |
| 866 |
according to \lpr {Udelcode} usage, but the returned table can have values there |
| 867 |
(if the delimiter code was set using \prm {delcode}, for example). Unset \type |
| 868 |
{delcode}'s can be recognized because \type {dval[1]} is $-1$. |
| 869 |
|
| 870 |
\stopsubsection |
| 871 |
|
| 872 |
\startsubsection[title={Box registers: \type {[get|set]box}}] |
| 873 |
|
| 874 |
\topicindex{registers} |
| 875 |
\topicindex{boxes} |
| 876 |
|
| 877 |
\libindex{box} |
| 878 |
\libindex{setbox} \libindex{getbox} |
| 879 |
|
| 880 |
It is possible to set and query actual boxes, coming for instance from \prm |
| 881 |
{hbox}, \prm {vbox} or \prm {vtop}, using the node interface as defined in the |
| 882 |
\type {node} library: |
| 883 |
|
| 884 |
\starttyping |
| 885 |
tex.box |
| 886 |
\stoptyping |
| 887 |
|
| 888 |
for array access, or |
| 889 |
|
| 890 |
\starttyping |
| 891 |
tex.setbox(["global",] <number> n, <node> s) |
| 892 |
tex.setbox(["global",] <string> cs, <node> s) |
| 893 |
<node> n = tex.getbox(<number> n) |
| 894 |
<node> n = tex.getbox(<string> cs) |
| 895 |
\stoptyping |
| 896 |
|
| 897 |
for function|-|based access. In the function-based interface, it is possible to |
| 898 |
define values globally by using the string \type {global} as the first function |
| 899 |
argument. |
| 900 |
|
| 901 |
Be warned that an assignment like |
| 902 |
|
| 903 |
\starttyping |
| 904 |
tex.box[0] = tex.box[2] |
| 905 |
\stoptyping |
| 906 |
|
| 907 |
does not copy the node list, it just duplicates a node pointer. If \type {\box2} |
| 908 |
will be cleared by \TEX\ commands later on, the contents of \type {\box0} becomes |
| 909 |
invalid as well. To prevent this from happening, always use \type |
| 910 |
{node.copy_list} unless you are assigning to a temporary variable: |
| 911 |
|
| 912 |
\starttyping |
| 913 |
tex.box[0] = node.copy_list(tex.box[2]) |
| 914 |
\stoptyping |
| 915 |
|
| 916 |
\stopsubsection |
| 917 |
|
| 918 |
\startsubsection[title={Reusing boxes: \type {[use|save]boxresource} and \type {getboxresourcedimensions}}] |
| 919 |
|
| 920 |
\topicindex{boxes+reuse} |
| 921 |
|
| 922 |
\libindex{useboxresource} |
| 923 |
\libindex{saveboxresource} |
| 924 |
\libindex{getboxresourcedimensions} |
| 925 |
|
| 926 |
The following function will register a box for reuse (this is modelled after so |
| 927 |
called xforms in \PDF). You can (re)use the box with \lpr {useboxresource} or |
| 928 |
by creating a rule node with subtype~2. |
| 929 |
|
| 930 |
\starttyping |
| 931 |
local index = tex.saveboxresource(n,attributes,resources,immediate,type,margin) |
| 932 |
\stoptyping |
| 933 |
|
| 934 |
The optional second and third arguments are strings, the fourth is a boolean. The |
| 935 |
fifth argument is a type. When set to non|-|zero the \type {/Type} entry is |
| 936 |
omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3 will write |
| 937 |
a \type {/Matrix}. The sixth argument is the (virtual) margin that extends beyond |
| 938 |
the effective boundingbox as seen by \TEX. Instead of a box number one can also |
| 939 |
pass a \type {[h|v]list} node. |
| 940 |
|
| 941 |
You can generate the reference (a rule type) with: |
| 942 |
|
| 943 |
\starttyping |
| 944 |
local reused = tex.useboxresource(n,wd,ht,dp) |
| 945 |
\stoptyping |
| 946 |
|
| 947 |
The dimensions are optional and the final ones are returned as extra values. The |
| 948 |
following is just a bonus (no dimensions returned means that the resource is |
| 949 |
unknown): |
| 950 |
|
| 951 |
\starttyping |
| 952 |
local w, h, d, m = tex.getboxresourcedimensions(n) |
| 953 |
\stoptyping |
| 954 |
|
| 955 |
This returns the width, height, depth and margin of the resource. |
| 956 |
|
| 957 |
\stopsubsection |
| 958 |
|
| 959 |
\startsubsection[title={\type {triggerbuildpage}}] |
| 960 |
|
| 961 |
\topicindex{pages} |
| 962 |
|
| 963 |
\libindex{triggerbuildpage} |
| 964 |
|
| 965 |
You should not expect to much from the \type {triggerbuildpage} helpers because |
| 966 |
often \TEX\ doesn't do much if it thinks nothing has to be done, but it might be |
| 967 |
useful for some applications. It just does as it says it calls the internal |
| 968 |
function that build a page, given that there is something to build. |
| 969 |
|
| 970 |
\stopsubsection |
| 971 |
|
| 972 |
\startsubsection[title={\type {splitbox}}] |
| 973 |
|
| 974 |
\topicindex{boxes+split} |
| 975 |
|
| 976 |
\libindex{splitbox} |
| 977 |
|
| 978 |
You can split a box: |
| 979 |
|
| 980 |
\starttyping |
| 981 |
local vlist = tex.splitbox(n,height,mode) |
| 982 |
\stoptyping |
| 983 |
|
| 984 |
The remainder is kept in the original box and a packaged vlist is returned. This |
| 985 |
operation is comparable to the \prm {vsplit} operation. The mode can be \type |
| 986 |
{additional} or \type {exactly} and concerns the split off box. |
| 987 |
|
| 988 |
\stopsubsection |
| 989 |
|
| 990 |
\startsubsection[title={Accessing math parameters: \type {[get|set]math}}] |
| 991 |
|
| 992 |
\topicindex{math+parameters} |
| 993 |
\topicindex{parameters+math} |
| 994 |
|
| 995 |
\libindex{setmath} |
| 996 |
\libindex{getmath} |
| 997 |
|
| 998 |
It is possible to set and query the internal math parameters using: |
| 999 |
|
| 1000 |
\startfunctioncall |
| 1001 |
tex.setmath(["global",] <string> n, <string> t, <number> n) |
| 1002 |
<number> n = tex.getmath(<string> n, <string> t) |
| 1003 |
\stopfunctioncall |
| 1004 |
|
| 1005 |
As before an optional first parameter \type {global} indicates a global |
| 1006 |
assignment. |
| 1007 |
|
| 1008 |
The first string is the parameter name minus the leading \quote {Umath}, and the |
| 1009 |
second string is the style name minus the trailing \quote {style}. Just to be |
| 1010 |
complete, the values for the math parameter name are: |
| 1011 |
|
| 1012 |
\starttyping |
| 1013 |
quad axis operatorsize |
| 1014 |
overbarkern overbarrule overbarvgap |
| 1015 |
underbarkern underbarrule underbarvgap |
| 1016 |
radicalkern radicalrule radicalvgap |
| 1017 |
radicaldegreebefore radicaldegreeafter radicaldegreeraise |
| 1018 |
stackvgap stacknumup stackdenomdown |
| 1019 |
fractionrule fractionnumvgap fractionnumup |
| 1020 |
fractiondenomvgap fractiondenomdown fractiondelsize |
| 1021 |
limitabovevgap limitabovebgap limitabovekern |
| 1022 |
limitbelowvgap limitbelowbgap limitbelowkern |
| 1023 |
underdelimitervgap underdelimiterbgap |
| 1024 |
overdelimitervgap overdelimiterbgap |
| 1025 |
subshiftdrop supshiftdrop subshiftdown |
| 1026 |
subsupshiftdown subtopmax supshiftup |
| 1027 |
supbottommin supsubbottommax subsupvgap |
| 1028 |
spaceafterscript connectoroverlapmin |
| 1029 |
ordordspacing ordopspacing ordbinspacing ordrelspacing |
| 1030 |
ordopenspacing ordclosespacing ordpunctspacing ordinnerspacing |
| 1031 |
opordspacing opopspacing opbinspacing oprelspacing |
| 1032 |
opopenspacing opclosespacing oppunctspacing opinnerspacing |
| 1033 |
binordspacing binopspacing binbinspacing binrelspacing |
| 1034 |
binopenspacing binclosespacing binpunctspacing bininnerspacing |
| 1035 |
relordspacing relopspacing relbinspacing relrelspacing |
| 1036 |
relopenspacing relclosespacing relpunctspacing relinnerspacing |
| 1037 |
openordspacing openopspacing openbinspacing openrelspacing |
| 1038 |
openopenspacing openclosespacing openpunctspacing openinnerspacing |
| 1039 |
closeordspacing closeopspacing closebinspacing closerelspacing |
| 1040 |
closeopenspacing closeclosespacing closepunctspacing closeinnerspacing |
| 1041 |
punctordspacing punctopspacing punctbinspacing punctrelspacing |
| 1042 |
punctopenspacing punctclosespacing punctpunctspacing punctinnerspacing |
| 1043 |
innerordspacing inneropspacing innerbinspacing innerrelspacing |
| 1044 |
inneropenspacing innerclosespacing innerpunctspacing innerinnerspacing |
| 1045 |
\stoptyping |
| 1046 |
|
| 1047 |
The values for the style parameter are: |
| 1048 |
|
| 1049 |
\starttyping |
| 1050 |
display crampeddisplay |
| 1051 |
text crampedtext |
| 1052 |
script crampedscript |
| 1053 |
scriptscript crampedscriptscript |
| 1054 |
\stoptyping |
| 1055 |
|
| 1056 |
The value is either a number (representing a dimension or number) or a glue spec |
| 1057 |
node representing a muskip for \type {ordordspacing} and similar spacing |
| 1058 |
parameters. |
| 1059 |
|
| 1060 |
\stopsubsection |
| 1061 |
|
| 1062 |
\startsubsection[title={Special list heads: \type {[get|set]list}}] |
| 1063 |
|
| 1064 |
\topicindex{lists} |
| 1065 |
|
| 1066 |
\libindex{lists} |
| 1067 |
\libindex{setlist} |
| 1068 |
\libindex{getlist} |
| 1069 |
|
| 1070 |
The virtual table \type {tex.lists} contains the set of internal registers that |
| 1071 |
keep track of building page lists. |
| 1072 |
|
| 1073 |
\starttabulate[|l|p|] |
| 1074 |
\DB field \BC explanation \NC \NR |
| 1075 |
\TB |
| 1076 |
\NC \type{page_ins_head} \NC circular list of pending insertions \NC \NR |
| 1077 |
\NC \type{contrib_head} \NC the recent contributions \NC \NR |
| 1078 |
\NC \type{page_head} \NC the current page content \NC \NR |
| 1079 |
%NC \type{temp_head} \NC \NC \NR |
| 1080 |
\NC \type{hold_head} \NC used for held-over items for next page \NC \NR |
| 1081 |
\NC \type{adjust_head} \NC head of the current \prm {vadjust} list \NC \NR |
| 1082 |
\NC \type{pre_adjust_head} \NC head of the current \type {\vadjust pre} list \NC \NR |
| 1083 |
%NC \type{align_head} \NC \NC \NR |
| 1084 |
\NC \type{page_discards_head} \NC head of the discarded items of a page break \NC \NR |
| 1085 |
\NC \type{split_discards_head} \NC head of the discarded items in a vsplit \NC \NR |
| 1086 |
\LL |
| 1087 |
\stoptabulate |
| 1088 |
|
| 1089 |
The getter and setter functions are \type {getlist} and \type {setlist}. You have |
| 1090 |
to be careful with what you set as \TEX\ can have expectations with regards to |
| 1091 |
how a list is constructed or in what state it is. |
| 1092 |
|
| 1093 |
\stopsubsection |
| 1094 |
|
| 1095 |
\startsubsection[title={Semantic nest levels: \type {getnest} and \type {ptr}}] |
| 1096 |
|
| 1097 |
\topicindex{nesting} |
| 1098 |
|
| 1099 |
\libindex{nest} |
| 1100 |
\libindex{ptr} |
| 1101 |
%libindex{setnest} % only a message |
| 1102 |
\libindex{getnest} |
| 1103 |
|
| 1104 |
The virtual table \type {nest} contains the currently active semantic nesting |
| 1105 |
state. It has two main parts: a zero-based array of userdata for the semantic |
| 1106 |
nest itself, and the numerical value \type {ptr}, which gives the highest |
| 1107 |
available index. Neither the array items in \type {nest[]} nor \type {ptr} can be |
| 1108 |
assigned to (as this would confuse the typesetting engine beyond repair), but you |
| 1109 |
can assign to the individual values inside the array items, e.g.\ \type |
| 1110 |
{tex.nest[tex.nest.ptr].prevdepth}. |
| 1111 |
|
| 1112 |
\type {tex.nest[tex.nest.ptr]} is the current nest state, \type {nest[0]} the |
| 1113 |
outermost (main vertical list) level. The getter function is \type {getnest}. You |
| 1114 |
can pass a number (which gives you a list), nothing or \type {top}, which returns |
| 1115 |
the topmost list, or the string \type {ptr} which gives you the index of the |
| 1116 |
topmost list. |
| 1117 |
|
| 1118 |
The known fields are: |
| 1119 |
|
| 1120 |
\starttabulate[|l|l|l|p|] |
| 1121 |
\DB key \BC type \BC modes \BC explanation \NC \NR |
| 1122 |
\TB |
| 1123 |
\NC \type{mode} \NC number \NC all \NC the meaning of these numbers depends on the engine |
| 1124 |
and sometimes even the version; you can use \typ |
| 1125 |
{tex.getmodevalues()} to get the mapping: positive |
| 1126 |
values signal vertical, horizontal and math mode, |
| 1127 |
while negative values indicate inner and inline |
| 1128 |
variants \NC \NR |
| 1129 |
\NC \type{modeline} \NC number \NC all \NC source input line where this mode was entered in, |
| 1130 |
negative inside the output routine \NC \NR |
| 1131 |
\NC \type{head} \NC node \NC all \NC the head of the current list \NC \NR |
| 1132 |
\NC \type{tail} \NC node \NC all \NC the tail of the current list \NC \NR |
| 1133 |
\NC \type{prevgraf} \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR |
| 1134 |
\NC \type{prevdepth} \NC number \NC vmode \NC depth of the previous paragraph \NC \NR |
| 1135 |
\NC \type{spacefactor} \NC number \NC hmode \NC the current space factor \NC \NR |
| 1136 |
\NC \type{dirs} \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR |
| 1137 |
\NC \type{noad} \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator, |
| 1138 |
for \prm {over} etc. \NC \NR |
| 1139 |
\NC \type{delimptr} \NC node \NC mmode \NC used for temporary storage of the previous math delimiter, |
| 1140 |
for \prm {middle} \NC \NR |
| 1141 |
\NC \type{mathdir} \NC boolean \NC mmode \NC true when during math processing the \lpr {mathdir} is not |
| 1142 |
the same as the surrounding \lpr {textdir} \NC \NR |
| 1143 |
\NC \type{mathstyle} \NC number \NC mmode \NC the current \lpr {mathstyle} \NC \NR |
| 1144 |
\LL |
| 1145 |
\stoptabulate |
| 1146 |
|
| 1147 |
\stopsubsection |
| 1148 |
|
| 1149 |
\startsubsection[reference=sec:luaprint,title={Print functions}] |
| 1150 |
|
| 1151 |
\topicindex{printing} |
| 1152 |
|
| 1153 |
The \type {tex} table also contains the three print functions that are the major |
| 1154 |
interface from \LUA\ scripting to \TEX. The arguments to these three functions |
| 1155 |
are all stored in an in|-|memory virtual file that is fed to the \TEX\ scanner as |
| 1156 |
the result of the expansion of \prm {directlua}. |
| 1157 |
|
| 1158 |
The total amount of returnable text from a \prm {directlua} command is only |
| 1159 |
limited by available system \RAM. However, each separate printed string has to |
| 1160 |
fit completely in \TEX's input buffer. The result of using these functions from |
| 1161 |
inside callbacks is undefined at the moment. |
| 1162 |
|
| 1163 |
\subsubsection{\type {print}} |
| 1164 |
|
| 1165 |
\libindex{print} |
| 1166 |
|
| 1167 |
\startfunctioncall |
| 1168 |
tex.print(<string> s, ...) |
| 1169 |
tex.print(<number> n, <string> s, ...) |
| 1170 |
tex.print(<table> t) |
| 1171 |
tex.print(<number> n, <table> t) |
| 1172 |
\stopfunctioncall |
| 1173 |
|
| 1174 |
Each string argument is treated by \TEX\ as a separate input line. If there is a |
| 1175 |
table argument instead of a list of strings, this has to be a consecutive array |
| 1176 |
of strings to print (the first non-string value will stop the printing process). |
| 1177 |
|
| 1178 |
The optional parameter can be used to print the strings using the catcode regime |
| 1179 |
defined by \lpr {catcodetable}~\type {n}. If \type {n} is $-1$, the currently |
| 1180 |
active catcode regime is used. If \type {n} is $-2$, the resulting catcodes are |
| 1181 |
the result of \prm {the} \prm {toks}: all category codes are 12 (other) except for |
| 1182 |
the space character, that has category code 10 (space). Otherwise, if \type {n} |
| 1183 |
is not a valid catcode table, then it is ignored, and the currently active |
| 1184 |
catcode regime is used instead. |
| 1185 |
|
| 1186 |
The very last string of the very last \type {tex.print} command in a \prm |
| 1187 |
{directlua} will not have the \prm {endlinechar} appended, all others do. |
| 1188 |
|
| 1189 |
\subsubsection{\type {sprint}} |
| 1190 |
|
| 1191 |
\libindex{sprint} |
| 1192 |
|
| 1193 |
\startfunctioncall |
| 1194 |
tex.sprint(<string> s, ...) |
| 1195 |
tex.sprint(<number> n, <string> s, ...) |
| 1196 |
tex.sprint(<table> t) |
| 1197 |
tex.sprint(<number> n, <table> t) |
| 1198 |
\stopfunctioncall |
| 1199 |
|
| 1200 |
Each string argument is treated by \TEX\ as a special kind of input line that |
| 1201 |
makes it suitable for use as a partial line input mechanism: |
| 1202 |
|
| 1203 |
\startitemize[packed] |
| 1204 |
\startitem |
| 1205 |
\TEX\ does not switch to the \quote {new line} state, so that leading spaces |
| 1206 |
are not ignored. |
| 1207 |
\stopitem |
| 1208 |
\startitem |
| 1209 |
No \prm {endlinechar} is inserted. |
| 1210 |
\stopitem |
| 1211 |
\startitem |
| 1212 |
Trailing spaces are not removed. Note that this does not prevent \TEX\ itself |
| 1213 |
from eating spaces as result of interpreting the line. For example, in |
| 1214 |
|
| 1215 |
\starttyping |
| 1216 |
before\directlua{tex.sprint("\\relax")tex.sprint(" inbetween")}after |
| 1217 |
\stoptyping |
| 1218 |
|
| 1219 |
the space before \type {in between} will be gobbled as a result of the \quote |
| 1220 |
{normal} scanning of \prm {relax}. |
| 1221 |
\stopitem |
| 1222 |
\stopitemize |
| 1223 |
|
| 1224 |
If there is a table argument instead of a list of strings, this has to be a |
| 1225 |
consecutive array of strings to print (the first non-string value will stop the |
| 1226 |
printing process). |
| 1227 |
|
| 1228 |
The optional argument sets the catcode regime, as with \type {tex.print}. This |
| 1229 |
influences the string arguments (or numbers turned into strings). |
| 1230 |
|
| 1231 |
Although this needs to be used with care, you can also pass token or node |
| 1232 |
userdata objects. These get injected into the stream. Tokens had best be valid |
| 1233 |
tokens, while nodes need to be around when they get injected. Therefore it is |
| 1234 |
important to realize the following: |
| 1235 |
|
| 1236 |
\startitemize |
| 1237 |
\startitem |
| 1238 |
When you inject a token, you need to pass a valid token userdata object. This |
| 1239 |
object will be collected by \LUA\ when it no longer is referenced. When it gets |
| 1240 |
printed to \TEX\ the token itself gets copied so there is no interference with the |
| 1241 |
\LUA\ garbage collection. You manage the object yourself. Because tokens are |
| 1242 |
actually just numbers, there is no real extra overhead at the \TEX\ end. |
| 1243 |
\stopitem |
| 1244 |
\startitem |
| 1245 |
When you inject a node, you need to pass a valid node userdata object. The |
| 1246 |
node related to the object will not be collected by \LUA\ when it no longer |
| 1247 |
is referenced. It lives on at the \TEX\ end in its own memory space. When it |
| 1248 |
gets printed to \TEX\ the node reference is used assuming that node stays |
| 1249 |
around. There is no \LUA\ garbage collection involved. Again, you manage the |
| 1250 |
object yourself. The node itself is freed when \TEX\ is done with it. |
| 1251 |
\stopitem |
| 1252 |
\stopitemize |
| 1253 |
|
| 1254 |
If you consider the last remark you might realize that we have a problem when a |
| 1255 |
printed mix of strings, tokens and nodes is reused. Inside \TEX\ the sequence |
| 1256 |
becomes a linked list of input buffers. So, \type {"123"} or \type {"\foo{123}"} |
| 1257 |
gets read and parsed on the fly, while \typ {<token userdata>} already is |
| 1258 |
tokenized and effectively is a token list now. A \typ {<node userdata>} is also |
| 1259 |
tokenized into a token list but it has a reference to a real node. Normally this |
| 1260 |
goes fine. But now assume that you store the whole lot in a macro: in that case |
| 1261 |
the tokenized node can be flushed many times. But, after the first such flush the |
| 1262 |
node is used and its memory freed. You can prevent this by using copies which is |
| 1263 |
controlled by setting \lpr {luacopyinputnodes} to a non|-|zero value. This is one |
| 1264 |
of these fuzzy areas you have to live with if you really mess with these low |
| 1265 |
level issues. |
| 1266 |
|
| 1267 |
\subsubsection{\type {tprint}} |
| 1268 |
|
| 1269 |
\libindex{tprint} |
| 1270 |
|
| 1271 |
\startfunctioncall |
| 1272 |
tex.tprint({<number> n, <string> s, ...}, {...}) |
| 1273 |
\stopfunctioncall |
| 1274 |
|
| 1275 |
This function is basically a shortcut for repeated calls to \type |
| 1276 |
{tex.sprint(<number> n, <string> s, ...)}, once for each of the supplied argument |
| 1277 |
tables. |
| 1278 |
|
| 1279 |
\subsubsection{\type {cprint}} |
| 1280 |
|
| 1281 |
\libindex{cprint} |
| 1282 |
|
| 1283 |
This function takes a number indicating the to be used catcode, plus either a |
| 1284 |
table of strings or an argument list of strings that will be pushed into the |
| 1285 |
input stream. |
| 1286 |
|
| 1287 |
\startfunctioncall |
| 1288 |
tex.cprint( 1," 1: $&{\\foo}") tex.print("\\par") -- a lot of \bgroup s |
| 1289 |
tex.cprint( 2," 2: $&{\\foo}") tex.print("\\par") -- matching \egroup s |
| 1290 |
tex.cprint( 9," 9: $&{\\foo}") tex.print("\\par") -- all get ignored |
| 1291 |
tex.cprint(10,"10: $&{\\foo}") tex.print("\\par") -- all become spaces |
| 1292 |
tex.cprint(11,"11: $&{\\foo}") tex.print("\\par") -- letters |
| 1293 |
tex.cprint(12,"12: $&{\\foo}") tex.print("\\par") -- other characters |
| 1294 |
tex.cprint(14,"12: $&{\\foo}") tex.print("\\par") -- comment triggers |
| 1295 |
\stopfunctioncall |
| 1296 |
|
| 1297 |
% \subsubsection{\type {write}, \type {twrite}, \type {nwrite}} |
| 1298 |
\subsubsection{\type {write}} |
| 1299 |
|
| 1300 |
\libindex{write} |
| 1301 |
% \libindex{twrite} |
| 1302 |
% \libindex{nwrite} |
| 1303 |
|
| 1304 |
\startfunctioncall |
| 1305 |
tex.write(<string> s, ...) |
| 1306 |
tex.write(<table> t) |
| 1307 |
\stopfunctioncall |
| 1308 |
|
| 1309 |
Each string argument is treated by \TEX\ as a special kind of input line that |
| 1310 |
makes it suitable for use as a quick way to dump information: |
| 1311 |
|
| 1312 |
\startitemize |
| 1313 |
\item All catcodes on that line are either \quote{space} (for '~') or \quote |
| 1314 |
{character} (for all others). |
| 1315 |
\item There is no \prm {endlinechar} appended. |
| 1316 |
\stopitemize |
| 1317 |
|
| 1318 |
If there is a table argument instead of a list of strings, this has to be a |
| 1319 |
consecutive array of strings to print (the first non-string value will stop the |
| 1320 |
printing process). |
| 1321 |
|
| 1322 |
% The functions \type {twrite} and \type {nwrite} can be used to write a token or |
| 1323 |
% node back to \TEX\, possibly intermixed with regular strings that will be |
| 1324 |
% tokenized. You have to make sure that you pass the right data because sometimes |
| 1325 |
% \TEX\ has expectations that need to be met. |
| 1326 |
|
| 1327 |
\stopsubsection |
| 1328 |
|
| 1329 |
\startsubsection[title={Helper functions}] |
| 1330 |
|
| 1331 |
\subsubsection{\type {round}} |
| 1332 |
|
| 1333 |
\topicindex {helpers} |
| 1334 |
|
| 1335 |
\libindex{round} |
| 1336 |
|
| 1337 |
\startfunctioncall |
| 1338 |
<number> n = tex.round(<number> o) |
| 1339 |
\stopfunctioncall |
| 1340 |
|
| 1341 |
Rounds \LUA\ number \type {o}, and returns a number that is in the range of a |
| 1342 |
valid \TEX\ register value. If the number starts out of range, it generates a |
| 1343 |
\quote {number too big} error as well. |
| 1344 |
|
| 1345 |
\subsubsection{\type {scale}} |
| 1346 |
|
| 1347 |
\libindex{scale} |
| 1348 |
|
| 1349 |
\startfunctioncall |
| 1350 |
<number> n = tex.scale(<number> o, <number> delta) |
| 1351 |
<table> n = tex.scale(table o, <number> delta) |
| 1352 |
\stopfunctioncall |
| 1353 |
|
| 1354 |
Multiplies the \LUA\ numbers \type {o} and \nod {delta}, and returns a rounded |
| 1355 |
number that is in the range of a valid \TEX\ register value. In the table |
| 1356 |
version, it creates a copy of the table with all numeric top||level values scaled |
| 1357 |
in that manner. If the multiplied number(s) are of range, it generates |
| 1358 |
\quote{number too big} error(s) as well. |
| 1359 |
|
| 1360 |
Note: the precision of the output of this function will depend on your computer's |
| 1361 |
architecture and operating system, so use with care! An interface to \LUATEX's |
| 1362 |
internal, 100\% portable scale function will be added at a later date. |
| 1363 |
|
| 1364 |
\subsubsection{\type {number} and \type {romannumeral}} |
| 1365 |
|
| 1366 |
\libindex{number} |
| 1367 |
\libindex{romannumeral} |
| 1368 |
|
| 1369 |
These are the companions to the primitives \prm {number} and \prm |
| 1370 |
{romannumeral}. They can be used like: |
| 1371 |
|
| 1372 |
\startfunctioncall |
| 1373 |
tex.print(tex.romannumeral(123)) |
| 1374 |
\stopfunctioncall |
| 1375 |
|
| 1376 |
\subsubsection{\type {fontidentifier} and \type {fontname}} |
| 1377 |
|
| 1378 |
\libindex{fontidentifier} |
| 1379 |
\libindex{fontname} |
| 1380 |
|
| 1381 |
The first one returns the name only, the second one reports the size too. |
| 1382 |
|
| 1383 |
\startfunctioncall |
| 1384 |
tex.print(tex.fontidentifier(1)) |
| 1385 |
tex.print(tex.fontname(1)) |
| 1386 |
\stopfunctioncall |
| 1387 |
|
| 1388 |
\subsubsection{\type {sp}} |
| 1389 |
|
| 1390 |
\libindex{sp} |
| 1391 |
|
| 1392 |
\startfunctioncall |
| 1393 |
<number> n = tex.sp(<number> o) |
| 1394 |
<number> n = tex.sp(<string> s) |
| 1395 |
\stopfunctioncall |
| 1396 |
|
| 1397 |
Converts the number \type {o} or a string \type {s} that represents an explicit |
| 1398 |
dimension into an integer number of scaled points. |
| 1399 |
|
| 1400 |
For parsing the string, the same scanning and conversion rules are used that |
| 1401 |
\LUATEX\ would use if it was scanning a dimension specifier in its \TEX|-|like |
| 1402 |
input language (this includes generating errors for bad values), expect for the |
| 1403 |
following: |
| 1404 |
|
| 1405 |
\startitemize[n] |
| 1406 |
\startitem |
| 1407 |
only explicit values are allowed, control sequences are not handled |
| 1408 |
\stopitem |
| 1409 |
\startitem |
| 1410 |
infinite dimension units (\type {fil...}) are forbidden |
| 1411 |
\stopitem |
| 1412 |
\startitem |
| 1413 |
\type {mu} units do not generate an error (but may not be useful either) |
| 1414 |
\stopitem |
| 1415 |
\stopitemize |
| 1416 |
|
| 1417 |
%\subsubsection{\type {tex.getlinenumber} and \type {tex.setlinenumber}} |
| 1418 |
% |
| 1419 |
%\libindex{getlinenumber} |
| 1420 |
%\libindex{setlinenumber} |
| 1421 |
% |
| 1422 |
%You can mess with the current line number: |
| 1423 |
% |
| 1424 |
%\startfunctioncall |
| 1425 |
%local n = tex.getlinenumber() |
| 1426 |
%tex.setlinenumber(n+10) |
| 1427 |
%\stopfunctioncall |
| 1428 |
% |
| 1429 |
%which can be shortcut to: |
| 1430 |
% |
| 1431 |
%\startfunctioncall |
| 1432 |
%tex.setlinenumber(10,true) |
| 1433 |
%\stopfunctioncall |
| 1434 |
% |
| 1435 |
%This might be handy when you have a callback that read numbers from a file and |
| 1436 |
%combines them in one line (in which case an error message probably has to refer |
| 1437 |
%to the original line). Interference with \TEX's internal handling of numbers is |
| 1438 |
%of course possible. |
| 1439 |
|
| 1440 |
\subsubsection{\type {error} and \type {show_context}} |
| 1441 |
|
| 1442 |
\topicindex{errors} |
| 1443 |
|
| 1444 |
\libindex{error} |
| 1445 |
\libindex{show_context} |
| 1446 |
|
| 1447 |
\startfunctioncall |
| 1448 |
tex.error(<string> s) |
| 1449 |
tex.error(<string> s, <table> help) |
| 1450 |
\stopfunctioncall |
| 1451 |
|
| 1452 |
This creates an error somewhat like the combination of \prm {errhelp} and \prm |
| 1453 |
{errmessage} would. During this error, deletions are disabled. |
| 1454 |
|
| 1455 |
The array part of the \type {help} table has to contain strings, one for each |
| 1456 |
line of error help. |
| 1457 |
|
| 1458 |
In case of an error the \type {show_context} function will show the current |
| 1459 |
context where we're at (in the expansion). |
| 1460 |
|
| 1461 |
\subsubsection{\type {run}, \type {finish}} |
| 1462 |
|
| 1463 |
\libindex{run} |
| 1464 |
\libindex{finish} |
| 1465 |
|
| 1466 |
These two functions start the interpretations and force its end. A runs normally |
| 1467 |
boils down to \TEX\ entering the so called main loop. A token is fetched and |
| 1468 |
depending on it current meaning some actions takes place. Sometimes that actions |
| 1469 |
comes immediately, sometimes more scanning is needed. Quite often tokens get |
| 1470 |
pushed back into the input. This all means that the \TEX\ scanner is constantly |
| 1471 |
pushing and popping input states, but in the end after all the action is done |
| 1472 |
returns to the main loop. |
| 1473 |
|
| 1474 |
\subsubsection{\type {runtoks}} |
| 1475 |
|
| 1476 |
Because of the fact that \TEX\ is in a complex dance of expanding, dealing with |
| 1477 |
fonts, typesetting paragraphs, messing around with boxes, building pages, and so |
| 1478 |
on, you cannot easily run a nested \TEX\ run (read nested main loop). However, |
| 1479 |
there is an option to force a local run with \type {runtoks}. The content of the |
| 1480 |
given token list register gets expanded locally after which we return to where we |
| 1481 |
triggered this expansion, at the \LUA\ end. Instead a function can get passed |
| 1482 |
that does some work. You have to make sure that at the end \TEX\ is in a sane |
| 1483 |
state and this is not always trivial. A more complex mechanism would complicate |
| 1484 |
\TEX\ itself (and probably also harm performance) so this simple local expansion |
| 1485 |
loop has to do. |
| 1486 |
|
| 1487 |
\startfunctioncall |
| 1488 |
tex.runtoks(<token register>) |
| 1489 |
tex.runtoks(<lua function>) |
| 1490 |
\stopfunctioncall |
| 1491 |
|
| 1492 |
When the \prm {tracingnesting} parameter is set to a value larger than~2 some |
| 1493 |
information is reported about the state of the local loop. |
| 1494 |
|
| 1495 |
This function has two optional arguments in case a token register is passed: |
| 1496 |
|
| 1497 |
\startfunctioncall |
| 1498 |
tex.runtoks(<token register>,force,grouped) |
| 1499 |
\stopfunctioncall |
| 1500 |
|
| 1501 |
Inside for instance an \type {\edef} the \type {runtoks} function behaves (at |
| 1502 |
least tries to) like it were an \type {\the}. This prevents unwanted side |
| 1503 |
effects: normally in such an definition tokens remain tokens and (for instance) |
| 1504 |
characters don't become nodes. With the second argument you can force the local |
| 1505 |
main loop, no matter what. The third argument adds a level of grouping. |
| 1506 |
|
| 1507 |
You can quit the local loop with \type {\endlocalcontrol} or from the \LUA\ end |
| 1508 |
with \type {tex.quittoks}. In that case you end one level up! Of course in the |
| 1509 |
end that can mean that you arrive at the main level in which case an extra end |
| 1510 |
will trigger a redundancy warning (not an abort!). |
| 1511 |
|
| 1512 |
\subsubsection{\type {forcehmode}} |
| 1513 |
|
| 1514 |
\libindex{forcehmode} |
| 1515 |
|
| 1516 |
An example of a (possible error triggering) complication is that \TEX\ expects to |
| 1517 |
be in some state, say horizontal mode, and you have to make sure it is when you |
| 1518 |
start feeding back something from \LUA\ into \TEX. Normally a user will not run |
| 1519 |
into issues but when you start writing tokens or nodes or have a nested run there |
| 1520 |
can be situations that you need to run \type {forcehmode}. There is no recipe for |
| 1521 |
this and intercepting possible cases would weaken \LUATEX's flexibility. |
| 1522 |
|
| 1523 |
\subsubsection{\type {hashtokens}} |
| 1524 |
|
| 1525 |
\libindex{hashtokens} |
| 1526 |
|
| 1527 |
\topicindex{hash} |
| 1528 |
|
| 1529 |
\startfunctioncall |
| 1530 |
for i,v in pairs (tex.hashtokens()) do ... end |
| 1531 |
\stopfunctioncall |
| 1532 |
|
| 1533 |
Returns a list of names. This can be useful for debugging, but note that this |
| 1534 |
also reports control sequences that may be unreachable at this moment due to |
| 1535 |
local redefinitions: it is strictly a dump of the hash table. You can use \type |
| 1536 |
{token.create} to inspect properties, for instance when the \type {command} key |
| 1537 |
in a created table equals \type {123}, you have the \type {cmdname} value \type |
| 1538 |
{undefined_cs}. |
| 1539 |
|
| 1540 |
\subsubsection{\type {definefont}} |
| 1541 |
|
| 1542 |
\topicindex{fonts+defining} |
| 1543 |
|
| 1544 |
\libindex{definefont} |
| 1545 |
|
| 1546 |
\startfunctioncall |
| 1547 |
tex.definefont(<string> csname, <number> fontid) |
| 1548 |
tex.definefont(<boolean> global, <string> csname, <number> fontid) |
| 1549 |
\stopfunctioncall |
| 1550 |
|
| 1551 |
Associates \type {csname} with the internal font number \type {fontid}. The |
| 1552 |
definition is global if (and only if) \type {global} is specified and true (the |
| 1553 |
setting of \type {globaldefs} is not taken into account). |
| 1554 |
|
| 1555 |
\stopsubsection |
| 1556 |
|
| 1557 |
\startsubsection[reference=luaprimitives,title={Functions for dealing with primitives}] |
| 1558 |
|
| 1559 |
\subsubsection{\type {enableprimitives}} |
| 1560 |
|
| 1561 |
\libindex{enableprimitives} |
| 1562 |
|
| 1563 |
\topicindex{initialization} |
| 1564 |
\topicindex{primitives} |
| 1565 |
|
| 1566 |
\startfunctioncall |
| 1567 |
tex.enableprimitives(<string> prefix, <table> primitive names) |
| 1568 |
\stopfunctioncall |
| 1569 |
|
| 1570 |
This function accepts a prefix string and an array of primitive names. For each |
| 1571 |
combination of \quote {prefix} and \quote {name}, the \type |
| 1572 |
{tex.enableprimitives} first verifies that \quote {name} is an actual primitive |
| 1573 |
(it must be returned by one of the \type {tex.extraprimitives} calls explained |
| 1574 |
below, or part of \TEX82, or \prm {directlua}). If it is not, \type |
| 1575 |
{tex.enableprimitives} does nothing and skips to the next pair. |
| 1576 |
|
| 1577 |
But if it is, then it will construct a csname variable by concatenating the |
| 1578 |
\quote {prefix} and \quote {name}, unless the \quote {prefix} is already the |
| 1579 |
actual prefix of \quote {name}. In the latter case, it will discard the \quote |
| 1580 |
{prefix}, and just use \quote {name}. |
| 1581 |
|
| 1582 |
Then it will check for the existence of the constructed csname. If the csname is |
| 1583 |
currently undefined (note: that is not the same as \prm {relax}), it will |
| 1584 |
globally define the csname to have the meaning: run code belonging to the |
| 1585 |
primitive \quote {name}. If for some reason the csname is already defined, it |
| 1586 |
does nothing and tries the next pair. |
| 1587 |
|
| 1588 |
An example: |
| 1589 |
|
| 1590 |
\starttyping |
| 1591 |
tex.enableprimitives('LuaTeX', {'formatname'}) |
| 1592 |
\stoptyping |
| 1593 |
|
| 1594 |
will define \type {\LuaTeXformatname} with the same intrinsic meaning as the |
| 1595 |
documented primitive \lpr {formatname}, provided that the control sequences \type |
| 1596 |
{\LuaTeXformatname} is currently undefined. |
| 1597 |
|
| 1598 |
When \LUATEX\ is run with \type {--ini} only the \TEX82 primitives and \prm |
| 1599 |
{directlua} are available, so no extra primitives {\bf at all}. |
| 1600 |
|
| 1601 |
If you want to have all the new functionality available using their default |
| 1602 |
names, as it is now, you will have to add |
| 1603 |
|
| 1604 |
\starttyping |
| 1605 |
\ifx\directlua\undefined \else |
| 1606 |
\directlua {tex.enableprimitives('',tex.extraprimitives ())} |
| 1607 |
\fi |
| 1608 |
\stoptyping |
| 1609 |
|
| 1610 |
near the beginning of your format generation file. Or you can choose different |
| 1611 |
prefixes for different subsets, as you see fit. |
| 1612 |
|
| 1613 |
Calling some form of \type {tex.enableprimitives} is highly important though, |
| 1614 |
because if you do not, you will end up with a \TEX82-lookalike that can run \LUA\ |
| 1615 |
code but not do much else. The defined csnames are (of course) saved in the |
| 1616 |
format and will be available at runtime. |
| 1617 |
|
| 1618 |
\subsubsection{\type {extraprimitives}} |
| 1619 |
|
| 1620 |
\libindex{extraprimitives} |
| 1621 |
|
| 1622 |
\startfunctioncall |
| 1623 |
<table> t = tex.extraprimitives(<string> s, ...) |
| 1624 |
\stopfunctioncall |
| 1625 |
|
| 1626 |
This function returns a list of the primitives that originate from the engine(s) |
| 1627 |
given by the requested string value(s). The possible values and their (current) |
| 1628 |
return values are given in the following table. In addition the somewhat special |
| 1629 |
primitives \quote{\tex{ }}, \quote{\tex {/}} and \quote{\type {-}} are defined. |
| 1630 |
|
| 1631 |
\startluacode |
| 1632 |
function document.showprimitives(tag) |
| 1633 |
local t = tex.extraprimitives(tag) |
| 1634 |
table.sort(t) |
| 1635 |
for i=1,#t do |
| 1636 |
local v = t[i] |
| 1637 |
if v ~= ' ' and v ~= "/" and v ~= "-" then |
| 1638 |
context.type(v) |
| 1639 |
context.space() |
| 1640 |
end |
| 1641 |
end |
| 1642 |
end |
| 1643 |
\stopluacode |
| 1644 |
|
| 1645 |
\starttabulate[|l|pl|] |
| 1646 |
\DB name \BC values \NC \NR |
| 1647 |
\TB |
| 1648 |
\NC tex \NC \ctxlua{document.showprimitives('tex') } \NC \NR |
| 1649 |
\NC core \NC \ctxlua{document.showprimitives('core') } \NC \NR |
| 1650 |
\NC etex \NC \ctxlua{document.showprimitives('etex') } \NC \NR |
| 1651 |
\NC luatex \NC \ctxlua{document.showprimitives('luatex') } \NC \NR |
| 1652 |
\LL |
| 1653 |
\stoptabulate |
| 1654 |
|
| 1655 |
Note that \type {luatex} does not contain \type {directlua}, as that is |
| 1656 |
considered to be a core primitive, along with all the \TEX82 primitives, so it is |
| 1657 |
part of the list that is returned from \type {'core'}. |
| 1658 |
|
| 1659 |
Running \type {tex.extraprimitives} will give you the complete list of |
| 1660 |
primitives \type {-ini} startup. It is exactly equivalent to \type |
| 1661 |
{tex.extraprimitives("etex","luatex")}. |
| 1662 |
|
| 1663 |
\subsubsection{\type {primitives}} |
| 1664 |
|
| 1665 |
\libindex{primitives} |
| 1666 |
|
| 1667 |
\startfunctioncall |
| 1668 |
<table> t = tex.primitives() |
| 1669 |
\stopfunctioncall |
| 1670 |
|
| 1671 |
This function returns a list of all primitives that \LUATEX\ knows about. |
| 1672 |
|
| 1673 |
\stopsubsection |
| 1674 |
|
| 1675 |
\startsubsection[title={Core functionality interfaces}] |
| 1676 |
|
| 1677 |
\subsubsection{\type {badness}} |
| 1678 |
|
| 1679 |
\libindex{badness} |
| 1680 |
|
| 1681 |
\startfunctioncall |
| 1682 |
<number> b = tex.badness(<number> t, <number> s) |
| 1683 |
\stopfunctioncall |
| 1684 |
|
| 1685 |
This helper function is useful during linebreak calculations. \type {t} and \type |
| 1686 |
{s} are scaled values; the function returns the badness for when total \type {t} |
| 1687 |
is supposed to be made from amounts that sum to \type {s}. The returned number is |
| 1688 |
a reasonable approximation of \mathematics {100(t/s)^3}; |
| 1689 |
|
| 1690 |
\subsubsection{\type {tex.resetparagraph}} |
| 1691 |
|
| 1692 |
\topicindex {paragraphs+reset} |
| 1693 |
|
| 1694 |
\libindex{resetparagraph} |
| 1695 |
|
| 1696 |
This function resets the parameters that \TEX\ normally resets when a new paragraph |
| 1697 |
is seen. |
| 1698 |
|
| 1699 |
\subsubsection{\type {linebreak}} |
| 1700 |
|
| 1701 |
\topicindex {linebreaks} |
| 1702 |
|
| 1703 |
\libindex{linebreak} |
| 1704 |
|
| 1705 |
\startfunctioncall |
| 1706 |
local <node> nodelist, <table> info = |
| 1707 |
tex.linebreak(<node> listhead, <table> parameters) |
| 1708 |
\stopfunctioncall |
| 1709 |
|
| 1710 |
The understood parameters are as follows: |
| 1711 |
|
| 1712 |
\starttabulate[|l|l|p|] |
| 1713 |
\DB name \BC type \BC explanation \NC \NR |
| 1714 |
\TB |
| 1715 |
\NC \type{pardir} \NC string \NC \NC \NR |
| 1716 |
\NC \type{pretolerance} \NC number \NC \NC \NR |
| 1717 |
\NC \type{tracingparagraphs} \NC number \NC \NC \NR |
| 1718 |
\NC \type{tolerance} \NC number \NC \NC \NR |
| 1719 |
\NC \type{looseness} \NC number \NC \NC \NR |
| 1720 |
\NC \type{hyphenpenalty} \NC number \NC \NC \NR |
| 1721 |
\NC \type{exhyphenpenalty} \NC number \NC \NC \NR |
| 1722 |
\NC \type{pdfadjustspacing} \NC number \NC \NC \NR |
| 1723 |
\NC \type{adjdemerits} \NC number \NC \NC \NR |
| 1724 |
\NC \type{pdfprotrudechars} \NC number \NC \NC \NR |
| 1725 |
\NC \type{linepenalty} \NC number \NC \NC \NR |
| 1726 |
\NC \type{lastlinefit} \NC number \NC \NC \NR |
| 1727 |
\NC \type{doublehyphendemerits} \NC number \NC \NC \NR |
| 1728 |
\NC \type{finalhyphendemerits} \NC number \NC \NC \NR |
| 1729 |
\NC \type{hangafter} \NC number \NC \NC \NR |
| 1730 |
\NC \type{interlinepenalty} \NC number or table \NC if a table, then it is an array like \prm {interlinepenalties} \NC \NR |
| 1731 |
\NC \type{clubpenalty} \NC number or table \NC if a table, then it is an array like \prm {clubpenalties} \NC \NR |
| 1732 |
\NC \type{widowpenalty} \NC number or table \NC if a table, then it is an array like \prm {widowpenalties} \NC \NR |
| 1733 |
\NC \type{brokenpenalty} \NC number \NC \NC \NR |
| 1734 |
\NC \type{emergencystretch} \NC number \NC in scaled points \NC \NR |
| 1735 |
\NC \type{hangindent} \NC number \NC in scaled points \NC \NR |
| 1736 |
\NC \type{hsize} \NC number \NC in scaled points \NC \NR |
| 1737 |
\NC \type{leftskip} \NC glue_spec node \NC \NC \NR |
| 1738 |
\NC \type{rightskip} \NC glue_spec node \NC \NC \NR |
| 1739 |
\NC \type{parshape} \NC table \NC \NC \NR |
| 1740 |
\LL |
| 1741 |
\stoptabulate |
| 1742 |
|
| 1743 |
Note that there is no interface for \prm {displaywidowpenalties}, you have to |
| 1744 |
pass the right choice for \type {widowpenalties} yourself. |
| 1745 |
|
| 1746 |
It is your own job to make sure that \type {listhead} is a proper paragraph list: |
| 1747 |
this function does not add any nodes to it. To be exact, if you want to replace |
| 1748 |
the core line breaking, you may have to do the following (when you are not |
| 1749 |
actually working in the \cbk {pre_linebreak_filter} or \cbk {linebreak_filter} |
| 1750 |
callbacks, or when the original list starting at listhead was generated in |
| 1751 |
horizontal mode): |
| 1752 |
|
| 1753 |
\startitemize |
| 1754 |
\startitem |
| 1755 |
add an \quote {indent box} and perhaps a \nod {local_par} node at the start |
| 1756 |
(only if you need them) |
| 1757 |
\stopitem |
| 1758 |
\startitem |
| 1759 |
replace any found final glue by an infinite penalty (or add such a penalty, |
| 1760 |
if the last node is not a glue) |
| 1761 |
\stopitem |
| 1762 |
\startitem |
| 1763 |
add a glue node for the \prm {parfillskip} after that penalty node |
| 1764 |
\stopitem |
| 1765 |
\startitem |
| 1766 |
make sure all the \type {prev} pointers are OK |
| 1767 |
\stopitem |
| 1768 |
\stopitemize |
| 1769 |
|
| 1770 |
The result is a node list, it still needs to be vpacked if you want to assign it |
| 1771 |
to a \prm {vbox}. The returned \type {info} table contains four values that are |
| 1772 |
all numbers: |
| 1773 |
|
| 1774 |
\starttabulate[|l|p|] |
| 1775 |
\DB name \BC explanation \NC \NR |
| 1776 |
\TB |
| 1777 |
\NC prevdepth \NC depth of the last line in the broken paragraph \NC \NR |
| 1778 |
\NC prevgraf \NC number of lines in the broken paragraph \NC \NR |
| 1779 |
\NC looseness \NC the actual looseness value in the broken paragraph \NC \NR |
| 1780 |
\NC demerits \NC the total demerits of the chosen solution \NC \NR |
| 1781 |
\LL |
| 1782 |
\stoptabulate |
| 1783 |
|
| 1784 |
Note there are a few things you cannot interface using this function: You cannot |
| 1785 |
influence font expansion other than via \type {pdfadjustspacing}, because the |
| 1786 |
settings for that take place elsewhere. The same is true for hbadness and hfuzz |
| 1787 |
etc. All these are in the \type {hpack} routine, and that fetches its own |
| 1788 |
variables via globals. |
| 1789 |
|
| 1790 |
\subsubsection{\type {shipout}} |
| 1791 |
|
| 1792 |
\topicindex {shipout} |
| 1793 |
|
| 1794 |
\libindex{shipout} |
| 1795 |
|
| 1796 |
\startfunctioncall |
| 1797 |
tex.shipout(<number> n) |
| 1798 |
\stopfunctioncall |
| 1799 |
|
| 1800 |
Ships out box number \type {n} to the output file, and clears the box register. |
| 1801 |
|
| 1802 |
\subsubsection{\type {getpagestate}} |
| 1803 |
|
| 1804 |
\topicindex {pages} |
| 1805 |
|
| 1806 |
\libindex{getpagestate} |
| 1807 |
|
| 1808 |
This helper reports the current page state: \type {empty}, \type {box_there} or |
| 1809 |
\type {inserts_only} as integer value. |
| 1810 |
|
| 1811 |
\subsubsection{\type {getlocallevel}} |
| 1812 |
|
| 1813 |
\topicindex {nesting} |
| 1814 |
|
| 1815 |
\libindex{getlocallevel} |
| 1816 |
|
| 1817 |
This integer reports the current level of the local loop. It's only useful for |
| 1818 |
debugging and the (relative state) numbers can change with the implementation. |
| 1819 |
|
| 1820 |
\stopsubsection |
| 1821 |
|
| 1822 |
\startsubsection[title={Randomizers}] |
| 1823 |
|
| 1824 |
\libindex{lua_math_random} |
| 1825 |
\libindex{lua_math_randomseed} |
| 1826 |
\libindex{init_rand} |
| 1827 |
\libindex{normal_rand} |
| 1828 |
\libindex{uniform_rand} |
| 1829 |
\libindex{uniformdeviate} |
| 1830 |
|
| 1831 |
For practical reasons \LUATEX\ has its own random number generator. The original |
| 1832 |
\LUA\ random function is available as \typ {tex.lua_math_random}. You can |
| 1833 |
initialize with a new seed with \type {init_rand} (\typ {lua_math_randomseed} is |
| 1834 |
equivalent to this one. |
| 1835 |
|
| 1836 |
There are three generators: \type {normal_rand} (no argument is used), \type |
| 1837 |
{uniform_rand} (takes a number that will get rounded before being used) and \type |
| 1838 |
{uniformdeviate} which behaves like the primitive and expects a scaled integer, so |
| 1839 |
|
| 1840 |
\startfunctioncall |
| 1841 |
tex.print(tex.uniformdeviate(65536)/65536) |
| 1842 |
\stopfunctioncall |
| 1843 |
|
| 1844 |
will give a random number between zero and one. |
| 1845 |
|
| 1846 |
\stopsubsection |
| 1847 |
|
| 1848 |
\startsubsection[reference=synctex,title={Functions related to synctex}] |
| 1849 |
|
| 1850 |
\topicindex {synctex} |
| 1851 |
|
| 1852 |
\libindex{set_synctex_mode} \libindex{get_synctex_mode} |
| 1853 |
\libindex{set_synctex_no_files} |
| 1854 |
\libindex{set_synctex_tag} \libindex{get_synctex_tag} \libindex{force_synctex_tag} |
| 1855 |
\libindex{set_synctex_line} \libindex{get_synctex_line} \libindex{force_synctex_line} |
| 1856 |
|
| 1857 |
The next helpers only make sense when you implement your own synctex logic. Keep in |
| 1858 |
mind that the library used in editors assumes a certain logic and is geared for |
| 1859 |
plain and \LATEX, so after a decade users expect a certain behaviour. |
| 1860 |
|
| 1861 |
\starttabulate[|l|p|] |
| 1862 |
\DB name \BC explanation \NC \NR |
| 1863 |
\TB |
| 1864 |
\NC \type{set_synctex_mode} \NC \type {0} is the default and used normal synctex |
| 1865 |
logic, \type {1} uses the values set by the next |
| 1866 |
helpers while \type {2} also sets these for glyph |
| 1867 |
nodes; \type{3} sets glyphs and glue and \type {4} |
| 1868 |
sets only glyphs \NC \NR |
| 1869 |
\NC \type{set_synctex_tag} \NC set the current tag (file) value (obeys save stack) \NC \NR |
| 1870 |
\NC \type{set_synctex_line} \NC set the current line value (obeys save stack) \NC \NR |
| 1871 |
\NC \type{set_synctex_no_files} \NC disable synctex file logging \NC \NR |
| 1872 |
\NC \type{get_synctex_mode} \NC returns the current mode (for values see above) \NC \NR |
| 1873 |
\NC \type{get_synctex_tag} \NC get the currently set value of tag (file) \NC \NR |
| 1874 |
\NC \type{get_synctex_line} \NC get the currently set value of line \NC \NR |
| 1875 |
\NC \type{force_synctex_tag} \NC overload the tag (file) value (\type {0} resets) \NC \NR |
| 1876 |
\NC \type{force_synctex_line} \NC overload the line value (\type {0} resets) \NC \NR |
| 1877 |
\LL |
| 1878 |
\stoptabulate |
| 1879 |
|
| 1880 |
The last one is somewhat special. Due to the way files are registered in \SYNCTEX\ we need |
| 1881 |
to explicitly disable that feature if we provide our own alternative if we want to avoid |
| 1882 |
that overhead. Passing a value of 1 disables registering. |
| 1883 |
|
| 1884 |
\stopsubsection |
| 1885 |
|
| 1886 |
\stopsection |
| 1887 |
|
| 1888 |
\startsection[title={The \type {texconfig} table},reference=texconfig][library=texconfig] |
| 1889 |
|
| 1890 |
\topicindex{libraries+\type{texconfig}} |
| 1891 |
|
| 1892 |
\topicindex {configuration} |
| 1893 |
|
| 1894 |
This is a table that is created empty. A startup \LUA\ script could |
| 1895 |
fill this table with a number of settings that are read out by |
| 1896 |
the executable after loading and executing the startup file. |
| 1897 |
|
| 1898 |
\starttabulate[|l|l|l|p|] |
| 1899 |
\DB key \BC type \BC default \BC explanation \NC \NR |
| 1900 |
\TB |
| 1901 |
\NC \type{kpse_init} \NC boolean \NC true |
| 1902 |
\NC |
| 1903 |
\type {false} totally disables \KPATHSEA\ initialisation, and enables |
| 1904 |
interpretation of the following numeric key--value pairs. (only ever unset |
| 1905 |
this if you implement {\it all\/} file find callbacks!) |
| 1906 |
\NC \NR |
| 1907 |
\NC |
| 1908 |
\type{shell_escape} \NC string \NC \type {'f'} \NC Use \type {'y'} or \type |
| 1909 |
{'t'} or \type {'1'} to enable \type {\write18} unconditionally, \type {'p'} |
| 1910 |
to enable the commands that are listed in \type {shell_escape_commands} |
| 1911 |
\NC \NR |
| 1912 |
\NC |
| 1913 |
shell_escape_commands \NC string \NC \NC Comma-separated list of command |
| 1914 |
names that may be executed by \type {\write18} even if \type {shell_escape} |
| 1915 |
is set to \type {'p'}. Do {\it not\/} use spaces around commas, separate any |
| 1916 |
required command arguments by using a space, and use the \ASCII\ double quote |
| 1917 |
(\type {"}) for any needed argument or path quoting |
| 1918 |
\NC \NR |
| 1919 |
\NC \type{string_vacancies} \NC number \NC 75000 \NC cf.\ web2c docs \NC \NR |
| 1920 |
\NC \type{pool_free} \NC number \NC 5000 \NC cf.\ web2c docs \NC \NR |
| 1921 |
\NC \type{max_strings} \NC number \NC 15000 \NC cf.\ web2c docs \NC \NR |
| 1922 |
\NC \type{strings_free} \NC number \NC 100 \NC cf.\ web2c docs \NC \NR |
| 1923 |
\NC \type{nest_size} \NC number \NC 50 \NC cf.\ web2c docs \NC \NR |
| 1924 |
\NC \type{max_in_open} \NC number \NC 15 \NC cf.\ web2c docs \NC \NR |
| 1925 |
\NC \type{param_size} \NC number \NC 60 \NC cf.\ web2c docs \NC \NR |
| 1926 |
\NC \type{save_size} \NC number \NC 4000 \NC cf.\ web2c docs \NC \NR |
| 1927 |
\NC \type{stack_size} \NC number \NC 300 \NC cf.\ web2c docs \NC \NR |
| 1928 |
\NC \type{dvi_buf_size} \NC number \NC 16384 \NC cf.\ web2c docs \NC \NR |
| 1929 |
\NC \type{error_line} \NC number \NC 79 \NC cf.\ web2c docs \NC \NR |
| 1930 |
\NC \type{half_error_line} \NC number \NC 50 \NC cf.\ web2c docs \NC \NR |
| 1931 |
\NC \type{max_print_line} \NC number \NC 79 \NC cf.\ web2c docs \NC \NR |
| 1932 |
\NC \type{hash_extra} \NC number \NC 0 \NC cf.\ web2c docs \NC \NR |
| 1933 |
\NC \type{pk_dpi} \NC number \NC 72 \NC cf.\ web2c docs \NC \NR |
| 1934 |
\NC \type{trace_file_names} \NC boolean \NC true |
| 1935 |
\NC |
| 1936 |
\type {false} disables \TEX's normal file open|-|close feedback (the |
| 1937 |
assumption is that callbacks will take care of that) |
| 1938 |
\NC \NR |
| 1939 |
\NC \type{trace_extra_newline} \NC boolean \NC false \NC adds an extra newline in \type{\tracingmacros} \NC\NR |
| 1940 |
\NC \type{file_line_error} \NC boolean \NC false |
| 1941 |
\NC |
| 1942 |
do \type {file:line} style error messages |
| 1943 |
\NC \NR |
| 1944 |
\NC \type{halt_on_error} \NC boolean \NC false |
| 1945 |
\NC |
| 1946 |
abort run on the first encountered error |
| 1947 |
\NC \NR |
| 1948 |
\NC \type{formatname} \NC string \NC |
| 1949 |
\NC |
| 1950 |
if no format name was given on the command line, this key will be tested first |
| 1951 |
instead of simply quitting |
| 1952 |
\NC \NR |
| 1953 |
\NC \type{jobname} \NC string \NC |
| 1954 |
\NC |
| 1955 |
if no input file name was given on the command line, this key will be tested |
| 1956 |
first instead of simply giving up |
| 1957 |
\NC \NR |
| 1958 |
\NC \type{level_chr} \NC number \NC |
| 1959 |
\NC |
| 1960 |
character to put in front of traced macros (see next value) |
| 1961 |
\NC \NR |
| 1962 |
\NC \type{level_max} \NC number \NC |
| 1963 |
\NC |
| 1964 |
when larger than zero the input nesting level will be shown when \type |
| 1965 |
{\tracingmacros} is set; levels above this value will be clipped with |
| 1966 |
the level shown up front |
| 1967 |
\NC \NR |
| 1968 |
\NC \type{check_dvi_total_pages} \NC boolean \NC |
| 1969 |
\NC |
| 1970 |
in \DVI\ output mode, if true abort run when the number of pages exceeds 65535. |
| 1971 |
This is the default behaviour. If false, the run goes on as is in \TEX. |
| 1972 |
\NC \NR |
| 1973 |
\NC \type{texlua_img} \NC boolean \NC |
| 1974 |
\NC |
| 1975 |
if true, allows access to the \type {img} library in \TEXLUA\ mode. If |
| 1976 |
false (the default), the \type {img} library is not available in \TEXLUA\ |
| 1977 |
mode (as it was unconditionally for \LUATEX\ versions prior to 1.22.0). |
| 1978 |
Note that this setting is {\bf experimental} and subject to be removed at |
| 1979 |
any time, without notice. |
| 1980 |
\NC \NR |
| 1981 |
\LL |
| 1982 |
\stoptabulate |
| 1983 |
|
| 1984 |
Note: the numeric values that match web2c parameters are only used if \type |
| 1985 |
{kpse_init} is explicitly set to \type {false}. In all other cases, the normal |
| 1986 |
values from \type {texmf.cnf} are used. |
| 1987 |
|
| 1988 |
You can kick in your own nesting level visualizer, for instance: |
| 1989 |
|
| 1990 |
\starttyping |
| 1991 |
callback.register("input_level_string",function(n) |
| 1992 |
if tex.tracingmacros > 0 and tex.count.tracingstacklevels > 0 then |
| 1993 |
if tex.tracingmacros > 1 then |
| 1994 |
return "! " .. string.rep(">",n) .. " " |
| 1995 |
end |
| 1996 |
end |
| 1997 |
return "" |
| 1998 |
end) |
| 1999 |
\stoptyping |
| 2000 |
|
| 2001 |
Or, in sync with other engines (not checked): |
| 2002 |
|
| 2003 |
\newcount\tracingstacklevels |
| 2004 |
|
| 2005 |
\starttyping |
| 2006 |
\directlua { |
| 2007 |
callback.register("input_level_string", function(n) |
| 2008 |
if tex.tracingmacros > 0 then |
| 2009 |
local l = tex.count.tracingstacklevels |
| 2010 |
if l > 0 then |
| 2011 |
return string.rep("~",l) .. string.rep(".",n-l) |
| 2012 |
end |
| 2013 |
end |
| 2014 |
return "" |
| 2015 |
end) |
| 2016 |
} |
| 2017 |
\stoptyping |
| 2018 |
|
| 2019 |
\stopsection |
| 2020 |
|
| 2021 |
\startsection[title={The \type {texio} library}][library=texio] |
| 2022 |
|
| 2023 |
\topicindex{libraries+\type{texio}} |
| 2024 |
\topicindex{\IO} |
| 2025 |
|
| 2026 |
This library takes care of the low|-|level I/O interface: writing to the log file |
| 2027 |
and|/|or console. |
| 2028 |
|
| 2029 |
\startsubsection[title={\type {write}}] |
| 2030 |
|
| 2031 |
\libindex{write} |
| 2032 |
|
| 2033 |
\startfunctioncall |
| 2034 |
texio.write(<string> target, <string> s, ...) |
| 2035 |
texio.write(<string> s, ...) |
| 2036 |
\stopfunctioncall |
| 2037 |
|
| 2038 |
Without the \type {target} argument, writes all given strings to the same |
| 2039 |
location(s) \TEX\ writes messages to at this moment. If \prm {batchmode} is in |
| 2040 |
effect, it writes only to the log, otherwise it writes to the log and the |
| 2041 |
terminal. The optional \type {target} can be one of three possibilities: \type |
| 2042 |
{term}, \type {log} or \type {term and log}. |
| 2043 |
|
| 2044 |
Note: If several strings are given, and if the first of these strings is or might |
| 2045 |
be one of the targets above, the \type {target} must be specified explicitly to |
| 2046 |
prevent \LUA\ from interpreting the first string as the target. |
| 2047 |
|
| 2048 |
\stopsubsection |
| 2049 |
|
| 2050 |
\startsubsection[title={\type {write_nl}}] |
| 2051 |
|
| 2052 |
\libindex{write_nl} |
| 2053 |
|
| 2054 |
\startfunctioncall |
| 2055 |
texio.write_nl(<string> target, <string> s, ...) |
| 2056 |
texio.write_nl(<string> s, ...) |
| 2057 |
\stopfunctioncall |
| 2058 |
|
| 2059 |
This function behaves like \type {texio.write}, but make sure that the given |
| 2060 |
strings will appear at the beginning of a new line. You can pass a single empty |
| 2061 |
string if you only want to move to the next line. |
| 2062 |
|
| 2063 |
\stopsubsection |
| 2064 |
|
| 2065 |
\startsubsection[title={\type {setescape}}] |
| 2066 |
|
| 2067 |
\libindex{setescape} |
| 2068 |
|
| 2069 |
You can disable \type {^^} escaping of control characters by passing a value of |
| 2070 |
zero. |
| 2071 |
|
| 2072 |
\stopsubsection |
| 2073 |
|
| 2074 |
\startsubsection[title={\type {closeinput}}] |
| 2075 |
|
| 2076 |
\libindex{closeinput} |
| 2077 |
|
| 2078 |
This function that should be used with care. It acts as \prm {endinput} but at |
| 2079 |
the \LUA\ end. You can use it to (sort of) force a jump back to \TEX. Normally a |
| 2080 |
\LUA\ will just collect prints and at the end bump an input level and flush these |
| 2081 |
prints. This function can help you stay at the current level but you need to know |
| 2082 |
what you're doing (or more precise: what \TEX\ is doing with input). |
| 2083 |
|
| 2084 |
\stopsubsection |
| 2085 |
|
| 2086 |
\stopsection |
| 2087 |
|
| 2088 |
\startsection[title={The \type {token} library}][library=token] |
| 2089 |
|
| 2090 |
\startsubsection[title={The scanner}] |
| 2091 |
|
| 2092 |
\topicindex{libraries+\type{token}} |
| 2093 |
\topicindex{tokens} |
| 2094 |
|
| 2095 |
\libindex{scan_keyword} |
| 2096 |
\libindex{scan_keyword_cs} |
| 2097 |
\libindex{scan_int} |
| 2098 |
\libindex{scan_real} |
| 2099 |
\libindex{scan_float} |
| 2100 |
\libindex{scan_dimen} |
| 2101 |
\libindex{scan_glue} |
| 2102 |
\libindex{scan_toks} |
| 2103 |
\libindex{scan_code} |
| 2104 |
\libindex{scan_string} |
| 2105 |
\libindex{scan_argument} |
| 2106 |
\libindex{scan_word} |
| 2107 |
\libindex{scan_csname} |
| 2108 |
\libindex{scan_list} |
| 2109 |
|
| 2110 |
The token library provides means to intercept the input and deal with it at the |
| 2111 |
\LUA\ level. The library provides a basic scanner infrastructure that can be used |
| 2112 |
to write macros that accept a wide range of arguments. This interface is on |
| 2113 |
purpose kept general and as performance is quite ok. One can build additional |
| 2114 |
parsers without too much overhead. It's up to macro package writers to see how |
| 2115 |
they can benefit from this as the main principle behind \LUATEX\ is to provide a |
| 2116 |
minimal set of tools and no solutions. The scanner functions are probably the |
| 2117 |
most intriguing. |
| 2118 |
|
| 2119 |
\starttabulate[|l|l|p|] |
| 2120 |
\DB function \BC argument \BC result \NC \NR |
| 2121 |
\TB |
| 2122 |
\NC \type{scan_keyword} \NC string \NC returns true if the given keyword is gobbled; as with |
| 2123 |
the regular \TEX\ keyword scanner this is case insensitive |
| 2124 |
(and \ASCII\ based) \NC \NR |
| 2125 |
\NC \type{scan_keyword_cs} \NC string \NC returns true if the given keyword is gobbled; this variant |
| 2126 |
is case sensitive and also suitable for \UTF8 \NC \NR |
| 2127 |
\NC \type{scan_int} \NC \NC returns an integer \NC \NR |
| 2128 |
\NC \type{scan_real} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1} with optional collapsed signs \NC \NR |
| 2129 |
\NC \type{scan_float} \NC \NC returns a number from e.g.\ \type {1}, \type {1.1}, \type {.1}, \type {1.1E10}, , \type {.1e-10} with optional collapsed signs \NC \NR |
| 2130 |
\NC \type{scan_dimen} \NC infinity, mu-units \NC returns a number representing a dimension and or two numbers being the filler and order \NC \NR |
| 2131 |
\NC \type{scan_glue} \NC mu-units \NC returns a glue spec node \NC \NR |
| 2132 |
\NC \type{scan_toks} \NC definer, expand \NC returns a table of tokens tokens \NC \NR |
| 2133 |
\NC \type{scan_code} \NC bitset \NC returns a character if its category is in the given bitset (representing catcodes) \NC \NR |
| 2134 |
\NC \type{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 |
| 2135 |
\NC \type{scan_argument} \NC boolean \NC this one is simular to \type {scanstring} but also accepts a \type {\cs} \NC \NR |
| 2136 |
\NC \type{scan_word} \NC \NC returns a sequence of characters with catcode 11 or 12 as string \NC \NR |
| 2137 |
\NC \type{scan_csname} \NC \NC returns \type {foo} after scanning \type {\foo} \NC \NR |
| 2138 |
\NC \type{scan_list} \NC \NC picks up a box specification and returns a \type {[h|v]list} node \NC \NR |
| 2139 |
\LL |
| 2140 |
\stoptabulate |
| 2141 |
|
| 2142 |
The scanners can be considered stable apart from the one scanning for a token. |
| 2143 |
The \type {scan_code} function takes an optional number, the \type {keyword} |
| 2144 |
function a normal \LUA\ string. The \type {infinity} boolean signals that we also |
| 2145 |
permit \type {fill} as dimension and the \type {mu-units} flags the scanner that |
| 2146 |
we expect math units. When scanning tokens we can indicate that we are defining a |
| 2147 |
macro, in which case the result will also provide information about what |
| 2148 |
arguments are expected and in the result this is separated from the meaning by a |
| 2149 |
separator token. The \type {expand} flag determines if the list will be expanded. |
| 2150 |
|
| 2151 |
The \type {scan_argument} function expands the given argument. When a braced |
| 2152 |
argument is scanned, expansion can be prohibited by passing \type {false} |
| 2153 |
(default is \type {true}). In case of a control sequence passing \type {false} |
| 2154 |
will result in a one|-|level expansion (the meaning of the macro). |
| 2155 |
|
| 2156 |
The string scanner scans for something between curly braces and expands on the |
| 2157 |
way, or when it sees a control sequence it will return its meaning. Otherwise it |
| 2158 |
will scan characters with catcode \type {letter} or \type {other}. So, given the |
| 2159 |
following definition: |
| 2160 |
|
| 2161 |
\startbuffer |
| 2162 |
\def\bar{bar} |
| 2163 |
\def\foo{foo-\bar} |
| 2164 |
\stopbuffer |
| 2165 |
|
| 2166 |
\typebuffer \getbuffer |
| 2167 |
|
| 2168 |
we get: |
| 2169 |
|
| 2170 |
\starttabulate[|l|Tl|l|] |
| 2171 |
\DB name \BC result \NC \NR |
| 2172 |
\TB |
| 2173 |
\NC \type {\directlua{token.scan_string()}{foo}} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} {foo} \NC full expansion \NC \NR |
| 2174 |
\NC \type {\directlua{token.scan_string()}foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")} foo \NC letters and others \NC \NR |
| 2175 |
\NC \type {\directlua{token.scan_string()}\foo} \NC \directlua{context("{\\red\\type {"..token.scan_string().."}}")}\foo \NC meaning \NC \NR |
| 2176 |
\LL |
| 2177 |
\stoptabulate |
| 2178 |
|
| 2179 |
The \type {\foo} case only gives the meaning, but one can pass an already |
| 2180 |
expanded definition (\prm {edef}'d). In the case of the braced variant one can of |
| 2181 |
course use the \prm {detokenize} and \prm {unexpanded} primitives since there we |
| 2182 |
do expand. |
| 2183 |
|
| 2184 |
The \type {scan_word} scanner can be used to implement for instance a number scanner: |
| 2185 |
|
| 2186 |
\starttyping |
| 2187 |
function token.scan_number(base) |
| 2188 |
return tonumber(token.scan_word(),base) |
| 2189 |
end |
| 2190 |
\stoptyping |
| 2191 |
|
| 2192 |
This scanner accepts any valid \LUA\ number so it is a way to pick up floats |
| 2193 |
in the input. |
| 2194 |
|
| 2195 |
You can use the \LUA\ interface as follows: |
| 2196 |
|
| 2197 |
\starttyping |
| 2198 |
\directlua { |
| 2199 |
function mymacro(n) |
| 2200 |
... |
| 2201 |
end |
| 2202 |
} |
| 2203 |
|
| 2204 |
\def\mymacro#1{% |
| 2205 |
\directlua { |
| 2206 |
mymacro(\number\dimexpr#1) |
| 2207 |
}% |
| 2208 |
} |
| 2209 |
|
| 2210 |
\mymacro{12pt} |
| 2211 |
\mymacro{\dimen0} |
| 2212 |
\stoptyping |
| 2213 |
|
| 2214 |
You can also do this: |
| 2215 |
|
| 2216 |
\starttyping |
| 2217 |
\directlua { |
| 2218 |
function mymacro() |
| 2219 |
local d = token.scan_dimen() |
| 2220 |
... |
| 2221 |
end |
| 2222 |
} |
| 2223 |
|
| 2224 |
\def\mymacro{% |
| 2225 |
\directlua { |
| 2226 |
mymacro() |
| 2227 |
}% |
| 2228 |
} |
| 2229 |
|
| 2230 |
\mymacro 12pt |
| 2231 |
\mymacro \dimen0 |
| 2232 |
\stoptyping |
| 2233 |
|
| 2234 |
It is quite clear from looking at the code what the first method needs as |
| 2235 |
argument(s). For the second method you need to look at the \LUA\ code to see what |
| 2236 |
gets picked up. Instead of passing from \TEX\ to \LUA\ we let \LUA\ fetch from |
| 2237 |
the input stream. |
| 2238 |
|
| 2239 |
In the first case the input is tokenized and then turned into a string, then it |
| 2240 |
is passed to \LUA\ where it gets interpreted. In the second case only a function |
| 2241 |
call gets interpreted but then the input is picked up by explicitly calling the |
| 2242 |
scanner functions. These return proper \LUA\ variables so no further conversion |
| 2243 |
has to be done. This is more efficient but in practice (given what \TEX\ has to |
| 2244 |
do) this effect should not be overestimated. For numbers and dimensions it saves |
| 2245 |
a bit but for passing strings conversion to and from tokens has to be done anyway |
| 2246 |
(although we can probably speed up the process in later versions if needed). |
| 2247 |
|
| 2248 |
\stopsubsection |
| 2249 |
|
| 2250 |
\startsubsection[title= {Picking up one token}] |
| 2251 |
|
| 2252 |
\libindex {get_next} |
| 2253 |
\libindex {scan_token} |
| 2254 |
\libindex {expand} |
| 2255 |
|
| 2256 |
The scanners look for a sequence. When you want to pick up one token from the |
| 2257 |
input you use \type {get_next}. This creates a token with the (low level) |
| 2258 |
properties as discussed next. This token is just the next one. If you want to |
| 2259 |
enforce expansion first you can use \type {scan_token}. Internally tokens are |
| 2260 |
characterized by a number that packs a lot of information. In order to access |
| 2261 |
the bits of information a token is wrapped in a userdata object. |
| 2262 |
|
| 2263 |
The \type {expand} function will trigger expansion of the next token in the |
| 2264 |
input. This can be quite unpredictable but when you call it you probably know |
| 2265 |
enough about \TEX\ not to be too worried about that. It basically is a call to |
| 2266 |
the internal expand related function. |
| 2267 |
|
| 2268 |
\stopsubsection |
| 2269 |
|
| 2270 |
\startsubsection[title={Creating tokens}] |
| 2271 |
|
| 2272 |
\libindex{create} |
| 2273 |
\libindex{new} |
| 2274 |
|
| 2275 |
\libindex{is_defined} |
| 2276 |
\libindex{is_token} |
| 2277 |
\libindex{biggest_char} |
| 2278 |
|
| 2279 |
\libindex{commands} |
| 2280 |
\libindex{command_id} |
| 2281 |
|
| 2282 |
\libindex{get_command} |
| 2283 |
\libindex{get_cmdname} |
| 2284 |
\libindex{get_csname} |
| 2285 |
\libindex{get_id} |
| 2286 |
\libindex{get_active} |
| 2287 |
\libindex{get_expandable} |
| 2288 |
\libindex{get_protected} |
| 2289 |
\libindex{get_mode} |
| 2290 |
\libindex{get_index} |
| 2291 |
\libindex{get_tok} |
| 2292 |
|
| 2293 |
\libindex{get_next} |
| 2294 |
|
| 2295 |
The creator function can be used as follows: |
| 2296 |
|
| 2297 |
\starttyping |
| 2298 |
local t = token.create("relax") |
| 2299 |
\stoptyping |
| 2300 |
|
| 2301 |
This gives back a token object that has the properties of the \prm {relax} |
| 2302 |
primitive. The possible properties of tokens are: |
| 2303 |
|
| 2304 |
\starttabulate[|l|p|] |
| 2305 |
\DB name \BC explanation \NC \NR |
| 2306 |
\TB |
| 2307 |
\NC \type {command} \NC a number representing the internal command number \NC \NR |
| 2308 |
\NC \type {cmdname} \NC the type of the command (for instance the catcode in case of a |
| 2309 |
character or the classifier that determines the internal |
| 2310 |
treatment \NC \NR |
| 2311 |
\NC \type {csname} \NC the associated control sequence (if applicable) \NC \NR |
| 2312 |
\NC \type {id} \NC the unique id of the token \NC \NR |
| 2313 |
\NC \type {tok} \NC the full token number as stored in \TEX \NC \NR |
| 2314 |
\NC \type {active} \NC a boolean indicating the active state of the token \NC \NR |
| 2315 |
\NC \type {expandable} \NC a boolean indicating if the token (macro) is expandable \NC \NR |
| 2316 |
\NC \type {protected} \NC a boolean indicating if the token (macro) is protected \NC \NR |
| 2317 |
\NC \type {mode} \NC a number either representing a character or another entity \NC \NR |
| 2318 |
\NC \type {index} \NC a number running from 0x0000 upto 0xFFFF indicating a \TEX\ register index \NC \NR |
| 2319 |
\LL |
| 2320 |
\stoptabulate |
| 2321 |
|
| 2322 |
Alternatively you can use a getter \type {get_<fieldname>} to access a property |
| 2323 |
of a token. |
| 2324 |
|
| 2325 |
The numbers that represent a catcode are the same as in \TEX\ itself, so using |
| 2326 |
this information assumes that you know a bit about \TEX's internals. The other |
| 2327 |
numbers and names are used consistently but are not frozen. So, when you use them |
| 2328 |
for comparing you can best query a known primitive or character first to see the |
| 2329 |
values. |
| 2330 |
|
| 2331 |
You can ask for a list of commands: |
| 2332 |
|
| 2333 |
\starttyping |
| 2334 |
local t = token.commands() |
| 2335 |
\stoptyping |
| 2336 |
|
| 2337 |
The id of a token class can be queried as follows: |
| 2338 |
|
| 2339 |
\starttyping |
| 2340 |
local id = token.command_id("math_shift") |
| 2341 |
\stoptyping |
| 2342 |
|
| 2343 |
If you really know what you're doing you can create character tokens by not |
| 2344 |
passing a string but a number: |
| 2345 |
|
| 2346 |
\starttyping |
| 2347 |
local letter_x = token.create(string.byte("x")) |
| 2348 |
local other_x = token.create(string.byte("x"),12) |
| 2349 |
\stoptyping |
| 2350 |
|
| 2351 |
Passing weird numbers can give side effects so don't expect too much help with |
| 2352 |
that. As said, you need to know what you're doing. The best way to explore the |
| 2353 |
way these internals work is to just look at how primitives or macros or \prm |
| 2354 |
{chardef}'d commands are tokenized. Just create a known one and inspect its |
| 2355 |
fields. A variant that ignores the current catcode table is: |
| 2356 |
|
| 2357 |
\starttyping |
| 2358 |
local whatever = token.new(123,12) |
| 2359 |
\stoptyping |
| 2360 |
|
| 2361 |
You can test if a control sequence is defined with \type {is_defined}, which |
| 2362 |
accepts a string and returns a boolean: |
| 2363 |
|
| 2364 |
\starttyping |
| 2365 |
local okay = token.is_defined("foo") |
| 2366 |
\stoptyping |
| 2367 |
|
| 2368 |
When a second argument to \type {is_defined} is \type {true} the check is for an |
| 2369 |
undefined control sequence (only), otherwise any undefined command gives true. |
| 2370 |
|
| 2371 |
The largest character possible is returned by \type {biggest_char}, just in case you |
| 2372 |
need to know that boundary condition. |
| 2373 |
|
| 2374 |
\stopsubsection |
| 2375 |
|
| 2376 |
\startsubsection[title={Macros}] |
| 2377 |
|
| 2378 |
\topicindex {macros} |
| 2379 |
|
| 2380 |
\libindex{set_macro} |
| 2381 |
\libindex{get_macro} |
| 2382 |
\libindex{get_meaning} |
| 2383 |
\libindex{set_char} |
| 2384 |
\libindex{set_lua} |
| 2385 |
\libindex{get_functions_table} |
| 2386 |
|
| 2387 |
The \type {set_macro} function can get upto 4 arguments: |
| 2388 |
|
| 2389 |
\starttyping |
| 2390 |
set_macro("csname","content") |
| 2391 |
set_macro("csname","content","global") |
| 2392 |
set_macro("csname") |
| 2393 |
\stoptyping |
| 2394 |
|
| 2395 |
You can pass a catcodetable identifier as first argument: |
| 2396 |
|
| 2397 |
\starttyping |
| 2398 |
set_macro(catcodetable,"csname","content") |
| 2399 |
set_macro(catcodetable,"csname","content","global") |
| 2400 |
set_macro(catcodetable,"csname") |
| 2401 |
\stoptyping |
| 2402 |
|
| 2403 |
The results are like: |
| 2404 |
|
| 2405 |
\starttyping |
| 2406 |
\def\csname{content} |
| 2407 |
\gdef\csname{content} |
| 2408 |
\def\csname{} |
| 2409 |
\stoptyping |
| 2410 |
|
| 2411 |
The \type {get_macro} function can be used to get the content of a macro while |
| 2412 |
the \type {get_meaning} function gives the meaning including the argument |
| 2413 |
specification (as usual in \TEX\ separated by \type {->}). |
| 2414 |
|
| 2415 |
The \type {set_char} function can be used to do a \prm {chardef} at the |
| 2416 |
\LUA\ end, where invalid assignments are silently ignored: |
| 2417 |
|
| 2418 |
\starttyping |
| 2419 |
set_char("csname",number) |
| 2420 |
set_char("csname",number,"global") |
| 2421 |
\stoptyping |
| 2422 |
|
| 2423 |
A special one is the following: |
| 2424 |
|
| 2425 |
\starttyping |
| 2426 |
set_lua("mycode",id) |
| 2427 |
set_lua("mycode",id,"global","protected") |
| 2428 |
\stoptyping |
| 2429 |
|
| 2430 |
This creates a token that refers to a \LUA\ function with an entry in the table |
| 2431 |
that you can access with \type {lua.get_functions_table}. It is the companion |
| 2432 |
to \lpr {luadef}. |
| 2433 |
|
| 2434 |
\stopsubsection |
| 2435 |
|
| 2436 |
\startsubsection[title={Pushing back}] |
| 2437 |
|
| 2438 |
\libindex{get_next} |
| 2439 |
\libindex{put_next} |
| 2440 |
\libindex{unchecked_put_next} |
| 2441 |
|
| 2442 |
There is a (for now) experimental putter: |
| 2443 |
|
| 2444 |
\starttyping |
| 2445 |
local t1 = token.get_next() |
| 2446 |
local t2 = token.get_next() |
| 2447 |
local t3 = token.get_next() |
| 2448 |
local t4 = token.get_next() |
| 2449 |
-- watch out, we flush in sequence |
| 2450 |
token.put_next { t1, t2 } |
| 2451 |
-- but this one gets pushed in front |
| 2452 |
token.put_next ( t3, t4 ) |
| 2453 |
\stoptyping |
| 2454 |
|
| 2455 |
When we scan \type {wxyz!} we get \type {yzwx!} back. The argument is either a table |
| 2456 |
with tokens or a list of tokens. The new function \type {token.unchecked_put_next} |
| 2457 |
has been added per request of the \LATEX\ team. It skips this error checking and |
| 2458 |
follows a different code path. It assumes that a valid token user datum is |
| 2459 |
passed and can crash the engine otherwise. |
| 2460 |
|
| 2461 |
The \type {token.expand} function will trigger |
| 2462 |
expansion but what happens really depends on what you're doing where. |
| 2463 |
|
| 2464 |
\stopsubsection |
| 2465 |
|
| 2466 |
\startsubsection[title={Nota bene}] |
| 2467 |
|
| 2468 |
When scanning for the next token you need to keep in mind that we're not scanning |
| 2469 |
like \TEX\ does: expanding, changing modes and doing things as it goes. When we |
| 2470 |
scan with \LUA\ we just pick up tokens. Say that we have: |
| 2471 |
|
| 2472 |
\starttyping |
| 2473 |
\bar |
| 2474 |
\stoptyping |
| 2475 |
|
| 2476 |
but \type {\bar} is undefined. Normally \TEX\ will then issue an error message. |
| 2477 |
However, when we have: |
| 2478 |
|
| 2479 |
\starttyping |
| 2480 |
\def\foo{\bar} |
| 2481 |
\stoptyping |
| 2482 |
|
| 2483 |
We get no error, unless we expand \type {\foo} while \type {\bar} is still |
| 2484 |
undefined. What happens is that as soon as \TEX\ sees an undefined macro it will |
| 2485 |
create a hash entry and when later it gets defined that entry will be reused. So, |
| 2486 |
\type {\bar} really exists but can be in an undefined state. |
| 2487 |
|
| 2488 |
\startbuffer[demo] |
| 2489 |
bar : \directlua{tex.print(token.scan_csname())}\bar |
| 2490 |
foo : \directlua{tex.print(token.scan_csname())}\foo |
| 2491 |
myfirstbar : \directlua{tex.print(token.scan_csname())}\myfirstbar |
| 2492 |
\stopbuffer |
| 2493 |
|
| 2494 |
\startlines |
| 2495 |
\getbuffer[demo] |
| 2496 |
\stoplines |
| 2497 |
|
| 2498 |
This was entered as: |
| 2499 |
|
| 2500 |
\typebuffer[demo] |
| 2501 |
|
| 2502 |
The reason that you see \type {bar} reported and not \type {myfirstbar} is that |
| 2503 |
\type {\bar} was already used in a previous paragraph. |
| 2504 |
|
| 2505 |
If we now say: |
| 2506 |
|
| 2507 |
\startbuffer |
| 2508 |
\def\foo{} |
| 2509 |
\stopbuffer |
| 2510 |
|
| 2511 |
\typebuffer \getbuffer |
| 2512 |
|
| 2513 |
we get: |
| 2514 |
|
| 2515 |
\startlines |
| 2516 |
\getbuffer[demo] |
| 2517 |
\stoplines |
| 2518 |
|
| 2519 |
And if we say |
| 2520 |
|
| 2521 |
\startbuffer |
| 2522 |
\def\foo{\bar} |
| 2523 |
\stopbuffer |
| 2524 |
|
| 2525 |
\typebuffer \getbuffer |
| 2526 |
|
| 2527 |
we get: |
| 2528 |
|
| 2529 |
\startlines |
| 2530 |
\getbuffer[demo] |
| 2531 |
\stoplines |
| 2532 |
|
| 2533 |
When scanning from \LUA\ we are not in a mode that defines (undefined) macros at |
| 2534 |
all. There we just get the real primitive undefined macro token. |
| 2535 |
|
| 2536 |
\startbuffer |
| 2537 |
\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\myfirstbar |
| 2538 |
\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mysecondbar |
| 2539 |
\directlua{local t = token.get_next() tex.print(t.id.." "..t.tok)}\mythirdbar |
| 2540 |
\stopbuffer |
| 2541 |
|
| 2542 |
\startlines |
| 2543 |
\getbuffer |
| 2544 |
\stoplines |
| 2545 |
|
| 2546 |
This was generated with: |
| 2547 |
|
| 2548 |
\typebuffer |
| 2549 |
|
| 2550 |
So, we do get a unique token because after all we need some kind of \LUA\ object |
| 2551 |
that can be used and garbage collected, but it is basically the same one, |
| 2552 |
representing an undefined control sequence. |
| 2553 |
|
| 2554 |
\stopsubsection |
| 2555 |
|
| 2556 |
\stopsection |
| 2557 |
|
| 2558 |
\startsection[title={The \type {kpse} library}][library=kpse] |
| 2559 |
|
| 2560 |
\topicindex{libraries+\type{kpse}} |
| 2561 |
|
| 2562 |
This library provides two separate, but nearly identical interfaces to the |
| 2563 |
\KPATHSEA\ file search functionality: there is a \quote {normal} procedural |
| 2564 |
interface that shares its kpathsea instance with \LUATEX\ itself, and an object |
| 2565 |
oriented interface that is completely on its own. |
| 2566 |
|
| 2567 |
\startsubsection[title={\type {set_program_name} and \type {new}}] |
| 2568 |
|
| 2569 |
\libindex{set_program_name} |
| 2570 |
\libindex{default_texmfcnf} |
| 2571 |
\libindex{new} |
| 2572 |
|
| 2573 |
The way the library looks up variables is driven by the \type {texmf.cmf} file |
| 2574 |
where the currently set program name acts as filter. You can check what file is |
| 2575 |
used by with \type {default_texmfcnf}. |
| 2576 |
|
| 2577 |
Before the search library can be used at all, its database has to be initialized. |
| 2578 |
There are three possibilities, two of which belong to the procedural interface. |
| 2579 |
|
| 2580 |
First, when \LUATEX\ is used to typeset documents, this initialization happens |
| 2581 |
automatically and the \KPATHSEA\ executable and program names are set to \type |
| 2582 |
{luatex} (that is, unless explicitly prohibited by the user's startup script. |
| 2583 |
See~\in {section} [init] for more details). |
| 2584 |
|
| 2585 |
Second, in \TEXLUA\ mode, the initialization has to be done explicitly via the |
| 2586 |
\type {kpse.set_program_name} function, which sets the \KPATHSEA\ executable |
| 2587 |
(and optionally program) name. |
| 2588 |
|
| 2589 |
\startfunctioncall |
| 2590 |
kpse.set_program_name(<string> name) |
| 2591 |
kpse.set_program_name(<string> name, <string> progname) |
| 2592 |
\stopfunctioncall |
| 2593 |
|
| 2594 |
The second argument controls the use of the \quote {dotted} values in the \type |
| 2595 |
{texmf.cnf} configuration file, and defaults to the first argument. |
| 2596 |
|
| 2597 |
Third, if you prefer the object oriented interface, you have to call a different |
| 2598 |
function. It has the same arguments, but it returns a userdata variable. |
| 2599 |
|
| 2600 |
\startfunctioncall |
| 2601 |
local kpathsea = kpse.new(<string> name) |
| 2602 |
local kpathsea = kpse.new(<string> name, <string> progname) |
| 2603 |
\stopfunctioncall |
| 2604 |
|
| 2605 |
Apart from these two functions, the calling conventions of the interfaces are |
| 2606 |
identical. Depending on the chosen interface, you either call \type |
| 2607 |
{kpse.find_file} or \type {kpathsea:find_file}, with identical arguments and |
| 2608 |
return values. |
| 2609 |
|
| 2610 |
\stopsubsection |
| 2611 |
|
| 2612 |
\startsubsection[title={\type {record_input_file} and \type {record_output_file}}] |
| 2613 |
|
| 2614 |
\topicindex {files+recording} |
| 2615 |
|
| 2616 |
\libindex{record_input_file} |
| 2617 |
\libindex{record_output_file} |
| 2618 |
|
| 2619 |
These two function can be used to register used files. Because callbacks can load |
| 2620 |
files themselves you might need these helpers (if you use recording at all). |
| 2621 |
|
| 2622 |
\startfunctioncall |
| 2623 |
kpse.record_input_file(<string> name) |
| 2624 |
kpse.record_output_file(<string> name) |
| 2625 |
\stopfunctioncall |
| 2626 |
|
| 2627 |
\stopsubsection |
| 2628 |
|
| 2629 |
\startsubsection[title={\type {find_file}}] |
| 2630 |
|
| 2631 |
\topicindex {files+finding} |
| 2632 |
|
| 2633 |
\libindex {find_file} |
| 2634 |
|
| 2635 |
The most often used function in the library is \type {find_file}: |
| 2636 |
|
| 2637 |
\startfunctioncall |
| 2638 |
<string> f = kpse.find_file(<string> filename) |
| 2639 |
<string> f = kpse.find_file(<string> filename, <string> ftype) |
| 2640 |
<string> f = kpse.find_file(<string> filename, <boolean> mustexist) |
| 2641 |
<string> f = kpse.find_file(<string> filename, <string> ftype, <boolean> mustexist) |
| 2642 |
<string> f = kpse.find_file(<string> filename, <string> ftype, <number> dpi) |
| 2643 |
\stopfunctioncall |
| 2644 |
|
| 2645 |
Arguments: |
| 2646 |
|
| 2647 |
\startitemize[intro] |
| 2648 |
|
| 2649 |
\sym{filename} |
| 2650 |
|
| 2651 |
the name of the file you want to find, with or without extension. |
| 2652 |
|
| 2653 |
\sym{ftype} |
| 2654 |
|
| 2655 |
maps to the \type {-format} argument of \KPSEWHICH. The supported \type {ftype} |
| 2656 |
values are the same as the ones supported by the standalone \type {kpsewhich} |
| 2657 |
program: \startluacode |
| 2658 |
local list = { |
| 2659 |
"afm", |
| 2660 |
"base", |
| 2661 |
"bib", |
| 2662 |
"bitmap font", |
| 2663 |
"bst", |
| 2664 |
"cid maps", |
| 2665 |
"clua", |
| 2666 |
"cmap files", |
| 2667 |
"cnf", |
| 2668 |
"cweb", |
| 2669 |
"dvips config", |
| 2670 |
"enc files", |
| 2671 |
"fmt", |
| 2672 |
"font feature files", |
| 2673 |
"gf", |
| 2674 |
"graphic|/|figure", |
| 2675 |
"ist", |
| 2676 |
"lig files", |
| 2677 |
"ls-R", |
| 2678 |
"lua", |
| 2679 |
"map", |
| 2680 |
"mem", |
| 2681 |
"MetaPost support", |
| 2682 |
"mf", |
| 2683 |
"mfpool", |
| 2684 |
"mft", |
| 2685 |
"misc fonts", |
| 2686 |
"mlbib", |
| 2687 |
"mlbst", |
| 2688 |
"mp", |
| 2689 |
"mppool", |
| 2690 |
"ocp", |
| 2691 |
"ofm", |
| 2692 |
"opentype fonts", |
| 2693 |
"opl", |
| 2694 |
"other binary files", |
| 2695 |
"other text files", |
| 2696 |
"otp", |
| 2697 |
"ovf", |
| 2698 |
"ovp", |
| 2699 |
"pdftex config", |
| 2700 |
"pk", |
| 2701 |
"PostScript header", |
| 2702 |
"subfont definition files", |
| 2703 |
"tex", |
| 2704 |
"TeX system documentation", |
| 2705 |
"TeX system sources", |
| 2706 |
"texmfscripts", |
| 2707 |
"texpool", |
| 2708 |
"tfm", |
| 2709 |
"Troff fonts", |
| 2710 |
"truetype fonts", |
| 2711 |
"type1 fonts", |
| 2712 |
"type42 fonts", |
| 2713 |
"vf", |
| 2714 |
"web", |
| 2715 |
"web2c files", |
| 2716 |
} |
| 2717 |
table.sort(list) |
| 2718 |
context("{\\tttf \letterpercent, t}",list) |
| 2719 |
\stopluacode |
| 2720 |
|
| 2721 |
The default type is \type {tex}. Note: this is different from \KPSEWHICH, which |
| 2722 |
tries to deduce the file type itself from looking at the supplied extension. |
| 2723 |
|
| 2724 |
\sym{mustexist} |
| 2725 |
|
| 2726 |
is similar to \KPSEWHICH's \type {-must-exist}, and the default is \type {false}. |
| 2727 |
If you specify \type {true} (or a non|-|zero integer), then the \KPSE\ library |
| 2728 |
will search the disk as well as the \type {ls-R} databases. |
| 2729 |
|
| 2730 |
\sym{dpi} |
| 2731 |
|
| 2732 |
This is used for the size argument of the formats \type {pk}, \type {gf}, and |
| 2733 |
\type {bitmap font}. \stopitemize |
| 2734 |
|
| 2735 |
If \type {--output-directory} is specified and the value is a relative pathname, |
| 2736 |
the file is searched first here and if it fails it will be searched in the standard tree. |
| 2737 |
|
| 2738 |
\stopsubsection |
| 2739 |
|
| 2740 |
\startsubsection[title={\type {lookup}}] |
| 2741 |
|
| 2742 |
\libindex{lookup} |
| 2743 |
|
| 2744 |
A more powerful (but slower) generic method for finding files is also available. |
| 2745 |
It returns a string for each found file. |
| 2746 |
|
| 2747 |
\startfunctioncall |
| 2748 |
<string> f, ... = kpse.lookup(<string> filename, <table> options) |
| 2749 |
\stopfunctioncall |
| 2750 |
|
| 2751 |
The options match commandline arguments from \type {kpsewhich}: |
| 2752 |
|
| 2753 |
\starttabulate[|l|l|p|] |
| 2754 |
\DB key \BC type \BC explanation \NC \NR |
| 2755 |
\TB |
| 2756 |
\NC \type{debug} \NC number \NC set debugging flags for this lookup\NC \NR |
| 2757 |
\NC \type{format} \NC string \NC use specific file type (see list above)\NC \NR |
| 2758 |
\NC \type{dpi} \NC number \NC use this resolution for this lookup; default 600\NC \NR |
| 2759 |
\NC \type{path} \NC string \NC search in the given path\NC \NR |
| 2760 |
\NC \type{all} \NC boolean \NC output all matches, not just the first\NC \NR |
| 2761 |
\NC \type{mustexist} \NC boolean \NC search the disk as well as ls-R if necessary\NC \NR |
| 2762 |
\NC \type{mktexpk} \NC boolean \NC disable/enable mktexpk generation for this lookup\NC \NR |
| 2763 |
\NC \type{mktextex} \NC boolean \NC disable/enable mktextex generation for this lookup\NC \NR |
| 2764 |
\NC \type{mktexmf} \NC boolean \NC disable/enable mktexmf generation for this lookup\NC \NR |
| 2765 |
\NC \type{mktextfm} \NC boolean \NC disable/enable mktextfm generation for this lookup\NC \NR |
| 2766 |
\NC \type{subdir} \NC string |
| 2767 |
or table \NC only output matches whose directory part |
| 2768 |
ends with the given string(s) \NC \NR |
| 2769 |
\LL |
| 2770 |
\stoptabulate |
| 2771 |
|
| 2772 |
If \type {--output-directory} is specified and the value is a relative pathname, |
| 2773 |
the file is searched first here and then in the standard tree. |
| 2774 |
|
| 2775 |
|
| 2776 |
\stopsubsection |
| 2777 |
|
| 2778 |
\startsubsection[title={\type {init_prog}}] |
| 2779 |
|
| 2780 |
\topicindex {initialization+bitmaps} |
| 2781 |
|
| 2782 |
\libindex{init_prog} |
| 2783 |
|
| 2784 |
Extra initialization for programs that need to generate bitmap fonts. |
| 2785 |
|
| 2786 |
\startfunctioncall |
| 2787 |
kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode) |
| 2788 |
kpse.init_prog(<string> prefix, <number> base_dpi, <string> mfmode, <string> fallback) |
| 2789 |
\stopfunctioncall |
| 2790 |
|
| 2791 |
\stopsubsection |
| 2792 |
|
| 2793 |
\startsubsection[title={\type {readable_file}}] |
| 2794 |
|
| 2795 |
\libindex{readable_file} |
| 2796 |
|
| 2797 |
Test if an (absolute) file name is a readable file. |
| 2798 |
|
| 2799 |
\startfunctioncall |
| 2800 |
<string> f = kpse.readable_file(<string> name) |
| 2801 |
\stopfunctioncall |
| 2802 |
|
| 2803 |
The return value is the actual absolute filename you should use, because the disk |
| 2804 |
name is not always the same as the requested name, due to aliases and |
| 2805 |
system|-|specific handling under e.g.\ \MSDOS. Returns \type {nil} if the file |
| 2806 |
does not exist or is not readable. |
| 2807 |
|
| 2808 |
\stopsubsection |
| 2809 |
|
| 2810 |
\startsubsection[title={\type {expand_path}}] |
| 2811 |
|
| 2812 |
\libindex{expand_path} |
| 2813 |
|
| 2814 |
Like kpsewhich's \type {-expand-path}: |
| 2815 |
|
| 2816 |
\startfunctioncall |
| 2817 |
<string> r = kpse.expand_path(<string> s) |
| 2818 |
\stopfunctioncall |
| 2819 |
|
| 2820 |
\stopsubsection |
| 2821 |
|
| 2822 |
\startsubsection[title={\type {expand_var}}] |
| 2823 |
|
| 2824 |
\libindex{expand_var} |
| 2825 |
|
| 2826 |
Like kpsewhich's \type {-expand-var}: |
| 2827 |
|
| 2828 |
\startfunctioncall |
| 2829 |
<string> r = kpse.expand_var(<string> s) |
| 2830 |
\stopfunctioncall |
| 2831 |
|
| 2832 |
\stopsubsection |
| 2833 |
|
| 2834 |
\startsubsection[title={\type {expand_braces}}] |
| 2835 |
|
| 2836 |
\libindex{expand_braces} |
| 2837 |
|
| 2838 |
Like kpsewhich's \type {-expand-braces}: |
| 2839 |
|
| 2840 |
\startfunctioncall |
| 2841 |
<string> r = kpse.expand_braces(<string> s) |
| 2842 |
\stopfunctioncall |
| 2843 |
|
| 2844 |
\stopsubsection |
| 2845 |
|
| 2846 |
\startsubsection[title={\type {in_name_ok}}] |
| 2847 |
|
| 2848 |
\libindex{in_name_ok} |
| 2849 |
|
| 2850 |
Returns true if \type{fname} is acceptable to open for reading, otherwise false and |
| 2851 |
write a message to standard error. |
| 2852 |
|
| 2853 |
\startfunctioncall |
| 2854 |
<boolean> r = kpse.in_name_ok(<string> fname) |
| 2855 |
\stopfunctioncall |
| 2856 |
|
| 2857 |
\startsubsection[title={\type {in_name_ok_silent_extended}}] |
| 2858 |
|
| 2859 |
\libindex{in_name_ok_silent_extended} |
| 2860 |
|
| 2861 |
\startfunctioncall |
| 2862 |
<boolean> r = kpse.in_name_ok_silent_extended(<string> fname) |
| 2863 |
\stopfunctioncall |
| 2864 |
|
| 2865 |
Returns true if \type{fname} is acceptable to open for reading; |
| 2866 |
the values of \type{TEXMFVAR} and \type{TEXMFSYSVAR} are also |
| 2867 |
checked for absolute filenames. Returns false otherwise but it doesn't write |
| 2868 |
a message to standard error. |
| 2869 |
|
| 2870 |
\stopsubsection |
| 2871 |
|
| 2872 |
|
| 2873 |
\startsubsection[title={\type {out_name_ok}}] |
| 2874 |
|
| 2875 |
\libindex{out_name_ok} |
| 2876 |
|
| 2877 |
Returns true if \type{fname} is acceptable to open for writing. |
| 2878 |
|
| 2879 |
\startfunctioncall |
| 2880 |
<boolean> r = kpse.out_name_ok(<string> fname) |
| 2881 |
\stopfunctioncall |
| 2882 |
|
| 2883 |
\stopsubsection |
| 2884 |
|
| 2885 |
|
| 2886 |
\startsubsection[title={\type {out_name_ok_silent_extended}}] |
| 2887 |
|
| 2888 |
\libindex{out_name_ok_silent_extended} |
| 2889 |
|
| 2890 |
\startfunctioncall |
| 2891 |
<boolean> r = kpse.out_name_ok_silent_extended(<string> fname) |
| 2892 |
\stopfunctioncall |
| 2893 |
|
| 2894 |
Returns true if \type{fname} is acceptable to open for writing; |
| 2895 |
the values of \type{TEXMFVAR} and \type{TEXMFSYSVAR} are also |
| 2896 |
checked for absolute filenames. Returns false otherwise but it doesn't write |
| 2897 |
a message to standard error. |
| 2898 |
|
| 2899 |
\stopsubsection |
| 2900 |
|
| 2901 |
|
| 2902 |
|
| 2903 |
|
| 2904 |
\startsubsection[title={\type {show_path}}] |
| 2905 |
|
| 2906 |
\libindex{show_path} |
| 2907 |
|
| 2908 |
Like kpsewhich's \type {-show-path}: |
| 2909 |
|
| 2910 |
\startfunctioncall |
| 2911 |
<string> r = kpse.show_path(<string> ftype) |
| 2912 |
\stopfunctioncall |
| 2913 |
|
| 2914 |
\stopsubsection |
| 2915 |
|
| 2916 |
\startsubsection[title={\type {var_value}}] |
| 2917 |
|
| 2918 |
\libindex{var_value} |
| 2919 |
|
| 2920 |
Like kpsewhich's \type {-var-value}: |
| 2921 |
|
| 2922 |
\startfunctioncall |
| 2923 |
<string> r = kpse.var_value(<string> s) |
| 2924 |
\stopfunctioncall |
| 2925 |
|
| 2926 |
\stopsubsection |
| 2927 |
|
| 2928 |
\startsubsection[title={\type {version}}] |
| 2929 |
|
| 2930 |
\libindex{version} |
| 2931 |
|
| 2932 |
Returns the kpathsea version string. |
| 2933 |
|
| 2934 |
\startfunctioncall |
| 2935 |
<string> r = kpse.version() |
| 2936 |
\stopfunctioncall |
| 2937 |
|
| 2938 |
\stopsubsection |
| 2939 |
|
| 2940 |
\startsubsection[title={\type {check_permission}}] |
| 2941 |
|
| 2942 |
\libindex{check\_permission} |
| 2943 |
|
| 2944 |
Checks if the \type{filename} can be executed or not. |
| 2945 |
Returns \type{1}, \type{filename} or a safe cmd alternative if it can be executed, |
| 2946 |
otherwise returns \type{0} and an error message. |
| 2947 |
|
| 2948 |
\startfunctioncall |
| 2949 |
<string> res, cmd = kpse.check_permission(<string> filename) |
| 2950 |
\stopfunctioncall |
| 2951 |
|
| 2952 |
\stopsubsection |
| 2953 |
|
| 2954 |
|
| 2955 |
\stopsection |
| 2956 |
|
| 2957 |
\stopchapter |
| 2958 |
|
| 2959 |
\stopcomponent |