. syck .

                         [ version 0.70 ]





INSTALLATION

   ./configure
   make
   make check
   sudo make install

If the unit tests don't pass, notify me immediately.  This distribution
is tested on FreeBSD and Linux.  I don't release it unless the tests
pass on those machines.  If tests aren't passing, then that's a problem.

ABOUT

Syck is the Scripters' YAML Cobble-Yourself-a-Parser Kit.  I don't
much care if the acronym works, as long as the library does!

The whole point of Syck is to make parsing and emitting YAML very
simple for scripting languages through C bindings.  It doesn't strive
to be a pull parser or very extendible.  It just is concerned with
loading a YAML document into a C structure which can be easily
translated into a scripting language's internal native data type.

RUBY INSTALLATION

You don't need to `make install', but please configure and make libsyck
as outlined above.

   cd ext/ruby
   ruby install.rb config
   ruby install.rb setup
   sudo ruby install.rb install

Syck works best with Ruby.  Ruby's symbol table is leveraged, as well
as Ruby's VALUE system.  (You can read more about that below.)

Syck is now included with Ruby (beginning with Ruby 1.8.0.)  Please
voice your support for Syck/YAML in Ruby distributions on the various
platforms.

PYTHON INSTALLATION

You'll need to `make install' as described above.

   cd ext/python/
   python setup.py build
   sudo python setup.py install

PHP INSTALLATION

You'll need to `make install' as described above.

   ln -s lib include    # or cp -r lib include
   cd ext/php/
   phpize
   ./configure --with-syck=../..
   make
   sudo make install

HOW SYCK IS SO GREAT

For example, in Ruby everything evaluates to a VALUE.  I merely
supply a handler to Syck that will take a SyckNode and transform
it into a Ruby VALUE.

A simple Ruby YAML::load could be built like so:

  static VALUE
  YAML_load( VALUE str )
  {
    SyckParser* parser;
    parser = syck_new_parser();
    syck_parser_handler( parser, YAML_handler );
    return syck_parse( parser, str );
  }

  static VALUE
  YAML_handler( SyckNode* node )
  {
    switch( node->kind )
    {
      case SYCK_MAP:
        VALUE key;
        VALUE h = rb_hash_new();
        for ( key = node->content[0]; key != null; key++ )
        {
          rb_hash_set( h, key, key++ );
        }
        return h;
      break;
    }
  }

For most C developers, it should be a no-brainer to bring
basic YAML serialization to PHP, Tcl, Cocoa, etc.

Instructions for using Syck's API are available in the
README.EXT in this very same directory.

#
# Reflects Oren's comments, adds yamlbyte.h at the bottom
#
subject: Revision #4 of YAML Bytecodes
summary: >
    This proposal defines a 'preparsed' format where a YAML syntax
    is converted into a series of events, as bytecodes.   Each bytecode
    appears on its own line, starting with a single character and ending
    with a line feed character, '\n'.
