Difference between revisions of "Command/definedataset"

From ConTeXt wiki
 
Line 4: Line 4:
 
}}
 
}}
  
== [[Help:Reference|Syntax]] (autogenerated)] ==
+
== [[Help:Reference|Syntax]] (autogenerated) ==
 
<syntax>definedataset</syntax>
 
<syntax>definedataset</syntax>
 
== [[Help:Reference|Syntax]] ==
 
== [[Help:Reference|Syntax]] ==

Latest revision as of 14:49, 13 October 2019

\definedataset

Syntax (autogenerated)

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: