Difference between revisions of "Command/definedataset"

From Wiki
Jump to navigation Jump to search
m (Fix typo)
(3 intermediate revisions by 3 users not shown)
Line 4: Line 4:
 
}}
 
}}
  
 +
== [[Help:Reference|Syntax]] (autogenerated) ==
 +
<syntax>definedataset</syntax>
 
== [[Help:Reference|Syntax]] ==
 
== [[Help:Reference|Syntax]] ==
 
<table cellspacing="4" cellpadding="2" class="cmd">
 
<table cellspacing="4" cellpadding="2" class="cmd">
Line 26: Line 28:
 
== Description ==  
 
== Description ==  
  
This command stores two-pass data in the <code>.tuc</code> file.
+
Define a dataset, inside which key-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}}.
  
 
== Usage ==
 
== 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>
 
<texcode>
\definedataset [somedataset]
+
% 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,
 +
%  },
 +
% }
 
</texcode>
 
</texcode>
  
or
+
== 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>
 
<texcode>
\definedataset [somedataset] [delay=yes]
+
\starttext
 +
 
 +
\startluacode
 +
  local setdata = job.datasets.setdata
 +
  setdata {
 +
    name  = "dataset_id",
 +
    tag  = "this",
 +
    data  = {
 +
      "does",
 +
      work = {
 +
        "splendidly",
 +
        "for",
 +
        nested = { "tables", "!", {{}} }
 +
      }
 +
    }
 +
  }
 +
\stopluacode
 +
 
 +
\stoptext \endinput
 
</texcode>
 
</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}} -->
 
  
More detailled explanations and examples can be found under
+
The complement to <code>setdata</code> is <code>getdata</code>.
[[System_Macros/Key_Value_Assignments|Key-Value Assignments]] section Two-pass data.
+
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>
  
{{cmd|setdataset}},
+
== See also ==
{{cmd|datasetvariable}}
 
  
 +
* {{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 ==
 
== Help from ConTeXt-Mailinglist/Forum ==
Line 56: Line 163:
 
{{Forum|{{SUBPAGENAME}}}}
 
{{Forum|{{SUBPAGENAME}}}}
  
[[Category:Commands|definedataset]]
+
[[Category:Command/Datasets|definedataset]]

Revision as of 14:49, 13 October 2019

\definedataset

Syntax (autogenerated)

\definedataset[...][...][...=...,...]
[...]name
[...]name
...=...,...inherits from \setupdataset


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: