138
edits
Changes
Jump to navigation
Jump to search
m
System Macros/Key Value Assignments (view source)
Revision as of 17:51, 1 December 2020
, 17:51, 1 December 2020typo
< '''Prev:''' [[System_MacrosSystem Macros/Comma Separated Lists|Comma Separated Lists]]| '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/User Interaction|User Interaction]] > = Assignments =
Assignments are the backbone of ConTeXt. Abhorred by the concept of style file hacking, we took a considerable effort in building a parameterized system. Unfortunately there is a price to pay in terms of speed. Compared to other packages and taking the functionality of ConTeXt into account, the total size of the format file is still very acceptable. Now how are these assignments done.
</texcode>
Some ConTeXt commands take their default setups from others. All commands that are able to provide backgounds backgrounds or rules around some content, for instance, default to the standard command for ruled boxes. In situations like this we can use:
<texcode>
The boolean <code>\ifparameters</code> can be used afterwards to verify that there were assignments in the supplied argument.
= Multi-pass data =
Sometimes, typesetting requires information that is not available until later on in the document. An example would be printing the total number of pages on the first page of the document. The solution is multi-pass data: data that is saved (in the <code>.tuc</code> file) in one pass, and retrieved and used in a later pass. This section explains how to store and retrieve such data across passes.
== Storing data ==
<texcode>
% To define a dataset.
\definedataset[cats]
% The first anonymous key-value table is saved at point 1 in the cats dataset.
% (The dataset is itself a key-value table, too.)
\setdataset[cats][name=Gus, job=Theatre Cat]
% The next anonymous table is saved at point 2
% (Regardless of intervening named tables)
\setdataset[cats][scene=crime, name=Macavity, is=not there]
% To save a table by name, add the name in between the dataset and the table
\setdataset[cats][culprit][name=Mungojerry]
% Named tables can be overwritten
\setdataset[cats][culprit][name=Rumpleteaser]
</texcode>
== Retrieving data ==
In contrast to the other mentioned commands, the arguments of
{{cmd|datasetvariable}} are delimited by braces instead of
brackets. The reasoning is that this command is about producing text rather than setting values.
<texcode>
% Retrieving a named value
The name of the culprit was \datasetvariable{cats}{culprit}{name}.
% Retrieving an anonymous value --- Macavity, in this case.
\datasetvariable{cats}{2}{name}.
</texcode>
== Technical properties ==
* The tables of key-value pairs are stored as Lua tables in a <code>.tuc</code> file. They look like this:
<pre>
utilitydata.job.datasets.collected={
["mydata"]={
{ -- this table is indexed at position 1 in mydata
["key"]="value",
},
["named"]={ -- this table is indexed at position "named" in mydata
["key_in_named_table"]="value",
},
},
["myotherdata"]={
{ -- this table is indexed at position 1 in myotherdata
["key"]=["othervalue"]
},
},
}
</pre>
* Adding the option <code>[delay=yes]</code> to a {{cmd|definedataset}} call ensures that the following three entries are present in every table saved with {{cmd|setdataset}}: <code>index</code>, <code>order</code>, and <code>realpage</code>.
** The entries <code>index</code> and <code>order</code> seem to have the same number: a table written by the first {{cmd|setdataset}} call has <code>index=1</code> and <code>order=1</code>, and so on. Tables may be overwritten, of course.
** The entry <code>realpage</code> contains the real page number (so every page is counted, numbered or not) of the page TeX was working on when it encountered the {{cmd|setdataset}} call.
<texcode>
% Create the dataset `mydata`
\definedataset[mydata][delay=yes]
% index=1, realpage=2
\setdataset[mydata][goldfish][colour=gold]
% index=2, realpage=1
\setdataset[mydata][silverfish][type=insect]
\page[yes]
% index=3, realpage=2; overwrites previous goldfish table.
\setdataset[mydata][goldfish][type=fish]
% Results in the following Lua table in the .tuc file
% ["mydata"]={
% ["goldfish"]={
% ["type"]="fish",
% ["index"]=3,
% ["order"]=3,
% ["realpage"]=2,
% },
% ["goldfish"]={
% ["type"]="insect",
% ["index"]=2,
% ["order"]=2,
% ["realpage"]=1,
% },
% }
</texcode>
* Keys or values cannot contain commas.
<texcode>
% This does not work
\definedataset[mydata]
\setdataset[mydata][name="Bond, James Bond"]
% Results in
% ["mydata"]={
% {
% ["name"]="\"Bond",
% ["James Bond\""]="",
% },
% }
</texcode>
* Single keys are stored as empty values.
<texcode>
\definedataset[mydata]
\setdataset[mydata][A4,landscape]
% Results in
% ["mydata"]={
% {
% ["A4"]="",
% ["landscape"]="",
% },
% }
</texcode>
* Values can store commands; the command is stored as a string, and expanded at the moment of retrieval.
<texcode>
% Create a macro
\def\mytitle{peanut butter}
% Store a command that uses that macro in a variable.
\definedataset[looks]
\setdataset[looks][narrower][before=\margintitle{\mytitle}]
% Redefine that macro
\def\mytitle{cheese}
% The margintitle is 'cheese', not 'peanut butter'.
\setupnarrower[before=\datasetvariable{looks}{narrower}{before}]
\startnarrower
sandwich
\stopnarrower
</texcode>
< '''Prev:''' [[System Macros/Comma Separated Lists|Comma Separated Lists]] | '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/User Interaction|User Interaction]] >
[[Category:Programming and Databases]]
[[Category:Tools]]
