diff options
author | Akira Kakuto <kakuto@fuk.kindai.ac.jp> | 2013-05-19 21:59:26 +0000 |
---|---|---|
committer | Akira Kakuto <kakuto@fuk.kindai.ac.jp> | 2013-05-19 21:59:26 +0000 |
commit | 34b06d0c827ffd5025170280ed1d2ac0382e53d8 (patch) | |
tree | a7d25a092a11f3b32f4e92588a36aa9de9506c1f /Master/texmf-dist/doc/luatex/base | |
parent | e8ccaf8c3b7255703def9e8e8ecd6e003843aef8 (diff) |
Update LuaTeX manuals
git-svn-id: svn://tug.org/texlive/trunk@30575 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/luatex/base')
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/fdata_epdf.lua | 139 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/functionref.pdf | bin | 107971 -> 396697 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/functionref.tex | 14 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatexref-env.tex | 24 | ||||
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatexref-t.pdf | bin | 779669 -> 809061 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/luatex/base/luatexref-t.tex | 512 |
6 files changed, 561 insertions, 128 deletions
diff --git a/Master/texmf-dist/doc/luatex/base/fdata_epdf.lua b/Master/texmf-dist/doc/luatex/base/fdata_epdf.lua index eea799d32c0..991b6223b39 100644 --- a/Master/texmf-dist/doc/luatex/base/fdata_epdf.lua +++ b/Master/texmf-dist/doc/luatex/base/fdata_epdf.lua @@ -1,4 +1,4 @@ --- $Id: fdata_epdf.lua 4165 2011-04-16 09:01:02Z taco $ +-- $Id: fdata_epdf.lua 4559 2013-01-20 19:58:26Z hhenkel $ local fdata_epdf = { functions = { @@ -351,13 +351,13 @@ local fdata_epdf = { }, embeddedFile = { type = "function", - shortdesc = "Get embedded file.", + shortdesc = "Get file spec of embedded file.", arguments = { {type = "Catalog", name = "catalog", optional = false, }, {type = "integer", name = "integer", optional = false, }, }, returnvalues = { - {type = "EmbFile", name = "var", optional = false, }, + {type = "FileSpec", name = "var", optional = false, }, }, }, numJS = { @@ -494,6 +494,70 @@ local fdata_epdf = { {type = "boolean", name = "var", optional = false, }, }, }, + save = { + type = "function", + shortdesc = "Save embedded file to disk.", + arguments = { + {type = "EmbFile", name = "embfile", optional = false, }, + {type = "string", name = "var", optional = false, }, + }, + returnvalues = { + {type = "boolean", name = "var", optional = false, }, + }, + }, + }, +------------------------------------------------------------------------ + FileSpec = { + isOk = { + type = "function", + shortdesc = "Check if filespec is ok.", + arguments = { + {type = "FileSpec", name = "filespec", optional = false, }, + }, + returnvalues = { + {type = "boolean", name = "var", optional = false, }, + }, + }, + getFileName = { + type = "function", + shortdesc = "Get file name of filespec.", + arguments = { + {type = "FileSpec", name = "filespec", optional = false, }, + }, + returnvalues = { + {type = "string", name = "string", optional = false, }, + }, + }, + getFileNameForPlatform = { + type = "function", + shortdesc = "Get file name for platform of filespec.", + arguments = { + {type = "FileSpec", name = "filespec", optional = false, }, + }, + returnvalues = { + {type = "string", name = "string", optional = false, }, + }, + }, + getDescription = { + type = "function", + shortdesc = "Get description of filespec.", + arguments = { + {type = "FileSpec", name = "filespec", optional = false, }, + }, + returnvalues = { + {type = "string", name = "string", optional = false, }, + }, + }, + getEmbeddedFile = { + type = "function", + shortdesc = "Get embedded file of filespec.", + arguments = { + {type = "FileSpec", name = "filespec", optional = false, }, + }, + returnvalues = { + {type = "EmbFile", name = "embfile", optional = false, }, + }, + }, }, ------------------------------------------------------------------------ Dict = { @@ -559,7 +623,7 @@ local fdata_epdf = { }, is = { type = "function", - shortdesc = "TODO", + shortdesc = "Check if Dict is of given /Type.", arguments = { {type = "Dict", name = "dict", optional = false, }, {type = "string", name = "string", optional = false, }, @@ -635,6 +699,42 @@ local fdata_epdf = { {type = "Object", name = "var", optional = false, }, }, }, + hasKey = { + type = "function", + shortdesc = "Check if Dict contains /Key.", + arguments = { + {type = "Dict", name = "dict", optional = false, }, + {type = "string", name = "string", optional = false, }, + }, + returnvalues = { + {type = "boolean", name = "var", optional = false, }, + }, + }, + }, +------------------------------------------------------------------------ + Link = { + isOK = { + type = "function", + shortdesc = "Check if Link object is ok.", + arguments = { + {type = "Link", name = "link", optional = false, }, + }, + returnvalues = { + {type = "boolean", name = "var", optional = false, }, + }, + }, + inRect = { + type = "function", + shortdesc = "Check if point is inside the link rectangle.", + arguments = { + {type = "Link", name = "link", optional = false, }, + {type = "number", name = "number", optional = false, }, + {type = "number", name = "number", optional = false, }, + }, + returnvalues = { + {type = "boolean", name = "var", optional = false, }, + }, + }, }, ------------------------------------------------------------------------ LinkDest = { @@ -780,6 +880,30 @@ local fdata_epdf = { }, }, ------------------------------------------------------------------------ + Links = { + getNumLinks = { + type = "function", + shortdesc = "Get number of links.", + arguments = { + {type = "Links", name = "links", optional = false, }, + }, + returnvalues = { + {type = "integer", name = "var", optional = false, }, + }, + }, + getLink = { + type = "function", + shortdesc = "Get link by number.", + arguments = { + {type = "Links", name = "links", optional = false, }, + {type = "integer", name = "integer", optional = false, }, + }, + returnvalues = { + {type = "Link", name = "var", optional = false, }, + }, + }, + }, +------------------------------------------------------------------------ Object = { initBool = { type = "function", @@ -842,7 +966,7 @@ local fdata_epdf = { }, initArray = { type = "function", - shortdesc = "Initialize an Array-type object.", + shortdesc = "Initialize an Array-type object with an empty array.", arguments = { {type = "Object", name = "object", optional = false, }, {type = "XRef", name = "xref", optional = false, }, @@ -852,7 +976,7 @@ local fdata_epdf = { }, initDict = { type = "function", - shortdesc = "Initialize a Dict-type object.", + shortdesc = "Initialize a Dict-type object with an empty dictionary.", arguments = { {type = "Object", name = "object", optional = false, }, {type = "XRef", name = "xref", optional = false, }, @@ -1352,9 +1476,10 @@ local fdata_epdf = { }, streamIs = { type = "function", - shortdesc = "TODO", + shortdesc = "Check if object contains a stream whose dictionary is of given /Type.", arguments = { {type = "Object", name = "object", optional = false, }, + {type = "string", name = "string", optional = false, }, }, returnvalues = { {type = "boolean", name = "var", optional = false, }, diff --git a/Master/texmf-dist/doc/luatex/base/functionref.pdf b/Master/texmf-dist/doc/luatex/base/functionref.pdf Binary files differindex 685dc21eb87..d639820ba0f 100644 --- a/Master/texmf-dist/doc/luatex/base/functionref.pdf +++ b/Master/texmf-dist/doc/luatex/base/functionref.pdf diff --git a/Master/texmf-dist/doc/luatex/base/functionref.tex b/Master/texmf-dist/doc/luatex/base/functionref.tex index 50332dfcf97..02e9c03b054 100644 --- a/Master/texmf-dist/doc/luatex/base/functionref.tex +++ b/Master/texmf-dist/doc/luatex/base/functionref.tex @@ -1,4 +1,6 @@ % $Id$ +\pdfcompresslevel=0 +\pdfobjcompresslevel=0 \nonknuthmode \catcode`\|=12 @@ -9,7 +11,7 @@ \setuptabulate[before=] \setuppagenumbering[location=,alternative=doublesided] -\setupheadertexts[Luatex 0.70 short reference][pagenumber] +\setupheadertexts[Luatex 0.66 short reference][pagenumber] \setupheader[style=\ssbf] \setupalign[flushleft] @@ -391,6 +393,11 @@ in the same format as \type{\pdfximage}. \presentmethod{epdf}{Dict}{getVal} \presentmethod{epdf}{Dict}{getValNF} +--- Link methods: + +\presentmethod{epdf}{Link}{isOK} +\presentmethod{epdf}{Link}{inRect} + --- LinkDest methods: \presentmethod{epdf}{LinkDest}{isOK} @@ -408,6 +415,11 @@ in the same format as \type{\pdfximage}. \presentmethod{epdf}{LinkDest}{getChangeTop} \presentmethod{epdf}{LinkDest}{getChangeZoom} +--- Links methods: + +\presentmethod{epdf}{Links}{getNumLinks} +\presentmethod{epdf}{Links}{getLink} + --- Object methods: \presentmethod{epdf}{Object}{initBool} diff --git a/Master/texmf-dist/doc/luatex/base/luatexref-env.tex b/Master/texmf-dist/doc/luatex/base/luatexref-env.tex index fe5256f9b9b..5cb29ec5cbe 100644 --- a/Master/texmf-dist/doc/luatex/base/luatexref-env.tex +++ b/Master/texmf-dist/doc/luatex/base/luatexref-env.tex @@ -4,28 +4,6 @@ % something rests this, but i hav eno time not to see where -\unprotect \bgroup - - \ifx\normalsuber\undefined \def\normalsuber{_} \fi - \ifx\normalsuper\undefined \def\normalsuper{^} \fi - - \catcode`_=\active - \catcode`^=\active - - \gdef\nonknuthmode - {\appendtoks\let_\normalsuber\let^\normalsuper\to\everymathematics - \mathcode`_="8000 - \mathcode`^="8000 - \catcode`_=\@@other - \catcode`^=\@@other - }% \let\nonknuthmode\relax} - - \gdef\donknuthmode - {\catcode`_=\@@subscript - \catcode`^=\@@superscript} - -\egroup \protect - \usemodule[abr-02] % \tex : tex command @@ -129,7 +107,7 @@ \definecolor[blue] [b=.5] \definecolor[red] [r=.5] \definecolor[green][g=.5] -\runMPgraphicstrue + \startuseMPgraphic{lualogo} color luaplanetcolor ; luaplanetcolor := .5blue ; color luaholecolor ; luaholecolor := white ; diff --git a/Master/texmf-dist/doc/luatex/base/luatexref-t.pdf b/Master/texmf-dist/doc/luatex/base/luatexref-t.pdf Binary files differindex 696b2fc94d2..fae64e04d67 100644 --- a/Master/texmf-dist/doc/luatex/base/luatexref-t.pdf +++ b/Master/texmf-dist/doc/luatex/base/luatexref-t.pdf diff --git a/Master/texmf-dist/doc/luatex/base/luatexref-t.tex b/Master/texmf-dist/doc/luatex/base/luatexref-t.tex index c9aaa684658..4b1f4bdc5c3 100644 --- a/Master/texmf-dist/doc/luatex/base/luatexref-t.tex +++ b/Master/texmf-dist/doc/luatex/base/luatexref-t.tex @@ -23,7 +23,7 @@ \setvariables [document] - [beta=0.70.1] + [beta=0.76.0] \starttext @@ -73,7 +73,7 @@ distinguishable parts: \startitemize[packed] \item \PDFTEX\ version 1.40.9, converted to C (with patches from later releases). \item The direction model and some other bits from \ALEPH\ RC4 converted to C. -\item \LUA\ 5.1.4 ($+$ coco 1.1.5 $+$ portable bytecode) +\item \LUA\ 5.2.1 \item dedicated \LUA\ libraries \item various \TEX\ extensions \item parts of \FONTFORGE\ 2008.11.17 @@ -92,7 +92,7 @@ in \LUA\ instead. \section{Introduction} From day one, \LUATEX\ has offered extra functionality when compared -to the superset of \PDFTEX\ and Aleph. That has not been limited to +to the superset of \PDFTEX\ and \ALEPH. That has not been limited to the possibility to execute lua code via \type{\directlua}, but \LUATEX\ also adds functionality via new \TEX-side primitives. @@ -393,13 +393,30 @@ further in this manual). This syntax is new in version 0.36.0. The chunk name should not start with a \type{@}, or it will be displayed as a file name (this is a quirk in the current \LUA\ implementation). +The \tex{directlua} command is expandable. Since it passes {\LUA} code to the +{\LUA} interpreter its expansion from the {\TEX} viewpoint is usually empty. +However, there are some {\LUA} functions that produce material to be read +by {\TeX}, the so called print functions. The most simple use of these is +\type{tex.print(<string> s)}. The characters of the string \type{s} will be placed +on the {\TeX} input buffer, that is, \quote{before \TeX's eyes} to be read by {\TeX} +immediately. For example: + \startbuffer -$\pi = \directlua{tex.print(math.pi)}$ +\count10=20 +a\directlua{tex.print(tex.count[10]+5)}b \stopbuffer -The \tex{directlua} command is expandable: the results of the \LUA\ -code become effective immediately. As an example, the following -input: +\typebuffer + +expands to + +\getbuffer + +Here is another example: + +\startbuffer +$\pi = \directlua{tex.print(math.pi)}$ +\stopbuffer \typebuffer @@ -407,6 +424,13 @@ will result in \getbuffer +Note that the expansion of \tex{directlua} is a sequence of characters, not +of tokens, contrary to all {\TeX} commands. So formally speaking its +expansion is null, but it places material on a pseudo-file to be +immediately read by {\TeX}, as etex's \tex{scantokens}. + +For a description of print functions look at \in{section~}[sec:luaprint]. + Because the \syntax{<general text>} is a chunk, the normal \LUA\ error handling is triggered if there is a problem in the included code. The \LUA\ error messages should be clear enough, but the contextual @@ -553,7 +577,7 @@ format file. \subsubsection{\tex{catcodetable}} \startsyntax -\catcodetable <16-bit number> +\catcodetable <15-bit number> \stopsyntax The primitive \tex{catcodetable} switches to a different catcode table. @@ -564,7 +588,7 @@ primitives below, or it has to be zero. Table zero is initialized by \subsubsection{\tex{initcatcodetable}} \startsyntax -\initcatcodetable <16-bit number> +\initcatcodetable <15-bit number> \stopsyntax The primitive \tex{initcatcodetable} creates a new table with catcodes @@ -589,7 +613,7 @@ the currently active table, an error is raised. \subsubsection{\tex{savecatcodetable}} \startsyntax -\savecatcodetable <16-bit number> +\savecatcodetable <15-bit number> \stopsyntax \tex{savecatcodetable} copies the current set of catcodes to a @@ -718,6 +742,13 @@ origin of the box to be shipped out. So they are like normal is based on the {\it largest\/} enclosing box instead of the {\it smallest\/}. + +\section{Expandable character codes (0.75)} + +The new expandable command \tex{Uchar} reads a number between~0 and +$1{,}114{,}111$ and expands to the associated Unicode character. + + \chapter {\LUA\ general} \section[init]{Initialization} @@ -921,17 +952,24 @@ needs to check \type{--progname}, or \type{--ini} and \type{--fmt}, if \section{\LUA\ changes} -The C coroutine (\COCO) patches from LuaJIT are applied to the \LUA\ -core, the used version is 1.1.5. See \hyphenatedurl{http://coco.luajit.org/} -for details. This functionality currently (0.45) does not work on -non-intel OpenBSD platforms nor on powerpc Linux-es. Additional note: -\type{coroutines.wrap()} under Windows does not inherit the state -of the random generator, it always has an implicit -\type{math.randomseed(1)} that is added by the Windows kernel. +{\bf NOTE:} \LUATEX\ 0.74.0 is the first version with Lua 5.2, and +this is used without any patches to the core, which has some side +effects. In particular, Lua's \type{tonumber()} may return values in +scientific notation, thereby confusing the \TEX\ end of things when it +is used as the right-hand side of an assignment to a \type{\dimen} +or \type{\count}. + +{\bf NOTE:} Also in \LUATEX\ 0.74.0 (this is a change in Lua 5.2), +loading dynamic Lua libraries will fail if there are two Lua libraries +loaded at the same time (which will typically happen on Win32, because +there is one Lua 5.2 inside luatex, and another will likely be linked +to the \type{dll} file of the module itself). We plan to fix that later +by switching \LUATEX\ itself to using de DLL version of Lua 5.2 inside +\LUATEX\ instead of including a static version in the binary. Starting from version 0.45, \LUATEX\ is able to use the kpathsea library to find \type{require()}d modules. For this purpose, -\type{package.loaders[2]} is replaced by a different loader function, +\type{package.searchers[2]} is replaced by a different loader function, that decides at runtime whether to use kpathsea or the built-in core lua function. It uses \KPATHSEA\ when that is already initialized at that point in time, otherwise it reverts to using the normal @@ -942,12 +980,11 @@ Initialization of \KPATHSEA\ can happen either implicitly (when \type{texconfig.kpse_init} to false), or explicitly by calling the \LUA\ function \type{kpse.set_program_name()}. - -Starting from version 0.46.0 (as an {\bf experimental} feature!) \LUATEX\ is +Starting from version 0.46.0 \LUATEX\ is also able to use dynamically loadable \LUA\ libraries, unless \type{--safer} was given as an option on the command line. -For this purpose, \type{package.loaders[3]} is replaced by a different +For this purpose, \type{package.searchers[3]} is replaced by a different loader function, that decides at runtime whether to use kpathsea or the build-in core lua function. As in the previous paragraph, it uses \KPATHSEA\ when that is already initialized at that point in time, @@ -990,15 +1027,10 @@ function as normal. This change is new in 0.37.0. -The \lua{read("*line")} function from the io library has been -adjusted so that it is line|-|ending neutral: any of \type{LF}, \type +The \lua{f:read("*line")} and \lua{f:lines()} functions from the io library have +been adjusted so that they are line|-|ending neutral: any of \type{LF}, \type {CR} or \type{CR+LF} are acceptable line endings. -The \lua{tostring()} printer for numbers has been changed so that it -returns~\type{0.00000000000001} instead of~\hbox{\type{1e-14}} (which -confused \TEX\ enormously). Even values with an even smaller exponent -print simply as~\type{0}. - \lua{luafilesystem} has been extended: there are two extra boolean functions (\luatex{lfs.isdir(filename)} and \luatex{lfs.isfile(filename)}) and one extra string field in its attributes table @@ -1044,6 +1076,12 @@ number as its second return value if the string length was odd. The \luatex{string.characterpairs()} and \luatex{string.bytepairs()} are useful especially in the conversion of UTF-16 encoded data into UTF-8. + +Starting with \LUATEX\ 0.74, there is also a two-argument form of +\type{string.dump()}. The second argument is a boolean which, if true, +strips the symbols from the dumped data. This matches an extension +made in \type{luajit}. + Note: The \lua{string} library functions \luatex{len}, \luatex{lower}, \luatex{sub} etc. are not \UNICODE|-|aware. For strings in the UTF-8 encoding, i.e., strings containing characters above code point 127, the @@ -1177,6 +1215,12 @@ LC_NUMERIC=C \section {\LUA\ modules} +{\bf NOTE}: Starting with \LUATEX\ 0.74, the implied use of the +built-in Lua modules in this section is deprecated. If you want to use +one of these libraries, please start your source file with a +proper \type{require} line. In the near future, \LUATEX\ will switch +to loading these modules on demand. + Some modules that are normally external to \LUA\ are statically linked in with \LUATEX, because they offer useful functionality: @@ -1188,10 +1232,10 @@ functions also accept the first 256 values of plane~18. This is the range \LUATE uses for raw binary output, as explained above. \item \lua{luazip}, from the kepler project, \hyphenatedurl{http://www.keplerproject.org/luazip/}. - (version 1.2.1, but patched for compilation with \LUA\ 5.1) + (version 1.2.1, but patched for compilation with \LUA\ 5.2) \item \lua{luafilesystem}, also from the kepler project, \hyphenatedurl{http://www.keplerproject.org/luafilesystem/}. (version 1.5.0) -\item \lua{lpeg}, by Roberto Ierusalimschy, \hyphenatedurl{http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html}. (version 0.9.0) +\item \lua{lpeg}, by Roberto Ierusalimschy, \hyphenatedurl{http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html}. (version 0.10.2) Note: \lua{lpeg} is not \UNICODE|-|aware, but interprets strings on a byte|-|per|-|byte basis. This mainly means that \luatex{lpeg.S} cannot be @@ -1219,6 +1263,13 @@ preloaded inside the executable, there are no external file dependencies. \chapter[libraries]{\LUATEX\ \LUA\ Libraries} +{\bf NOTE}: Starting with \LUATEX\ 0.74, the implied use of the +built-in Lua modules \type{epdf}, \type{fontloader}, \type{mplib}, +and \type{pdfscanner} is deprecated. If you want to use these, please +start your source file with a proper \type{require} line. In the near +future, \LUATEX\ will switch to loading these modules on demand. + + The interfacing between \TEX\ and \LUA\ is facilitated by a set of library modules. The \LUA\ libraries in this chapter are all defined and initialized by the \LUATEX\ executable. Together, they allow \LUA\ @@ -1308,7 +1359,7 @@ Arguments: \sym{id_number} -This number is zero for the log or \tex {input} files. For \TEX's \tex{read} or +This number is zero for the log or \tex{input} files. For \TEX's \tex{read} or \tex{write} the number is incremented by one, so \tex{read0} becomes~1. \sym{asked_name} @@ -1378,6 +1429,10 @@ both \ALEPH's \OVF\ files and traditional Knuthian \VF\ files. Like \luatex{find_font_file}, but for map files. +\subsubsection{\luatex{find_cidmap_file} (new in 0.73)} + +Like \luatex{find_font_file}, but for cidmap files. + \subsubsection{\luatex{find_enc_file}} Like \luatex{find_font_file}, but for enc files. @@ -1543,6 +1598,7 @@ The list of functions is as follows: \NC \luatex{read_font_file} \NC ofm or tfm files \NC\NR \NC \luatex{read_vf_file} \NC virtual fonts \NC\NR \NC \luatex{read_map_file} \NC map files \NC\NR +\NC \luatex{read_cidmap_file} \NC cidmap files \NC\NR \NC \luatex{read_enc_file} \NC encoding files \NC\NR \NC \luatex{read_sfd_file} \NC subfont definition files \NC\NR \NC \luatex{read_pk_file} \NC pk bitmap files \NC\NR @@ -1592,6 +1648,27 @@ that. This callback does not replace any internal code. + +\subsubsection{\luatex{process_jobname} (0.71)} + +This callback allows you to change the jobname given by \type{\jobname} +in \TEX\ and \type{tex.jobname} in Lua. It does not affect the internal +job name or the name of the output or log files. + +\startfunctioncall +function(<string> jobname) + return <string> adjusted_jobname +end +\stopfunctioncall + +The only argument is the actual job name; you should not use +\type{tex.jobname} inside this function or infinite recursion may occur. +If you return \type{nil}, \LUATEX\ will pretend your callback never +happened. + +This callback does not replace any internal code. + + \subsubsection{\luatex{token_filter}} This callback allows you to replace the way \LUATEX\ fetches @@ -2068,7 +2145,9 @@ by the \type{epdf} library, currently these are \type{EmbFile}, \type{Dict}, \type{GString}, +\type{Link}, \type{LinkDest}, +\type{Links}, \type{Object}, \type{ObjectStream}, \type{Page}, @@ -2202,6 +2281,14 @@ All object constructors: <string> = <Dict>:getKey(<integer>) <Object> = <Dict>:getVal(<integer>) <Object> = <Dict>:getValNF(<integer>) +<boolean> = <Dict>:hasKey(<string>) +\stopfunctioncall + +\type{Link} methods: + +\startfunctioncall +<boolean> = <Link>:isOK() +<boolean> = <Link>:inRect(<number>, <number>) \stopfunctioncall \type{LinkDest} methods: @@ -2223,6 +2310,13 @@ All object constructors: <boolean> = <LinkDest>:getChangeZoom() \stopfunctioncall +\type{Links} methods: + +\startfunctioncall +<integer> = <Links>:getNumLinks() +<Link> = <Links>:getLink(<integer>) +\stopfunctioncall + \type{Object} methods: \startfunctioncall @@ -2282,7 +2376,7 @@ All object constructors: <string> = <Object>:dictgetKey(<integer>) <Object> = <Object>:dictgetVal(<integer>) <Object> = <Object>:dictgetValNF(<integer>) -<boolean> = <Object>:streamIs() +<boolean> = <Object>:streamIs(<string>) = <Object>:streamReset() <integer> = <Object>:streamGetChar() <integer> = <Object>:streamLookChar() @@ -3518,8 +3612,8 @@ are hashes with: \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR -\NC unicode \NC number \NC \NC \NR -\NC variant \NC number \NC \NC \NR +\NC unicode \NC number \NC this glyph is also used for this unicode\NC \NR +\NC variant \NC number \NC the alternative is driven by this unicode selector\NC \NR \stoptabulate \subsubsubsection{vert_variants and horiz_variants table} @@ -3586,7 +3680,7 @@ actual lookups, represented as dictionary tables. \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR -\NC type \NC number \NC \NC\NR +\NC type \NC string \NC \NC\NR \NC format \NC enum \NC one of \type {glyphs}, \type {class}, \type {coverage}, \type {reversecoverage} \NC\NR \NC tag \NC string \NC \NC\NR \NC current_class \NC array \NC \NC\NR @@ -3600,10 +3694,10 @@ Rule items have one common item and one specialized item: \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR \NC lookups \NC array \NC a linear array of lookup names\NC\NR -\NC glyph \NC array \NC only if the parent's format is \type{glyph}\NC\NR -\NC class \NC array \NC only if the parent's format is \type{glyph}\NC\NR -\NC coverage \NC array \NC only if the parent's format is \type{glyph}\NC\NR -\NC reversecoverage \NC array \NC only if the parent's format is \type{glyph}\NC\NR +\NC glyphs \NC array \NC only if the parent's format is \type{glyphs}\NC\NR +\NC class \NC array \NC only if the parent's format is \type{class}\NC\NR +\NC coverage \NC array \NC only if the parent's format is \type{coverage}\NC\NR +\NC reversecoverage \NC array \NC only if the parent's format is \type{reversecoverage}\NC\NR \stoptabulate A glyph table is: @@ -5110,7 +5204,44 @@ This function also accept string \type{id}'s. <node> t = node.traverse(<node> n) \stopfunctioncall -This is an iterator that loops over the node list that starts at \type{n}. +This is a lua iterator that loops over the node list that starts at \type{n}. +Typical input code like this + +\starttyping +for n in node.traverse(head) do + ... +end +\stoptyping + +is functionally equivalent to: + +\starttyping +do + local n + local function f (head,var) + local t + if var == nil then + t = head + else + t = var.next + end + return t + end + while true do + n = f (head, n) + if n == nil then break end + ... + end +end +\stoptyping + +It should be clear from the definition of the function \type{f} that +even though it is possible to add or remove nodes from the node list while +traversing, you have to take great care to make sure all the \type{next} +(and \type{prev}) pointers remain valid. + +If the above is unclear to you, see the section \quote{For Statement} +in the Lua Reference Manual. \subsubsection{\luatex{node.traverse_id}} @@ -5121,6 +5252,33 @@ This is an iterator that loops over the node list that starts at \type{n}. This is an iterator that loops over all the nodes in the list that starts at \type{n} that have a matching \type{id} field. +See the previous section for details. The change is in the local +function \type{f}, which now does an extra while loop checking +against the upvalue \type{id}: + +\starttyping + local function f (head,var) + local t + if var == nil then + t = head + else + t = var.next + end + while not t.id == id do + t = t.next + end + return t + end +\stoptyping + +\subsubsection{\luatex{node.end_of_math} (0.76)} + +\startfunctioncall +<node> t = node.end_of_math(<node> start) +\stopfunctioncall + +Looks for and returns the next \type{math_node} following the \type{start}. + \subsubsection{\luatex{node.remove}} \startfunctioncall @@ -5515,6 +5673,173 @@ used from within \type{\latelua}. pdf.registerannot (<number> objnum) \stopfunctioncall +\section{The \luatex{pdfscanner} library (new in 0.72.0)} + +The \luatex{pdfscanner} library allows interpretation of PDF content streams +and \type{/ToUnicode} (cmap) streams. You can get those streams from the +\luatex{epdf} library, as explained in an earlier section. There is only +a single top|-|level function in this library: + +\startfunctioncall +pdfscanner.scan (<Object> stream, <table> operatortable, <table> info) +\stopfunctioncall + +The first argument, \type{stream}, should be either a PDF stream +object, or a PDF array of PDF stream objects (those options comprise +the possible return values of \type{<Page>:getContents()} +and \type{<Object>:getStream()} in the \type{epdf} library). + +The second argument, \type{operatortable}, should be a Lua table where +the keys are PDF operator name strings and the values are Lua +functions (defined by you) that are used to process those +operators. The functions are called whenever the scanner finds one +of these PDF operators in the content stream(s). The functions are +called with two arguments: the \type{scanner} object itself, and +the \type{info} table that was passed are the third argument +to \type{pdfscanner.scan}. + +Internally, \type{pdfscanner.scan} loops over the PDF operators in the +stream(s), collecting operands on an internal stack until it finds a +PDF operator. If that PDF operator's name exists +in \type{operatortable}, then the associated function is +executed. After the function has run (or when there is no function to +execute) the internal operand stack is cleared in preparation for the +next operator, and processing continues. + +The \type{scanner} argument to the processing functions is needed +because it offers various methods to get the actual operands from the +internal operand stack. The most important of those functions is +\type{} + +A simple example of processing a PDF's document stream +could look like this: + +\starttyping +function Do (scanner, info) + local val = scanner:pop() + local name = val[2] -- val[1] == 'name' + print (info.space ..'Use XObject '.. name) + local resources = info.resources + local xobject = resources:lookup("XObject"):getDict():lookup(name) + if (xobject and xobject:isStream()) then + local dict = xobject:getStream():getDict() + if dict then + local name = dict:lookup('Subtype') + if name:getName() == 'Form' then + local newinfo = { space = info.space .. " " , + resources = dict:lookup('Resources'):getDict() } + pdfscanner.scan(xobject, operatortable, newinfo) + end + end + end +end +operatortable = {Do = Do} + +doc = epdf.open(arg[1]) +pagenum = 1 +while pagenum <= doc:getNumPages() do + local page = doc:getCatalog():getPage(pagenum) + local info = { space = " " , resources = page:getResourceDict()} + print ('Page ' .. pagenum) + pdfscanner.scan(page:getContents(), operatortable, info) + pagenum = pagenum + 1 +end +\stoptyping + +This example iterates over all the actual content in the PDF, and +prints out the found XObject names. While the code demonstrates quite +some of the \type{epdf} functions, let's focus on the type +\type{pdfscanner} specific code instead. + +From the bottom up, the line + +\starttyping + pdfscanner.scan(page:getContents(), operatortable, info) +\stoptyping + +runs the scanner with the PDF page's top-level content. + +The third argument, \type{info}, contains two entries: \type{space} is +used to indent the printed output, and \type{resources} is needed so +that embedded \type{XForms} can find their own content. + +The second argument, \type{operatortable} defines a processing function +for a single PDF operator, \type{Do}. + +The function \type{Do} prints the name of the current XObject, and +then starts a new scanner for that object's content stream, under the +condition that the XObject is in fact a \type{/Form}. That nested +scanner is called with new \type{info} argument with an +updated \type{space} value so that the indentation of the output nicely +nests, and with an new \type{resources} field to help the next +iteration down to properly process any other, embedded XObjects. + +Of course, this is not a very useful example in practise, but for the +purpose of demonstrating \type{pdfscanner}, it is just long enough. +It makes use of only one \type{scanner} method: \type{scanner:pop()}. +That function pops the top operand of the internal stack, and returns +a lua table where the object at index one is a string representing +the type of the operand, and object two is its value. + +The list of possible operand types and associated lua value types is: + +\starttabulate[|lT|p|] +\NC integer \NC <number> \NC \NR +\NC real \NC <number> \NC \NR +\NC boolean \NC <boolean> \NC \NR +\NC name \NC <string> \NC \NR +\NC operator \NC <string> \NC \NR +\NC string \NC <string> \NC \NR +\NC array \NC <table> \NC \NR +\NC dict \NC <table> \NC \NR +\stoptabulate + +In case of \type{integer} or \type{real}, the value is always +a Lua (floating point) number. + +In case of \type{name}, the leading slash is always stripped. + +In case of \type{string}, please bear in mind that PDF actually +supports different types of strings (with different encodings) in +different parts of the PDF document, so may need to reencode some of +the results; \type{pdfscanner} always outputs the byte stream without +reencoding anything. \type{pdfscanner} does not differentiate between +literal strings and hexidecimal strings (the hexadecimal values are +decoded), and it treats the stream data for inline images as a string +that is the single operand for \type{EI}. + +In case of \type{array}, the table content is a list of \type{pop} +return values. + +In case of \type{dict}, the table keys are PDF name strings +and the values are \type{pop} return values. + +\blank + +There are few more methods defined that you can ask \type{scanner}: + +\starttabulate[|lT|p|] +\NC pop \NC as explained above\NC \NR +\NC popNumber \NC return only the value of a \type{real} or \type{integer}\NC \NR +\NC popName \NC return only the value of a \type{name} \NC \NR +\NC popString \NC return only the value of a \type{string} \NC \NR +\NC popArray \NC return only the value of a \type{array} \NC \NR +\NC popDict \NC return only the value of a \type{dict} \NC \NR +\NC popBool \NC return only the value of a \type{boolean} \NC \NR +\NC done \NC abort further processing of this \type{scan()} call\NC \NR +\stoptabulate + +The \type{popXXX} are convenience functions, and come in handy when +you know the type of the operands beforehand (which you usually do, in +PDF). For example, the \type{Do} function could have used \type{local +name = scanner:popName()} instead, because the single operand +to the \type{Do} operator is always a PDF name object. + +The \type{done} function allows you to abort processing of a stream +once you have learned everything you want to learn. This comes in handy +while parsing \type{/ToUnicode}, because there usually is trailing +garbage that you are not interested in. Without \type{done}, processing +only end at the end of the stream, possibly wasting CPU cycles. \section{The \luatex{status} library} @@ -5907,11 +6232,7 @@ The supported commands at this moment are: \startcolumns[n=2] \starttyping -tex.AlephVersion -tex.Alephrevision -tex.OmegaVersion -tex.Omegarevision -tex.eTeXversion +tex.eTeXVersion tex.eTeXrevision tex.formatname tex.jobname @@ -5965,10 +6286,6 @@ tex.pdflastypos tex.pdfrandomseed tex.pdflastlink tex.luatexversion -tex.Alephversion -tex.Omegaversion -tex.Alephminorversion -tex.Omegaminorversion tex.eTeXminorversion tex.eTeXversion tex.currentgrouplevel @@ -6133,8 +6450,11 @@ for array access, or \starttyping tex.setbox(<number> n, <node> s) +tex.setbox(<string> cs, <node> s) tex.setbox('global', <number> n, <node> s) +tex.setbox('global', <string> cs, <node> s) <node> n = tex.getbox(<number> n) +<node> n = tex.getbox(<string> cs) \stoptyping for function|-|based access. @@ -6316,7 +6636,7 @@ The known fields are: \stoptabulate -\subsection{Print functions} +\subsection[sec:luaprint]{Print functions} The \luatex{tex} table also contains the three print functions that are the major interface from \LUA\ scripting to \TEX. @@ -6502,6 +6822,19 @@ and \tex{errmessage} would. During this error, deletions are disabled. The array part of the \type{help} table has to contain strings, one for each line of error help. + +\subsubsection{\luatex{tex.hashtokens} (0.25)} + +\startfunctioncall +for i,v in pairs (tex.hashtokens()) do ... end +\stopfunctioncall + +Returns a name and token table pair (see~\in{section}[luatokens] about +token tables) iterator for every non-zero entry in the hash table. +This can be useful for debugging, but note that this also reports +control sequences that may be unreachable at this moment due to local +redefinitions: it is strictly a dump of the hash table. + \subsection[luaprimitives]{Functions for dealing with primitives } \subsubsection{\luatex{tex.enableprimitives}} @@ -6605,12 +6938,17 @@ end \NC omega \NC \ctxlua{out_prim('omega') } \NC \NR \NC aleph \NC \ctxlua{out_prim('aleph') } \NC \NR \NC luatex \NC \ctxlua{out_prim('luatex') } \NC \NR +\NC umath \NC \ctxlua{out_prim('umath') } \NC \NR \stoptabulate Note that \type{'luatex'} does not contain \type{directlua}, as that is considered to be a core primitive, along with all the \TEX82 primitives, so it is part of the list that is returned from \type{'core'}. +\type{'umath'} is a subset of \type{'luatex'} that covers the Unicode math +primitives and have been added in \LUATEX\ 0.75.0 as it might be desired to +handle the prefixing of that subset differently. + Running \type{tex.extraprimitives()} will give you the complete list of primitives that are not defined at \LUATEX\ 0.39.0 \type{-ini} startup. It is exactly equivalent to \type{tex.extraprimitives('etex', @@ -6632,12 +6970,12 @@ is always zero. \subsubsection{\luatex{tex.badness} (0.53)} \startfunctioncall -<number> b = tex.badness(<number> f, <number> s) +<number> b = tex.badness(<number> t, <number> s) \stopfunctioncall This helper function is useful -during linebreak calculations. \type{f} and \type{s} are scaled values; the function -returns the badness for when total \type{f} is supposed to be made from amounts +during linebreak calculations. \type{t} and \type{s} are scaled values; the function +returns the badness for when total \type{t} is supposed to be made from amounts that sum to \type{s}. The returned number is a reasonable approximation of $100(t/s)^3$; \subsubsection{\luatex{tex.linebreak} (0.53)} @@ -7005,17 +7343,15 @@ math group with the correct (numerator) math style. \section{Unicode math characters} -Character handling is now extended up to the full \UNICODE\ range. The -extension from 8-bit to 16-bit was already present in \ALEPH\ by means of a -set of extra primitives starting with the \type{\o} prefix, the extension -to full \UNICODE\ (the \type{\U} prefix) is compatible with \XETEX. +Character handling is now extended up to the full \UNICODE\ range +(the \type{\U} prefix), which is compatible with \XETEX. -The math primitives from \TEX\ and \ALEPH\ are kept as they are, except for +The math primitives from \TEX\ are kept as they are, except for the ones that convert from input to math commands: \type{mathcode}, -\type{omathcode}, \type{delcode}, and \type{odelcode}. These four now allow +and \type{delcode}. These two now allow for a 21-bit character argument on the left hand side of the equals sign. -Some of the \ALEPH\ math primitives and the new \LUATEX\ primitives read +Some of the new \LUATEX\ primitives read more than one separate value. This is shown in the tables below by a plus sign in the second column. @@ -7045,30 +7381,12 @@ Unaltered: \NC \tex{radical} \NC 0--7FFFFFF \NC\NR \stoptabulate -Altered \ALEPH\ primitives: - -\starttabulate[|l|l|l|] -\NC \bf primitive \NC \bf value range (in hex) \NC\NR -\NC \tex{omathcode} \NC 0--10FFFF = 0--8000000 \NC\NR -\NC \tex{odelcode} \NC 0--10FFFF = 0+0--FFFFFF+FFFFFF \NC\NR -\stoptabulate - -Unaltered: - -\starttabulate[|l|l|l|] -\NC \bf primitive \NC \bf value range (in hex) \NC\NR -\NC \tex{omathchardef} \NC 0--8000000 \NC\NR -\NC \tex{omathchar} \NC 0--7FFFFFF \NC\NR -\NC \tex{omathaccent} \NC 0--7FFFFFF \NC\NR -\NC \tex{odelimiter} \NC 0+0--7FFFFFF + FFFFFF \NC\NR -\NC \tex{oradical} \NC 0+0--7FFFFFF + FFFFFF \NC\NR -\stoptabulate - New primitives that are compatible with \XETEX: \starttabulate[|l|l|l|l|] \NC \bf primitive \NC \bf value range (in hex) \NC\NR \NC \tex{Umathchardef} \NC 0+0+0--7+FF+10FFFF$^1$ \NC\NR +\NC \tex{Umathcharnumdef}$^5$ \NC -80000000--7FFFFFFF$^3$ \NC\NR \NC \tex{Umathcode} \NC 0--10FFFF = 0+0+0--7+FF+10FFFF$^1$ \NC\NR \NC \tex{Udelcode} \NC 0--10FFFF = 0+0--FF+10FFFF$^2$ \NC\NR \NC \tex{Umathchar} \NC 0+0+0--7+FF+10FFFF \NC\NR @@ -7104,6 +7422,8 @@ Note 4: As of \LUATEX\ 0.65, \tex{Umathaccent} accepts optional keywords to control various details regarding math accents. See \in{section}[mathacc] below for details. +Note 5: \tex{Umathcharnumdef} was added in release 0.72. + New primitives that exist in \LUATEX\ only (all of these will be explained in following sections): @@ -7111,8 +7431,6 @@ in following sections): \starttabulate[|l|l|l|l|] \NC \bf primitive \NC \bf value range (in hex) \NC\NR -%\NC \tex{Umathbotaccent} \NC 0+0+0--7+FF+10FFFF \NC\NR -%\NC \tex{Umathaccents} \NC 0+0+0+0+0+0--7+FF+10FFFF+7+FF+10FFFF \NC\NR \NC \tex{Uroot} \NC 0+0--FF+10FFFF$^2$ \NC\NR \NC \tex{Uoverdelimiter} \NC 0+0--FF+10FFFF$^2$ \NC\NR \NC \tex{Uunderdelimiter} \NC 0+0--FF+10FFFF$^2$ \NC\NR @@ -7460,9 +7778,6 @@ A simple example: \Umathaccent both fixed 0 0 "20D7 fixed 0 0 "20D7 {example} \stoptyping -The primitives \tex{Umathbotaccent} and \tex{Umathaccents} are deprecated since -version 0.65, and will be removed eventually. - If a math top accent has to be placed and the accentee is a character and has a non-zero \type{top_accent} value, then this value will be used to place the accent instead of the \type{\skewchar} kern used by \TEX82. @@ -7590,8 +7905,8 @@ commands with explicit dollar sign(s). \subsection{Allowed math commands in non-math modes} -The commands \type{\mathchar}, \type{\omathchar}, and \type{\Umathchar} and control -sequences that are the result of \type{\mathchardef}, \type{\omathchardef}, or +The commands \type{\mathchar}, and \type{\Umathchar} and control +sequences that are the result of \type{\mathchardef} or \type{\Umathchardef} are also acceptable in the horizontal and vertical modes. In those cases, the \type{\textfont} from the requested math family is used. @@ -7702,7 +8017,7 @@ character, font, and component fields, and the new special fields like \stopitemize -Incidentally, \LUATEX\ allows 32768 separate languages, and words can +Incidentally, \LUATEX\ allows 16383 separate languages, and words can be 256 characters long. Because the \tex{uchyph} value is saved in the actual nodes, its @@ -8338,7 +8653,7 @@ components is itself a hash of up to five keys: \starttabulate[|lT|l|p|] \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR -\NC component \NC number \NC The character index (note that this is an encoding number, not a name).\NC \NR +\NC glyph \NC number \NC The character index (note that this is an encoding number, not a name).\NC \NR \NC extender \NC number \NC One (1) if this part is repeatable, zero (0) otherwise.\NC \NR \NC start \NC number \NC Maximum overlap at the starting side (in scaled points).\NC \NR \NC end \NC number \NC Maximum overlap at the ending side (in scaled points).\NC \NR @@ -8552,6 +8867,7 @@ allowed commands and their arguments are: \NC down \NC 1 \NC number \NC move down on the page\NC\NR \NC right \NC 1 \NC number \NC move right on the page\NC\NR \NC special \NC 1 \NC string \NC output a \tex{special} command\NC\NR +\NC lua \NC 1 \NC string \NC execute a \LUA\ script (at \tex{latelua} time)\NC\NR \NC image \NC 1 \NC image \NC output an image (the argument can be either an \type{<image>} variable or an \type{image_spec} table)\NC\NR \NC comment \NC any \NC any \NC the arguments of this command are ignored\NC\NR @@ -8692,7 +9008,7 @@ accessible fields: \stoptabulate These objects are reference counted, so there is actually an extra -field named \type {ref_count} as well. This item type will likely +read-only field named \type {ref_count} as well. This item type will likely disappear in the future, and the glue fields themselves will become part of the nodes referencing glue items. @@ -8744,7 +9060,7 @@ pdf start link objects. \NC file \NC string \NC \NC\NR \NC new_window \NC number \NC \NC\NR \NC data \NC string \NC \NC\NR -\NC ref_count \NC number \NC \NC\NR +\NC ref_count \NC number \NC (read-only)\NC\NR \stoptabulate \subsection{Main text nodes} @@ -8792,7 +9108,7 @@ linebreaking, 2 = explicit box command. (0.46.0), \NC glue_order \NC number \NC a number in the range 0--4, indicating the glue order\NC\NR \NC glue_set \NC number \NC the calculated glue ratio\NC\NR -\NC glue_sign \NC number \NC \NC\NR +\NC glue_sign \NC number \NC 0 = normal,1 = stretching,2 = shrinking \NC\NR \NC head \NC \syntax{<node>} \NC the first node of the body of this list\NC\NR \NC dir \NC string \NC the direction of this box. see~\in{}[dirnodes]\NC\NR \stoptabulate @@ -9025,11 +9341,10 @@ Valid bits for the \type{subtype} field are: \starttabulate[|c|l|] \NC \ssbf bit \NC \bf meaning \NC\NR \NC 0 \NC character \NC\NR -\NC 1 \NC glyph \NC\NR -\NC 2 \NC ligature \NC\NR -\NC 3 \NC ghost \NC\NR -\NC 4 \NC left \NC\NR -\NC 5 \NC right \NC\NR +\NC 1 \NC ligature \NC\NR +\NC 2 \NC ghost \NC\NR +\NC 3 \NC left \NC\NR +\NC 4 \NC right \NC\NR \stoptabulate See \in{section}[charsandglyphs] for a detailed description of the @@ -9820,6 +10135,9 @@ and \tex{pdfxformattr}, as an alternative to \tex{pdfxform} keywords. \startitemize +\item Starting with \LUATEX\ 0.75.0, the extended 16-bit math primitives + (\tex{omathcode} etc.~) have been removed. + \item Starting with \LUATEX\ 0.63.0, OCP processing is no longer supported at all. As a consequence, the following primitives have been removed: @@ -10031,4 +10349,4 @@ There used to be a lists of bugs and planned features below here, but that did n work out too well. There are lists of open bugs and feature requests in the tracker at \hyphenatedurl{http://tracker.luatex.org}. -\stoptext
\ No newline at end of file +\stoptext |