Command/definedataset
\definedataset
Syntax
\definedataset[...][...,...=...,...] | |
[...] | name |
[...,...=...,...] | delay |
delay | yes no |
Description
Define a dataset, inside which key-value tables can be stored with \setdataset. If any tables are defined, the dataset is stored in the .tuc
file. If the optional second argument [delay=yes]
is added, each table stored in this dataset will have three extra entries: index
and order
will both contain the number (1, 2, 3, ...) of the \setdataset call that defined the table; realpage
will contain the number of the PDF page that TeX was working on when the table was stored with \setdataset.
Usage
Here is an example where the dataset is defined with the [delay=yes]
option. If the option had not been given, the index
, order
, and realpage
entries would simple be missing.
% 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, % }, % }
Storing and Accessing Datasets from Lua
The macro interface for datasets does not allow saving arbitrarily
structured data to the .tuc
file. This limitation can be
overcome by using the governing Lua functions directly. They reside in
the job.datasets namespace.
(Cf. core-dat.lua, later than 2012-09-18.)
Saving Data
The function job.datasets.setdata
handles the storing.
It takes one argument of type table.
This table has three required fields: name, tag and data.
The name field is equivalent to the first argument of
\definedataset (see above): the dataset answers to this
identifier.
The tag field is the id of the entry that will be saved,
corresponding to the second argument of \setdataset.
The data field is supposed to containt the actual content that
needs saving. If it is a table, it will be serialized to the
.tuc
file under the namespace
utilitydata.job.datasets.collected
.
Take the following snippet as an example. A fairly elaborated nested
structure is passed to datasets.setdata()
.
\starttext \startluacode local setdata = job.datasets.setdata setdata { name = "dataset_id", tag = "this", data = { "does", work = { "splendidly", "for", nested = { "tables", "!", {{}} } } } } \stopluacode \stoptext \endinput
This will cause the following section to be added to the
.tuc
file (note that the “tag” is represented by a simple
hash entry):
utilitydata.job.datasets.collected={ ["dataset_id"]={ ["this"]={ "does", ["work"]={ "splendidly", "for", ["nested"]={ "tables", "!", { {}, }, }, }, }, }, }
Retrieving Stored Data
The complement to setdata
is getdata
.
Of its four possible arguments, the two are essential. They correspond
to the name and tag fields of a stored dataset.
NB: It is not possible to retrieve the entire dataset all at once
by passing getdata
only one argument.
The following example demonstrates how to restore the subentry this of the dataset dataset_id as defined in the previous section:
\startluacode local getdata = job.datasets.getdata table.print(getdata ("dataset_id", "this"), "this") \stopluacode
See also
- \setdataset to store a key-value tables in a dataset
- \datasetvariable to retrieve a value from a key-value table in a dataset
- More detailed explanations and examples can be found in the Key-Value Assignments article, under the section Multi-pass data.
Help from ConTeXt-Mailinglist/Forum
All issues with: