summaryrefslogtreecommitdiff
path: root/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex
blob: 1da447fef6a70cb376b12d529c6817ad8f06aabd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
% language=uk

% lua.newtable

\environment luametatex-style

\startcomponent luametatex-metapost

\startchapter[reference=metapost,title={The \METAPOST\ library \type {mplib}}]

\startsection[title={Process management}][library=mplib]

\topicindex {\METAPOST}
\topicindex {\METAPOST+mplib}
\topicindex {images+mplib}
\topicindex {images+\METAPOST}

\libindex{version}

The \METAPOST\ library interface registers itself in the table \type {mplib}. It
is based on \MPLIB\ version \ctxlua {context(mplib.version())}.

\subsection{\type {new}}

\libindex{new}

To create a new \METAPOST\ instance, call

\startfunctioncall
<mpinstance> mp = mplib.new({...})
\stopfunctioncall

This creates the \type {mp} instance object. The argument is a hash table that
can have a number of different fields, as follows:

\starttabulate[|l|l|pl|pl|]
\DB name               \BC type     \BC description                \BC default           \NC \NR
\TB
\NC \type{error_line}  \NC number   \NC error line width           \NC 79                \NC \NR
\NC \type{print_line}  \NC number   \NC line length in ps output   \NC 100               \NC \NR
\NC \type{random_seed} \NC number   \NC the initial random seed    \NC variable          \NC \NR
\NC \type{math_mode}   \NC string   \NC the number system to use:
                                        \type {scaled},
                                        \type {double} or
                                      % \type {binary} or
                                        \type {decimal}            \NC \type {scaled}    \NC \NR
\NC \type{interaction} \NC string   \NC the interaction mode:
                                        \type {batch},
                                        \type {nonstop},
                                        \type {scroll} or
                                        \type {errorstop}          \NC \type {errorstop} \NC \NR
\NC \type{job_name}    \NC string   \NC a compatibility value      \NC \type {mpout}     \NC \NR
\NC \type{find_file}   \NC function \NC a function to find files   \NC only local files  \NC \NR
\NC \type{utf8_mode}   \NC boolean  \NC permit characters in the
                                        range 128 upto 255 to be
                                        part of names              \NC \type {false}     \NC \NR
\NC \type{text_mode}   \NC boolean  \NC permit characters 2 and 3
                                        as fencing string literals \NC \type {false}     \NC \NR
\LL
\stoptabulate

The binary mode is no longer available in the \LUATEX\ version of \MPLIB. It
offers no real advantage and brings a ton of extra libraries with platform
specific properties that we can now avoid. We might introduce a high resolution
scaled variant at some point but only when it pays of performance wise.

The \type {find_file} function should be of this form:

\starttyping
<string> found = finder (<string> name, <string> mode, <string> type)
\stoptyping

with:

\starttabulate[|l|p|]
\DB name        \BC the requested file \NC \NR
\TB
\NC \type{mode} \NC the file mode: \type {r} or \type {w} \NC \NR
\NC \type{type} \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map},
                    \type {pfb}, \type {enc} \NC \NR
\LL
\stoptabulate

Return either the full path name of the found file, or \type {nil} if the file
cannot be found.

Note that the new version of \MPLIB\ no longer uses binary mem files, so the way
to preload a set of macros is simply to start off with an \type {input} command
in the first \type {execute} call.

When you are processing a snippet of text starting with \type {btex} or \type
{verbatimtex} and ending with \type {etex}, the \METAPOST\ \type {texscriptmode}
parameter controls how spaces and newlines get honoured. The default value is~1.
Possible values are:

\starttabulate[|l|p|]
\DB name      \BC meaning \NC \NR
\TB
\NC \type {0} \NC no newlines \NC \NR
\NC \type {1} \NC newlines in \type {verbatimtex} \NC \NR
\NC \type {2} \NC newlines in \type {verbatimtex} and \type {etex} \NC \NR
\NC \type {3} \NC no leading and trailing strip in \type {verbatimtex} \NC \NR
\NC \type {4} \NC no leading and trailing strip in \type {verbatimtex} and \type {btex} \NC \NR
\LL
\stoptabulate

