1,964
edits
Changes
Jump to navigation
Jump to search
TwoSometimes, 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 is : data that is saved to an external file (in the<code>.tuc</code> file) instead of being used directly. The reason is that theinformation might not be present at that point. Oneexample is the page counter. It's possible to print the total amount of pagesonto the first page. This data is saved in one pass, and retrieved again during the second run, which typsets the correct valuesand used in a later pass. Thissection explains how to define store and retrieve such two-pass data. == Defining a data set == To store values to the <code>.tuc</code> the command <code>\definedataset [myset]</code> is used to define a container for the data. To save additional data, a second argument can be used: <code>\definedataset [myset] [delay=yes]</code>. In that case a node is injected and the dataset is extended with <code>realpage</code>, <code>index</code> and <code>order</code>information with the realpage being synchronized when the node is flushedacross passes.
To store key-value pairs the command <code>\setdataset</code> is used.
\setdataset [myset] [foo=foo-first, bar=bar-first] \setdataset [myset] [foo=foo-second, bar=bar-second]% To define a dataset. \setdataset definedataset[mysetcats] [foo=foo-third, bar=bar-third]</texcode>
Subsequent calls with the same keys to different data like % The first anonymous key-value table is saved at point 1 in the example above does not overwrite the former values. All values are stored and enumeratedcats dataset. % (The calls above lead to the following entries in the <code>.tuc</code> filedataset is itself a key-value table, too.)\setdataset[cats][name=Gus, job=Theatre Cat]
<pre>% The next anonymous table is saved at point 2 utilitydata.job.datasets.collected={ ["myset"]={ {% (Regardless of intervenening named tables) \setdataset["bar"cats]="bar-first", ["foo"]scene="foo-first"crime, }, { ["bar"]="bar-second", ["foo"]name="foo-second"Macavity, }, { ["bar"]is="bar-third", ["foo"not there]="foo-third", }, },}</pre>
The system takes care of % To save a table by name, add the name of in between the dataset and the table not to interfere with core tables.\setdataset[cats][culprit][name=Mungojerry]
One % Named tables can also add another parameter to address the individual values (with the same keys) from subsequent calls. <texcode>be overwritten\setdataset [mysetcats] [firstculprit] [foo=foo-first, bar=bar-first]\setdataset [myset] [second] [foo=foo-second, bar=bar-second]\setdataset [myset] [third] [foo=foo-third, barname=bar-thirdRumpleteaser]
These calls with the additional parameter lead to the following entries in the <code>.tuc</code> file. <pre>utilitydata.job.datasets.collected={ ["myset"]={ ["first"]Retrieving data ={ ["bar"]="bar-first", ["foo"]="foo-first", }, ["second"]={ ["bar"]="bar-second", ["foo"]="foo-second", }, ["third"]={ ["bar"]="bar-third", ["foo"]="foo-third", }, },}</pre>
If one is only interested in In contrast to the last saved valuesother mentioned commands, the <code>\setdataset</code> should be used with three argements and the second argument should stay the samearguments of{{cmd|datasetvariable}} are delimited by braces instead ofbrackets. The reasoning is that this command is about producing text rather than setting values. Example:
\setdataset [test] [foo] [foo=first]\setdataset [test] [foo] [foo=second] \setdataset [test] [bar] [bar=first]\setdataset [test] [bar] [bar=second]% Retrieving a named valueThe name of the culprit was \setdataset [test] [bar] [bar=third]datasetvariable{cats}{culprit}{name}.
If the data was defined with <code>delay=yes</code>, then additionalinformation will be written to the <code>.tuc</code> file. <texcode>\definedataset [test] [delay=yes]…\setdataset [test] [foo] [fooTechnical properties =first]\setdataset [test] [foo] [foo=second]</texcode> If e.g. the <code>\setdataset</code> calls happen to end up on the secondpage, the <code>.tuc</code> file will contain the following collected data.
{ }, ["foomyotherdata"]="second",{ ["index"]=2, { -- this table is indexed at position 1 in myotherdata ["orderkey"]=2, ["realpageothervalue"]=2,
% index=1, realpage=2\definedataset setdataset[mydata][goldfish][myset-1colour=gold]
% two arguments ⇒ the data is accessed by numberindex=2, realpage=1 \setdataset [myset-1mydata][silverfish] [foo=foo-first, bartype=bar-firstinsect] \setdataset [myset-1] page[foo=foo-second, bar=bar-secondyes]
% Outputs foo-firstindex=3, realpage=2; overwrites previous goldfish table. \datasetvariable{myset-1}{1}{foo}\parsetdataset[mydata][goldfish][type=fish]
% Outputs foo-secondResults in the following Lua table in the .tuc file \datasetvariable% ["mydata"]={myset-1% ["goldfish"]={% ["type"]="fish",% ["index"]=3,% ["order"]=3,% ["realpage"]=2,% },% ["goldfish"]={% ["type"]="insect",% ["index"]=2,% ["order"]=2,% ["realpage"]=1,% }{foo,% }\par</texcode>
* Keys or values cannot contain commas.<texcode>% Outputs bar-firstThis does not work \datasetvariable{myset-1}{1}{bar}definedataset[mydata]\parsetdataset[mydata][name="Bond, James Bond"]
% Outputs bar-secondResults in \datasetvariable% ["mydata"]={myset-1}% {2% ["name"]="\"Bond", % ["James Bond\""]="",% }{bar,% }\blank</texcode>
\definedataset % Results in % [myset-2"mydata"]={% {% ["A4"]="", % ["landscape"]="",% },% }</texcode>
% three arguments ⇒ * Values can store commands; the data command is accessed by identifierstored as a string, and expanded at the moment of retrieval.<texcode>% Create a macro \setdataset [myset-2] [first] [alpha=alpha-first, beta=beta-first] def\setdataset [myset-2] [second] [alpha=alpha-second, beta=beta-second]mytitle{peanut butter}
% Outputs alpha-firstStore a command that uses that macro in a variable. \datasetvariabledefinedataset[looks]\setdataset[looks][narrower][before=\margintitle{myset-2\mytitle}{first} {alpha}\par]
% Outputs alpha-secondRedefine that macro \datasetvariable{myset-2}{second}def\mytitle{alphacheese}\par
% Outputs beta-firstThe margintitle is 'cheese', not 'peanut butter'. \setupnarrower[before=\datasetvariable{myset-2looks}{firstnarrower} {betabefore}]\parstartnarrower % Outputs beta-second \datasetvariable{myset-2}{second}{beta}\parsandwich\stoptextstopnarrower
System Macros/Key Value Assignments (view source)
Revision as of 22:47, 26 April 2012
, 22:47, 26 April 2012→Two-pass data: A rewrite. More compact, and less metasyntactic variables.
The boolean <code>\ifparameters</code> can be used afterwards to verify that there were assignments in the supplied argument.
= TwoMulti-pass data =
== Storing data ==
<texcode>
</texcode>
<texcode>
% Retrieving an anonymous value --- Macavity, in this case.
\datasetvariable{cats}{2}{name}.
</texcode>
* 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={
["testmydata"]={ { -- this table is indexed at position 1 in mydata ["fookey"]="firstvalue", }, ["indexnamed"]=1,{ -- this table is indexed at position "named" in mydata ["orderkey_in_named_table"]=1, ["realpagevalue"]=2,
},
},
},
</pre>
* Adding the option <code>[delay== Retrieving yes]</code> to a {{cmd|definedataset}} call ensures that the values ==following three entries are present in every table saved with {{cmd|setdataset}}: <code>index</code>, <code>order</code>, and <code>realpage</code>.
** The values can be retrieved with the entries <code>\datasetvariableindex</code> command. The first argument is the data set defined with and <code>\definedatasetorder</code>. The second argument is seem to have the same number: a number if table written by the first variant with two parameters of {{cmd|setdataset}} call has <code>\setdatasetindex=1</code> was used. It's the number of the and <code>\setdatasetorder=1</code> call. If the second variant with three parameters was used, then it is the identifier given in the second argumentand so on. And the third argument is the key which value should Tables may be retrieved. Note: In contrast to the other mentioned commands, the arguments of <code>\datasetvariable</code> are delimited by bracesoverwritten, instead of brackets, because the actually typeset data. That's ConTeXts conventioncourse. Complete example
** 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`\starttextdefinedataset[mydata][delay=yes]
* Single keys are stored as empty values.
<texcode>
\definedataset[mydata]
\setdataset[mydata][A4,landscape]
</texcode>
< '''Prev:''' [[System Macros/Comma Separated Lists|Comma Separated Lists]] | '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/User Interaction|User Interaction]] >
[[Category:System Macros]]
[[Category:ConTeXt programming]]
code>order
