diff options
Diffstat (limited to 'doc/context/sources/general/manuals/cld/cld-specialcommands.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/cld/cld-specialcommands.tex | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/cld/cld-specialcommands.tex b/doc/context/sources/general/manuals/cld/cld-specialcommands.tex new file mode 100644 index 000000000..37ecf45c6 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-specialcommands.tex @@ -0,0 +1,257 @@ +% language=uk + +\startcomponent cld-specialcommands + +\environment cld-environment + +\startchapter[title=Special commands] + +\index{tracing} + +\startsection[title=Tracing] + +There are a few functions in the \type {context} namespace that are no +macros at the \TEX\ end. + +\starttyping +context.runfile("somefile.cld") +\stoptyping + +Another useful command is: + +\starttyping +context.settracing(true) +\stoptyping + +There are a few tracing options that you can set at the \TEX\ end: + +\starttyping +\enabletrackers[context.files] +\enabletrackers[context.trace] +\stoptyping + +\stopsection + +\startsection[title=Overloads] + +A few macros have special functions (overloads) at the \LUA\ end. One of them is +\type {\char}. The function makes sure that the characters ends up right. The +same is true for \type {\chardef}. So, you don't need to mess around with \type +{\relax} or trailing spaces as you would do at the \TEX\ end in order to tell the +scanner to stop looking ahead. + +\starttyping +context.char(123) +\stoptyping + +Other examples of macros that have optimized functions are \type {\par}, +\type{\bgroup} and \type {\egroup}. Or take this: + +\startbuffer +1: \ctxlua{commands.doif(true)}{one} +2: \cldcommand{doif("a","a","two")} +3: \ctxcommand{doif(true)}{three} +\stopbuffer + +\typebuffer + +\startlines +\getbuffer +\stoplines + +\stopsection + +\startsection[title=Steps] + +% added and extended in sync with an article about a generic 'execute' +% feature + +We already mentioned the stepper as a very special trick so let's give +some more explanation here. When you run the following code: + +\setbox0\emptybox + +\starttyping +\startluacode + context.startitemize() + context.startitem() + context("BEFORE 1") + context.stopitem() + context("\\setbox0\\hbox{!!!!}") + context.startitem() + context("%p",tex.getbox(0).width) + context.stopitem() + context.stopitemize() +\stopluacode +\stoptyping + +You get a message like: + +\starttyping +[ctxlua]:8: attempt to index a nil value +... +10 context("\\setbox0\\hbox{!!!!}") +11 context.startitem() +12 >> context("%p",tex.getbox(0).width) +... +\stoptyping + +due to the fact that the box is still void. All that the \CONTEXT\ commands feed +into \TEX\ happens when the code snippet has finished. You can however run a +snippet of code the following way: + +\startbuffer +\startluacode + context.stepwise (function() + context.startitemize() + context.startitem() + context.step("BEFORE 1") + context.stopitem() + context.step("\\setbox0\\hbox{!!!!}") + context.startitem() + context.step("%p",tex.getbox(0).width) + context.stopitem() + context.stopitemize() + end) +\stopluacode +\stopbuffer + +\typebuffer + +and get: + +\getbuffer + +A more extensive example is: + +\startbuffer +\startluacode + context.stepwise (function() + context.startitemize() + context.startitem() + context.step("BEFORE 1") + context.stopitem() + context.step("\\setbox0\\hbox{!!!!}") + context.startitem() + context.step("%p",tex.getbox(0).width) + context.stopitem() + context.startitem() + context.step("BEFORE 2") + context.stopitem() + context.step("\\setbox2\\hbox{????}") + context.startitem() + context.step("%p",tex.getbox(2).width) + context.startitem() + context.step("BEFORE 3") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2") + context.stopitem() + context.startitem() + context.step("BEFORE 4") + context.startitemize() + context.stepwise (function() + context.step("\\bgroup") + context.step("\\setbox0\\hbox{>>>>}") + context.startitem() + context.step("%p",tex.getbox(0).width) + context.stopitem() + context.step("\\setbox2\\hbox{<<<<}") + context.startitem() + context.step("%p",tex.getbox(2).width) + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2") + context.stopitem() + context.step("\\egroup") + end) + context.stopitemize() + context.stopitem() + context.startitem() + context.step("AFTER 1\\par") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2\\par") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2\\par") + context.stopitem() + context.startitem() + context.step("AFTER 2\\par") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2\\par") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2\\par") + context.stopitem() + context.stopitemize() + end) +\stopluacode +\stopbuffer + +\typebuffer + +which gives: + +\getbuffer + +A step returns control to \TEX\ immediately and after the \TEX\ code that it +feeds back is expanded, returns to \LUA. There are some limitations due to the +input stack but normally that is no real issue. + +You can run the following code: + +\starttyping +\definenumber[LineCounter][way=bypage] +\starttext +\startluacode +for i=1,2000 do + context.incrementnumber { "LineCounter" } + context.getnumber { "LineCounter" } + context.par() +end +\stopluacode +\stoptext +\stoptyping + +You will notice however that the number is not right on each page. This is +because \TEX\ doesn't know yet that there is no room on the page. The next will +work better: + +\starttyping +\definenumber[LineCounter][way=bypage] +\starttext +\startluacode +context.stepwise(function() + for i=1,2000 do + context.testpage { 0 } + context.incrementnumber { "LineCounter" } + context.getnumber { "LineCounter" } + context.par() + context.step() + end +end) +\stopluacode +\stoptext +\starttyping + +Instead of the \type {testpage} function you can also play directly with +registers, like: + +\starttyping +if tex.pagegtotal + tex.count.lineheight > tex.pagetotal then +\starttyping + +but often an already defined helper does a better job. Of course you will +probably never need this kind of hacks anyway, if only because much more is going +on and there are better ways then. + +\stopsection + +\stopchapter + +\stopcomponent |