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
|
% language=us
\environment luametafun-style
\startcomponent luametafun-interface
\startchapter[title={Interface}]
Because graphic solutions are always kind of personal or domain driven it makes not
much sense to cook up very generic solutions. If you have a project where \METAPOST\
can be of help, it also makes sense to spend some time on implementing the basics that
you need. In that case you can just copy and tweak what is there. The easiest way to
do that is to make a test file and use:
\starttyping[option=TEX]
\startMPpage
% your code
\stopMPpage
\stoptyping
Often you don't need to write macros, and standard drawing commands will do the
job, but when you find yourself repeating code, a wapper might make sense. And
this is why we have this key|/|value interface: it's easier to abstract your
settings than to pass them as (expression or text) arguments to a macro,
especially when there are many.
You can find many examples of the key|/|value driven user interface in the source
files and these are actually not that hard to understand when you know a bit of
\METAPOST\ and the additional macros that come with \METAFUN. In case you wonder
about overhead: the performance of this mechanism is pretty good.
Although the parameter handler runs on top of the \LUA\ interface, you don't need
to use \LUA\ unless you find that \METAPOST\ can't do the job. I won't give
examples of coding because I think that the source of \METAFUN\ provides enough
clues, especially the file \type {mp-lmtx.mpxl}. As the name suggests this is
part of the \CONTEXT\ version \LMTX, which runs on top of \LUAMETATEX. I leave it
open if I will backport this functionality to \LUATEX\ and therefore \MKIV.
An excellent explanation of this interface can be found at:
\starttyping
https://adityam.github.io/context-blog/post/new-metafun-interface/
\stoptyping
So (at least for now) here I can stick to just mentioning the currently stable
interface macros:
\starttabulate[|T|l|pl|]
\FL
\NC presetparameters \NC \type {name [...]} \NC
Assign default values to a category of parameters. Sometimes it makes sense
not to set a default, because then you can check if a parameter has been set
at all.
\NC \NR
\NC applyparameters \NC \type {name macro} \NC
This prepares the parameter handler for the given category and calls the
given macro when that is done.
\NC \NR
\NC getparameters \NC \type {name [...]} \NC
The parameters given after the category name are set.
\NC \NR
\ML
\NC hasparameter \NC \type {names} \NC
Returns \type {true} when a parameter is set, and \type {false} otherwise.
\NC \NR
\NC hasoption \NC \type {names options} \NC
Returns \type {true} when there is overlap in given options, and \type
{false} otherwise.
\NC \NR
\ML
\NC getparameter \NC \type {names} \NC
Resolves the parameter with the given name. because a parameter itself can
have a parameter list you can pass additional names to reach the final
destination.
\NC \NR
\NC getparameterdefault \NC \type {names} \NC
Resolves the parameter with the given name. because a parameter itself can
have a parameter list you can pass additional names to reach the final
destination. The last value is used when no parameter is found.
\NC \NR
\ML
\NC getparametercount \NC \type {names} \NC
Returns the size if a list (array).
\NC \NR
\NC getmaxparametercount \NC \type {names} \NC
Returns the size if a list (array) but descends into lists to find the largest size
of a sublist.
\NC \NR
\ML
\NC getparameterpath \NC \type {names string boolean} \NC
Returns the parameter as path. The optional string is one of \type {--},
\type {..} or \type {...} and the also optional boolean will force a closed
path.
\NC \NR
\NC getparameterpen \NC \type {names} \NC
Returns the parameter as pen (path).
\NC \NR
\NC getparametertext \NC \type {names boolean} \NC
Returns the parameter as string. The boolean can be used to force prepending
a so called \type {\strut}.
\NC \NR
\ML
\NC pushparameters \NC \type {category} \NC
Pushed the given (sub) category onto the stack so that we don't need to give
the category each time.
\NC \NR
\NC popparameters \NC \NC
Pops the current (sub) category from the stack.
\NC \NR
\LL
\stoptabulate
Most commands accept a list of strings separated by one or more spaces, The
resolved will then stepwise descend into the parameter tree. This means that a
parameter itself can refer to a list. When a value is an array and the last name
is a number, the value at the given index will be returned.
\starttyping
"category" "name" ... "name"
"category" "name" ... number
\stoptyping
The \type {category} is not used when we have pushed a (sub) category which can
save you some typing and also is more efficient. Of course than can mean that you
need to store values at a higher level when you need them at a deeper level.
There are quite some extra helpers that relate to this mechanism, at the
\METAPOST\ end as well as at the \LUA\ end. They aim for instance at efficiently
dealing with paths and can be seen at work in the mentioned module.
There is one thing you should notice. While \METAPOST\ has numeric, string,
boolean and path variables that can be conveniently be passed to and from \LUA,
communicating colors is a bit of a hassle. This is because \RGB\ and \CMYK\
colors and gray scales use different types. For this reason it is strongly
recommended to use strings that refer to predefined colors instead. This also
enforces consistency with the \TEX\ end. As convenience you can define colors at
the \METAFUN\ end.
\startbuffer
\startMPcode
definecolor [ name = "MyColor", r = .5, g = .25, b = .25 ]
fill fullsquare xyscaled (TextWidth,5mm) withcolor "MyColor" ;
\stopMPcode
\stopbuffer
\typebuffer[option=TEX]
\startlinecorrection
\getbuffer
\stoplinecorrection
\stopchapter
\stopcomponent
|
