NAME

tclyaml - TclYAML - API

Table Of Contents

• Table Of Contents

• Synopsis

• Description

• Introspection

• Parsing YAML

• Generating YAML

• Standard converters for YAML generation

• The Writer Object API

• Bugs, Ideas, Feedback

• Keywords

• Category

• Copyright

SYNOPSIS

package require Tcl 8.5
package require tclyaml ?0.5?

tclyaml type value
tclyaml version
tclyaml read channel chan
tclyaml read file path
tclyaml readTags channel chan
tclyaml readTags file path
tclyaml parse channel channel cmd...
tclyaml write channel spec chan value
tclyaml write file spec path value
tclyaml write string spec value
tclyaml write deftype name arguments body
tclyaml writeTags channel chan value
tclyaml writeTags file path value
tclyaml writeTags string value
string
scalar
bool
int
float
null
list
array
sequence
dict
object
mapping
writer alias anchor
writer sequence-start ?anchor? ?tag? ?implicit?
writer sequence-end
writer mapping-start ?anchor? ?tag? ?implicit?
writer mapping-end
writer scalar type value ?anchor? ?tag?
writer blockstyle style
writer scalarstyle style

DESCRIPTION

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.

Introspection

• tclyaml type value

  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
  

• tclyaml version

  This command returns a string containing the version number of the libyaml library wrapped and provided by this Tcl package.

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.

  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.

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

  • bool

    The value is a boolean. The only possible values are true and false.

  • float

    The value is a floating point number.

  • int

    The value is an integer number

  • mapping

    The value is a mapping from keys to other values. Note that the keys are tagged structures as well, i.e. values.

  • null

    The value indicates a nothingness. The only possible value is the empty string.

  • sequence

    The value is a sequence of values.

  • string

    The value is a string, and not any of the other types.

• 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

• tclyaml write string spec value

  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:

  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.

• tclyaml writeTags channel chan value

• tclyaml writeTags file path value

• tclyaml writeTags string value

  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.

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 of type string to the writer, with the value as the value of the scalar.

• bool

• int

• float

  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.

• null

  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.

• 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 as per the type, 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 "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.

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 type value ?anchor? ?tag?

  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.

  • ?? anchor

    %%TODO%% description

  • ?? tag

    %%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

COPYRIGHT

Copyright © 2012-2014, 2021 Andreas Kupries
Copyright © 2012-2014, 2021 Documentation, Andreas Kupries