Source Browser ?

1% language=us
2
3\usemodule[present-boring,abbreviations-logos]
4
5\setuptolerance[verytolerant,stretch]
6
7\startdocument
8  [title={LUAMETAFUN},
9   banner={the new interfaces},
10   location={context\enspace {\bf 2021}\enspace meeting}]
11
12\starttitle[title=Three subsystems]
13
14\startitemize
15
16\startitem
17    The core of the engine in still \TEX. It all starts there.
18\stopitem
19
20\startitem
21    The \TEX\ internals are opened up via \LUA. We can call out to \LUA\ from
22    \TEX\ and to some extend from \LUA\ to \TEX. Quite often we push back
23    something via the input channels.
24\stopitem
25
26\startitem
27    The \METAPOST\ library is accessed from \LUA. So from within \TEX\ there is
28    always \LUA\ in between. Results go back via \LUA. The library can also call
29    out to \LUA\ and from there to \TEX.
30\stopitem
31
32\startitem
33    This means that all three major components of \LUAMETATEX\ can talk to each
34    other and use each others capabilities.
35\stopitem
36
37\startitem
38    With \LUA\ in the center, we also have access to other mechanism, for instance
39    fonts, graphics and libraries.
40\stopitem
41
42\startitem
43    In \CONTEXT\ the \LUA\ language also permits using \XML, \JSON, \CSV, \SQL\
44    databases and other input that can be dealt with programmatically.
45\stopitem
46
47\startitem
48    All has been reasonably optimized for efficiency and performance.
49\stopitem
50
51\stopitemize
52
53\stoptitle
54
55\starttitle[title=The (\LUATEX) library]
56
57\startitemize
58
59\startitem
60    Turning \METAPOST\ into a library has been a subproject of the \LUATEX\ project. The
61    semi|-|official team (Taco, Jacko, Hans, Luigi) got John Hobbies blessing.
62\stopitem
63
64\startitem
65    This was a rather massive (and impressive) operation by Taco because multiple
66    number models were to be supported and the internals had to be made such that
67    different backends were possible. All with remaining perfect (DEK) compatibility.
68\stopitem
69
70\startitem
71    The \METAPOST\ library serves both the stand alone program and \LUATEX.
72\stopitem
73
74\startitem
75    That means the \POSTSCRIPT\ backend is built in plus some basic (\TYPEONE)
76    font handling. We support \PDF\ output via the \METAPOST\ \LUA\ backend (in
77    \MKII\ that is done by parsing the \POSTSCRIPT\ and specials).
78\stopitem
79
80\startitem
81    In addition there is \PNG\ and \SVG\ output. It helps that \METAPOST\ output is
82    rather simple.
83\stopitem
84
85\startitem
86    The \LUATEX\ engine uses the \LUA\ backend which represents the result in \LUA\ tables
87    resembling the \METAPOST\ internal representation.
88\stopitem
89
90\startitem
91    The library supports scaled and double (internal) but also binary and decimal
92    number models that use (linked in) libraries.
93\stopitem
94
95% this would force a page
96%
97% \startitem
98%     The library is quite stable and Taco transferred maintenance to Luigi.
99% \stopitem
100
101\stopitemize
102
103\stoptitle
104
105\starttitle[title=The (\LUAMETATEX) library]
106
107\startitemize
108
109\startitem
110    We don't need the \POSTSCRIPT\ backend (which only does \TYPEONE\ anyway).
111\stopitem
112
113\startitem
114    We also have no use for \SVG\ and \PNG\ output.
115\stopitem
116
117\startitem
118    The binary number model has no advantages over the decimal one but brings
119    quite some dependency with it (library code).
120\stopitem
121
122\startitem
123    The \TYPEONE\ font support is not used in \CONTEXT\ because we handle text
124    differently.
125\stopitem
126
127\startitem
128    All this means that we can do with a smaller (simplified) \METAPOST\ library.
129\stopitem
130
131\startitem
132    The codebase has been overhauled. We still have \type {.w} files (\CWEB) but
133    use a \LUA\ script to convert that to \CCODE\ which means that we have better
134    control over how it comes out.
135\stopitem
136
137\startitem
138    As with \LUATEX\ the file \IO, message handling etc.\ now largely goes via \LUA;
139    it is more integrated.
140\stopitem
141
142\startitem
143    The same is true for scanning interfaces and return values (injectors). That also
144    made for more symbolic coding.
145\stopitem
146
147\startitem
148    Memory management (allocation) is under engine control (as with \TEX\ and \LUA);
149    we use a common high performance allocator library.
150\stopitem
151
152\stopitemize
153
154\stoptitle
155
156\starttitle[title=The (\LUAMETATEX) library]
157
158\startitemize
159
160\startitem
161    Some already present mechanism have been extended, for instance clips have
162    pre- and postscripts.
163\stopitem
164
165\startitem
166    A grouping wrapper has been added (handy for some graphic trickery supported in the
167    backend.)
168\stopitem
169
170\startitem
171    The \type {runscript} primitive supports symbolic references to functions (of course to
172    be provided at the \LUA\ end).
173\stopitem
174
175\startitem
176    The \type {runscript} return values can be more native, in addition to the already
177    present (default) \type {scantokens} support.
178\stopitem
179
180\startitem
181    Internals are extended with booleans and strings.
182\stopitem
183
184\startitem
185    Output (paths, clips etc) can be stacked in a different order.
186\stopitem
187
188\startitem
189    There are additional statistics available.
190\stopitem
191
192\startitem
193    In some places performance could be improved.
194\stopitem
195
196\startitem
197    In the meantime it can be considered a major upgrade and (for various
198    reasons) backporting to \LUATEX\ makes no sense. And yes, all errors are
199    mine.
200\stopitem
201
202\stopitemize
203
204\starttitle[title=The \LUA fication]
205
206    {\em See Taco's presentation where he gives some examples.}
207
208\stoptitle
209
210\starttitle[title=Callbacks]
211
212We need to hook in some functions: \blank[2*big]
213
214\starttabulate[|T|T|T|p|]
215    \HL
216    \NC   \NC find_file    \NC (name,mode,kind)           \NC locate a file (usually within the \TDS\ setup) \NC \NR
217    \NC f \NC open_file    \NC (name,mode,kind)           \NC open given file \NC \NR
218    \NC   \NC close_file   \NC (handle)                   \NC close opened file \NC \NR
219    \NC s \NC read_file    \NC (handle,size)              \NC read from file \NC \NR
220    \NC   \NC write_file   \NC (handle,str)               \NC write to file \NC \NR
221    \HL
222    \NC s \NC run_script   \NC (code,size,index)          \NC run the given string as \LUA\ script \NC \NR
223    \NC s \NC make_text    \NC (str,size,mode)            \NC process btex/etex \NC \NR
224    \HL
225    \NC   \NC run_internal \NC (action,index,kind,name)   \NC act on internal definition \NC \NR
226    \HL
227    \NC n \NC run_overload \NC (property,name,mode)       \NC process overload check \NC \NR
228    \HL
229    \NC   \NC run_logger   \NC (target,str,size)          \NC process log message \NC \NR
230    \NC   \NC run_error    \NC (message,help,interaction) \NC handle error (message) \NC \NR
231    \NC   \NC run_warning  \NC (message)                  \NC handle warning \NC \NR
232    \HL
233\stoptabulate
234
235% check_overload shipout_backend
236
237\stoptitle
238
239\starttitle[title=Two calling methods]
240
241The runner can be called as:
242
243\starttyping
244runscript("mp.MyFunction()")
245\stoptyping
246
247which implies at the \LUA\ end:
248
249\starttyping
250function mp.MyFunction()
251    ...
252end
253\stoptyping
254
255Here the callback function is responsible for loading the string and executing it.
256
257Alternatively one can say:
258
259\starttyping
260runscript <number>
261\stoptyping
262
263The number can be intercepted at the \LUA\ end to do some associated action.
264
265\stoptitle
266
267\starttitle[title=Variables]
268
269We can do:
270
271\starttyping
272lua.mp.MyFunction("foo",123,true)
273\stoptyping
274
275which in the end is equivalent to:
276
277\starttyping
278runscript("mp.MyFunction('foo',123,true)")
279\stoptyping
280
281Alternatively one can pick up values by scanning: like \type {scannext}, \type
282{scanexpression}, \type {scantoken}, \type {scansymbol}, \type {scannumeric},
283\type {scaninteger}, \type {scanboolean}, \type {scanstring}, \type {scanpair},
284\type {scancolor}, \type {scancmykcolor}, \type {scantransform}, \type
285{scanpath}, \type {scanpen}, etc.
286
287\stoptitle
288
289\starttitle[title=Return values]
290
291The runner can return:
292
293\startitemize
294
295\startitem
296    a string that gets fed into the \type {scantokens} primitive
297\stopitem
298
299\startitem
300    a numeric or boolean that gets injected as native \METAPOST\ object
301\stopitem
302
303\startitem
304    a table that gets concatenated and fed into the \type {scantokens} primitive
305\stopitem
306
307\startitem
308    \type {true} and a second argument that gets converted into a native \METAPOST\ object
309\stopitem
310
311\startitem
312    in the last case the number of table elements determines the object
313\stopitem
314
315\stopitemize
316
317Instead of returning a value one can inject: \type {injectnumeric}, \type
318{injectinteger}, \type {injectboolean}, \type {injectstring}, \type {injectpair},
319\type {injectcolor}, \type {injectcmykcolor}, \type {injecttransform}, \type
320{injectpath}, \type {injectwhatever}, etc.\ and these accept one or more values
321and|/|or tables.
322
323These mechanisms might evolve a bit over time. Lots of examples can be found in
324the \type {mlib-*.lmt} files.
325
326\stoptitle
327
328\starttitle[title=Parameters]
329
330\startitemize
331    \startitem
332        The new interfaces permit us to program quite robust parameter driven
333        interfaces that (sort of) match the way we do things at the \TEX\ end.
334    \stopitem
335    \startitem
336        The distribution has several examples of usage and more will be added.
337    \stopitem
338    \startitem
339        Macros that use the new mechanisms can be recognized by the \type {lmt_}
340        prefix.
341    \stopitem
342\stopitemize
343
344\starttyping
345lmt_mytrick [
346    somestring  = "test",
347    somenumeric = 123,
348    someboolean = true,
349    somecolor   = (1, 0, 1),
350    somepath    = fullsquare scaled 10cm,
351    somelist    = { (0, 0), (1, 3), (8, 9) },
352    sometable   = [
353        somenumeric = 321,
354   ],
355] ;
356\stoptyping
357
358{\em Show the pattern of defining these at the \LUA\ end and in \METAPOST\ files.}
359
360\stoptitle
361
362\stopdocument
363