System Macros/Key Value Assignments

From ConTeXt wiki
Jump to: navigation, search

< Prev: Comma Separated Lists | Top: System Macros | Next: User Interaction >

Contents

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.

Assignments can be realized with:

\doassign[label][variable=value]
\undoassign[label][variable=value]

and:

\doassignempty[label][variable=value]

These macros are a syntactic rewrite for the 'set', 'clear' and 'initialize' actions:

\def\labelvariable{value}      % \doassign
\def\labelvariable{}           % \undoassign
\doifundefined{\labelvariable}
   {\def\labelvariable{value}} % \doassignempty

Using the assignment commands directly is not our ideal of user friendly interfacing, so we take some further steps.

\getparameters [label] [...=...,...=...]

Again, the label identifies the category a variable belongs to. The second argument can be a comma separated list of assignments. Duplicates are allowed, later appearances overrule earlier ones.

\getparameters
  [demo]
  [alfa=1,
   beta=2]

is equivalent to

\def\demoalfa{1}
\def\demobeta{2}

Some explanation of the inner workings of ConTeXt is in order here to make sure the source is understandable for readers, since the actual internal usage is a bit more complex than this.

In the pre-multi-lingual (simple) stadium ConTeXt took the next approach. With these definitions (that are mainly there to conserve TeX's string space):

\def\??demo {@@demo}
\def\!!width {width}
\def\!!height {height}

calling

\getparameters
  [\??demo]
  [\!!width=one,
   \!!height=2]

lead to:

\def\@@demowidth{one}
\def\@@demoheight{2}

Because we want to be able to distinguish the !! pre-tagged user supplied variables from internal counterparts, we will introduce a slightly different tag in the multi-lingual modules. There we will use c! or v!, depending on the context.

The call will typically somewhat look like this:

\getparameters
  [\??demo]
  [\c!width=\v!one,
   \c!height=2]

In the dutch interface, this would (e.g.) expand into:

\def\@@demobreedte{een}
\def\@@demohoogte{2}

but in the english interface it would become:

\def\@@demowidth{one}
\def\@@demoheight{2}

ConTeXt continues to function, because it never uses the explicit expansion, anywhere. It always relies on the \s! and \v! definitions (remember I told you not to touch them? this is why.)

Sometimes we explicitly want variables to default to an empty string, so we welcome:

\getemptyparameters [label] [...=...,...=...]

Some ConTeXt commands take their default setups from others. All commands that are able to provide backgounds or rules around some content, for instance, default to the standard command for ruled boxes. In situations like this we can use:

\copyparameters [to-label] [from-label] [name1,name2,...]

For instance

\copyparameters
  [\??internal][\??external]
  [\c!width,\c!height]

Leads to (english version):

\def\@@internalwidth  {\@@externalwidth}
\def\@@internalheight {\@@externalheight}

A lot of ConTeXt commands take optional arguments, for instance:

\dothisorthat[alfa,beta]
\dothisorthat[first=foo,second=bar]
\dothisorthat[alfa,beta][first=foo,second=bar]

Although a combined solution is possible, we prefer a separation between argument keywords and parameter assignments. The next command takes care of propper handling of such multi-faced commands.

\doifassignmentelse {...} {then ...} {else ...}

A slightly different approach is \checkparameters, which also checks on the presence of a =, just like the previous macro.

\checkparameters[argument]

The boolean \ifparameters 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 .tuc 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

% 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]

Retrieving data

In contrast to the other mentioned commands, the arguments of \datasetvariable are delimited by braces instead of brackets. The reasoning is that this command is about producing text rather than setting values.

% 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}.

Technical properties

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"]
  },
 },
}
% 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,
%  },
% }
% This does not work
\definedataset[mydata]
\setdataset[mydata][name="Bond, James Bond"]

% Results in 
% ["mydata"]={
%  {
%   ["name"]="\"Bond", 
%   ["James Bond\""]="",
%  },
% }
\definedataset[mydata]
\setdataset[mydata][A4,landscape]

% Results in 
% ["mydata"]={
%  {
%   ["A4"]="", 
%   ["landscape"]="",
%  },
% }
% 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

< Prev: Comma Separated Lists | Top: System Macros | Next: User Interaction > code>order

C O N T E X T G A R D E N

Personal tools
Namespaces
Variants
Actions
Help
External Help
Installation
Navigation
Toolbox