Source Browser ?

1% language=us runpath=texruns:manuals/luametafun
2
3\environment luametafun-style
4
5\startcomponent luametafun-interface
6
7\startchapter[title={Interface}]
8
9Because graphic solutions are always kind of personal or domain driven it makes not
10much sense to cook up very generic solutions. If you have a project where \METAPOST\
11can be of help, it also makes sense to spend some time on implementing the basics that
12you need. In that case you can just copy and tweak what is there. The easiest way to
13do that is to make a test file and use:
14
15\starttyping[option=TEX]
16\startMPpage
17    % your code
18\stopMPpage
19\stoptyping
20
21Often you don't need to write macros, and standard drawing commands will do the
22job, but when you find yourself repeating code, a wapper might make sense. And
23this is why we have this key|/|value interface: it's easier to abstract your
24settings than to pass them as (expression or text) arguments to a macro,
25especially when there are many.
26
27You can find many examples of the key|/|value driven user interface in the source
28files and these are actually not that hard to understand when you know a bit of
29\METAPOST\ and the additional macros that come with \METAFUN. In case you wonder
30about overhead: the performance of this mechanism is pretty good.
31
32Although the parameter handler runs on top of the \LUA\ interface, you don't need
33to use \LUA\ unless you find that \METAPOST\ can't do the job. I won't give
34examples of coding because I think that the source of \METAFUN\ provides enough
35clues, especially the file \type {mp-lmtx.mpxl}. As the name suggests this is
36part of the \CONTEXT\ version \LMTX, which runs on top of \LUAMETATEX. I leave it
37open if I will backport this functionality to \LUATEX\ and therefore \MKIV.
38
39An excellent explanation of this interface can be found at:
40
41\starttyping
42https://adityam.github.io/context-blog/post/new-metafun-interface/
43\stoptyping
44
45So (at least for now) here I can stick to just mentioning the currently stable
46interface macros:
47
48\starttabulate[|T|l|pl|]
49\FL
50\NC presetparameters \NC \type {name [...]} \NC
51    Assign default values to a category of parameters. Sometimes it makes sense
52    not to set a default, because then you can check if a parameter has been set
53    at all.
54    \NC \NR
55\NC applyparameters \NC \type {name macro} \NC
56    This prepares the parameter handler for the given category and calls the
57    given macro when that is done.
58    \NC \NR
59\NC getparameters \NC \type {name [...]} \NC
60    The parameters given after the category name are set.
61    \NC \NR
62\ML
63\NC hasparameter \NC \type {names} \NC
64    Returns \type {true} when a parameter is set, and \type {false} otherwise.
65    \NC \NR
66\NC hasoption \NC \type {names options} \NC
67    Returns \type {true} when there is overlap in given options, and \type
68    {false} otherwise.
69    \NC \NR
70\ML
71\NC getparameter \NC \type {names} \NC
72    Resolves the parameter with the given name. because a parameter itself can
73    have a parameter list you can pass additional names to reach the final
74    destination.
75    \NC \NR
76\NC getparameterdefault \NC \type {names} \NC
77    Resolves the parameter with the given name. because a parameter itself can
78    have a parameter list you can pass additional names to reach the final
79    destination. The last value is used when no parameter is found.
80    \NC \NR
81\ML
82\NC getparametercount \NC \type {names} \NC
83    Returns the size if a list (array).
84    \NC \NR
85\NC getmaxparametercount \NC \type {names} \NC
86    Returns the size if a list (array) but descends into lists to find the largest size
87    of a sublist.
88    \NC \NR
89\ML
90\NC getparameterpath \NC \type {names string boolean} \NC
91    Returns the parameter as path. The optional string is one of \type {--},
92    \type {..} or \type {...} and the also optional boolean will force a closed
93    path.
94    \NC \NR
95\NC getparameterpen \NC \type {names} \NC
96    Returns the parameter as pen (path).
97    \NC \NR
98\NC getparametertext \NC \type {names boolean} \NC
99    Returns the parameter as string. The boolean can be used to force prepending
100    a so called \type {\strut}.
101    \NC \NR
102\ML
103\NC pushparameters \NC \type {category} \NC
104    Pushed the given (sub) category onto the stack so that we don't need to give
105    the category each time.
106    \NC \NR
107\NC popparameters \NC \NC
108    Pops the current (sub) category from the stack.
109    \NC \NR
110\LL
111\stoptabulate
112
113Most commands accept a list of strings separated by one or more spaces, The
114resolved will then stepwise descend into the parameter tree. This means that a
115parameter itself can refer to a list. When a value is an array and the last name
116is a number, the value at the given index will be returned.
117
118\starttyping
119"category" "name" ... "name"
120"category" "name" ... number
121\stoptyping
122
123The \type {category} is not used when we have pushed a (sub) category which can
124save you some typing and also is more efficient. Of course than can mean that you
125need to store values at a higher level when you need them at a deeper level.
126
127There are quite some extra helpers that relate to this mechanism, at the
128\METAPOST\ end as well as at the \LUA\ end. They aim for instance at efficiently
129dealing with paths and can be seen at work in the mentioned module.
130
131There is one thing you should notice. While \METAPOST\ has numeric, string,
132boolean and path variables that can be conveniently be passed to and from \LUA,
133communicating colors is a bit of a hassle. This is because \RGB\ and \CMYK\
134colors and gray scales use different types. For this reason it is strongly
135recommended to use strings that refer to predefined colors instead. This also
136enforces consistency with the \TEX\ end. As convenience you can define colors at
137the \METAFUN\ end.
138
139\startbuffer
140\startMPcode
141    definecolor [ name = "MyColor", r = .5, g = .25, b = .25 ]
142
143    fill fullsquare xyscaled (TextWidth,5mm) withcolor "MyColor" ;
144\stopMPcode
145\stopbuffer
146
147\typebuffer[option=TEX]
148
149\startlinecorrection
150\getbuffer
151\stoplinecorrection
152
153\stopchapter
154
155\stopcomponent
156