That way the \LUA\ handler (assigned to \type {make_text}) can do what it likes.
An \type {etex} has to be followed by a space or \type {;} or be at the end of a
line and preceded by a space or at the beginning of a line.

\subsection{\type {statistics}}

\libindex{statistics}

You can request statistics with:

\startfunctioncall
<table> stats = mp:statistics()
\stopfunctioncall

This function returns the vital statistics for an \MPLIB\ instance. There are
four fields, giving the maximum number of used items in each of four allocated
object classes:

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{main_memory} \NC number \NC memory size \NC \NR
\NC \type{hash_size}   \NC number \NC hash size\NC \NR
\NC \type{param_size}  \NC number \NC simultaneous macro parameters\NC \NR
\NC \type{max_in_open} \NC number \NC input file nesting levels\NC \NR
\LL
\stoptabulate

Note that in the new version of \MPLIB, this is informational only. The objects
are all allocated dynamically, so there is no chance of running out of space
unless the available system memory is exhausted.

\subsection{\type {execute}}

\libindex{execute}

You can ask the \METAPOST\ interpreter to run a chunk of code by calling

\startfunctioncall
<table> rettable = execute(mp,"metapost code")
\stopfunctioncall

for various bits of \METAPOST\ language input. Be sure to check the \type
{rettable.status} (see below) because when a fatal \METAPOST\ error occurs the
\MPLIB\ instance will become unusable thereafter.

Generally speaking, it is best to keep your chunks small, but beware that all
chunks have to obey proper syntax, like each of them is a small file. For
instance, you cannot split a single statement over multiple chunks.

In contrast with the normal stand alone \type {mpost} command, there is
\notabene {no} implied \quote{input} at the start of the first chunk.

\subsection{\type {finish}}

\libindex{finish}

\startfunctioncall
<table> rettable = finish(mp)
\stopfunctioncall

If for some reason you want to stop using an \MPLIB\ instance while processing is
not yet actually done, you can call \type {finish}. Eventually, used memory
will be freed and open files will be closed by the \LUA\ garbage collector, but
an explicit \type {finish} is the only way to capture the final part of the
output streams.

\stopsection

\startsection[title={The end result}]

\libindex {fields}

The return value of \type {execute} and \type {finish} is a table with a
few possible keys (only \type {status} is always guaranteed to be present).

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{log}    \NC string \NC output to the \quote {log} stream \NC \NR
\NC \type{term}   \NC string \NC output to the \quote {term} stream \NC \NR
\NC \type{error}  \NC string \NC output to the \quote {error} stream
                                 (only used for \quote {out of memory}) \NC \NR
\NC \type{status} \NC number \NC the return value:
                                 \type {0} = good,
                                 \type {1} = warning,
                                 \type {2} = errors,
                                 \type {3} = fatal error \NC \NR
\NC \type{fig}    \NC table  \NC an array of generated figures (if any) \NC \NR
\LL
\stoptabulate

When \type {status} equals~3, you should stop using this \MPLIB\ instance
immediately, it is no longer capable of processing input.

If it is present, each of the entries in the \type {fig} array is a userdata
representing a figure object, and each of those has a number of object methods
you can call:

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{boundingbox}  \NC function \NC returns the bounding box, as an array of 4
                                         values \NC \NR
\NC \type{postscript}   \NC function \NC returns a string that is the ps output of the
                                         \type {fig}. this function accepts two optional
                                         integer arguments for specifying the values of
                                         \type {prologues} (first argument) and \type
                                         {procset} (second argument) \NC \NR
\NC \type{svg}          \NC function \NC returns a string that is the svg output of the
                                         \type {fig}. This function accepts an optional
                                         integer argument for specifying the value of
                                         \type {prologues} \NC \NR
\NC \type{objects}      \NC function \NC returns the actual array of graphic objects in
                                         this \type {fig} \NC \NR
\NC \type{copy_objects} \NC function \NC returns a deep copy of the array of graphic
                                         objects in this \type {fig} \NC \NR
\NC \type{filename}     \NC function \NC the filename this \type {fig}'s \POSTSCRIPT\
                                         output would have written to in stand alone
                                         mode \NC \NR
