Source Browser ?

1% language=us runpath=texruns:manuals/luametatex
2
3\environment luametatex-style
4
5\startdocument[title=Metapost]
6
7\startsection[title={Introduction}]
8
9Four letters in the name \LUAMETATEX\ refer to the graphical subsystem \METAPOST,
10originally writen by John Hobby as follow up on \METAFONT. This library was
11introduced in \LUATEX\ in order to generate graphics runtime instead of via a
12separate system call. The library in \LUATEX\ is also used for the stand-alone
13program so it has a \POSTSCRIPT\ backend as well as font related frontend. The
14version used in \LUAMETATEX\ has neither. The lack of a backend can be explained
15from the fact that we have to provide one anyway: the \PDF\ output is generated
16by \LUA, which at that time was derived from the converter that I wrote for
17\PDFTEX, although there the starting point is the \POSTSCRIPT\ output. Removing
18the font related code also makes sense, because in \MKIV\ we never used it: we
19need to support \OPENTYPE\ and also want to use properly typeset text so we used
20a different approach (\type [option=MP] {textext} and friends).
21
22Another difference with the \LUATEX\ library is that we don't support the binary
23number model, which removes a dependency. We kept decimal number support and also
24opened that up to the \TEX\ end via \LUA. In addition we support the posit number
25model, mostly because we also have that at the \TEX\ end to suit the 32 bit
26model. The repertoire of scanners and injectors has been enlarged which makes it
27easier and more efficient to interface between the \LUAMETATEX\ subsystems. We
28also added functionality to \METAPOST, the language and processor. From the users
29perspective the library is downward compatible but at the same time it offers
30more.
31
32Just as \LUATEX\ is frozen, the \METAPOST\ library that it uses can be considered
33frozen. In \LUAMETATEX\ we have plans for some more extensions. We don't discuss
34the already present new functionality here in detail, for that we have separate
35manuals, organized under the \LUAMETAFUN\ umbrella. After all, most of what we
36did was done in the perspective of using \CONTEXT. Users don't use the functions
37discussed below because they only make sense in a more integrated approach as
38with \LUAMETAFUN.
39
40\stopsection
41
42\startsection[title={Instances}]
43
44Before you can process \METAPOST\ code an instance needs to be created. There can
45be multiple instances active at the same time. They are isolated from each other
46so they can use different number models and macro sets. Although you can do
47without files, normally you will load (for instance) macros from a file. This
48means that we need to interface the library to the file system. If we want to run
49\LUA, we need to be able to load \LUA\ code. All this is achieved via callbacks
50that have to be set up when an instance is created.
51
52\starttyping[option=LUA]
53function mplib.new (
54    {
55        random_seed    = <t:integer>,
56        interaction    = <t:string>,
57        job_name       = <t:string>,
58        find_file      = <t:function>,
59        open_file      = <t:function>,
60        run_script     = <t:function>,
61        run_internal   = <t:function>,
62        make_text      = <t:function>,
63        math_mode      = <t:string>,
64        utf8_mode      = <t:boolean>,
65        text_mode      = <t:boolean>,
66        show_mode      = <t:boolean>,
67        halt_on_error  = <t:boolean>,
68        run_logger     = <t:function>,
69        run_overload   = <t:function>,
70        run_error      = <t:function>,
71        run_warning    = <t:function>,
72        bend_tolerance = <t:number>,
73        move_tolerance = <t:number>,
74    }
75)
76    return <t:mp>
77end
78\stoptyping
79
80The library is fed with \METAPOST\ snippets via an \type {execute} function. We
81will discuss this in a while.
82
83\starttyping[option=LUA]
84function mplib.execute ( <t:mp> instance )
85    return <t:table> -- results
86end
87\stoptyping
88
89An instance can be released with:
90
91\starttyping[option=LUA]
92function mplib.finish ( <t:mp> instance )
93    return <t:table> -- results
94end
95\stoptyping
96
97Keeping an instance open is more efficient than creating one per graphic
98especially when a format has to be loaded. When you execute code, there can be
99results that for instance can be converted into \PDF\ and included in the
100currently made document. If one closes an instance it can be that there are
101pending results to take care of, although in practice that is unlikely to happen.
102
103When the \type {utf8_mode} parameter is set to \type {true} characters with codes
104128 upto 255 can be part of identifiers. There is no checking if we have valid
105\UTF\ but it permits to use that encoding. In \CONTEXT, of course, we enable
106this. When \type {text_mode} is \type {true} you can use the characters with
107\ASCII\ \type {STX} (2) and \type {ETC} (3) to fence string literals so that we
108can use double quotes in strings without the need to escape them. The \type
109{math_mode} parameter controls the number model that this instance will use.
110Valid values are \type {scaled} (default), \type {double} (default in \CONTEXT),
111\type {binary} (not supported), \type {decimal} (less performing but maybe
112useful) and \type {posit} (so that we can complements the \TEX\ end).
113
114Valid \type {interaction} values are \type {batch}, \type {nonstop}, \type
115{scroll}, \type {errorstop} (default) and \type {silent} but in \CONTEXT\ only
116the last one makes sense. Setting the \type {random_seed} parameter makes it
117possible to reproduce graphics and prevent documents to be different each run
118when the size of graphics are different due to randomization. The \type
119{job_name} parameter is used in reporting and therefore it is mandate.
120
121Both tolerance parameters default to \im {131 / 65536 = \cldcontext
122{"\letterpercent N", 131 / 65536}} and help to make the output smaller: \quote
123{bend} relate to straight lines and \quote {move} to effectively similar points.
124You can adapt the tolerance any time with:
125
126\starttyping[option=LUA]
127function mplib.settolerance (
128    <t:mp>     instance,
129    <t:number> bendtolerance,
130    <t:number> movetolerance
131)
132    -- no return values
133end
134\stoptyping
135
136\starttyping[option=LUA]
137function mplib.gettolerance ( <t:mp> instance )
138    return
139        <t:number>, -- bendtolerance
140        <t:number>  -- movetolerance
141end
142\stoptyping
143
144Next we detail the functions that are hooked into the instance because without
145them being passed to the engine not that much will happen. We start with the
146finder. Here \type {mode} is \type {w} or \type {r}. Normally a lookup of a file
147that is to be read from is done by a dedicated lookup mechanism that knows about
148the ecosystem the library operates in (like the \TEX\ Directory Structure).
149
150\starttyping[option=LUA]
151function find_file (
152    <t:string> filename,
153    <t:string> mode,
154    <t:string> filetype | <t:integer> index
155)
156    return <t:string> -- foundname
157end
158\stoptyping
159
160% todo filetype vs index
161
162A (located) file is opened with the \type {open_file} callback that has to
163return a table with a \type {close} method and a \type {reader} or a \type
164{writer} dependent of the \type {mode}.
165
166\starttyping[option=LUA]
167function open_file (
168    <t:string> filename,
169    <t:string> mode,
170    <t:string> filetype | <t:integer> index
171)
172    return {
173        close  = function()
174            -- return nothing
175        end,
176        reader = function()
177            return <t:string>
178        end,
179        writer = function(<t:string>)
180            -- return nothing
181        end
182    }
183end
184\stoptyping
185
186This approach is not that different from the way we do this at the \TEX\ so like
187there a reader normally returns lines. The way \METAPOST\ writes to and read from
188files using primitives is somewhat curious which is why the file type can be a
189number indicating what handle is used. However, apart from reading files that
190have code using \type [option=MP] {input} one hardly needs the more low level
191read and write related primitives.
192
193The runner is what makes it possible to communicate between \METAPOST\ and
194\LUA\ and thereby \TEX. There are two possible calls:
195
196\starttyping[option=LUA]
197function run_script ( <t:string> code | <t:integer> reference )
198    return <t:string> metapost
199end
200\stoptyping
201
202The second approach makes it possible to implement efficient interfaces where
203code is turned into functions that are kept around. At the \METAPOST\ end we
204therefore have, as in \LUATEX:
205
206\starttyping[option=MP]
207runscript "some code that will be loaded and run"
208% more code
209runscript "some code that will be loaded and run"
210\stoptyping
211
212which can of course be optimized by caching, but more interesting is:
213
214\starttyping[option=MP]
215newinternal my_function ; my_function := 123 ;
216runscript my_function ;
217% more code
218runscript my_function ;
219\stoptyping
220
221which of course has to be dealt with in \LUA. The return value can be a string but also
222a direct object:
223
224\starttyping[option=LUA]
225function run_script (
226    <t:string> code | <t:integer> reference,
227    <t:boolean> direct
228)
229    return
230        <t:boolean> | <t:number> | <t:string> | <t:table>, -- result
231        <t:boolean>                                        -- success
232end
233\stoptyping
234
235When the second argument is true, the results are injected directly and tables
236become pairs, colors, paths, transforms, depending on how many elements there
237are.
238
239In \METAPOST\ internal variables are quantities that are stored a bit differently
240and are accessed without using the expression scanner. The \type {run_internal}
241function triggers when internal \METAPOST\ variables flagged with \type
242{runscript} are initialized, saved or restored. The first argument is an action,
243the second the value of internal. When we initialize an internal a third and
244fourth argument are passed.
245
246\starttyping[option=LUA]
247function run_internal (
248    <t:integer> action,
249    <t:integer> internal,
250    <t:integer> category,
251    <t:string>  name
252)
253    -- no return values
254end
255\stoptyping
256
257The category is one of the types that \METAPOST\ also uses elsewhere: integer,
258boolean, numeric or known. From this you can deduce that internals in \LUAMETATEX\
259can not only be numbers but also strings or booleans. The possible actions are:
260
261\ctxlua{moduledata.mplib.codes("getinternalactions")}
262
263There is of course bit extra overhead involved than normal but that can be
264neglected especially because we can have more efficient calls to \LUA\ using
265references stored in internals. It also has the benefit that one can implement
266additional tracing.
267
268\METAPOST\ is a graphic language and system and typesetting text is not what it
269is meant for so that gets delegated to (for instance) \TEX\ using \type
270[option=MP] {btex} which grabs text upto \type [option=MP] {etex} and passes it
271to this callback:
272
273\starttyping[option=LUA]
274function make_text ( <t:string> str, <t:integer> mode )
275    return <t:string> -- metapost
276end
277\stoptyping
278
279Here mode is only relevant if you want to intercept \typ {verbatimtex} which is
280something that we don't recommend doing in \CONTEXT, just like we don't recommend
281using \type [option=MP] {btex}. But, if you use these, keep in mind that spaces
282matter. The parameter \type [option=MP] {texscriptmode} controls how spaces and
283newlines get honored. The default value is~1. Possible values are:
284
285\starttabulate[|l|p|]
286% \DB name      \BC meaning \NC \NR
287% \TB
288\FL
289\BC value      \BC meaning \NC \NR
290\ML
291\NC \type {0} \NC no newlines \NC \NR
292\NC \type {1} \NC newlines in \type [option=MP] {verbatimtex} \NC \NR
293\NC \type {2} \NC newlines in \type [option=MP] {verbatimtex} and \type [option=MP] {etex} \NC \NR
294\NC \type {3} \NC no leading and trailing strip in \type [option=MP] {verbatimtex} \NC \NR
295\NC \type {4} \NC no leading and trailing strip in \type [option=MP] {verbatimtex} and \type [option=MP] {btex} \NC \NR
296\LL
297\stoptabulate
298
299That way the \LUA\ handler (assigned to \type {make_text}) can do what it likes.
300An \type [option=MP] {etex} has to be followed by a space or \type [option=MP]
301{;} or be at the end of a line and preceded by a space or at the beginning of a
302line. But let's repeat: these commands are kind of old school and not to be used
303in \LUAMETAFUN.
304
305Logging, which includes the output of \type {message} and \type {show}, is also
306handled by a callback:
307
308\starttyping[option=LUA]
309function run_logger ( <t:integer> target, <t:string> str )
310    -- no return values
311end
312\stoptyping
313
314The possible log targets are:
315
316\ctxlua{moduledata.mplib.codes("getlogtargets")}
317
318An overload handler will take care of potentially dangerous overloading of for
319instance primitives, macro package definitions and special variables.
320
321\starttyping[option=LUA]
322function run_overload ( <t:integer> property, <t:string> name, <t:integer> mode )
323    return <t:boolean> -- resetproperty
324end
325\stoptyping
326
327The \type {mode} value is the currently set \type [option=MP] {overloadmode}
328internal. The \METAPOST\ command \typ [option=MP] {setproperty} can be used to
329relate an integer value to a quantity and when that value is positive a callback
330is triggered when that quantity gets redefined. Primitives get a property value~1
331by the engine.
332
333\startluacode
334context.starttabulate { "|rT|lT|" }
335for k, v in table.sortedhash(mplib.propertycodes) do
336    context.NC() context(k)
337    context.NC() context(v)
338    context.NC() context.NR()
339end
340context.stoptabulate()
341\stopluacode
342
343Overload protect is something very \CONTEXT\ and also present at the \TEX\ end.
344All \TEX\ and \METAPOST\ quantities have such properties assigned.
345
346When an error is issued it is often best to just quit the run and fix the issue,
347just because the instance can now be in a confused state,
348
349\starttyping[option=LUA]
350function run_error (
351    <t:string>  message,
352    <t:string>  helpinfo,
353    <t:integer> interactionmode
354)
355    -- no return values
356end
357\stoptyping
358
359You can get some statistics concerning an instance but in practice that is not so
360relevant for users. In \CONTEXT\ these go to the log file.
361
362\starttyping[option=LUA]
363function mplib.getstatistics ( <t:mp> instance )
364    return <t:table>
365end
366\stoptyping
367
368The next set of numbers reflect for the current state of the \type {metafun:1}
369instance that is active for this specific run.
370
371\startthreerows
372\startluacode
373local t = mplib.getstatistics(metapost.getinstancebyname("metafun:1"))
374context.starttabulate { "|l|r|" }
375    for k, v in table.sortedhash(t) do
376        context.NC() context(k)
377        context.NC() context(v)
378        context.NC() context.NR()
379    end
380context.stoptabulate()
381\stopluacode
382\stopthreerows
383
384In this version of \MPLIB\ this is informational only. The objects are all
385allocated dynamically, so there is no chance of running out of space unless the
386available system memory is exhausted. There is no need to configure memory.
387
388The scanner in an instance can be in a specific state:
389
390\starttyping[option=LUA]
391function mplib.getstatus ( <t:mp> instance )
392    return <t:integer>
393end
394\stoptyping
395
396where possible states are:
397
398\startfourrows
399    \ctxlua{moduledata.mplib.codes("getstates")}
400\stopfourrows
401
402Macro names and variable names are stored in a hash table. You can get a list
403with entries with \type {gethashentries}, which takes an instance as first
404argument. When the second argument is \type {true} more details will be provided.
405With \type {gethashentry} you get info about the given macro or variable.
406
407\starttyping[option=LUA]
408function mplib.gethashentries ( <t:mp> instance, <t:boolean> details )
409    <t:table> hashentries
410end
411\stoptyping
412
413\starttyping[option=LUA]
414function mplib.gethashentry ( <t:mp> instance, <t:string> name )
415    return
416        <t:integer> -- command
417        <t:integer> -- property
418        <t:integer> -- subcommand
419end
420\stoptyping
421
422Say that we have defined:
423
424\starttyping[option=MP]
425numeric a ; numeric b ; numeric c ; a = b ; c := b ;
426\stoptyping
427
428\startMPcalculation
429    numeric a ; numeric b ; numeric c ; a = b ; c := b ;
430\stopMPcalculation
431
432We get values like:
433
434\startluacode
435local r = {
436    { "a",          mplib.gethashentry(metapost.getinstancebyname("metafun:1"),"a") },
437    { "b",          mplib.gethashentry(metapost.getinstancebyname("metafun:1"),"b") },
438    { "c",          mplib.gethashentry(metapost.getinstancebyname("metafun:1"),"c") },
439    { "d",          mplib.gethashentry(metapost.getinstancebyname("metafun:1"),"d") },
440    { "def",        mplib.gethashentry(metapost.getinstancebyname("metafun:1"),"def") },
441    { "vardef",     mplib.gethashentry(metapost.getinstancebyname("metafun:1"),"vardef") },
442    { "fullcircle", mplib.gethashentry(metapost.getinstancebyname("metafun:1"),"fullcircle") },
443}
444context.starttabulate { "|T|r|r|r|" }
445for i=1,#r do
446    context.NC() context(r[i][1])
447    context.NC() context(r[i][2])
448    context.NC() context(r[i][3])
449    context.NC() context(r[i][4])
450    context.NC() context.NR()
451end
452context.stoptabulate()
453\stopluacode
454
455These numbers represent commands, properties and subcommands, and thereby also
456assume some knowledge about how \METAPOST\ works internally. As this kind of
457information is only useful when doing low level development we leave it at that.
458
459\stopsection
460
461\startsection[title=Processing]
462
463It is up to the user to decide what to pass to the \type {execute} function as
464long as it is valid code. Think of each chunk being a syntactically correct file.
465Statements cannot be split over chunks.
466
467\starttyping[option=LUA]
468function mplib.execute ( <t:mp> instance, <t:string> code )
469    return {
470        status = <t:integer>,
471        fig    = <t:table>,
472    }
473end
474\stoptyping
475
476In contrast with the normal stand alone \type {mpost} command, there is no
477implied \quote {input} at the start of the first chunk. When no string is passed
478to the execute function, there will still be one triggered because it then
479expects input from the terminal and you can emulate that channel with the
480callback you provide. In practice this is not something you need to be worry
481about.
482
483When code is fed into the library at some point it will shipout a picture. The
484result always has a \type {status} field and an indexed \type {fig} table that
485has the graphics produced, although that is not mandate, for instance macro
486definitions can happen or variables can be set in which case graphics will be
487constructed later.
488
489\starttyping[option=LUA]
490<t:userdata> o = <t:mpobj>:objects     ( )
491<t:table>    b = <t:mpobj>:boundingbox ( )
492<t:number>   w = <t:mpobj>:width       ( )
493<t:number>   h = <t:mpobj>:height      ( )
494<t:number>   d = <t:mpobj>:depth       ( )
495<t:number>   i = <t:mpobj>:italic      ( )
496<t:integer>  c = <t:mpobj>:charcode    ( )
497<t:number>   t = <t:mpobj>:tolerance   ( )
498<t:boolean>  s = <t:mpobj>:stacking    ( )
499\stoptyping
500
501When you access a object that object gets processed before its properties are
502returned and in the process we loose the original. This means that some
503information concerning the whole graphic is also no longer reliably available.
504For instance, you can check if a figure uses stacking with the \type {stacking}
505function but because objects gets freed after being accessed, no information
506about stacking is available then.
507
508The \type {charcode}, \type {width}, \type {height}, \type {depth} and \type
509{italic} are a left-over from \METAFONT. They are values of the \METAPOST\
510variables \typ [option=MP] {charcode}, \typ [option=MP] {fontcharwd}, \typ
511[option=MP] {fontcharht}, \typ [option=MP] {fontchardp} and \typ [option=MP]
512{fontcharit} at the time the graphic is shipped out.
513
514You can call \type {fig:objects()} only once for any one \type {fig} object! In
515the end the graphic is a list of such userdata objects with accessors that
516depends on what specific data we have at hand. You can check out what fields with
517the following helper:
518
519\starttyping[option=LUA]
520function mplib.getfields ( <t:integer> object | <t:mpobj> object | <t:nil> )
521    return <t:table>
522end
523\stoptyping
524
525You get a simple table with one list of fields, or a table with all possible
526fields, organized per object type. In practice this helper is only used for
527documentation.
528
529\startluacode
530    local t = mplib.getobjecttypes()
531    local f = mplib.getfields()
532    context.starttabulate { "|lT|lT|plT|" }
533    for i=1,#t do
534        context.NC() context(i)
535        context.NC() context(t[i])
536        context.NC() context("% t",f[i])
537        context.NC() context.NR()
538    end
539    context.stoptabulate()
540\stopluacode
541
542All graphical objects have a field \type {type} (the second column in the table
543above) that gives the object type as a string value. When you have a non circular
544pen an envelope is uses defined by \type {path} as well as \type {htap} and the
545backend has to make sure that this gets translated into the proper \PDF\
546operators. Discussing this is beyond this manual. A \type {color} table has one,
547three or four values depending on the color space used. The \typ {prescript} and
548\typ {postscript} strings are the accumulated values of these operators,
549separated by newline characters. The \typ {stacking} number is just that: a
550number, which can be used to put shapes in front or other shapes, some order, but
551it depends on the macro package as well as the backend to deal with that; it's
552basically just a numeric tag.
553
554Each \type {dash} is a hash with two items. We use the same model as \POSTSCRIPT\
555for the representation of the dash list; \type {dashes} is an array of \quote
556{on} and \quote {off}, values, and \type {offset} is the phase of the pattern.
557
558There is helper function \type {peninfo} that returns a table containing a bunch
559of vital characteristics of the used pen:
560
561\starttyping[option=LUA]
562function mplib.peninfo ( <t:mpobj> object )
563    return {
564        width = <t:number>,
565        rx    = <t:number>,
566        ry    = <t:number>,
567        sx    = <t:number>,
568        sy    = <t:number>,
569        tx    = <t:number>,
570        ty    = <t:number>,
571    }
572end
573\stoptyping
574
575\stopsection
576
577\startsection[title=Internals]
578
579There are a couple of helpers that can be used to query the meaning of specific
580codes and states.
581
582\starttyping[option=LUA]
583function mplib.gettype ( <mopobj> object )
584    return <t:integer> -- typenumber
585end
586\stoptyping
587
588\starttyping[option=LUA]
589function mplib.gettypes ( )
590    return <t:table> -- types
591end
592\stoptyping
593
594\startfourrows
595    \ctxlua{moduledata.mplib.codes("gettypes")}
596\stopfourrows
597
598\starttyping[option=LUA]
599function mplib.getcolormodels ( )
600    return <t:table> -- colormodels
601end
602\stoptyping
603
604\startfourrows
605    \ctxlua{moduledata.mplib.codes("getcolormodels")}
606\stopfourrows
607
608\starttyping[option=LUA]
609function mplib.getcodes ( )
610    return <t:table> -- codes
611end
612\stoptyping
613
614\startfourrows
615    \ctxlua{moduledata.mplib.codes("getcodes")}
616\stopfourrows
617
618\starttyping[option=LUA]
619function mplib.getstates ( )
620    return <t:table> -- states
621end
622\stoptyping
623
624\startfourrows
625    \ctxlua{moduledata.mplib.codes("getstates")}
626\stopfourrows
627
628Knots is how the \quote {points} in a curve are called internally and in paths we
629can find these:
630
631\starttyping[option=LUA]
632function mplib.getknotstates ( )
633    return <t:table> -- knotstates
634end
635\stoptyping
636
637\startfourrows
638    \ctxlua{moduledata.mplib.codes("getknotstates")}
639\stopfourrows
640
641\starttyping[option=LUA]
642function mplib.getscantypes ( )
643    return <t:table> -- scantypes
644end
645\stoptyping
646
647\startfourrows
648    \ctxlua{moduledata.mplib.codes("getscantypes")}
649\stopfourrows
650
651As with \TEX\ we can log to the console, a log file or both. But one will normally
652intercept log message anyway.
653
654\starttyping[option=LUA]
655function mplib.getlogtargets ( )
656    return <t:table> -- logtargets
657end
658\stoptyping
659
660\startfourrows
661    \ctxlua{moduledata.mplib.codes("getlogtargets")}
662\stopfourrows
663
664\starttyping[option=LUA]
665function mplib.getinternalactions ( )
666    return <t:table> -- internalactions
667end
668\stoptyping
669
670\startfourrows
671    \ctxlua{moduledata.mplib.codes("getinternalactions")}
672\stopfourrows
673
674\starttyping[option=LUA]
675function mplib.getobjecttypes ( )
676    return <t:table> -- objecttypes
677end
678\stoptyping
679
680\startfourrows
681    \ctxlua{moduledata.mplib.codes("getobjecttypes")}
682\stopfourrows
683
684The next one is of course dependent on what one runs. These statistics are for
685all instances:
686
687\starttyping[option=LUA]
688function mplib.getcallbackstate ( )
689    return <t:table> -- callbackstate
690end
691\stoptyping
692
693\starttworows
694    \ctxlua{moduledata.mplib.codes("getcallbackstate")}
695\stoptworows
696
697The text counter is only counting what gets intercepted by \METAPOST\ and as you
698can see below, the recommended \type {textext} is handled differently and not
699counted at all.
700
701\startlinecorrection
702\startcombination[nx=2,ny=1,width=.4tw]
703  {\startMPcode
704      fill fullcircle xyscaled (4cm,2cm) withcolor "maincolor" ;
705      draw textext("okay") withcolor "white" ;
706   \stopMPcode} {intercepted by \CONTEXT}
707  {\startMPcode
708      fill fullcircle xyscaled (4cm,2cm) withcolor "maincolor" ;
709      draw btex okay etex withcolor "white" ;
710   \stopMPcode} {intercepted by \METAPOST}
711\stopcombination
712\stoplinecorrection
713
714So we get this now. The file count goes up because from the perspective of
715\METAPOST\ code that gets executed and passed as string is just like reading from
716file. The relative high number that we see here reflects that we load quite some
717\METAFUN\ macros when an instance is initialized.
718
719\startthreerows
720    \ctxlua{moduledata.mplib.codes("getcallbackstate")}
721\stopthreerows
722
723\stopsection
724
725\startsection[title=Information]
726
727The \METAPOST\ library in \LUATEX\ starts with version~2 so in \LUAMETATEX\ we
728start with version~3, assuming that there will me no major update to the older
729library.
730
731\starttyping[option=LUA]
732function mplib.version ( )
733    return <t:string>
734end
735\stoptyping
736
737When there is an error you can ask for some more context:
738
739\starttyping[option=LUA]
740function mplib.showcontext ( <t:mp> instance )
741    return <t:string>
742end
743\stoptyping
744
745\stopsection
746
747\startsection[title=Methods]
748
749For historical reasons we provide a few functions as methods to an instance: \typ
750{execute}, \typ {finish}, \typ {getstatistics}, \typ {getstatus} and \typ
751{solvepath}, just in case someone goes low level.
752
753\stopsection
754
755\startsection[title=Scanners]
756
757There are quite some scanners available and they all take an instance as first
758argument. Some have optional arguments that give some control. A very basic one
759is the following. Scanning for a next token in \METAPOST\ is different from \TEX\
760because while \TEX\ just gets the token, \METAPOST\ can delay in cases where an
761expression is seen. This means that you can inspect what is coming but do some
762further scanning based on that. Examples of usage can be found in \CONTEXT\ as it
763permits to come up with extensions that behave like new primitives or implement
764interfaces that are otherwise hard to do in pure \METAPOST.
765
766\starttyping[option=LUA]
767function mplib.scannext ( <t:mp> instance, <t:boolean> keep )
768    return <t:integer> token, <t:integer> mode, <t:integer> kind
769end
770\stoptyping
771
772here the optional \type {keep} boolean argument default to false but when true we
773basically have a look ahead scan. Contrary to \TEX\ a next token is not expanded. If we
774want to pick up the result from an expression we use the next one where again we can
775push back the result:
776
777\startfourrows
778    \ctxlua{moduledata.mplib.codes("getscantypes")}
779\stopfourrows
780
781\starttyping[option=LUA]
782function mplib.scanexpression ( <t:mp> instance, <t:boolean> keep )
783    return <t:integer> -- kind
784end
785\stoptyping
786
787The difference between \typ {scantoken} and \typ {scannext} is that the first one
788scans for a token and the later for a value and yes, one has to play a bit with
789this to see when one gets what.
790
791\starttyping[option=LUA]
792function mplib.scantoken ( <t:mp> instance, <t:boolean> keep )
793    return
794        <t:integer>, -- token
795        <t:integer>, -- mode
796        <t:integer>  -- kind
797end
798\stoptyping
799
800\starttyping[option=LUA]
801function mplib.scansymbol ( <t:mp> instance, <t:boolean> expand, <t:boolean> keep )
802    return <t:string>
803end
804\stoptyping
805
806\starttyping[option=LUA]
807function mplib.scanproperty ( <t:mp> instance )
808    return <t:integer>
809end
810\stoptyping
811
812These are scanners for the simple data types:
813
814\starttyping[option=LUA]
815function mplib.scannumeric ( <t:mp> instance ) return <t:number>  end -- scannumber
816function mplib.scaninteger ( <t:mp> instance ) return <t:integer> end
817function mplib.scanboolean ( <t:mp> instance ) return <t:boolean> end
818function mplib.scanstring  ( <t:mp> instance ) return <t:string>  end
819\stoptyping
820
821The scanners that return data types with more than one value can will return a
822table when the second argument is \type {true}:
823
824\starttyping[option=LUA]
825function mplib.scanpair ( <t:mp> instance, <t:boolean astable )
826    return
827        <t:number>, -- x
828        t:number>   -- y
829end
830\stoptyping
831
832\starttyping[option=LUA]
833function mplib.scancolor (
834    <t:mp>      instance,
835    <t:boolean astable
836)
837    return
838        <t:number>, -- r
839        <t:number>, -- g
840        <t:number>  -- b
841end
842\stoptyping
843
844\starttyping[option=LUA]
845function mplib.scancmykcolor ( <t:mp> instance, <t:boolean astable )
846    return
847        <t:number>, -- c
848        <t:number>, -- m
849        <t:number>, -- y
850        <t:number>  -- k
851end
852\stoptyping
853
854\starttyping[option=LUA]
855function mplib.scantransform ( <t:mp> instance, <t:boolean astable )
856    return
857        <t:number>, -- x
858        <t:number>, -- y
859        <t:number>, -- xx
860        <t:number>, -- yx
861        <t:number>, -- xy
862        <t:number>  -- yy
863end
864\stoptyping
865
866The path scanned is more complex. First an expression is scanned and when okay
867it is converted to a table. The compact option gives:
868
869\starttyping[option=LUA]
870{
871    cycle = <t:boolean>, -- close
872    pen   = <t:boolean>,
873    {
874        <t:number>, -- x_coordinate
875        <t:number>, -- y_coordinate
876    },
877    ...
878}
879\stoptyping
880
881otherwise we get the more detailed:
882
883\starttyping[option=LUA]
884{
885    curved = <t:boolean>,
886    pen    = <t:boolean>,
887    {
888        [1]        = <t:number>,  -- x_coordinate
889        [2]        = <t:number>,  -- y_coordinate
890        [3]        = <t:number>,  -- x_left
891        [4]        = <t:number>,  -- y_left
892        [5]        = <t:number>,  -- x_right
893        [6]        = <t:number>,  -- y_right
894        left_type  = <t:integer>,
895        right_type = <t:integer>,
896        curved     = <t:boolean>,
897        state      = <t:integer>,
898    },
899    ...
900}
901\stoptyping
902
903Possible (knot, the internal name for a point) states are:
904
905\startfourrows
906\ctxlua{moduledata.mplib.codes("getknotstates")}
907\stopfourrows
908
909The path scanner function that produces such tables is:
910
911\starttyping[option=LUA]
912function mplib.scanpath (
913    <t:mp>      instance,
914    <t:boolean> compact,
915    <t:integer> kind,
916    <t:boolean> check
917)
918    return <t:table>
919end
920\stoptyping
921
922This pen scanner returns similar tables:
923
924\starttyping[option=LUA]
925function mplib.scanpen (
926    <t:mp>      instance,
927    <t:boolean> compact,
928    <t:integer> kind,
929    <t:boolean> check
930)
931    return <t:table>
932end
933\stoptyping
934
935The next is not really a scanner. It skips a token that matches the given command
936and returns a boolean telling if that succeeded.
937
938\starttyping[option=LUA]
939function mplib.skiptoken ( <t:mp> instance, <t:integer> command )
940    return <t:boolean>
941end
942\stoptyping
943
944\stopsection
945
946\startsection[title=Injectors]
947
948The scanners are complemented by injectors. Instead of strings that have to be
949parsed by \METAPOST\ they inject the right data structures directly.
950
951\starttyping[option=LUA]
952function mplib.injectnumeric ( <t:mp> instance, <t:number>  value ) end
953function mplib.injectinteger ( <t:mp> instance, <t:integer> value ) end
954function mplib.injectboolean ( <t:mp> instance, <t:boolean> value ) end
955function mplib.injectstring  ( <t:mp> instance, <t:string>  value ) end
956\stoptyping
957
958In following injectors accept a table as well as just the values. which can more
959efficient:
960
961\starttyping[option=LUA]
962function mplib.injectpair      ( <t:mp> instance, <t:table> value ) end
963function mplib.injectcolor     ( <t:mp> instance, <t:table> value ) end
964function mplib.injectcmykcolor ( <t:mp> instance, <t:table> value ) end
965function mplib.injecttransform ( <t:mp> instance, <t:table> value ) end
966\stoptyping
967
968Injecting a path is not always trivial because we have to connect the points
969emulating \type [option=MP] {..}, \type [option=MP] {...}, \type [option=MP]
970{---} and even \type [option=MP] {&&} and \type [option=MP] {cycle}. A path is
971passed as table. The table can be nested and has entries like these:
972
973\starttyping[option=LUA]
974{
975    {
976        x_coord       = <t:number>,
977        y_coord       = <t:number>,
978        x_left        = <t:number>,
979        y_left        = <t:number>,
980        x_right       = <t:number>,
981        y_right       = <t:number>,
982        left_curl     = <t:number>,
983        right_curl    = <t:number>,
984        left_tension  = <t:number>,
985        right_tension = <t:number>,
986        direction_x   = <t:number>,
987        direction_y   = <t:number>,
988    },
989    {
990        [1] = <t:number>, -- x_coordinate
991        [2] = <t:number>, -- x_coordinate
992        [3] = <t:number>, -- x_left
993        [4] = <t:number>, -- y_left
994        [5] = <t:number>, -- x_right
995        [6] = <t:number>, -- y_right
996    },
997    "append",
998    "cycle",
999}
1000\stoptyping
1001
1002Here \type [option=MP] {append} is like \type [option=MP] {&&} which picks up the
1003pen, and \type [option=MP] {cycle}, not surprisingly, behaves like the \type
1004[option=MP] {cycle} operator.
1005
1006\starttyping[option=LUA]
1007function mplib.injectpath ( <t:mp> instance,  <t:table> value )
1008    -- return nothing
1009end
1010\stoptyping
1011
1012\starttyping[option=LUA]
1013function mplib.injectwhatever ( <t:mp> instance, <t:hybrid> value )
1014    -- return nothing
1015end
1016\stoptyping
1017
1018When a path is entered and has to be injected some preparation takes place out of
1019the users sight. A special variant of the path processor is the following, where
1020the path is adapted and the boolean indicates success.
1021
1022\starttyping[option=LUA]
1023function mplib.solvepath ( <t:mp> instance, <t:table> value )
1024    return <t:boolean>
1025end
1026\stoptyping
1027
1028A still somewhat experimental injectors is the following one, that can be used to
1029fetch information from the \TEX\ end. Valid values for \type {expected} are 1
1030(integer), 2 (cardinal, 3 (dimension), 5 (boolean) and 7 (string).
1031
1032\starttyping[option=LUA]
1033function mplib.expandtex (
1034    <t:mp>       instance,
1035    <t:integer>  expected,
1036    <t:string>   macro,
1037    <t:whatever> arguments
1038)
1039    return <t:whatever>
1040end
1041\stoptyping
1042
1043\stopsection
1044
1045\stopdocument
1046