[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

tclyaml(n) 0.1 doc "TclYAML"

Name

tclyaml - TclYAML - API

Table Of Contents

Synopsis

Description

Welcome to TclYAML, a binding to the C-based libyaml parser library for YAML (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.

Parsing YAML

tclyaml read channel chan
tclyaml read file path

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.

tclyaml readTags channel chan
tclyaml readTags file path

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).

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.

tclyaml parse channel channel cmd...

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.

stream-start

Parsing has begun.

encoding

Name of the character encoding used by the input.

stream-end

Parsing of the current stream ended. No details.

document-start

A new document has begun.

implicit

Boolean flag.

version

Version information as 2-element list of integers.

tags

Yaml type tags.

document-end

The current document has ended.

implicit

Boolean flag.

alias
anchor

%%TODO%% explain

scalar

A scalar value has been found.

anchor

%%TODO%% explain

tag

Yaml type tag. %%TODO%% which known

scalar

Value of the scalar, string.

plain-implicit

Boolean flag.

quoted-implicit

Boolean flag.

style

One of any, plain, single, double, literal, or folded.

sequence-start

A sequence (aka list) has started.

anchor

%%TODO%% explain

tag

Yaml type tag. %%TODO%% which known

implicit

Boolean flag.

style

One of any, block, or flow.

sequence-end

The current sequence ends. No details.

mapping-start

A mapping (aka dictionary) has started.

anchor

%%TODO%% explain

tag

Yaml type tag. %%TODO%% which known

implicit

Boolean flag.

style

One of any, block, or flow.

mapping-end

The current mapping ends. No details.

Generating YAML

tclyaml write channel spec chan value
tclyaml write file spec path value

These two commands convert the Tcl data structure value into YAML, under the guidance of the type information in spec, which describes the expected structure of the value, i.e. essentially provides type annotation/tagging of the value, but separate from the value itself.

The resulting YAML is written to a channel (chan, expected to be open for writing), or file (path). For the latter, an existing file is overwritten.

The syntax of structure spec'ification is:

  1. A list of one or more elements.

  2. 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.

  3. The command name can be followed by additional arguments and detail information.

  4. 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.

  5. 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.

tclyaml write deftype name arguments body

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:

object writer

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.

list structure

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.

any value

This argument holds the Tcl structure to convert.

Standard converters for YAML generation

The package provides the following pre-defined conversion commands for use in structure specifications taken by the tclyaml write commands.

string
scalar

This command/type is for the conversion of plain Tcl strings.

No additional arguments.

The detail information is ignored.

Adds a scalar entry to the writer, with the value as the value of the scalar.

list
array
sequence

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, and at last ends the sequence in the writer.

dict
object
mapping

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 "scalar".

The keys of value themselves are always converted with type "scalar".

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.

The Writer Object API

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.

writer alias anchor

%%TODO%% method - alias - description

?? anchor

%%TODO%% description

writer sequence-start ?anchor? ?tag? ?implicit?

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.

?? anchor

%%TODO%% description

?? tag

%%TODO%% description

boolean implicit

%%TODO%% description

writer sequence-end

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.

writer mapping-start ?anchor? ?tag? ?implicit?

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.

?? anchor

%%TODO%% description

?? tag

%%TODO%% description

boolean implicit

%%TODO%% description

writer mapping-end

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.

writer scalar value ?anchor? ?tag? ?plain? ?quoted?

This method adds a single scalar value to the yaml structure, i.e. a string, roughly.

?? anchor

%%TODO%% description

?? tag

%%TODO%% description

boolean plain

%%TODO%% description

boolean quoted

%%TODO%% description

writer blockstyle style

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:

any

%%TODO%% description

block

%%TODO%% description

flow

%%TODO%% description

writer scalarstyle style

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

any

%%TODO%% description

plain

%%TODO%% description

single

%%TODO%% description

double

%%TODO%% description

literal

%%TODO%% description

folded

%%TODO%% description

Bugs, Ideas, Feedback

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.

Keywords

YAML, markup language, serialization

Category

3rd party library binding