\NC \type{width}        \NC function \NC the \type {fontcharwd} value \NC \NR
\NC \type{height}       \NC function \NC the \type {fontcharht} value \NC \NR
\NC \type{depth}        \NC function \NC the \type {fontchardp} value \NC \NR
\NC \type{italcorr}     \NC function \NC the \type {fontcharit} value \NC \NR
\NC \type{charcode}     \NC function \NC the (rounded) \type {charcode} value \NC \NR
\LL
\stoptabulate

Note: you can call \type {fig:objects()} only once for any one \type {fig}
object!

When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the
first set of coordinates is larger than the second set, the picture is empty.

Graphical objects come in various types: \type {fill}, \type {outline}, \type
{text}, \type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type
{stop_bounds}, \type {special}. Each type has a different list of accessible
values.

There is a helper function (\type {mplib.fields(obj)}) to get the list of
accessible values for a particular object, but you can just as easily use the
tables given below.

All graphical objects have a field \type {type} that gives the object type as a
string value; it is not explicit mentioned in the following tables. In the
following, \type {number}s are \POSTSCRIPT\ points represented as a floating
point number, unless stated otherwise. Field values that are of type \type
{table} are explained in the next section.

\subsection{fill}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{path}       \NC table  \NC the list of knots \NC \NR
\NC \type{htap}       \NC table  \NC the list of knots for the reversed trajectory \NC \NR
\NC \type{pen}        \NC table  \NC knots of the pen \NC \NR
\NC \type{color}      \NC table  \NC the object's color \NC \NR
\NC \type{linejoin}   \NC number \NC line join style (bare number)\NC \NR
\NC \type{miterlimit} \NC number \NC miterlimit\NC \NR
\NC \type{prescript}  \NC string \NC the prescript text \NC \NR
\NC \type{postscript} \NC string \NC the postscript text \NC \NR
\LL
\stoptabulate

The entries \type {htap} and \type {pen} are optional.

\subsection{outline}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{path}       \NC table  \NC the list of knots \NC \NR
\NC \type{pen}        \NC table  \NC knots of the pen \NC \NR
\NC \type{color}      \NC table  \NC the object's color \NC \NR
\NC \type{linejoin}   \NC number \NC line join style (bare number) \NC \NR
\NC \type{miterlimit} \NC number \NC miterlimit \NC \NR
\NC \type{linecap}    \NC number \NC line cap style (bare number) \NC \NR
\NC \type{dash}       \NC table  \NC representation of a dash list \NC \NR
\NC \type{prescript}  \NC string \NC the prescript text \NC \NR
\NC \type{postscript} \NC string \NC the postscript text \NC \NR
\LL
\stoptabulate

The entry \type {dash} is optional.

\subsection{text}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{text}       \NC string \NC the text \NC \NR
\NC \type{font}       \NC string \NC font tfm name \NC \NR
\NC \type{dsize}      \NC number \NC font size \NC \NR
\NC \type{color}      \NC table  \NC the object's color \NC \NR
\NC \type{width}      \NC number \NC \NC \NR
\NC \type{height}     \NC number \NC \NC \NR
\NC \type{depth}      \NC number \NC \NC \NR
\NC \type{transform}  \NC table  \NC a text transformation \NC \NR
\NC \type{prescript}  \NC string \NC the prescript text \NC \NR
\NC \type{postscript} \NC string \NC the postscript text \NC \NR
\LL
\stoptabulate

\subsection{special}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{prescript} \NC string \NC special text \NC \NR
\LL
\stoptabulate

\subsection{start_bounds, start_clip}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{path} \NC table \NC the list of knots \NC \NR
\LL
\stoptabulate

\subsubsection{stop_bounds, stop_clip}

Here are no fields available.

\stopsection

\startsection[title={Subsidiary table formats}]

\subsection{Paths and pens}

