57
edits
Changes
Jump to navigation
Jump to search
< [[Main Page]]= Programming Topics =
<texcode>== Commands and Arguments ==* [[System Macros]] (''Recommended reading''. Topics: temporary variables, expansion control, argument grabbing and handling, definitions and assignments, branches and decisions, cases, comma separated lists, assignments and parameters, user interaction.)\setvariables* [[namespaceProgramming in LuaTeX]] (Topic: alleviating the more cumbersome sides of TeX programming.)* [[keyCommands with KeyVal arguments|Commands with Key=valueValue arguments]]: (Topic: things like <code>\getvariable{namespace}{key}command[thiskey=thatvalue]</texcodecode>.) * [[Commands with optional arguments]]: (Topic: one or more optional arguments within brackets.) == Module Parameters ==* [[Module Parameters]]: Passing parameters to modules.
Some commands have special characters in their names, that TeX normally does not consider to be letters: <tt>@</tt>, <tt>!</tt> and <tt>?</tt>. Before and after the use or definition of such protected commands in your input files, the catcode of these characters has to be changed. This is done by <cmd>unprotect</cmd> and <cmd>protect</cmd>:== Debugging ==
The newly defined command <tt>\!test</tt> can = Use of course only be called upon when we are in the <cmd>unprotect</cmd>ed state, otherwise TeX reads the command <tt>\!</tt>, followed by the word <tt>test</tt> (and probably complains loudly about not being in math mode). These protection/unprotection commands can be nested. When the nesting becomes deeper than one level, the system reports the current protection level. It is a good habit to always start your macro files with <cmd>unprotect</cmd> and end them with <cmd>protect</cmd>.brackets =
== Processing lists of values ==Curly braces not only give grouping but generally=== Processing are used for objects to be typeset, as for \in{Figure}{a comma-separated list of values ===} [fig:ref].
Suppose you defined For new users, it is worth repeating here that arguments within bracescan be either a command like this one somewhere in your document:comma-separated list of words OR a comma-separated<texcode>list of keyword=value pairs, BUT NOT A MIXTURE OF BOTH. Generally, akeyword=value exists for all words, for example \def\IHaveTo#1#2{I have to #1 on #2.\par}</texcode>So calling<texcode>cite[authoryear][ref]and \IHaveTo{tidy up}{Monday}</texcode>This will print out:cite[alternative=authoryear,reference=ref]
<context>values can be grouped using curly braces, as in\def\IHaveTo#1#2cite[alternative=authoryear,lefttext={I have to #1 on #2.\par}\IHaveTo{tidy upsee }{Monday,}][ref1,ref2] where the</context>lefttext is associated with the first cite reference (and none with thesecond). This can be tricky but is in fact rather straight-forward.
But sometimes you have to repeat some task more than once. In this case you can define a new command:<texcode>\def\MyMumOrderedMeTo[#1]#2% {\processcommalist[#1]{\IHaveTo{#2}}}</texcode>Calling<texcode>\MyMumOrderedMeTo[Monday,Wednesday,Saturday]{tidy up}</texcode>will spare you some typing <i>(but not some tidying up!)</i>:= Using variables =
<context>\def\IHaveTo#1#2{I have There are several ways to #1 on #2handle variables in ConTeXt.\par}\def\MyMumOrderedMeTo[#1]#2%The recommended and easiest method is to use the {<tt>\processcommalist[#1]{\IHaveTo{#2}}}setvariables</tt> and <tt>\MyMumOrderedMeTo[Monday,Wednesday,Saturday]{tidy up}getvariable</contexttt>macros.Doing it this way you also avoid to get in conflict withalready defined stuff (as variables use their own namespace).
In case a command <tt>\IHaveTo</tt> is already defined in a slightly different way:
you can define Use <tt>\getvariable</tt> to process a variable. Reading an undefinedvariable results in the <tt>\MyMumOrderedMeToempty</tt> token. This is not a serious problem,as long asyou expect text only.But be warned:the compilation process breaks, if you expect a dimensionor number. So better take care, that you define your variables, before you use them.
\def\MyMumOrderedMeTo[#1]#2%gets value of the variable namespace:key {\begingroup \def\processitem##1getvariable{\IHaveTo[##1]namespace}{#2}}% \processcommalist[#1]\processitem \endgroupkey}
ThisTo avoid problems, again, producesalso pay attention to the following:
=== Processing OK, here comes a dash-separated list of values === Sometimes you have more work to do than just that boring stuff at homesimple example. And as it is quite important as wellLet's say, you don't that we want to loose your time enumerating all of the tasks. Being able to do something likehave variablespace before and after a letter macro called <texcodett>\IHaveToDoTheTasks[1-4,7,9-11]{until tomorrow}Opening</texcodett>may sound like a good idea.
Suppose you already defined:
You have to define some By using variables in your macros first (thanks to Taco!):, you can separate the layout definition,<texcode>% a few auxiliary core so that your macros are needed to uncompress the listget much more flexible.%% \uncompresslist is the twin of the already existing \compresslist% which works in the other direction (syst-new)%\unprotect % I guess this function is already available but couldnt find it...%\def\apptomac#1#2% {\ifx#1\empty\def#1{#2}\else \@EA\def\@EA#1\@EA{#1Just ensure, that all variables are set,#2}\fi}before you use them!
% the next macro does In this:%% \itemwithdash<<9-11>>- => \dorecurse {<<1+11-9>>}% {\apptomac\uncompressedlist<<9-1+\recurselevel>>}%% (example we want to have a blank line in front of the 1+ opening, and -1 are needed to solve a counter offsettwo blank lines right after it.)\def\itemwithdash#1-#2-% {\@EA\dorecurse\@EA {\The value for the\numexpr 1+#2-#1\relax}%second key contains {\@EA\apptomac\@EA\uncompressedlist\@EA {\the\numexpr #1-1+\recurselevel\relax}}}%square brackets, so it must be enclosed in braces.
% top level. The result will be in \uncompressedlist
\def\uncompresslist[#1]%
{\def\uncompressedlist{}%
\def\processitem##1%
{\doifinstringelse{-}{##1}
{\itemwithdash##1-}
{\apptomac\uncompressedlist{##1}}}%
\processcommalist[#1]\processitem }
\protect
</texcode>
And then you're ready to define
Guess what! Your You can now save this style setup (among others) in a separate file andinclude it at the start of your document (before <tt>\IHaveToDoTheTasks[1-4,7,9-11]{until tomorrow}Opening</tt> results in:isdefined or at least used).
<context>And don't forget:\def\IHaveToDoTheTask[#1]#2{The task #1 has to be done #2.\par}'''Ensure that all variables are set before you use them!'''
% a few auxiliary core macros are needed == CLD ==How to pass variable from TeX to uncompress the listLua and vice versa? See [[CLD_passing_variables#Variables|CLD passing variables]].%% \uncompresslist is the twin of the already existing \compresslist% which works in the other direction (syst-new)%\unprotect
% I guess this function is already available but couldnt find it...%\def\apptomac#1#2% {\ifx#1\empty\def#1{#2}\else \@EA\def\@EA#1\@EA{#1,#2}\fi}= Defining new commands =
% the next macro does this:%% \itemwithdash<<9-11>>- => \dorecurse {<<1+11-9>>}% {\apptomac\uncompressedlist<<9-1+\recurselevel>>}%% (the 1+ and -1 are needed to solve a counter offset.)\def\itemwithdash#1-#2-% {\@EA\dorecurse\@EA {\the\numexpr 1+#2-#1\relax}% {\@EA\apptomac\@EA\uncompressedlist\@EA {\the\numexpr #1-1+\recurselevel\relax}}}%= Special characters in command names ==
% top level. The result will Some commands have special characters in their names, that TeX normally does not consider to be in \uncompressedlist\def\uncompresslist[#1]%letters: <tt>@</tt>, <tt>!</tt> and <tt>?</tt>. {\def\uncompressedlist{}%Before and after the use or definition of such protected commands in your input files, the catcode of these \def\processitem##1% characters has to be changed. This is done by {\doifinstringelse{-cmd|unprotect}{##1} and {\itemwithdash##1-} {\apptomac\uncompressedlist{##1}}cmd|protect}% \processcommalist[#1]\processitem }:
So - what The newly defined command <tt>\!test</tt> can of course only be called upon when we are you still waiting for? Go back in the {{cmd|unprotect}}ed state, otherwise TeX reads the command <tt>\!</tt>, followed by the word <tt>test</tt> (and probably complains loudly about not being in math mode). These protection/unprotection commands can be nested. When the nesting becomes deeper than one level, the system reports the current protection level. It is a good habit to work always start your macro files with {{cmd|unprotect}} and do end them right away!with {{cmd|protect}}.
=== Comments ===
Resulted from thread [http://archive.contextgarden.net/thread/20050704.151237.f815d89d.html] and will be used in some modules such as [[RawSteps]]. It would be nice if processing dash-separated lists of values would make it into the ConTeXt core.
== Passing (For passing text to LuaTex verbatim text as macro parameter ==, see the [[Programming_in_LuaTeX#Manipulating_verbatim_text_for_dummies|Programming in LuaTeX]] article on this wiki.)
Add hints on bracket usage; c&p from the list: https://www.mail-archive.com/ntg-context@ntg.nl/msg87937.html
== Using variables ConTeXt Features ==* [[Modes]]: Conditional processing of text* [[Setups]]: An alternative to macros for storing chunks of code
== Defining new commands Programming Techniques =='''Special characters * [[Processing Lists]]: Processing lists of values* [[Counters]]: Manipulating counters in command names'''context* [[Expressions]]: Evaluating expressions of type number, dimen, glue or muglue* [[Executesystemcommand]]: process contents of an environment by another program* Loops and expansion [http://randomdeterminism.wordpress.com/2009/03/05/tex-programming-the-past-the-present-and-the-future/ (blog post)]
* [[Console Mode]]: Using ConTeXt on keyboard input directly, rather than loading a <texcodett>\unprotect\def\!test{alfa} \protect .tex</texcodett>file.
One must '''See alsonot''':confuse with the LaTeX convention where "mandatory"[[Commands with KeyVal arguments|Commands with Key=Value arguments]], are contained in curly braces and brackets indicate[[Commands with "optional " arguments]]>.
To store variables, you can use the <tt>\setvariables</tt>
macro.
<texcode>
% stores value in variable namespace:key\defsetvariables[namespace][key=value]% stores the expanded value\IHaveTosetevariables[namespace][#1key=value]#2{I have to #2 on #1.% global\par}setgvariables[namespace][key=value]% global and expanded value\setxvariables[namespace][key=value]
</texcode>
<texcode>
</texcode>
You can set several variables (same namespace) at the same time.So the command <tt>\setvariables<context/tt>logically uses the '''plural''' form\def\IHaveTo[#1]#2{I have to #2 on #1and works with '''square brackets'''.\par}\def\MyMumOrderedMeTo[#1]#2%On the other hand you can only process one variable at the same time, so {<tt>\begingroup \def\processitem##1{\IHaveTo[##1]{#2}}% \processcommalist[#1]\processitem \endgroup}\MyMumOrderedMeTo[Monday,Wednesday,Saturday]{tidy up}getvariable</contexttt>uses the '''singular''' form and works with '''braces'''.
<texcode>
\long\def\IHaveToDoTheTask[Opening#1]#2{The task % \getvariable{Letter:opening}{before} \noindent{\begstrut#1 has to be done #2.\parendstrut} \getvariable{Letter:opening}{after}}
</texcode>
<texcode>
\def\IHaveToDoTheTaskssetvariables[#1Letter:opening]#2% {[before=\begingroupblank, \uncompresslist[#1]% <after= Yeah! \def\processitem##1{\IHaveToDoTheTaskblank[##12*big]{#2}}%, \processcommacommand[\uncompressedlist ]\processitem \endgroup}
</texcode>
<texcode>\protectunprotect\def\IHaveToDoTheTasks[#1]#2% {\begingroup \uncompresslist[#1]% <= Yeah! \def\processitem##1{\IHaveToDoTheTask[##1]test{#2}alfa}% \processcommacommand[\uncompressedlist]\processitem \endgroup} \IHaveToDoTheTasks[1-4,7,9-11]{until tomorrow}protect </contexttexcode>
= Passing verbatim text as macro parameter =
In case you want to write macros that should handle verbatim text,
\TextWithSpaces{A gap from here to there!}
</context>
[[Category:Programming and Databases]]
[[Category:Tools]]
