cld-specialcommands.tex /size: 6337 b    last modification: 2021-10-28 13:50
1% language=us runpath=texruns:manuals/cld
2
3\startcomponent cld-specialcommands
4
5\environment cld-environment
6
7\startchapter[title=Special commands]
8
9\index{tracing}
10
11\startsection[title=Tracing]
12
13There are a few functions in the \type {context} namespace that are no
14macros at the \TEX\ end.
15
16\starttyping
17context.runfile("somefile.cld")
18\stoptyping
19
20Another useful command is:
21
22\starttyping
23context.settracing(true)
24\stoptyping
25
26There are a few tracing options that you can set at the \TEX\ end:
27
28\starttyping
29\enabletrackers[context.files]
30\enabletrackers[context.trace]
31\stoptyping
32
33\stopsection
34
35\startsection[title=Overloads]
36
37A few macros have special functions (overloads) at the \LUA\ end. One of them is
38\type {\char}. The function makes sure that the characters ends up right. The
39same is true for \type {\chardef}. So, you don't need to mess around with \type
40{\relax} or trailing spaces as you would do at the \TEX\ end in order to tell the
41scanner to stop looking ahead.
42
43\starttyping
44context.char(123)
45\stoptyping
46
47Other examples of macros that have optimized functions are \type {\par},
48\type{\bgroup} and \type {\egroup}. Or take this:
49
50\startbuffer
511: \ctxlua{commands.doif(true)}{one}
522: \cldcommand{doif("a","a","two")}
533: \ctxcommand{doif(true)}{three}
54\stopbuffer
55
56\typebuffer
57
58\startlines
59\getbuffer
60\stoplines
61
62\stopsection
63
64\startsection[title=Steps]
65
66% added and extended in sync with an article about a generic 'execute'
67% feature
68
69We already mentioned the stepper as a very special trick so let's give
70some more explanation here. When you run the following code:
71
72\setbox0\emptybox
73
74\starttyping
75\startluacode
76  context.startitemize()
77    context.startitem()
78      context("BEFORE 1")
79    context.stopitem()
80    context("\\setbox0\\hbox{!!!!}")
81    context.startitem()
82      context("%p",tex.getbox(0).width)
83    context.stopitem()
84  context.stopitemize()
85\stopluacode
86\stoptyping
87
88You get a message like:
89
90\starttyping
91[ctxlua]:8: attempt to index a nil value
92...
9310             context("\\setbox0\\hbox{!!!!}")
9411             context.startitem()
9512 >>              context("%p",tex.getbox(0).width)
96...
97\stoptyping
98
99due to the fact that the box is still void. All that the \CONTEXT\ commands feed
100into \TEX\ happens when the code snippet has finished. You can however run a
101snippet of code the following way:
102
103\startbuffer
104\startluacode
105  context.stepwise (function()
106    context.startitemize()
107      context.startitem()
108        context.step("BEFORE 1")
109      context.stopitem()
110      context.step("\\setbox0\\hbox{!!!!}")
111      context.startitem()
112        context.step("%p",tex.getbox(0).width)
113      context.stopitem()
114    context.stopitemize()
115  end)
116\stopluacode
117\stopbuffer
118
119\typebuffer
120
121and get:
122
123\getbuffer
124
125A more extensive example is:
126
127\startbuffer
128\startluacode
129  context.stepwise (function()
130    context.startitemize()
131      context.startitem()
132        context.step("BEFORE 1")
133      context.stopitem()
134      context.step("\\setbox0\\hbox{!!!!}")
135      context.startitem()
136        context.step("%p",tex.getbox(0).width)
137      context.stopitem()
138      context.startitem()
139        context.step("BEFORE 2")
140      context.stopitem()
141      context.step("\\setbox2\\hbox{????}")
142      context.startitem()
143        context.step("%p",tex.getbox(2).width)
144      context.startitem()
145        context.step("BEFORE 3")
146      context.stopitem()
147      context.startitem()
148        context.step("\\copy0\\copy2")
149      context.stopitem()
150      context.startitem()
151        context.step("BEFORE 4")
152        context.startitemize()
153          context.stepwise (function()
154            context.step("\\bgroup")
155            context.step("\\setbox0\\hbox{>>>>}")
156            context.startitem()
157              context.step("%p",tex.getbox(0).width)
158            context.stopitem()
159            context.step("\\setbox2\\hbox{<<<<}")
160            context.startitem()
161              context.step("%p",tex.getbox(2).width)
162            context.stopitem()
163            context.startitem()
164              context.step("\\copy0\\copy2")
165            context.stopitem()
166            context.startitem()
167              context.step("\\copy0\\copy2")
168            context.stopitem()
169            context.step("\\egroup")
170          end)
171        context.stopitemize()
172      context.stopitem()
173      context.startitem()
174        context.step("AFTER 1\\par")
175      context.stopitem()
176      context.startitem()
177        context.step("\\copy0\\copy2\\par")
178      context.stopitem()
179      context.startitem()
180        context.step("\\copy0\\copy2\\par")
181      context.stopitem()
182      context.startitem()
183        context.step("AFTER 2\\par")
184      context.stopitem()
185      context.startitem()
186        context.step("\\copy0\\copy2\\par")
187      context.stopitem()
188      context.startitem()
189        context.step("\\copy0\\copy2\\par")
190      context.stopitem()
191    context.stopitemize()
192  end)
193\stopluacode
194\stopbuffer
195
196\typebuffer
197
198which gives:
199
200\getbuffer
201
202A step returns control to \TEX\ immediately and after the \TEX\ code that it
203feeds back is expanded, returns to \LUA. There are some limitations due to the
204input stack but normally that is no real issue.
205
206You can run the following code:
207
208\starttyping
209\definenumber[LineCounter][way=bypage]
210\starttext
211\startluacode
212for i=1,2000 do
213    context.incrementnumber { "LineCounter" }
214    context.getnumber { "LineCounter" }
215    context.par()
216end
217\stopluacode
218\stoptext
219\stoptyping
220
221You will notice however that the number is not right on each page. This is
222because \TEX\ doesn't know yet that there is no room on the page. The next will
223work better:
224
225\starttyping
226\definenumber[LineCounter][way=bypage]
227\starttext
228\startluacode
229context.stepwise(function()
230    for i=1,2000 do
231        context.testpage { 0 }
232        context.incrementnumber { "LineCounter" }
233        context.getnumber { "LineCounter" }
234        context.par()
235        context.step()
236    end
237end)
238\stopluacode
239\stoptext
240\stoptyping
241
242Instead of the \type {testpage} function you can also play directly with
243registers, like:
244
245\starttyping
246if tex.pagegtotal + tex.count.lineheight > tex.pagetotal then
247\stoptyping
248
249but often an already defined helper does a better job. Of course you will
250probably never need this kind of hacks anyway, if only because much more is going
251on and there are better ways then.
252
253\stopsection
254
255\stopchapter
256
257\stopcomponent
258