973
edits
Changes
Jump to navigation
Jump to search
This command stores twoDefine a dataset, inside which key-pass data value tables can be stored with {{cmd|setdataset}}. If any tables are defined, the dataset is stored in the <code>.tuc</code> file. If the optional second argument <code>[delay=yes]</code> is added, each table stored in this dataset will have three extra entries: <code>index</code> and <code>order</code> will both contain the number (1, 2, 3, ...) of the {{cmd|setdataset}} call that defined the table; <code>realpage</code> will contain the number of the PDF page that TeX was working on when the table was stored with {{cmd|setdataset}}.
or== Storing and Accessing Datasets from Lua == The macro interface for datasets does not allow saving arbitrarilystructured data to the <code>.tuc</code> file. This limitation can beovercome by using the governing Lua functions directly. They reside inthe <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 thisidentifier.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 thatneeds 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>.
More detailled explanations The complement to <code>setdata</code> is <code>getdata</code>.Of its four possible arguments, the two are essential. They correspondto the ''name'' and examples can be found under ''tag'' fields of a stored dataset.'''NB''': It is not possible to retrieve the entire dataset all at once[[System_Macrosby passing <code>getdata</Key_Value_Assignments|Key-Value Assignments]] section Two-pass datacode> only one argument.
{{cmd|setdataset}},{{cmd|datasetvariable}}== See also ==
no edit summary
}}
== [[Help:Reference|Syntax]] (autogenerated) ==
<syntax>definedataset</syntax>
== [[Help:Reference|Syntax]] ==
<table cellspacing="4" cellpadding="2" class="cmd">
== Description ==
== Usage ==
Here is an example where the dataset is defined with the <code>[delay=yes]</code> option. If the option had not been given, the <code>index</code>, <code>order</code>, and <code>realpage</code> entries would simple be missing.
<texcode>
% Create the dataset `mydata`\definedataset [somedatasetmydata][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>
Take the following snippet as an example. A fairly elaborated nested
structure is passed to <code>datasets.setdata()</code>.
<texcode>
\definedataset [somedataset] [delaystarttext \startluacode local setdata =yes]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>
== See also = Retrieving Stored Data ===<!-- something like {{cmd|goto}} -->
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>
* {{cmd|setdataset}} to store a key-value tables in a dataset
* {{cmd|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 [[System_Macros/Key_Value_Assignments#Multi-pass data|Multi-pass data]].
== Help from ConTeXt-Mailinglist/Forum ==
{{Forum|{{SUBPAGENAME}}}}
[[Category:CommandsCommand/Datasets|definedataset]]