Paths and pens (that are really just a special type of paths as far as \MPLIB\ is
concerned) are represented by an array where each entry is a table that
represents a knot.

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{left_type}  \NC string \NC when present: endpoint, but usually absent \NC \NR
\NC \type{right_type} \NC string \NC like \type {left_type} \NC \NR
\NC \type{x_coord}    \NC number \NC X coordinate of this knot \NC \NR
\NC \type{y_coord}    \NC number \NC Y coordinate of this knot \NC \NR
\NC \type{left_x}     \NC number \NC X coordinate of the precontrol point of this knot \NC \NR
\NC \type{left_y}     \NC number \NC Y coordinate of the precontrol point of this knot \NC \NR
\NC \type{right_x}    \NC number \NC X coordinate of the postcontrol point of this knot \NC \NR
\NC \type{right_y}    \NC number \NC Y coordinate of the postcontrol point of this knot \NC \NR
\LL
\stoptabulate

There is one special case: pens that are (possibly transformed) ellipses have an
extra key \type {type} with value \type {elliptical} besides the array part
containing the knot list.

\subsection{Colors}

A color is an integer array with 0, 1, 3 or 4 values:

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{0} \NC marking only \NC no values                                                     \NC \NR
\NC \type{1} \NC greyscale    \NC one value in the range $(0,1)$, \quote {black} is $0$         \NC \NR
\NC \type{3} \NC \RGB         \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$  \NC \NR
\NC \type{4} \NC \CMYK        \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC \NR
\LL
\stoptabulate

If the color model of the internal object was \type {uninitialized}, then it was
initialized to the values representing \quote {black} in the colorspace \type
{defaultcolormodel} that was in effect at the time of the \type {shipout}.

\subsection{Transforms}

Each transform is a six|-|item array.

\starttabulate[|l|l|p|]
\DB index  \BC type \BC explanation \NC \NR
\TB
\NC \type{1} \NC number \NC represents x  \NC \NR
\NC \type{2} \NC number \NC represents y  \NC \NR
\NC \type{3} \NC number \NC represents xx \NC \NR
\NC \type{4} \NC number \NC represents yx \NC \NR
\NC \type{5} \NC number \NC represents xy \NC \NR
\NC \type{6} \NC number \NC represents yy \NC \NR
\LL
\stoptabulate

Note that the translation (index 1 and 2) comes first. This differs from the
ordering in \POSTSCRIPT, where the translation comes last.

\subsection{Dashes}

Each \type {dash} is a hash with two items. We use the same model as \POSTSCRIPT\
for the representation of the dashlist. \type {dashes} is an array of \quote {on}
and \quote {off}, values, and \type {offset} is the phase of the pattern.

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{dashes} \NC hash   \NC an array of on-off numbers \NC \NR
\NC \type{offset} \NC number \NC the starting offset value  \NC \NR
\LL
\stoptabulate

\subsection{Pens and \type {pen_info}}

\libindex{pen_info}

There is helper function (\type {pen_info(obj)}) that returns a table containing
a bunch of vital characteristics of the used pen (all values are floats):

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{width} \NC number \NC width of the pen \NC \NR
\NC \type{sx}    \NC number \NC $x$ scale        \NC \NR
\NC \type{rx}    \NC number \NC $xy$ multiplier  \NC \NR
\NC \type{ry}    \NC number \NC $yx$ multiplier  \NC \NR
\NC \type{sy}    \NC number \NC $y$ scale        \NC \NR
\NC \type{tx}    \NC number \NC $x$ offset       \NC \NR
\NC \type{ty}    \NC number \NC $y$ offset       \NC \NR
\LL
\stoptabulate

\subsection[title={Character size information}]

\libindex{char_width}
\libindex{char_height}
\libindex{char_depth}

These functions find the size of a glyph in a defined font. The \type {fontname}
is the same name as the argument to \type {infont}; the \type {char} is a glyph
id in the range 0 to 255; the returned \type {w} is in AFM units.

\startfunctioncall
<number> w = char_width(mp,<string> fontname, <number> char)
<number> h = char_height(mp,<string> fontname, <number> char)
<number> d = char_depth(mp,<string> fontname, <number> char)
\stopfunctioncall

\stopsection

\startsection[title=Scanners]

After a relative long period of testing the scanners are now part of the
interface. That doesn't mean that there will be no changes: depending on the
needs and experiences details might evolve. The summary below is there
still preliminary and mostly provided as reminder.

\starttabulate[|l|l|p|]
\DB scanner \BC argument \BC returns \NC \NR
\TB
\NC \type{scan_next}       \NC instance, keep         \NC token, mode, type \NC \NR
\NC \type{scan_expression} \NC instance, keep         \NC type \NC \NR
\NC \type{scan_token}      \NC instance, keep         \NC token, mode, kind \NC \NR
\NC \type{scan_symbol}     \NC instance, keep, expand \NC string \NC \NR
\NC \type{scan_numeric}    \NC instance, type         \NC number \NC \NR
\NC \type{scan_integer}    \NC instance, type         \NC integer \NC \NR
\NC \type{scan_boolean}    \NC instance, type         \NC boolean \NC \NR
\NC \type{scan_string}     \NC instance, type         \NC string \NC \NR
\NC \type{scan_pair}       \NC instance, hashed, type \NC table or two numbers \NC \NR
\NC \type{scan_color}      \NC instance, hashed, type \NC table or three numbers \NC \NR
\NC \type{scan_cmykcolor}  \NC instance, hashed, type \NC table or four numbers \NC \NR
\NC \type{scan_transform}  \NC instance, hashed, type \NC table or six numbers \NC \NR
\NC \type{scan_path}       \NC instance, hashed, type \NC table with hashes or arrays \NC \NR
\NC \type{scan_pen}        \NC instance, hashed, type \NC table with hashes or arrays \NC \NR
\LL
\stoptabulate

The types and token codes are numbers but they actually depend on the
implementation (although changes are unlikely). The types of data structures can
be queried with \type {mplib.types()}:

\dontleavehmode \startluacode
    local t = mplib.types()
    for i=0,#t do
        if i > 0 then
            context(", ")
        end
        context("%i: %s",i,t[i])
    end
\stopluacode .

The command codes are available with \type {mplib.codes()}:

\dontleavehmode \startluacode
    local t = mplib.codes()
    for i=0,#t do
        if i > 0 then
            context(", ")
        end
        context("%i: %s",i,t[i])
    end
\stopluacode .

Now, if you really want to use these, keep in mind that the internals of
\METAPOST\ are not trivial, especially because expression scanning can be
complex. So you need to experiment a bit. In \CONTEXT\ all is (and will be)
hidden below an abstraction layer so users are not bothered by all these
look|-|ahead and push|-|back issues that originate in the way \METAPOST\ scans
its input.

\stopsection

\startsection[title=Injectors]

It is important to know that piping code into the library is pretty fast and
efficient. Most processing time relates to memory management, calculations and
generation of output can not be neglected either. Out of curiousity I added some
functions that directly push data into the library but the gain is not that
large. \footnote {The main motivation was checking of huge paths could be
optimized. The other data structures were then added for completeness.}

\starttabulate[|l|l|]
\DB scanner \BC argument \NC \NR
\TB
\NC \type{inject_numeric}   \NC instance, number \NC \NR
\NC \type{inject_integer}   \NC instance, number \NC \NR
\NC \type{inject_boolean}   \NC instance, boolean \NC \NR
\NC \type{inject_string}    \NC instance, string \NC \NR
\NC \type{inject_pair}      \NC instance, (table with) two numbers \NC \NR
\NC \type{inject_color}     \NC instance, (table with) three numbers \NC \NR
\NC \type{inject_cmykcolor} \NC instance, (table with) four numbers \NC \NR
\NC \type{inject_transform} \NC instance, (table with) six numbers \NC \NR
\NC \type{inject_path}      \NC instance, table with hashes or arrays, cycle, variant \NC \NR
\LL
\stoptabulate

The path injector takes a table with subtables that are either hashed (like the
path solver) or arrays with two, four or six entries. When the third argument has
the value \type {true} the path is closed. When the fourth argument is \type
{true} the path is constructed out of straight lines (as with \type {--}) by
setting the \type {curl} values to~1 automatically. \footnote {This is all
experimental so future versions might provide more control.}

\stopsection

\stopchapter

\stopcomponent