188
edits
Changes
Jump to navigation
Jump to search
Command/definedataset (view source)
Revision as of 22:03, 18 September 2012
, 22:03, 18 September 2012→Interfacing from Lua
</texcode>
== Storing and Accessing Datasets from Lua ==
The macro interface for datasets does not allow saving arbitrarily
structured data to the <code>.tuc</code> file. This limitation can be
overcome by using the governing Lua functions directly. They reside in
the <em>job.datasets</em> namespace.
(Cf. {{src|core-dat.lua}}, later than 2012-09-18.)
=== Saving Data ===
The function <code>job.datasets.setdata</code> 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
{{cmd|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 {{cmd|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
<code>.tuc</code> file under the namespace
<code>utilitydata.job.datasets.collected</code>.
Take the following snippet as an example. A fairly elaborated nested
structure is passed to <code>datasets.setdata()</code>.
<texcode>
\starttext
\startluacode
local setdata = job.datasets.setdata
setdata {
name = "dataset_id",
tag = "this",
data = {
"does",
work = {
"splendidly",
"for",
nested = { "tables", "!", {{}} }
}
}
}
\stopluacode
\stoptext \endinput
</texcode>
This will cause the following section to be added to the
<code>.tuc</code> file (note that the “tag” is represented by a simple
hash entry):
<pre>
utilitydata.job.datasets.collected={
["dataset_id"]={
["this"]={
"does",
["work"]={
"splendidly",
"for",
["nested"]={
"tables",
"!",
{
{},
},
},
},
},
},
}
</pre>
=== Retrieving Stored Data ===
The complement to <code>setdata</code> is <code>getdata</code>.
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 <code>getdata</code> only one argument.
The following example demonstrates how to restore the subentry ''this''
of the dataset ''dataset_id'' as defined in the previous section:
<texcode>
\startluacode
local getdata = job.datasets.getdata
table.print(getdata ("dataset_id", "this"), "this")
\stopluacode
</texcode>
== See also ==
