Source Browser ?

1% language=us runpath=texruns:manuals/cld
2
3\startcomponent cld-summary
4
5\environment cld-environment
6
7\usemodule[s][characters-properties]
8
9\startchapter[title=A sort of summary]
10
11In this chapter we summarize the functionality provided by the \type {context}
12namespace. We repeat some of what has been explained in other chapter so that in
13fact you can start with this summary.
14
15If you have read this manual (or seen code) you know that you can access all the
16core commands using this namespace:
17
18\starttyping
19context.somecommand("some argument")
20context["somecommand"]("some argument")
21\stoptyping
22
23These calls will eventually expand \type {\somecommand} with the given argument.
24This interface has been around form the start and has proven to be quite flexible
25and robust. In spite of what you might think, the \type {somecommand} is not
26really defined in the \type {context} namespace, but in its own one called \type
27{core}, accessible via \type {context.core}.
28
29Next we describe the commands that are naturally defined in the \type {context}
30namespace. Some have counterparts at the macro level (like \type {bgroup}) but
31many haven't (for instance \type {rule}). We tried not to polute the \type
32{context} namespace too much but although we could have put the helpers in a
33separate namespace it would make usage a bit more unnatural.
34
35\startsection[title=Access to commands]
36
37\startsummary[title={context(".. some text ..")}]
38
39The string is flushed as|-|is:
40
41\starttyping
42.. some text ..
43\stoptyping
44
45\stopsummary
46
47\startsummary[title={context("format",...)}]
48
49The first string is a format specification according that is passed to the \LUA\
50function \type {format} in the \type {string} namespace. Following arguments are
51passed too.
52
53\stopsummary
54
55\startsummary[title={context(123,...)}]
56
57The numbers (and following numbers or strings) are flushed without any
58formatting.
59
60\starttyping
61123... (concatenated)
62\stoptyping
63
64\stopsummary
65
66\startsummary[title={context(true)}]
67
68An explicit \type {endlinechar} is inserted, in \TEX\ speak:
69
70\starttyping
71^^M
72\stoptyping
73
74\stopsummary
75
76\startsummary[title={context(false,...)}]
77
78Strings and numbers are flushed surrounded by curly braces, an indexed table is
79flushed as option list, and a hashed table is flushed as parameter set.
80
81\starttyping
82multiple {...} or [...] etc
83\stoptyping
84
85\stopsummary
86
87\startsummary[title={context(node)}]
88
89The node (or list of nodes) is injected at the spot. Keep in mind that you need
90to do the proper memory management yourself.
91
92\stopsummary
93
94\startsummary[title={context["command"] context.core["command"]}]
95
96The function that implements \type {\command}. The \type{core} table is where
97these functions realy live.
98
99\stopsummary
100
101\startsummary[title={context["command"](value,...)}]
102
103The value (string or number) is flushed as a curly braced (regular) argument.
104
105\starttyping
106\command {value}...
107\stoptyping
108
109\stopsummary
110
111\startsummary[title={context["command"]({ value },...)}]
112
113The table is flushed as value set. This can be an identifier,
114a list of options, or a directive.
115
116\starttyping
117\command [value]...
118\stoptyping
119
120\stopsummary
121
122\startsummary[title={context["command"]({ key = val },...)}]
123
124The table is flushed as key|/|value set.
125
126\starttyping
127\command [key={value}]...
128\stoptyping
129
130\stopsummary
131
132\startsummary[title={context["command"](true)}]
133
134An explicit \type {endlinechar} is inserted.
135
136\starttyping
137\command ^^M
138\stoptyping
139
140\stopsummary
141
142\startsummary[title={context["command"](node)}]
143
144The node(list) is injected at the spot. Keep in mind that you need to do the
145proper memory management yourself.
146
147\starttyping
148\command {node(list)}
149\stoptyping
150
151\stopsummary
152
153\startsummary[title={context["command"](false,value)}]
154
155The value is flushed without encapsulating tokens.
156
157\starttyping
158\command value
159\stoptyping
160
161\stopsummary
162
163\startsummary[title={context["command"]({ value }, { key = val }, val, false, val)}]
164
165The arguments are flushed accordingly their nature and the order can be any.
166
167\starttyping
168\command [value][key={value}]{value}value
169\stoptyping
170
171\stopsummary
172
173\startsummary[title={context.direct(...)}]
174
175The arguments are interpreted the same as if \type {direct} was a command, but no
176\type {\direct} is injected in front. Braces are added:
177
178\startbuffer
179regular \expandafter \bold \ctxlua{context.direct("bold")} regular
180black \expandafter \color \ctxlua{context.direct({"red"})}{red} black
181black \expandafter \color \ctxlua{context.direct({"green"},"green")} black
182\stopbuffer
183
184\typebuffer
185
186The \type {\expandafter} makes sure that the \type {\bold} and \type {\color}
187macros see the following \type{{bold}}, \type {[red]}, and \type {[green]{green}}
188arguments.
189
190\startlines\getbuffer\stoplines
191
192\stopsummary
193
194\startsummary[title={context.delayed(...)}]
195
196The arguments are interpreted the same as in a \type {context} call, but instead
197of a direct flush, the arguments will be flushed in a next cycle.
198
199\stopsummary
200
201\startsummary[title={context.delayed["command"](...)}]
202
203The arguments are interpreted the same as in a \type {command} call, but instead
204of a direct flush, the command and arguments will be flushed in a next cycle.
205
206\stopsummary
207
208\startsummary[title={context.nested["command"]}]
209
210This command returns the command, including given arguments as a string. No
211flushing takes place.
212
213\stopsummary
214
215\startsummary[title={context.nested}]
216
217This command returns the arguments as a string and treats them the same as a
218regular \type {context} call.
219
220\stopsummary
221
222\startsummary[title={context.formatted["command"]([<regime>,]<format>,<arguments>)}]
223
224This command returns the command that will pass it's arguments to the string
225formatter. When the first argument is a number, then it is interpreted as a
226catcode regime.
227
228\stopsummary
229
230\startsummary[title={context.formatted([<regime>,]<format>,<arguments>)}]
231
232This command passes it's arguments to the string formatter. When the first
233argument is a number, then it is interpreted as a catcode regime.
234
235\stopsummary
236
237\stopsection
238
239\startsection[title=\METAFUN]
240
241\startsummary[title={context.metafun.start()}]
242
243This starts a \METAFUN\ (or \METAPOST) graphic.
244
245\stopsummary
246
247\startsummary[title={context.metafun.stop()}]
248
249This finishes and flushes a \METAFUN\ (or \METAPOST) graphic.
250
251\stopsummary
252
253\startsummary[title={context.metafun("format",...)}]
254
255The argument is appended to the current graphic data but the string formatter is
256used on following arguments.
257
258\stopsummary
259
260\startsummary[title={context.metafun.delayed}]
261
262This namespace does the same as \type {context.delayed}: it wraps the code in such
263a way that it can be used in a function call.
264
265\stopsummary
266
267\startsection[title=Building blocks]
268
269\startsummary[title={context.bgroup() context.egroup()}]
270
271These are just \type {\bgroup} and \type {\egroup} equivalents and as these are
272in fact shortcuts to the curly braced we output these instead.
273
274\stopsummary
275
276\startsummary[title={context.space()}]
277
278This one directly maps onto \type {\space}.
279
280\stopsummary
281
282\startsummary[title={context.par()}]
283
284This one directly maps onto \type {\par}.
285
286\stopsummary
287
288\stopsection
289
290\startsection[title=Basic Helpers]
291
292\startsummary[title={context.rule(wd,ht,dp,direction) context.rule(specification)}]
293
294A rule node is injected with the given properties. A specification is just a
295table with the four fields. The rule gets the current attributes.
296
297\stopsummary
298
299\startsummary[title={context.glyph(fontid,n) context.glyph(n)}]
300
301A glyph node is injected with the given font id. When no id is given, the current font
302is used. The glyph gets the current attributes.
303
304\stopsummary
305
306\startsummary[title={context.char(n) context.char(str)  context.char(tab)}]
307
308This will inject one or more copies of \type {\char} calls. You can pass a
309number, a string representing a number, or a table with numbers.
310
311\stopsummary
312
313\startsummary[title={context.utfchar(n) context.utfchar(str)}]
314
315This injects is \UTF\ character (one or more bytes). You can pass a number
316or a string representing a numbers. You need to be aware of special
317characters in \TEX, like \type {#}.
318
319\stopsummary
320
321\stopsection
322
323\startsection[title={Registers}]
324
325This is a table that hosts a couple of functions. The following \type {new}
326ones are available:
327
328\starttyping
329local n = newdimen (name)
330local n = newskip  (name)
331local n = newcount (name)
332local n = newmuskip(name)
333local n = newtoks  (name)
334local n = newbox   (name)
335\stoptyping
336
337These define a register with name \type {name} at the \LUA\ end and \type {\name}
338at the \TEX\ end. The registers' number is returned. The next function is like
339\type {\chardef}: it defines \type {\name} with value \type {n}.
340
341\starttyping
342local n = newchar(name,n)
343\stoptyping
344
345It's not likely that you will use any of these commands, if only because when
346you're operating from the \LUA\ end using \LUA\ variables is more convenient.
347
348\stopsection
349
350\startsection[title=Catcodes]
351
352Normally we operate under the so called \type {context} catcode regime. This
353means that content gets piped to \TEX\ using the same meanings for characters as
354you normally use in \CONTEXT. So, a \type {$} starts math. In \in {table}
355[tab:catcodes] we show the catcode regimes.
356
357\startplacetable[location=page,title={Catcode regimes},reference=tab:catcodes]
358    \showcharactercatcodes
359\stopplacetable
360
361\startsummary[title={context.catcodes}]
362
363The \type {context.catcodes} tables contains the internal numbers of the
364catcode tables used. The next table shows the names that can be used.
365
366\starttabulate[|lT|cT|lT|]
367\BC name     \BC mnemonic \BC \TEX\ command \NC \NR
368\NC context  \NC ctx      \NC ctxcatcodes   \NC \NR
369\NC protect  \NC prt      \NC prtcatcodes   \NC \NR
370\NC plain    \NC tex      \NC texcatcodes   \NC \NR
371\NC text     \NC txt      \NC txtcatcodes   \NC \NR
372\NC verbatim \NC vrb      \NC vrbcatcodes   \NC \NR
373\stoptabulate
374
375\stopsummary
376
377\startsummary[title={context.newindexer(catcodeindex)}]
378
379This function defines a new indexer. You can think of the context command itself
380as an indexer. There are two (extra) predefined indexers:
381
382\starttyping
383context.verbatim = context.newindexer(context.catcodes.verbatim)
384context.puretext = context.newindexer(context.catcodes.text)
385\stoptyping
386
387\stopsummary
388
389\startsummary[title={context.pushcatcodes(n) context.popcatcodes()}]
390
391These commands switch to another catcode regime and back. They have to be used
392in pairs. Only the regimes atthe \LUA\ end are set.
393
394\stopsummary
395
396\startsummary[title={context.unprotect() context.protect()}]
397
398These commands switch to the protected regime and back. They have to be used in
399pairs. Beware: contrary to what its name suggests, the \type {unprotect} enables
400the protected regime. These functions also issue an \type {\unprotect} and \type
401{\protect} equivalent at the \TEX\ end.
402
403\stopsummary
404
405\startsummary[title={context.verbatim context.puretext}]
406
407The differences between these are subtle:
408
409\startbuffer
410\startluacode
411    context.verbatim.bold("Why do we use $ for math?") context.par()
412    context.verbatim.bold("Why do we use { as start?") context.par()
413    context.verbatim.bold("Why do we use } as end?")   context.par()
414    context.puretext.bold("Why do we use {\\bi $} at all?")
415\stopluacode
416\stopbuffer
417
418\typebuffer
419
420Verbatim makes all characters letters while pure text leaves the backslash and
421curly braces special.
422
423\startpacked \getbuffer \stoppacked
424
425\stopsummary
426
427\startsummary[title={context.protected}]
428
429The protected namespace is only used for commands that are in the \CONTEXT\
430private namespace.
431
432\stopsummary
433
434\startsummary[title={context.escaped(str) context.escape(str)}]
435
436The first command pipes the escaped string to \TEX, while the second one just
437returns an unescaped string. The characters \typ {# $ % \ \ { }} are escaped.
438
439\stopsummary
440
441\startsummary[title={context.startcollecting() context.stopcollecting()}]
442
443These two commands will turn flushing to \TEX\ into collecting. This can be handy
444when you want to interface commands that grab arguments using delimiters and as
445such they are used deep down in some table related interfacing. You probably
446don't need them.
447
448\stopsummary
449
450\stopsection
451
452\startsection[title={Templates}]
453
454In addition to the regular template mechanism (part of the utilities) there is a
455dedicated template feature in the \type {context} namespace. An example demonstrates
456its working:
457
458\startbuffer
459\startluacode
460  local MyTable = [[
461    \bTABLE
462      \bTR
463         \bTD \bf %one_first% \eTD
464         \bTD %[one_second]% \eTD
465      \eTR
466      \bTR
467        \bTD \bf %two_first% \eTD
468        \bTD %[two_second]% \eTD
469      \eTR
470    \eTABLE
471  ]]
472
473  context.templates[MyTable] {
474    one_first  = "one",
475    two_first  = "two",
476    one_second = "just one $",
477    two_second = "just two $",
478  }
479\stopluacode
480\stopbuffer
481
482\typebuffer
483
484This renders:
485
486\startlinecorrection
487    \getbuffer
488\stoplinecorrection
489
490You can also use more complex tables. Watch the space before and after the keys:
491
492\startbuffer
493\startluacode
494  local MyOtherTable = [[
495    \bTABLE
496      \bTR
497        \bTD \bf % ['one']['first'] % \eTD
498        \bTD %[ ['one']['second'] ]% \eTD
499      \eTR
500      \bTR
501        \bTD \bf % ['two']['first'] % \eTD
502        \bTD %[ ['two']['second'] ]% \eTD
503      \eTR
504    \eTABLE
505  ]]
506
507  local data = {
508    one = { first = "one", second = "only 1$" },
509    two = { first = "two", second = "only 2$" },
510  }
511
512  context.templates[MyOtherTable](data)
513
514  context.templates(MyOtherTable,data)
515\stopluacode
516\stopbuffer
517
518\typebuffer
519
520We get:
521
522\startlinecorrection
523    \getbuffer
524\stoplinecorrection
525
526\stopsection
527
528\startsection[title={Management}]
529
530\startsummary[title={context.functions}]
531
532This is private table that hosts managament of functions. You'd better leave this
533one alone!
534
535\stopsummary
536
537\startsummary[title={context.nodes}]
538
539Normally you will just use \type {context(<somenode>)} to flush a node and this
540private table is more for internal use.
541
542\stopsummary
543
544\stopsection
545
546\startsection[title=String handlers]
547
548These two functions implement handlers that split a given string into lines and
549do something with it. We stick to showing their call. They are used for special
550purpose flushing, like flushing content to \TEX\ in commands discussed here. The
551\XML\ subsystem also used a couple of dedicated handlers.
552
553\starttyping
554local foo = newtexthandler {
555    content    = function(s) ... end,
556    endofline  = function(s) ... end,
557    emptyline  = function(s) ... end,
558    simpleline = function(s) ... end,
559}
560
561local foo = newverbosehandler {
562    line    = function(s) ... end,
563    space   = function(s) ... end,
564    content = function(s) ... end,
565    before  = function() ... end,
566    after   = function() ... end,
567}
568\stoptyping
569
570\startsummary[title={context.printlines(str)}]
571
572The low level \type {tex.print} function pipes its content to \TEX\ and thereby
573terminates at at \type {\r} (cariage return, \ASCII\ 13), although it depends on
574the way catcodes and line endings are set up. In fact, a line ending in \TEX\ is
575not really one, as it gets replaced by a space. Only several lines in succession
576indicate a new paragraph.
577
578\startbuffer
579\startluacode
580    tex.print("line 1\n line 2\r line 3")
581\stopluacode
582\stopbuffer
583
584\typebuffer
585
586This renders only two lines:
587
588\getbuffer
589
590\startbuffer
591\startluacode
592    context("line 1\n line 2\r line 3")
593\stopluacode
594\stopbuffer
595
596However, the \type {context} command gives all three lines:
597
598\typebuffer
599
600Like:
601
602\getbuffer
603
604The \type {context.printlines} command is a direct way to print a string in a way
605similar to reading from a file. So,
606
607\starttyping
608tex.print(io.loaddata(resolvers.findfile("tufte")))
609\stoptyping
610
611Gives one line, while:
612
613\starttyping
614context.printlines(io.loaddata(resolvers.findfile("tufte")))
615\stoptyping
616
617gives them all, as does:
618
619\starttyping
620context(io.loaddata(resolvers.findfile("tufte")))
621\stoptyping
622
623as does a na\"ive:
624
625\starttyping
626tex.print((string.gsub(io.loaddata(resolvers.findfile("tufte")),"\r","\n")))
627\stoptyping
628
629But, because successive lines need to become paragraph separators as bit more
630work is needed and that is what \type {printlines} and \type {context} do for
631you. However, a more convenient alternative is presented next.
632
633\stopsummary
634
635\startsummary[title={context.loadfile(name)}]
636
637This function locates and loads the file with the given name. The leading and
638trailing spaces are stripped.
639
640\stopsummary
641
642\startsummary[title={context.runfile(name)}]
643
644This function locates and processes the file with the given name. The assumption
645is that it is a valid \LUA\ file! When no suffix is given, the suffix \type {cld}
646(\CONTEXT\ \LUA\ document) is used.
647
648\stopsummary
649
650\startsummary[title={context.viafile(data[,tag])}]
651
652The \type {data} is saved to a (pseudo) file with the optional name \type {tag}
653and read in again from that file. This is a robust way to make sure that the data
654gets processed like any other data read from file. It permits all kind of
655juggling with catcodes, verbatim and alike.
656
657\stopsummary
658
659\stopsection
660
661\startsection[title={Helpers}]
662
663\startsummary[title={context.tocontext(variable)}]
664
665For documentation or tracing it can be handy to serialize a variable. The \type
666{tocontext} function does this:
667
668\starttyping
669context.tocontext(true)
670context.tocontext(123)
671context.tocontext("foo")
672context.tocontext(tonumber)
673context.tocontext(nil)
674context.tocontext({ "foo", "bar" },true)
675context.tocontext({ this = { foo , "bar" } },true)
676\stoptyping
677
678Beware, \type {tocontext} is also a table that you can assign to, but that might
679spoil serialization. This property makes it possible to extend the serializer.
680
681\stopsummary
682
683\startsummary[title={context.tobuffer(name,str[,catcodes])}]
684
685With this function you can put content in a buffer, optionally under a catcode
686regime.
687
688\stopsummary
689
690\startsummary[title={context.tolines(str[,true])}]
691
692This function splits the string in lines and flushes them one by one. When the
693second argument is \type {true} leading and trailing spaces are stripped. Each
694flushed line always gets one space appended.
695
696\stopsummary
697
698\startsummary[title={context.fprint([regime,]fmt,...),tex.fprint([regime,]fmt,...)}]
699
700The \type {tex.fprint} is just there to complement the other flushers in the
701\type {tex} namespace and therefore we also have it in the \type {context}
702namespace.
703
704\stopsummary
705
706\stopsection
707
708\startsection[title=Tracing]
709
710\startsummary[title={context.settracing(true or false))}]
711
712You can trace the \TEX\ code that is generated at the \TEX\ end with:
713
714\starttyping
715\enabletrackers[context.trace]
716\stoptyping
717
718The \LUA\ function sets the tracing from the \LUA\ end. As the \type {context}
719command is used a lot in the core, you can expect some more tracing that the code
720that you're currently checking.
721
722\stopsummary
723
724\startsummary[title={context.pushlogger(fnc) context.poplogger() context.getlogger()}]
725
726You can provide your own logger if needed. The pushed function receives one string
727argument. The getter returns three functions:
728
729\starttyping
730local flush, writer, flushdirect = context.getlogger()
731\stoptyping
732
733The \type{flush} function is similar to \type {tex.sprint} and appends its
734arguments, while \type {flushdirect} treats each argument as a line and behaves
735like \type {tex.print}. The \type {flush} function adds braces and paranthesis
736around its arguments, apartt from the first one, which is considered to be a
737command. Examples are:
738
739\starttyping
740flush("one",2,"three") -- catcode, strings|numbers
741writer("\\color",{"red"},"this is red")
742\stoptyping
743
744and:
745
746\starttyping
747flush(context.catcodes.verbatim,"one",2,"three")
748writer(context.catcodes.verbatim,"\\color",{"red"},"this is red")
749\stoptyping
750
751\stopsummary
752
753\stopsection
754
755\startsection[title=States]
756
757There are several ways to implement alternative code paths in \CONTEXT\ but modes
758and conditionals are used mostly. There area few helpers for that.
759
760\startsummary[title={context.conditionals context.setconditional(name,value)}]
761
762Conditionals are used to keep a state. You can set their value using the setter,
763but their effect is not immediate but part of the current sequence of commands
764which is delegated to \TEX. However, you can easily keep track of your state
765at the \LUA\ end with an extra boolean. So, after
766
767\starttyping
768if context.conditionals.whatever then
769    context.setconditional("dothis",false)
770else
771    context.setconditional("dothat",true)
772end
773\stoptyping
774
775the value of \type {dothis} and \type {dothat} conditions are not yet set in
776\LUA.
777
778\stopsummary
779
780\startsummary[title={context.modes context.setmode(name,value)}]
781
782As with conditionals, you can (re)set the modes in \LUA\ but their values
783get changes as part of the command sequence which is delayed till after the
784\LUA\ call.
785
786\stopsummary
787
788\startsummary[title={context.systemmodes context.setsystemmode(name,value)}]
789
790The same applies as for regular modes.
791
792\stopsummary
793
794\startsummary[title={context.trialtypesetting()}]
795
796This function returns \type {true} if we're in trial typesetting mode (used when
797for instance prerolling a table).
798
799\stopsummary
800
801\stopsection
802
803\startsection[title=Steps]
804
805The stepper permits stepwise processing of \CONTEXT\ code: after a step contyrol
806gets delegated to \CONTEXT\ and afterwards back to \LUA. There main limitation of
807this mechanism is that it cannot exceed the number of input levels.
808
809\startsummary[title={context.stepwise() context.step([str])}]
810
811Usage is as follows:
812
813\starttyping
814context.stepwise (function()
815    ...
816    context.step(...)
817    ...
818    context.step(...)
819    ...
820    context.stepwise (function()
821        ...
822        context.step(...)
823        ...
824    context.step(...)
825    ...
826    end)
827    ...
828    context.step(...)
829    ...
830    context.step(...)
831    ...
832end)
833\stoptyping
834
835\stopsummary
836
837\stopsection
838
839\stopchapter
840
841\stopcomponent
842