SourceBrowser

luametatex-metapost.tex /size: 28 Kb last modification: 2021-10-28 13:50
1% language=us runpath=texruns:manuals/luametatex
2
3\environment luametatex-style
4
5\startcomponent luametatex-metapost
6
7\startluacode
8    function document.showmpcodes(what)
9        context.type("mplib."..what.."()")
10        context(": ")
11        local t = mplib[what]()
12        for i=0,#t do
13            if i > 0 then
14                context(", ")
15            end
16            context("%i: %s",i,t[i])
17        end
18    end
19\stopluacode
20
21\startchapter[reference=metapost,title={The \METAPOST\ library \type {mplib}}]
22
23\startsection[title={Introduction}][library=mplib]
24
25The library used in \LUAMETATEX\ differs from the one used in \LUATEX. There are
26for instance no backends and the binary number model is not available. There is
27also no textual output. There are scanners and injectors that make it possible to
28enhance the language and efficiently feed back into \METAPOST. File handling is
29now completely delegated to \LUA, so there are more callbacks.
30
31{\em Some functionality is experimental and therefore documentation is limited.
32Also, details are discussed in articles.}
33
34\stopsection
35
36\startsection[title={Process management}][library=mplib]
37
38\topicindex {\METAPOST}
39\topicindex {\METAPOST+mplib}
40\topicindex {images+mplib}
41\topicindex {images+\METAPOST}
42
43\libindex{version}
44
45The \METAPOST\ library interface registers itself in the table \type {mplib}. It
46is based on \MPLIB\ version \ctxlua {context(mplib.version())} (\LUATEX\ used
47version 2+). Not all functionality is described here. Once we're out of the
48experimental stage some more information will be added. Using the library boils
49down to initializing an instance, executing statements and picking up assembled
50figures in the form of \LUA\ user data objects (and from there on \LUA\ variables
51like tables).
52
53
54\startsubsection[title={\type {new}}]
55
56\libindex{new}
57
58To create a new \METAPOST\ instance, call
59
60\startfunctioncall
61<mpinstance> mp = mplib.new({...})
62\stopfunctioncall
63
64This creates the \type {mp} instance object. The argument is a hash table that
65can have a number of different fields, as follows:
66
67\starttabulate[|l|l|pl|pl|]
68\DB name                 \BC type     \BC description                \BC default           \NC \NR
69\TB
70\NC \type {error_line}   \NC number   \NC error line width           \NC 79                \NC \NR
71\NC \type {print_line}   \NC number   \NC line length in ps output   \NC 100               \NC \NR
72\NC \type {random_seed}  \NC number   \NC the initial random seed    \NC variable          \NC \NR
73\NC \type {math_mode}    \NC string   \NC the number system to use:
74                                          \type {scaled},
75                                          \type {double} or
76                                        % \type {binary} or
77                                          \type {decimal}            \NC \type {scaled}    \NC \NR
78\NC \type {interaction}  \NC string   \NC the interaction mode:
79                                         \type {batch},
80                                         \type {nonstop},
81                                         \type {scroll} or
82                                         \type {errorstop}          \NC \type {errorstop}  \NC \NR
83\NC \type {job_name}     \NC string   \NC a compatibility value      \NC                   \NC \NR
84\NC \type {utf8_mode}    \NC boolean  \NC permit characters in the
85                                          range 128 upto 255 to be
86                                          part of names              \NC \type {false}     \NC \NR
87\NC \type {text_mode}    \NC boolean  \NC permit characters 2 and 3
88                                          as fencing string literals \NC \type {false}     \NC \NR
89\NC \type {tolerance}    \NC number   \NC the value used as criterium
90                                          for straight lines         \NC \type {131/65536} \NC \NR
91\NC \type {extensions}   \NC boolean  \NC enable all extensions      \NC (might go)        \NC \NR
92\LL
93\stoptabulate
94
95The binary mode is no longer available in the \LUAMETATEX\ version of \MPLIB. It
96offers no real advantage and brings a ton of extra libraries with platform
97specific properties that we can now avoid. We might introduce a high resolution
98scaled variant at some point but only when it pays of performance wise.
99
100In addition to the above we need to provide functions that helps \METAPOST\
101communicate to the outside world.
102
103\starttabulate[|l|l|pl|pl|]
104\DB name                 \BC type     \BC argument(s)                    \BC result       \NC \NR
105\TB
106\NC \type {find_file}    \NC function \NC string, string, string         \NC string       \NC \NR
107\NC                      \NC function \NC string, string, number         \NC string       \NC \NR
108\NC \type {open_file}    \NC function \NC string, string, string         \NC table        \NC \NR
109\NC                      \NC function \NC string, string, number         \NC table        \NC \NR
110\NC \type {run_logger}   \NC function \NC number, string                 \NC              \NC \NR
111\NC \type {run_script}   \NC function \NC string                         \NC whatever [, boolean] \NC \NR
112\NC                      \NC function \NC number                         \NC whatever [, boolean] \NC \NR
113\NC \type {make_text}    \NC function \NC string, number                 \NC string       \NC \NR
114\NC \type {run_internal} \NC function \NC number, number, number, string \NC              \NC \NR
115\NC \type {run_overload} \NC function \NC number, string, number         \NC boolean      \NC \NR
116\NC \type {run_error}    \NC function \NC string, string, number         \NC              \NC \NR
117\LL
118\stoptabulate
119
120The \type {find_file} and \type {open_file} functions should be of this form:
121
122\starttyping
123<string> found   = find_file (<string> name, <string> mode, <string> type)
124<table>  actions = open_file (<string> name, <string> mode, <string> type)
125\stoptyping
126
127where the mode is \type {r} or \type {w} and the type is \type {mp}, \type
128{data}, \type {terminal} or a number, The finder is supposed to return the full
129path name of the found file, or \type {nil} if the file cannot be found. The
130\type {open_file} is supposed to return a table with a \type {close} and \type
131{read} function. This is similar to the way we do it in \TEX. The special name
132\type {terminal} is used for interactive input. A numeric type indicates a
133specific read or write channel.
134
135The \type {run_logger} callback gets a target and a string. A target \type {1}
136means log, a value \type {2} means and \type {3} means both.
137
138The \type {run_script} function gets either a number or a string. The string
139represents a script, the number can be used as reference to something stored. The
140return value can be a boolean, number, string or table. Booleans and numbers are
141injected directly, strings and concatenated tables are fed into scantokens. When
142the second argument is true, the strings are also injected directly and tables
143are injected as pairs, colors, paths, transforms, depending on how many elements
144there are.
145
146The \type {run_internal} function triggers when internal \METAPOST\ variables
147flagged with \type {runscript} are initialized, saved or restored. The first
148argument is an index, the second the action. When initialized a third and fourth
149argument are passed. This is an experimental feature.
150
151The experimental \type {run_overload} callback kicks in when a variable (or
152macro) with a property other than zero is redefined. It gets a property, name and
153the value of \type {overloadmode} passed and when the function returns \type
154{true} redefinition is permitted.
155
156The \type {run_error} callback gets the error message, help text and current
157interaction mode passed. Normally it's best to just quit and let the user fix
158the code.
159
160When you are processing a snippet of text starting with \type {btex} or \type
161{verbatimtex} and ending with \type {etex}, the \METAPOST\ \type {texscriptmode}
162parameter controls how spaces and newlines get honoured. The default value is~1.
163Possible values are:
164
165\starttabulate[|l|p|]
166\DB name      \BC meaning \NC \NR
167\TB
168\NC \type {0} \NC no newlines \NC \NR
169\NC \type {1} \NC newlines in \type {verbatimtex} \NC \NR
170\NC \type {2} \NC newlines in \type {verbatimtex} and \type {etex} \NC \NR
171\NC \type {3} \NC no leading and trailing strip in \type {verbatimtex} \NC \NR
172\NC \type {4} \NC no leading and trailing strip in \type {verbatimtex} and \type {btex} \NC \NR
173\LL
174\stoptabulate
175
176That way the \LUA\ handler (assigned to \type {make_text}) can do what it likes.
177An \type {etex} has to be followed by a space or \type {;} or be at the end of a
178line and preceded by a space or at the beginning of a line. The \type {make_text}
179function can return a string that gets fed into scantokens.
180
181\stopsubsection
182
183\startsubsection[title={\type {getstatistics}}]
184
185\libindex{statistics}
186
187You can request statistics with:
188
189\startfunctioncall
190<table> stats = mp:getstatistics()
191\stopfunctioncall
192
193This function returns the vital statistics for an \MPLIB\ instance. Some are
194useful, others make more sense when debugging.
195
196\starttabulate[|l|l|p|]
197\DB field  \BC type \BC explanation \NC \NR
198\TB
199\NC \type {memory}     \NC number \NC bytes of node memory      \NC \NR
200\NC \type {hash}       \NC number \NC size of the hash          \NC \NR
201\NC \type {parameters} \NC number \NC allocated parameter stack \NC \NR
202\NC \type {input}      \NC number \NC allocated input stack     \NC \NR
203\NC \type {tokens}     \NC number \NC number of token nodes     \NC \NR
204\NC \type {pairs}      \NC number \NC number of pair nodes      \NC \NR
205\NC \type {knots}      \NC number \NC number of knot nodes      \NC \NR
206\NC \type {nodes}      \NC number \NC number of value nodes     \NC \NR
207\NC \type {symbols}    \NC number \NC number of symbolic nodes  \NC \NR
208\NC \type {characters} \NC number \NC number of string bytes    \NC \NR
209\NC \type {strings}    \NC number \NC number of strings         \NC \NR
210\NC \type {internals}  \NC number \NC number of internals       \NC \NR
211\LL
212\stoptabulate
213
214Note that in the new version of \MPLIB, this is informational only. The objects
215are all allocated dynamically, so there is no chance of running out of space
216unless the available system memory is exhausted.
217
218\stopsubsection
219
220\startsubsection[title={\type {execute}}]
221
222\libindex{execute}
223
224You can ask the \METAPOST\ interpreter to run a chunk of code by calling
225
226\startfunctioncall
227<table> rettable = execute(mp,"metapost code")
228\stopfunctioncall
229
230for various bits of \METAPOST\ language input. Be sure to check the \type
231{rettable.status} (see below) because when a fatal \METAPOST\ error occurs the
232\MPLIB\ instance will become unusable thereafter.
233
234Generally speaking, it is best to keep your chunks small, but beware that all
235chunks have to obey proper syntax, like each of them is a small file. For
236instance, you cannot split a single statement over multiple chunks.
237
238In contrast with the normal stand alone \type {mpost} command, there is \notabene
239{no} implied \quote{input} at the start of the first chunk. When no string is
240passed to the execute function, there will still be one triggered because it then
241expects input from the terminal and you can emulate that channel with the
242callback you provide.
243
244\stopsubsection
245
246\startsubsection[title={\type {finish}}]
247
248\libindex{finish}
249
250Once you create an instance it is likely that you will keep it open for
251successive processing, if only because you want to avoid loading a format each
252time. If for some reason you want to stop using an \MPLIB\ instance while
253processing is not yet actually done, you can call \type {finish}.
254
255\startfunctioncall
256<table> rettable = finish(mp)
257\stopfunctioncall
258
259Eventually, used memory
260will be freed and open files will be closed by the \LUA\ garbage collector, but
261an explicit \type {finish} is the only way to capture the final part of the
262output streams.
263
264\stopsubsection
265
266\startsubsection[title={\type {settolerance} and \type {gettolerance}}]
267
268\libindex{gettolerance}
269\libindex{settolerance}
270
271These two functions relate to the bend tolerance, a value that is used when the
272export determines if a path has straight lines (like a rectangle has).
273
274\stopsubsection
275
276\startsubsection[title={Errors}]
277
278\libindex{showcontext}
279
280In case of an error you can get the context where it happened with \type
281{showcontext}.
282
283\stopsubsection
284
285\startsubsection[title={The scanner status}]
286
287\libindex {getstatus}
288\libindex {getstates}
289
290When processing a graphic an instance is in a specific state and again we have a
291getter for the (internal) values \ctxlua {document.showmpcodes ("getstates")}.
292The current status can be queried with \type {getstatus}.
293
294\stopsubsection
295
296\startsubsection[title={The hash}]
297
298\libindex {gethashentries}
299\libindex {gethashentry}
300
301Macro names and variable names are stored in a hash table. You can get a list
302with entries with \type {gethashentries}, which takes an instance as first
303argument. When the second argument is \type {true} more details will be provided.
304With \type {gethashentry} you get info about the given macro or variable.
305
306\stopsubsection
307
308\startsubsection[title={Callbacks}]
309
310\libindex{getcallbackstate}
311
312Some statistics about the number of calls to the callbacks can be queried with
313\type {getcallbackstate}, This function expects a valid instance.
314
315\stopsubsection
316
317\stopsection
318
319\startsection[title={The end result}]
320
321\startsubsection[title={The figure}]
322
323\libindex {fields}
324\libindex {stacking}
325
326The return value of \type {execute} and \type {finish} is a table with a
327few possible keys (only \type {status} is always guaranteed to be present).
328
329\starttabulate[|l|l|p|]
330\DB field  \BC type \BC explanation \NC \NR
331\TB
332\NC \type{status} \NC number \NC the return value:
333                                 \type {0} = good,
334                                 \type {1} = warning,
335                                 \type {2} = errors,
336                                 \type {3} = fatal error \NC \NR
337\NC \type{fig}    \NC table  \NC an array of generated figures (if any) \NC \NR
338\LL
339\stoptabulate
340
341When \type {status} equals~3, you should stop using this \MPLIB\ instance
342immediately, it is no longer capable of processing input.
343
344If it is present, each of the entries in the \type {fig} array is a userdata
345representing a figure object, and each of those has a number of object methods
346you can call:
347
348You can check if a figure uses stacking with the \type {stacking} function. When
349objects are fetched, memory gets freed so no information about stacking is
350available then. You can get the used bend tolerance of an object with \type
351{tolerance}.
352
353\starttabulate[|l|l|p|]
354\DB field  \BC type \BC explanation \NC \NR
355\TB
356\NC \type{boundingbox}  \NC function \NC returns the bounding box, as an array of 4
357                                         values \NC \NR
358\NC \type{objects}      \NC function \NC returns the actual array of graphic objects in
359                                         this \type {fig} \NC \NR
360\NC \type{filename}     \NC function \NC the filename this \type {fig}'s \POSTSCRIPT\
361                                         output would have written to in stand alone
362                                         mode \NC \NR
363\NC \type{width}        \NC function \NC the \type {fontcharwd} value \NC \NR
364\NC \type{height}       \NC function \NC the \type {fontcharht} value \NC \NR
365\NC \type{depth}        \NC function \NC the \type {fontchardp} value \NC \NR
366\NC \type{italic}       \NC function \NC the \type {fontcharit} value \NC \NR
367\NC \type{charcode}     \NC function \NC the (rounded) \type {charcode} value \NC \NR
368\NC \type{stacking}     \NC function \NC is there a non|-|zero stacking  \NC \NR
369\LL
370\stoptabulate
371
372Note: you can call \type {fig:objects()} only once for any one \type {fig}
373object! Some information, like stacking, can only be queried when the complete
374figure is still present and calling up objects will free elements in the original
375once they are transferred.
376
377When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the
378first set of coordinates is larger than the second set, the picture is empty.
379
380Graphical objects come in various types: \type {fill}, \type {outline}, \type
381{text}, \type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type
382{stop_bounds}, \type {start_group} and \type {stop_group}. Each type has a
383different list of accessible values.
384
385There is a helper function (\type {mplib.fields(obj)}) to get the list of
386accessible values for a particular object, but you can just as easily use the
387tables given below.
388
389All graphical objects have a field \type {type} that gives the object type as a
390string value; it is not explicit mentioned in the following tables. In the
391following, \type {number}s are \POSTSCRIPT\ points (base points in \TEX\ speak)
392represented as a floating point number, unless stated otherwise. Field values
393that are of type \type {table} are explained in the next section.
394
395\stopsubsection
396
397\startsubsection[title={fill}]
398
399\starttabulate[|l|l|p|]
400\DB field  \BC type \BC explanation \NC \NR
401\TB
402\NC \type{path}       \NC table  \NC the list of knots \NC \NR
403\NC \type{htap}       \NC table  \NC the list of knots for the reversed trajectory \NC \NR
404\NC \type{pen}        \NC table  \NC knots of the pen \NC \NR
405\NC \type{color}      \NC table  \NC the object's color \NC \NR
406\NC \type{linejoin}   \NC number \NC line join style (bare number)\NC \NR
407\NC \type{miterlimit} \NC number \NC miterlimit\NC \NR
408\NC \type{prescript}  \NC string \NC the prescript text \NC \NR
409\NC \type{postscript} \NC string \NC the postscript text \NC \NR
410\NC \type{stacking}   \NC number \NC the stacking (level) \NC \NR
411\LL
412\stoptabulate
413
414The entries \type {htap} and \type {pen} are optional.
415
416\stopsubsection
417
418\startsubsection[title={outline}]
419
420\starttabulate[|l|l|p|]
421\DB field  \BC type \BC explanation \NC \NR
422\TB
423\NC \type{path}       \NC table  \NC the list of knots \NC \NR
424\NC \type{pen}        \NC table  \NC knots of the pen \NC \NR
425\NC \type{color}      \NC table  \NC the object's color \NC \NR
426\NC \type{linejoin}   \NC number \NC line join style (bare number) \NC \NR
427\NC \type{miterlimit} \NC number \NC miterlimit \NC \NR
428\NC \type{linecap}    \NC number \NC line cap style (bare number) \NC \NR
429\NC \type{dash}       \NC table  \NC representation of a dash list \NC \NR
430\NC \type{prescript}  \NC string \NC the prescript text \NC \NR
431\NC \type{postscript} \NC string \NC the postscript text \NC \NR
432\NC \type{stacking}   \NC number \NC the stacking (level) \NC \NR
433\LL
434\stoptabulate
435
436The entry \type {dash} is optional.
437
438\stopsubsection
439
440\startsubsection[title={start_bounds, start_clip, start_group}]
441
442\starttabulate[|l|l|p|]
443\DB field  \BC type \BC explanation \NC \NR
444\TB
445\NC \type{path}     \NC table \NC the list of knots \NC \NR
446\NC \type{stacking} \NC number \NC the stacking (level) \NC \NR
447\LL
448\stoptabulate
449
450\stopsubsection
451
452\startsubsection[title={stop_bounds, stop_clip, stop_group}]
453
454Here we have only one key:
455
456\starttabulate[|l|l|p|]
457\DB field  \BC type \BC explanation \NC \NR
458\TB
459\NC \type{stacking} \NC number \NC the stacking (level) \NC \NR
460\LL
461\stoptabulate
462
463\stopsubsection
464
465\stopsection
466
467\startsection[title={Subsidiary table formats}]
468
469\startsubsection[title={Paths and pens}]
470
471Paths and pens (that are really just a special type of paths as far as \MPLIB\ is
472concerned) are represented by an array where each entry is a table that
473represents a knot.
474
475\starttabulate[|l|l|p|]
476\DB field  \BC type \BC explanation \NC \NR
477\TB
478\NC \type{left_type}  \NC string \NC when present: endpoint, but usually absent \NC \NR
479\NC \type{right_type} \NC string \NC like \type {left_type} \NC \NR
480\NC \type{x_coord}    \NC number \NC X coordinate of this knot \NC \NR
481\NC \type{y_coord}    \NC number \NC Y coordinate of this knot \NC \NR
482\NC \type{left_x}     \NC number \NC X coordinate of the precontrol point of this knot \NC \NR
483\NC \type{left_y}     \NC number \NC Y coordinate of the precontrol point of this knot \NC \NR
484\NC \type{right_x}    \NC number \NC X coordinate of the postcontrol point of this knot \NC \NR
485\NC \type{right_y}    \NC number \NC Y coordinate of the postcontrol point of this knot \NC \NR
486\LL
487\stoptabulate
488
489There is one special case: pens that are (possibly transformed) ellipses have an
490extra key \type {type} with value \type {elliptical} besides the array part
491containing the knot list.
492
493\stopsubsection
494
495\startsubsection[title={Colors}]
496
497A color is an integer array with 0, 1, 3 or 4 values:
498
499\starttabulate[|l|l|p|]
500\DB field  \BC type \BC explanation \NC \NR
501\TB
502\NC \type{0} \NC marking only \NC no values                                                     \NC \NR
503\NC \type{1} \NC greyscale    \NC one value in the range $(0,1)$, \quote {black} is $0$         \NC \NR
504\NC \type{3} \NC \RGB         \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$  \NC \NR
505\NC \type{4} \NC \CMYK        \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC \NR
506\LL
507\stoptabulate
508
509If the color model of the internal object was \type {uninitialized}, then it was
510initialized to the values representing \quote {black} in the colorspace \type
511{defaultcolormodel} that was in effect at the time of the \type {shipout}.
512
513\stopsubsection
514
515\startsubsection[title={Transforms}]
516
517Each transform is a six|-|item array.
518
519\starttabulate[|l|l|p|]
520\DB index  \BC type \BC explanation \NC \NR
521\TB
522\NC \type{1} \NC number \NC represents x  \NC \NR
523\NC \type{2} \NC number \NC represents y  \NC \NR
524\NC \type{3} \NC number \NC represents xx \NC \NR
525\NC \type{4} \NC number \NC represents yx \NC \NR
526\NC \type{5} \NC number \NC represents xy \NC \NR
527\NC \type{6} \NC number \NC represents yy \NC \NR
528\LL
529\stoptabulate
530
531Note that the translation (index 1 and 2) comes first. This differs from the
532ordering in \POSTSCRIPT, where the translation comes last.
533
534\stopsubsection
535
536\startsubsection[title={Dashes}]
537
538Each \type {dash} is a hash with two items. We use the same model as \POSTSCRIPT\
539for the representation of the dashlist. \type {dashes} is an array of \quote {on}
540and \quote {off}, values, and \type {offset} is the phase of the pattern.
541
542\starttabulate[|l|l|p|]
543\DB field  \BC type \BC explanation \NC \NR
544\TB
545\NC \type{dashes} \NC hash   \NC an array of on-off numbers \NC \NR
546\NC \type{offset} \NC number \NC the starting offset value  \NC \NR
547\LL
548\stoptabulate
549
550\stopsubsection
551
552\startsubsection[title={Pens and \type {peninfo}}]
553
554\libindex{peninfo}
555
556There is helper function (\type {peninfo(obj)}) that returns a table containing
557a bunch of vital characteristics of the used pen (all values are floats):
558
559\starttabulate[|l|l|p|]
560\DB field  \BC type \BC explanation \NC \NR
561\TB
562\NC \type{width} \NC number \NC width of the pen \NC \NR
563\NC \type{sx}    \NC number \NC $x$ scale        \NC \NR
564\NC \type{rx}    \NC number \NC $xy$ multiplier  \NC \NR
565\NC \type{ry}    \NC number \NC $yx$ multiplier  \NC \NR
566\NC \type{sy}    \NC number \NC $y$ scale        \NC \NR
567\NC \type{tx}    \NC number \NC $x$ offset       \NC \NR
568\NC \type{ty}    \NC number \NC $y$ offset       \NC \NR
569\LL
570\stoptabulate
571
572\stopsubsection
573
574\startsubsection[title={Character size information}]
575
576\libindex{char_width}
577\libindex{char_height}
578\libindex{char_depth}
579
580These functions find the size of a glyph in a defined font. The \type {fontname}
581is the same name as the argument to \type {infont}; the \type {char} is a glyph
582id in the range 0 to 255; the returned \type {w} is in AFM units.
583
584\startfunctioncall
585<number> w = char_width(mp,<string> fontname, <number> char)
586<number> h = char_height(mp,<string> fontname, <number> char)
587<number> d = char_depth(mp,<string> fontname, <number> char)
588\stopfunctioncall
589
590\stopsubsection
591
592\stopsection
593
594\startsection[title=Scanners]
595
596After a relative long period of testing the scanners are now part of the
597interface. That doesn't mean that there will be no changes: depending on the
598needs and experiences details might evolve. The summary below is there
599still preliminary and mostly provided as reminder.
600
601\starttabulate[|l|l|p|]
602\DB scanner \BC argument \BC returns \NC \NR
603\TB
604\NC \type{scannext}       \NC instance, keep         \NC token, mode, type \NC \NR
605\NC \type{scanexpression} \NC instance, keep         \NC type \NC \NR
606\NC \type{scantoken}      \NC instance, keep         \NC token, mode, kind \NC \NR
607\NC \type{scansymbol}     \NC instance, keep, expand \NC string \NC \NR
608\NC \type{scannumeric}    \NC instance, type         \NC number \NC \NR
609\NC \type{scaninteger}    \NC instance, type         \NC integer \NC \NR
610\NC \type{scanboolean}    \NC instance, type         \NC boolean \NC \NR
611\NC \type{scanstring}     \NC instance, type         \NC string \NC \NR
612\NC \type{scanpair}       \NC instance, hashed, type \NC table or two numbers \NC \NR
613\NC \type{scancolor}      \NC instance, hashed, type \NC table or three numbers \NC \NR
614\NC \type{scancmykcolor}  \NC instance, hashed, type \NC table or four numbers \NC \NR
615\NC \type{scantransform}  \NC instance, hashed, type \NC table or six numbers \NC \NR
616\NC \type{scanpath}       \NC instance, hashed, type \NC table with hashes or arrays \NC \NR
617\NC \type{scanpen}        \NC instance, hashed, type \NC table with hashes or arrays \NC \NR
618\NC \type{scanproperty}   \NC {\em todo}             \NC \NC \NR
619\HL
620\NC \type{skiptoken}      \NC {\em todo}             \NC \NC \NR
621\LL
622\stoptabulate
623
624The types and token codes are numbers but they actually depend on the
625implementation (although changes are unlikely). The types of data structures can
626be queried with \ctxlua {document.showmpcodes ("gettypes")}, and command codes
627with \ctxlua {document.showmpcodes ("getcodes")}
628
629Now, if you really want to use these, keep in mind that the internals of
630\METAPOST\ are not trivial, especially because expression scanning can be
631complex. So you need to experiment a bit. In \CONTEXT\ all is (and will be)
632hidden below an abstraction layer so users are not bothered by all these
633look|-|ahead and push|-|back issues that originate in the way \METAPOST\ scans
634its input.
635
636The supported color models are: \ctxlua {document.showmpcodes ("getcolormodels")}.
637
638If you want the internal codes of the possible fields in a graphic object use
639\ctxlua {document.showmpcodes ("getobjecttypes")}. You can query the id of a
640graphic object with the \type {gettype} function.
641
642\startluacode
643local t = mplib.getobjecttypes()
644local f = mplib.getfields()
645context.starttabulate { "|T|T|Tpl|" }
646    context.DB()
647        context("id")
648    context.BC()
649        context("object")
650    context.BC()
651        context("fields")
652    context.NC()
653    context.NR()
654    for i=1,#t do
655        context.NC()
656            context(i)
657        context.NC()
658            context(t[i])
659        context.NC()
660            context("% t",f[i])
661        context.NC()
662        context.NR()
663    end
664    context.LL()
665context.stoptabulate()
666\stopluacode
667
668\stopsection
669
670\startsection[title=Injectors]
671
672It is important to know that piping code into the library is pretty fast and
673efficient. Most processing time relates to memory management, calculations and
674generation of output can not be neglected either. Out of curiousity I added some
675functions that directly push data into the library but the gain is not that
676large. \footnote {The main motivation was checking of huge paths could be
677optimized. The other data structures were then added for completeness.}
678
679\starttabulate[|l|l|]
680\DB scanner \BC argument \NC \NR
681\TB
682\NC \type{injectnumeric}   \NC instance, number \NC \NR
683\NC \type{injectinteger}   \NC instance, number \NC \NR
684\NC \type{injectboolean}   \NC instance, boolean \NC \NR
685\NC \type{injectstring}    \NC instance, string \NC \NR
686\NC \type{injectpair}      \NC instance, (table with) two numbers \NC \NR
687\NC \type{injectcolor}     \NC instance, (table with) three numbers \NC \NR
688\NC \type{injectcmykcolor} \NC instance, (table with) four numbers \NC \NR
689\NC \type{injecttransform} \NC instance, (table with) six numbers \NC \NR
690\NC \type{injectpath}      \NC instance, table with hashes or arrays, cycle, variant \NC \NR
691\NC \type{injectwhatever}  \NC instance, ont of the above depending on type and size \NC \NR
692\LL
693\stoptabulate
694
695The path injector takes a table with subtables that are either hashed (like the
696path solver) or arrays with two, four or six entries. When the third argument has
697the value \type {true} the path is closed. When the fourth argument is \type
698{true} the path is constructed out of straight lines (as with \type {--}) by
699setting the \type {curl} values to~1 automatically. \footnote {This is all
700experimental so future versions might provide more control.}
701
702This is the simplest path definition:
703
704\starttyping
705{
706    { x, y },
707    ...,
708    cycle = true
709}
710\stoptyping
711
712and this one also has the control points:
713
714\starttyping
715{
716    { x0, y0, x1, y1, x2, y2 },
717    ...,
718    cycle = true
719}
720\stoptyping
721
722A very detailed specification is this but you have to make sure that the
723parameters make sense.
724
725\starttyping
726{
727    {
728        x_coord       = ...,
729        y_coord       = ...,
730        left_x        = ...,
731        left_y        = ...,
732        right_x       = ...,
733        right_y       = ...,
734        left_tension  = ...,
735        right_tension = ...,
736        left_curl     = ...,
737        right_curl    = ...,
738        direction_x   = ...,
739        direction_y   = ...,
740        left_type     = ...,
741        right_type    = ...,
742    },
743    ...,
744    cycle = true
745}
746\stoptyping
747
748Instead of the optional keyword \type {cycle} you can use \type {close}.
749
750\stopsection
751
752\startsection[title={To be checked}]
753
754\starttyping
755% solvepath
756% expandtex
757\stoptyping
758
759\stopsection
760
761\stopchapter
762
763\stopcomponent
764
Source Browser ?