codes:
  #
  # Primary Bytecodes  (Capital Letters)
  #
  # These bytecodes form the minimum needed to represent YAML information
  # from the serial model (ie, without format and comments)
  #
    'D':
        name: Document
        desc: >
          Indicates that a document has begun, either it is
          the beginning of a YAML stream, or a --- has been
          found.   Thus, an empty document is expressed
          as "D\n"
    'V':
        name: Directive
        desc: >
          This represents any YAML directives immediately following
          a 'D' bytecode.  For example '--- %YAML:1.0' produces the
          bytecode "D\nVYAML:1.0\n".
    'P':
        name: Pause Stream
        desc: >
          This is the instruction when a document is terminated, but
          another document has not yet begun.  Thus, it is optional,
          and typically used to pause parsing.  For example,
          a stream starting with an empty document, but then in a
          hold state for the next document would be: "D\nP\n"
    '\z':
        name: Finish (end stream)
        desc: >
          YAML bytecodes are meant to be passable as a single "C"
          string, and thus the null terminator can optionally be
          used to signal the end of a stream.  When writing bytecodes
          out to a flat file, the file need not contain a null
          terminator; however, when read into memory it should
          always have a null terminator.
    'M':
        name: Mapping
        desc: >
          Indicates the begin of a mapping, children of the
          mapping are provided as a series of K1,V1,K2,V2
          pairs as they are found in the input stream.  For
          example, the bytecodes for "{ a: b, c: d }" would
          be "M\nSa\nSb\nSc\nSd\nE\n"
    'Q':
        name: Sequence
        desc: >
          Indicates the begin of a sequence, children are provided
          following till a '.' bytecode is encountered.  So, the
          bytecodes for "[ one, two ]" would be "Q\nSone\nStwo\nE\n"
    'E':
        name: End Collection
        desc: >
          This closes the outermost Collection (Mapping, Sequence),
          note that the document has one and only one node following
          it, therefore it is not a branch.
    'S':
        name: Scalar
        desc: >
          This indicates the start of a scalar value, which can
          be continued by the 'N' and 'C' bytecodes.   This bytecode
          is used for sequence entries, keys, values, etc.
    'C':
        name: Scalar Continuation
        desc: >
          Since a scalar may not fit within a buffer, and since it
          may not contain a \n character, it may have to be broken
          into several chunks.
    'N':
        name: Normalized New Line (in a scalar value)
        desc: >
          Scalar values must be chunked so that new lines and
          null values do not occur within a 'S' or 'C' bytecode
          (in the bytecodes, all other C0 need not be escaped).
          This bytecode is then used to represent one or more
          newlines, with the number of newlines optionally
          following.   For example,
          "Hello\nWorld" would be "SHello\nN\nCWorld\n", and
          "Hello\n\n\nWorld" is "SHello\nN3\nCWorld\n"

          If the new line is an LS or a PS, the N bytecode can
          be followed with a L or P.   Thus, "Hello\PWorld\L" is
          reported "SHello\nNP\nWorld\NL\n"

    'Z':
        name: Null Character (in a scalar value)
        desc: >
          As in normalized new lines above, since the null character
          cannot be used in the bytecodes, is must be escaped, ie,
          "Hello\zWorld" would be "SHello\nZ\nCWorld\n".
    'A':
        name: Alias
        desc: >
          This is used when ever there is an alias node, for
          example, "[ &X one, *X ]" would be normalized
          to "S\nAX\nSone\nRX\nE\n" -- in this example, the
          anchor bytecode applies to the very next content
          bytecode.
    'R':
        name: Reference (Anchor)
        desc: >
          This bytecode associates an anchor with the very next
          content node, see the 'A' alias bytecode.
    'T':
        name: Transfer
        desc: >
          This is the transfer method.  If the value begins with
          a '!', then it is not normalized.  Otherwise, the value
          is a fully qualified URL, with a semicolon.  The transfer
          method applies only to the node immediately following,
          and thus it can be seen as a modifier like the anchor.
          For example, "Ttag:yaml.org,2002:str\nSstring\n" is
          normalized, "T!str\nSstring\n" is not.
  #
  # Formatting bytecodes (lower case)
  #
  # The following bytecodes are purely at the syntax level and
  # useful for pretty printers and emitters.  Since the range of
  # lower case letters is contiguous, it could be easy for a
  # processor to simply ignore all bytecodes in this range.
  #
    'c':
        name: Comment
        desc: >
          This is a single line comment.  It is terminated like all
          of the other variable length items, with a '\n'.
    'i':
        name: Indent
        desc: >
          Specifies number of additional spaces to indent for
          subsequent block style nodes, "i4\n" specifies 4 char indent.
    's':
        name: Scalar styling
        desc: >
          This bytecode, is followed with one of the following
          items to indicate the style to be used for the very
          next content node.  It is an error to specify a style for
          a scalar other than double quoted when it must be escaped.
          Furthermore, there must be agreement between the style
          and the very next content node, in other words, a scalar
          style requires that the next content node be an S.

          > flow scalar
          " double quoted scalar
          ' single quoted scalar
          | literal scalar
          p plain scalar
          { inline mapping
          [ inline sequence
          b block style (for mappings and sequences'")

   #
   # Advanced bytecodes (not alphabetic)
   #
   # These are optional goodies which one could find useful.
   #
    '#':
        name: Line Number
        desc: >
          This bytecode allows the line number of the very next
          node to be reported.
    '!':
        name: Notice
        desc: >
          This is a message sent from the producer to the consumer
          regarding the state of the stream or document.  It does
          not necessarly end a stream, as the 'finish' bytecode can
          be used for this purpose.  This signal has a packed format,
          with the error number, a comma, and a textual message:
              "#22\n!73,Indentation mismatch\n"
              "#132\n!84,Tabs are illegal for indentation\n"
    ',':
        name: Span
        desc: >
          This bytecode gives the span of the very next 'S', 'M',
          or 'Q' bytecode -- including its subordinates.  For scalars,
          it includes the span of all subordinate 'N' and 'C' codes.
          For mappings or sequences, this gives the length all the
          way to the corresponding 'E' bytecode so that the entire
          branch can be skipped.   The length is given starting at
          the corresponding 'S', 'M' or 'Q' bytecode and extends
          to the first character following subordinate nodes.

          Since this length instruction is meant to be used to 'speed'
          things up, and since calculating the length via hand is not
          really ideal, the length is expressed in Hex.  This will allow
          programs to easily convert the length to an actual value
          (converting from hex to integers is easier than decimal).
          Furthermore, all leading x's are ignored (so that they can
          be filled in later) and if the bytecode value is all x's,
          then the length is unknown.  Lastly, this length is expressed
          in 8 bit units for UTF-8, and 16 bit units for UTF-16.

          For example,
             --- [[one, two], three]
          Is expressed as,
             "?25\nD\n?x1E\nQ\n?xxE\nQ\nSone\nStwo\nE\nSthree\nE\n"

          Thus it is seen that the address of D plus 37 is the null
          terminator for the string, the first 'Q' plus 30 also
          gives the null teriminator, and the second 'Q' plus
          14 jumps to the opening 'S' for the third scalar.
    '@':
        name: Allocate
        desc: >
          This is a hint telling the processor how many items
          are in the following collection (mapping pairs, or
          sequence values), or how many character units need
          to be allocated to hold the next value.  Clearly this
          is encoding specific value.   The length which
          follows is in hex (not decimal).

          For example, "one", could be  "@x3\nSone"

design:
  -
    name: streaming support
    problem: >
      The interface should ideally allow for a YAML document to be
      moved incrementally as a stream through a process.   In particular,
      YAML is inheritently line oriented, thus the interface should
      probably reflect this fundamental character.
    solution: >
      The bytecodes deliver scalars as chunks, each chunk limited to
      at most one line.   While this is not ideal for passing large
      binary objects, it is simple and easy to understand.
  -
    name: push
    problem: >
      The most common 'parsers' out there for YAML are push style, where
      the producer owns the 'C' program stack, and the consumer keeps
      its state as a heap object.  Ideal use of a push interface is an
      emitter, since this allows the sender (the application program)
      to use the program stack and thus keep its state on the call stack
      in local, automatic variables.
    solution: >
      A push interface simply can call a single event handler with a
      (bytecode, payload) tuple.  Since the core complexity is in the
      bytecodes, the actual function signature is straight-forward
      allowing for relative language independence.  Since the bytecode
      is always one character, the event handler could just receive
      a string where the tuple is implicit.
  -
    name: pull
    problem: >
      The other alternative for a streaming interface is a 'pull' mechanism,
      or iterator model where the consumer owns the C stack and the producer
      keeps any state needed as a heap object.  Ideal use of a pull
      interface is a parser, since this allows the receiver (the application
      program) to use the program stack, keeping its state on the call stack
      in local variables.
    solution: >
      A pull interface would also be a simple function, that when called
      filles a buffer with binary node(s).   Or, in a language with
      garbage collection, could be implemented as an iterator returning
      a string containing the bytecode line (bytecode followed immediately
      by the bytecode argument as a single string) or as a tuple.
  -
    name: pull2push
    problem: >
      This is done easily via a small loop which pulls from the
      iterator and pushes to the event handler.
    solution: >
      For python, assuming the parser is implemented as an iterator
      where one can 'pull' bytecode, args tuples, and assuming the
      emitter has a event callback taking a bytecode, args tuple,
      we have:

        def push2pull(parser, emitter):
           for (bytecode, args) in parser:
               emitter.push(bytecode, args)

  -
    name: push2pull
    problem: >
      This requires the entire YAML stream be cashed in memory, or
      each of the two stages in a thread or different continuation
      with shared memory or pipe between them.
    solution: >
      This use case seems much easier with a binary stream; that is,
      one need not convert the style of functions between the push
      vs pull pattern.   And, for languages supporting continuations,
      (ruby) perhaps push vs pull is not even an issue...   for a
      language like python, one would use the threaded Queue object,
      one thread pushes (bytecode, args) tuples into the Queue, while
      the other thread pulls the tuples out.  Simple.
  -
    name: neutrality
    problem: >
      It would be ideal of the C Program interface was simple enough
      to be independent of programming language.   In an ideal case,
      imagine a flow of YAML structured data through various processing
      stages on a server; where each processing stage is written in
      a different programming language.
    solution: >
      While it may be hard for each language to write a syntax parser
      filled with all of the little details, it would be much much
      easier to write a parser for these bytecodes; as it involves
      simple string handling, dispatching on the first character in
      each string.
  -
    name: tools
    problem: >
      A goal of mine is to have a YPATH expression language, a schema
      language, and a transformation language.   I would like these items
      to be reusable by a great number of platforms/languages, and in
      particular as its own callable processing stage.
    solution: >
      If such an expression language was written on top of a bytecode
      format like this, via a simple pull function (/w adapters for
      push2pull and pull2push) quite a bit of reusability could emerge.
      Imagine a schema validator which is injected into the bytecode stream
      and it is an identity operation unless an exception occurs, in
      which case, it terminates the document and makes the next document
      be a description of the validation error.
  -
    name: encoding
    problem: >
      Text within the bytecode format must be given an encoding.  There are
      several considerations at hand listed below.
    solution: >
      The YAML bytecode format uses the same encodings as YAML itself,
      and thus is independent of actual encoding.  A parser library should
      have several functions to convert between the encodings.
examples:
  -
    yaml: |
      ---
      - plain
      - >
        this is a flow scalar
      - >
        another flow scalar which is continued
        on a second line and indented 2 spaces
      - &001 !str |
        This is a block scalar, both typed
        and anchored
      - *001 # this was an alias
      - "This is a \"double quoted\" scalar"
    bytecode: |
      D
      Q
      Splain
      f
      Sthis is a flow scalar
      Sanother flow scalar which is continued
      Con a second line and indented 2 spaces
      b
      a001
      t!str
      SThis is a block scalar, both typed
      N
      Cand anchored
      R001
      cthis was an alias
      d
      SThis is a "double quoted" scalar
      E
cheader: |
    /*  yamlbyte.h
     *
     *  The YAML bytecode "C" interface header file.   See the YAML bytecode
     *  reference for bytecode sequence rules and for the meaning of each
     *  bytecode.
     */

    #ifndef YAMLBYTE_H
    #define YAMLBYTE_H
    #include <stddef.h>
    /* list out the various YAML bytecodes */
    typedef enum {
        /* content bytecodes */
        YAML_FINISH    = 0,
        YAML_DOCUMENT  = 'D',
        YAML_DIRECTIVE = 'V',
        YAML_PAUSE     = 'P',
        YAML_MAPPING   = 'M',
        YAML_SEQUENCE  = 'S',
        YAML_ENDMAPSEQ = 'E',
        YAML_SCALAR    = 'S',
        YAML_CONTINUE  = 'C',
        YAML_NEWLINE   = 'N',
        YAML_NULLCHAR  = 'Z',
        YAML_ALIAS     = 'A',
        YAML_ANCHOR    = 'R',
        YAML_TRANSFER  = 'T',
        /* formatting bytecodes */
        YAML_COMMENT = 'c',
        YAML_INDENT  = 'i',
        YAML_STYLE   = 's',
        /* other bytecodes */
        YAML_LINENUMBER = '#',
        YAML_NOTICE = '!',
        YAML_SPAN   = ',',
        YAML_ALLOC  = '@'
    } yaml_code_t;

    /* additional modifiers for the YAML_STYLE bytecode */
    typedef enum {
       YAML_FLOW = '>',
       YAML_LITERAL = '|',
       YAML_BLOCK = 'b',
       YAML_PLAIN = 'p',
       YAML_INLINE_MAPPING = '{',
       YAML_INLINE_SEQUENCE = '}',
       YAML_SINGLE_QUOTED = 39,
       YAML_DOUBLE_QUOTED = '"'
    } yaml_style_t;

    typedef unsigned char yaml_utf8_t;
    typedef unsigned short yaml_utf16_t;
    #ifdef YAML_UTF8
      #ifdef YAML_UTF16
        #error Must only define YAML_UTF8 or YAML_UTF16
      #endif
      typedef yaml_utf8_t yaml_char_t;
    #else
      #ifdef YAML_UTF16
        typedef yaml_utf16_t yaml_char_t;
      #else
        #error Must define YAML_UTF8 or YAML_UTF16
      #endif
    #endif

    /* return value for push function, tell parser if you want to stop */
    typedef enum {
        YAML_MORE = 1, /* producer should continue to fire events */
        YAML_STOP = 0  /* producer should stop firing events      */
    } yaml_more_t;

    /* push bytecodes from a producer to a consumer
     * where arg is null terminated /w a length */
    typedef void * yaml_consumer_t;
    typedef
      yaml_more_t
       (*yaml_push_t)(
         yaml_consumer_t self,
         yaml_code_t code,
         const yaml_char_t *arg,
         size_t arglen
       );

    /* pull bytecodes by the producer from the consumer, where
     * producer must null terminate buff and return the number
     * of sizeof(yaml_char_t) bytes used */
    typedef void * yaml_producer_t;
    typedef
      size_t
        (*yaml_pull_t)(
          yaml_producer_t self,
          yaml_code_t *code,
          yaml_char_t *buff,     /* at least 1K buffer */
          size_t buffsize
        );  /* returns number of bytes used in the buffer */

    /* canonical helper to show how to hook up a parser (as a push
     * producer) to an emitter (as a push consumer)  */
    #define YAML_PULL2PUSH(pull, producer, push, consumer)      \
      do {                                                      \
          yaml_code_t code = YAML_NOTICE;                       \
          yaml_more_t more = YAML_CONTINUE;                     \
          yaml_char_t buff[1024];                               \
          size_t      size = 0;                                 \
          memset(buff, 0, 1024 * sizeof(yaml_char_t));          \
          while( code && more) {                                \
              size = (pull)((producer),&code, buff, 1024);      \
              assert(size < 1024 && !buff[size]);               \
              more = (push)((consumer),code, buff, size);       \
          }                                                     \
          buff[0] = 0;                                          \
          (push)((consumer),YAML_FINISH, buff, 0);              \
      } while(1)

    #endif

$Id$

This is the documentation for libsyck and describes how to extend it.

= Overview =

Syck is designed to take a YAML stream and a symbol table and move
data between the two.  Your job is to simply provide callback functions which
understand the symbol table you are keeping.

Syck also includes a simple symbol table implementation.

== About the Source ==

The Syck distribution is laid out as follows:

  lib/             libsyck source (core API)
    bytecode.re    lexer for YAML bytecode (re2c)
    emitter.c      emitter functions
    gram.y         grammar for YAML documents (bison)
    handler.c      internal handlers which glue the lexer and grammar
    implicit.re    lexer for builtin YAML types (re2c)
    node.c         node allocation and access
    syck.c         parser funcs, central funcs
    syck.h         libsyck definitions
    syck_st.c      symbol table functions
    syck_st.h      symbol table definitions
    token.re       lexer for YAML plaintext (re2c)
    yaml2byte.c    simple bytecode emitter
  ext/             ruby, python, php, cocoa extensions
  tests/           unit tests for libsyck
    YTS.c.rb       generates YAML Testing Suite unit test
                   (use: ruby YTS.c.rb > YTS.c)
    Basic.c        allocation and buffering tests
    Parse.c        parser sanity
    Emit.c         emitter sanity

== Using SyckNodes ==

The SyckNode is the structure which YAML data is loaded into
while parsing.  It's also a good structure to use while emitting,
however you may choose to emit directly from your native types
if your extension is very small.

SyckNodes are designed to be used in conjunction with a symbol
table.  More on that in a moment.  For now, think of a symbol
table as a library which stores nodes, assigning each node a
unique identifier.

This identifier is called the SYMID in Syck.  Nodes refer to
each other by SYMIDs, rather than pointers.  This way, the
nodes can be free'd as the parser goes.

To be honest, SYMIDs are used because this is the way Ruby
works.  And this technique means Syck can use Ruby's symbol
table directly.  But the included symbol table is lightweight,
solves the problem of keeping too much data in memory, and
simply pairs SYMIDs with your native object type (such as
PyObject pointers.)

Three kinds of SyckNodes are available:

1. scalar nodes (syck_str_kind):
   These nodes store a string, a length for the string
   and a style (indicating the format used in the YAML
   document).

2. sequence nodes (syck_seq_kind):
   Sequences are YAML's array or list type.
   These nodes store a list of items, which allocation
   is handled by syck functions.

3. mapping nodes (syck_map_kind):
   Mappings are YAML's dictionary or hashtable type.
   These nodes store a list of pairs, which allocation
   is handled by syck functions.

The syck_kind_tag enum specifies the above enumerations,
which can be tested against the SyckNode.kind field.

PLEASE leave the SyckNode.shortcut field alone!!  It's
used by the parser to workaround parser ambiguities!!

=== Node API ===

  SyckNode *
  syck_alloc_str()
  syck_alloc_seq()
  syck_alloc_str()

    Allocates a node of a given type and initializes its
    internal union to emptiness.  When left as-is, these
    nodes operate as a valid empty string, empty sequence
    and empty map.

    Remember that the node's id (SYMID) isn't set by the
    allocation functions OR any other node functions herein.
    It's up to your handler function to do that.

  void
  syck_free_node( SyckNode *n )

    While the Syck parser will free nodes it creates, use
    this to free your own nodes.  This function will free
    all of its internals, its type_id and its anchor.  If
    you don't need those members free, please be sure they
    are set to NULL.

  SyckNode *
  syck_new_str( char *str, enum scalar_style style )
  syck_new_str2( char *str, long len, enum scalar_style style )

    Creates scalar nodes from C strings.  The first function
    will call strlen() to determine length.

  void
  syck_replace_str( SyckNode *n, char *str, enum scalar_style style )
  syck_replace_str2( SyckNode *n, char *str, long len, enum scalar_style style )

    Replaces the string content of a node `n', while keeping
    the node's type_id, anchor and id.

  char *
  syck_str_read( SyckNode *n )

    Returns a pointer to the null-terminated string inside scalar node
    `n'.  Normally, you might just want to use:

      char *ptr = n->data.str->ptr
      long len = n->data.str->len

  SyckNode *
  syck_new_map( SYMID key, SYMID value )

    Allocates a new map with an initial pair of nodes.

  void
  syck_map_empty( SyckNode *n )

    Empties the set of pairs for a mapping node.

  void
  syck_map_add( SyckNode *n, SYMID key, SYMID value )

    Pushes a key-value pair on the mapping.  While the ordering
    of pairs DOES affect the ordering of pairs on output, loaded
    nodes are deliberately out of order (since YAML mappings do
    not preserve ordering.)

    See YAML's builtin !omap type for ordering in mapping nodes.

  SYMID
  syck_map_read( SyckNode *n, enum map_part, long index )

    Loads a specific key or value from position `index' within
    a mapping node.  Great for iteration:

      for ( i = 0; i < syck_map_count( n ); i++ ) {
        SYMID key = sym_map_read( n, map_key, i );
        SYMID val = sym_map_read( n, map_value, i );
      }

  void
  syck_map_assign( SyckNode *n, enum map_part, long index, SYMID id )

    Replaces a specific key or value at position `index' within
    a mapping node.  Useful for replacement only, will not allocate
    more room when assigned beyond the end of the pair list.

  long
  syck_map_count( SyckNode *n )

    Returns a count of the pairs contained by the mapping node.

  void
  syck_map_update( SyckNode *n, SyckNode *n2 )

    Combines all pairs from mapping node `n2' into mapping node
    `n'.

  SyckNode *
  syck_new_seq( SYMID val )

    Allocates a new seq with an entry `val'.

  void
  syck_seq_empty( SyckNode *n )

    Empties a sequence node `n'.

  void
  syck_seq_add( SyckNode *n, SYMID val )

    Pushes a new item `val' onto the end of the sequence.

  void
  syck_seq_assign( SyckNode *n, long index, SYMID val )

    Replaces the item at position `index' in the sequence
    node with item `val'.  Useful for replacement only, will not allocate
    more room when assigned beyond the end of the pair list.

  SYMID
  syck_seq_read( SyckNode *n, long index )

    Reads the item at position `index' in the sequence node.
    Again, for iteration:

      for ( i = 0; i < syck_seq_count( n ); i++ ) {
        SYMID val = sym_seq_read( n, i );
      }

  long
  syck_seq_count( SyckNode *n )

    Returns a count of items contained by sequence node `n'.

== YAML Parser ==

Syck's YAML parser is extremely simple.  After setting up a
SyckParser struct, along with callback functions for loading
node data, use syck_parse() to start reading data.  Since
syck_parse() only reads single documents, the stream can be
managed by calling syck_parse() repeatedly for an IO source.

The parser has four callbacks: one for reading from the IO
source, one for handling errors that show up, one for
handling nodes as they come in, one for handling bad
anchors in the document.  Nodes are loaded in the order they
appear in the YAML document, however nested nodes are loaded
before their parent.

=== How to Write a Node Handler ===

Inside the node handler, the normal process should be:

1. Convert the SyckNode data to a structure meaningful
   to your application.

2. Check for the bad anchor caveat described in the
   next section.

3. Add the new structure to the symbol table attached
   to the parser.  Found at parser->syms.

4. Return the SYMID reserved in the symbol table.

=== Nodes and Memory Allocation ===

One thing about SyckNodes passed into your handler:
Syck WILL free the node once your handler is done with it.
The node is temporary.  So, if you plan on keeping a node
around, you'll need to make yourself a new copy.

And you'll probably need to reassign all the items
in a sequence and pairs in a map.  You can do this
with syck_seq_assign() and syck_map_assign().  But, before
you do that, you might consider using your own node structure
that fits your application better.

=== A Note About Anchors in Parsing ===

YAML anchors can be recursive.  This means deeper alias nodes
can be loaded before the anchor.  This is the trickiest part
of the loading process.

Assuming this YAML document:

  --- &a [*a]

The loading process is:

1. Load alias *a by calling parser->bad_anchor_handler, which
   reserves a SYMID in the symbol table.

2. The `a' anchor is added to Syck's own anchor table,
   referencing the SYMID above.

3. When the anchor &a is found, the SyckNode created is
   given the SYMID of the bad anchor node above.  (Usually
   nodes created at this stage have the `id' blank.)

4. The parser->handler function is called with that node.
   Check for node->id in the handler and overwrite the
   bad anchor node with the new node.

=== Parser API ===

 See <syck.h> for layouts of SyckParser and SyckNode.

 SyckParser *
 syck_new_parser()

  Creates a new Syck parser.

 void
 syck_free_parser( SyckParser *p )

  Frees the parser, as well as associated symbol tables
  and buffers.

 void
 syck_parser_implicit_typing( SyckParser *p, int on )

  Toggles implicit typing of builtin YAML types.  If
  this is passed a zero, YAML builtin types will be
  ignored (!int, !float, etc.)  The default is 1.

 void
 syck_parser_taguri_expansion( SyckParser *p, int on )

  Toggles expansion of types in full taguri.  This
  defaults to 1 and is recommended to stay as 1.
  Turning this off removes a layer of abstraction
  that will cause incompatibilities between YAML
  documents of differing versions.

 void
 syck_parser_handler( SyckParser *p, SyckNodeHandler h )

  Assign a callback function as a node handler.  The
  SyckNodeHandler signature looks like this:

    SYMID node_handler( SyckParser *p, SyckNode *n )

 void
 syck_parser_error_handler( SyckParser *p, SyckErrorHandler h )

  Assign a callback function as an error handler.  The
  SyckErrorHandler signature looks like this:

   void error_handler( SyckParser *p, char *str )

 void
 syck_parser_bad_anchor_handler( SyckParser *p, SyckBadAnchorHandler h )

  Assign a callback function as a bad anchor handler.
  The SyckBadAnchorHandler signature looks like this:

   SyckNode *bad_anchor_handler( SyckParser *p, char *anchor )

 void
 syck_parser_file( SyckParser *p, FILE *f, SyckIoFileRead r )

   Assigns a FILE pointer as an IO source and a callback function
   which handles buffering of that IO source.

   The SyckIoFileRead signature looks like this:

     long SyckIoFileRead( char *buf, SyckIoFile *file, long max_size, long skip );

   Syck comes with a default FILE handler named `syck_io_file_read'.  You
   can assign this default handler explicitly or by simply passing in NULL
   as the `r' parameter.

  void
  syck_parser_str( SyckParser *p, char *ptr, long len, SyckIoStrRead r )

    Assigns a string as the IO source with a callback function `r'
    which handles buffering of the string.

    The SyckIoStrRead signature looks like this:

      long SyckIoFileRead( char *buf, SyckIoStr *str, long max_size, long skip );

   Syck comes with a default string handler named `syck_io_str_read'.  You
   can assign this default handler explicitly or by simply passing in NULL
   as the `r' parameter.

  void
  syck_parser_str_auto( SyckParser *p, char *ptr, SyckIoStrRead r )

    Same as the above, but uses strlen() to determine string size.


  SYMID
  syck_parse( SyckParser *p )

    Parses a single document from the YAML stream, returning the SYMID for
    the root node.

== YAML Emitter ==

Since the YAML 0.50 release, Syck has featured a new emitter API.  The idea
here is to let Syck figure out shortcuts that will clean up output, detect
builtin YAML types and -- especially -- determine the best way to format
outgoing strings.

The trick with the emitter is to learn its functions and let it do its
job.  If you don't like the formatting Syck is producing, please get in
contact the author and pitch your ideas!!

Like the YAML parser, the emitter has a couple of callbacks: namely,
one for IO output and one for handling nodes.  Nodes aren't necessarily
SyckNodes.  Since we're ultimately worried about creating a string, SyckNodes
become sort of unnecessary.

=== The Emitter Process ===

1. Traverse the structure you will be emitting, registering all nodes
   with the emitter using syck_emitter_mark_node().  This step will
   determine anchors and aliases in advance.

2. Call syck_emit() to begin emitting the root node.

3. Within your emitter handler, use the syck_emit_* convenience methods
   to build the document.

4. Call syck_emit_flush() to end the document and push the remaining
   document to the IO stream.  Or continue to add documents to the output
   stream with syck_emit().

=== Emitter API ===

 See <syck.h> for the layout of SyckEmitter.

 SyckEmitter *
 syck_new_emitter()

  Creates a new Syck emitter.

 SYMID
 syck_emitter_mark_node( SyckEmitter *e, st_data_t node )

  Adds an outgoing node to the symbol table, allocating an anchor
  for it if it has repeated in the document and scanning the type
  tag for auto-shortcut.

 void
 syck_output_handler( SyckEmitter *e, SyckOutputHandler out )

  Assigns a callback as the output handler.

    void *out_handler( SyckEmitter *e, char * ptr, long len );

  Receives the emitter object, pointer to the buffer and a count
  of bytes which should be read from the buffer.

 void
 syck_emitter_handler( SyckEmitter *e, SyckEmitterHandler


 void
 syck_free_emitter