tclyaml - TclYAML - API
Welcome to TclYAML, a binding to the C-based libyaml parser library for YAML Ain't Markup Language.
This document is the reference manpage for the publicly visible API, i.e. the API a user will see, and use. This API falls into two big sections, for the generation of YAML from Tcl data structures on one side, and the parsing of YAML into Tcl structures on the other.
This command applies the typing rules of the YAML Core Schema to the value and returns a 2-element list containing the type of the value, and the value normalized according to the type, in this order.
Examples:
% puts [type NULL]
null {}
% puts [type 0xff4f]
int 65359
% puts [type 0.1e3]
float 100.0
% puts [type .inf]
float Inf
% puts [type foo]
string foo
This command returns a string containing the version number of the libyaml library wrapped and provided by this Tcl package.
These two commands read the YAML documents found in the channel (chan), or file (path) and return a Tcl list where each element represents a single document found in the input.
For each document YAML scalars are converted to Tcl strings, and YAML sequences and mappings to Tcl lists and dictionaries.
Note that the command applies the typing rules of the YAML Core Schema to the retrieved values. While the type information is not part of the returned structure the normalization implied by a type are applied to the values.
These two commands behave like their plain read counterparts above, except that the data structure they return per element is a tagged structure where each YAML construct is converted into a 2-element list of type-tag and value (in this order). In other words, the type determined by rules of the YAML Core Schema is not discarded here.
While this type of structure is more difficult to access due to the additional nesting levels, in return it does not lose YAML's type information. This allows users to properly distinguish between lists and dictionaries, for example, if the input YAML allows different syntax for specific keys. Another example would be string versus list, for example in a key allowing one to many things of some kind, and a string is the same as a list of one element. In an untagged conversion these cases are difficult to impossible to distinguish.
The tags able to appear in the result are:
The value is a boolean. The only possible values are true and false.
The value is a floating point number.
The value is an integer number
The value is a mapping from keys to other values. Note that the keys are tagged structures as well, i.e. values.
The value indicates a nothingness. The only possible value is the empty string.
The value is a sequence of values.
The value is a string, and not any of the other types.
This command provides the lowest level of access to the YAML parser. Reading YAML data from the specified channel each structural element encountered is reported through an invokation of the command prefix cmd...
This command prefix is invoked with one or two additional arguments, the type of the found element, and a dictionary holding detailed information about it. The contents of the latter are type specific, and may be missing completely if the type does not have details.
The possible types, with their details, if any, are listed below. For the details, the dictionary keys and their meanings are listed.
Parsing has begun.
Name of the character encoding used by the input.
Parsing of the current stream ended. No details.
A new document has begun.
Boolean flag.
Version information as 2-element list of integers.
Yaml type tags.
The current document has ended.
Boolean flag.
%%TODO%% explain
A scalar value has been found.
%%TODO%% explain
Yaml type tag. %%TODO%% which known
Value of the scalar, string.
Boolean flag.
Boolean flag.
One of any, plain, single, double, literal, or folded.
A sequence (aka list) has started.
%%TODO%% explain
Yaml type tag. %%TODO%% which known
Boolean flag.
One of any, block, or flow.
The current sequence ends. No details.
A mapping (aka dictionary) has started.
%%TODO%% explain
Yaml type tag. %%TODO%% which known
Boolean flag.
One of any, block, or flow.
The current mapping ends. No details.
These three commands convert the Tcl data structure in value into YAML, under the guidance of the type information in spec.
The spec describes the expected structure of the value. In essence it is the type/tag information which is missing from the value itself.
The resulting YAML is written to the channel chan, or to the file referenced by path, or returned as the result of the command.
For channels, chan is expected to be open for writing. For files, an existing file is overwritten with the generated YAML.
The syntax of structure spec'ification is:
A list of one or more elements.
The first element of the list is the name of the type. This name has to be the name of a conversion command declared via tclyaml write deftype, see below.
The command name can be followed by additional arguments and detail information.
If the list contains only the command name then no additional arguments are assumed, and the detail information defaults to the empty string or list.
Otherwise the detail information is the last element of the list and anything else between command name and details are the additional arguments to use.
The interpretation of the detail information depends on the conversion command. For examples please see the descriptions of the standard converters the package makes available in section Standard converters for YAML generation.
To convert the value the conversion command is run, with the additional arguments from the spec, followed by the handle of the low-level writer object, the detail information from the spec, and the value itself. The conversion command then uses the API of the writer object to add YAML structures to it, representing the value.
This command defines a new type conversion command name for use in the tclyaml write ... commands above. This part of tclyaml is only relevant to users wishing to write their own type conversions.
The arguments are what has to be specified in a structure specification (see spec above). Beyond these the body will have access to three standard arguments, namely:
This is the low-level object instance holding the YAML structures we wish to generate. The conversion command has to use its API to add the structures it needs to represent the value.
For more details about this object and its API please section The Writer Object API.
This is the detail information from the structure specification given to the tclyaml write commands. The conversion command may interpret this as it sees fit.
For the use type information in this data, to be applied to parts of the value (see below) the body has access to the otherwise internal command ::tclyaml::write::type::__convert. It has to be called with three arguments, the writer, the relevant type structure (extracted from our current structure), and the value to apply it to (extracted from our current value).
This allows new type converters to make use of all other types known to the system in their type specifications, be they builtin or custom.
Note, when going this far for custom conversions it is strongly recommended to look at the implementations of the standard converters for sequences and mappings provided by the package.
This argument holds the Tcl structure to convert.
These three commands convert the Tcl data structure value into YAML. Instead of taking a separate structure holding the necessary type information these commands expected a data structure where all elements are pairs of type and a value proper for that type. In other words, the type tags are part of the incoming value.
Note that this is the same kind of data structure as is returned by the tclyaml readTags command.
The resulting YAML is written to the channel chan, or to the file referenced by path, or returned as the result of the command.
For channels, chan is expected to be open for writing. For files, an existing file is overwritten with the generated YAML.
The package provides the following pre-defined conversion commands for use in structure specifications taken by the tclyaml write commands.
This command/type is for the conversion of plain Tcl strings.
No additional arguments.
The detail information is ignored.
Adds a scalar entry of type string to the writer, with the value as the value of the scalar.
This command/type is for the conversion of plain Tcl strings whose value matches the particular type.
No additional arguments.
The detail information is ignored.
Adds a scalar entry of the given type to the writer, with the value as the value of the scalar.
Note that the value is normalized according to its type, and the capabilities of YAML, before being written. For example, Tcl is able to handle both positive and negative NaN's. YAML does not handle a signed NaN, thus both kinds are mapped to that.
This command/type forces the writing of a null value to the YAML, regardless of the value in the provided data. As such its use in a specification does not truly makes sense. It exists mainly to have full symmetry here with the tags returned by readTags and accepted by writeTags.
No additional arguments.
The detail information is ignored.
This command/type is for the conversion of Tcl lists. In YAML parlance, sequences. In JSON parlance, arrays.
No additional arguments.
The detail information is treated as a single structure specification as taken by the tclyaml write commands. This specification describes the type with which to convert the elements of the Tcl list held in the value.
The converter starts a sequence in the writer object, then converts all list elements as per the type, and at last ends the sequence in the writer.
This command/type is for the conversion of Tcl dictionaries. In YAML parlance, mappings. In JSON parlance, objects.
No additional arguments.
The detail information is treated as a dictionary of structure specifications as taken by the tclyaml write commands. This dictionary describes the types with which to convert the values of the Tcl dictionary held in the value. All keys in value also found as key in the structure use the associated type specification for the conversion of their value. The values of all keys without an explicit conversion are converted with the type specification found under the key *. If such a key does not exist their conversion is done with type "string".
The keys of value themselves are always converted with type "string".
The converter starts a mapping in the writer object, then converts all dictionary elements (keys, and values), and at last ends the mapping in the writer.
Note that the mapping always writes the keys in dictionary order.
This section is only relevant to users wishing to write their own type conversions. See the command tclyaml write deftype above, also.
Here we are documenting the instance API of the low-level object holding the YAML structures we wish to generate. Construction and destruction of these instances is done internally by the package as needed and the relevant APIs are not documented. Neither are the instance methods reserved for use by the package internals.
%%TODO%% method - alias - description
%%TODO%% description
This method starts a sequence (list) of yaml values.
After this method the user has to issue calls for each value in the sequence, followed lastly by a call to sequence-end (see below), to close it.
%%TODO%% description
%%TODO%% description
%%TODO%% description
This method is the complement to sequence-start, above. Calling it closes the currently open sequence (which may be nested in other sequences, mappings, etc). Calling it while not within an open sequence is an error.
The method starts a mapping (dictionary) of yaml values.
After this method the user has to issue calls for each key and value in the mapping, followed lastly by a call to mapping-end (see below), to close it.
%%TODO%% description
%%TODO%% description
%%TODO%% description
This method is the complement to mapping-start, above. Calling it closes the currently open mapping (which may be nested in other sequences, mappings, etc). Calling it while not within an open mapping is an error.
This method adds a single scalar value to the yaml structure, of the given type. The only acceptable types are the scalar types as returned by readTags. In other words, bool, float, int, null, and string.
The formatting of the value is decided automatically, based on the type, and, in case of strings, on the actual value.
%%TODO%% description
%%TODO%% description
These methods set the currently active formatting style for blocks (sequences, mappings). The active style applies only to blocks started after it was set. A block opened, but not yet closed during a style change is not affected by that change.
The default, i.e. initial style is "any".
The available styles are:
%%TODO%% description
%%TODO%% description
%%TODO%% description
These methods set the currently active formatting style for scalar values. The active style applies only to scalars added after it was set.
The default, i.e. initial style is "any".
The available styles are
%%TODO%% description
%%TODO%% description
%%TODO%% description
%%TODO%% description
%%TODO%% description
%%TODO%% description
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the TclYAML Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.
3rd party library binding
Copyright © 2012-2014, 2021 Andreas Kupries
Copyright © 2012-2014, 2021 Documentation, Andreas Kupries