mkrf 0.1.0

data/test/sample_files/syck-0.55/README.EXT

@@ -0,0 +1,444 @@
+$Id: README.EXT,v 1.5 2005/05/19 04:51:31 why Exp $
+
+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

data/test/sample_files/syck-0.55/RELEASE

@@ -0,0 +1,123 @@
+released: { name: Syck, version: 0.54 }
+for: [ Ruby, PHP, Python ]
+by: why the lucky stiff
+about: >
+
+  Syck is a YAML parser, an extension for scripting
+  languages, written in C.  
+
+  So what is YAML?  YAML is a new language for data.
+  Describe objects in plain text.  Load the data into
+  your scripting language as arrays, dictionaries,
+  classes, or primitives.
+
+links:
+  YAML: http://www.yaml.org/
+  YAML Cookbook: http://yaml4r.sf.net/cookbook/
+  YAML Type Repository: http://yaml.org/type/
+  YAML Specification: http://yaml.org/spec/
+  Syck: http://www.whytheluckystiff.net/syck/
+  Syck Benchmarks: http://www.whytheluckystiff.net/arch/2003/03/19
+
+status: >
+
+  Syck is about 95% compliant with the YAML spec.  Largely, small
+  issues remain.
+
+  The extensions are quite usable.  Ruby, PHP and Python
+  can load from a string containing YAML.
+
+  Ruby has support for stream loading, type handling, YPath, Okay.
+  This release includes an amount of Ruby code comprising the 0.60 
+  release of YAML.rb.
+
+benchmarks: >
+
+  Syck is quite speedy, although not as swift as most language's
+  native serialization.
+
+  Syck runs at about:
+
+  50-60% of the speed of Ruby's Marshal.
+  65-90% of the speed of PHP's deserialize().
+  600% of the speed of Python's Pickle.
+  50-60% of the speed of Python's cPickle.
+
+  (Based on various types of structured data.)
+
+installation: >
+
+  Syck contains working extensions for the Ruby, PHP, and Python
+  languages.  Each requires compilation of the libsyck library,
+  followed by compilation of the extension.
+
+  To compile libsyck, first download libsyck.
+
+    tar xzvf syck-0.54.tar.gz
+    cd syck-0.54
+    ./configure
+    make
+    sudo make install
+
+  To install the Ruby extension:
+
+    cd ext/ruby
+    ruby install.rb config
+    ruby install.rb setup
+    sudo ruby install.rb install
+
+  To install the Python extension:
+
+    cd ext/python
+    python setup.py build
+    sudo python setup.py install
+
+  To install the PHP extension:
+
+    sh make_module.sh
+    sudo make install (if you weren't root during make_module.sh)
+    php -q syck.php
+
+examples:
+
+  To load this document in Ruby: |
+
+     ($:~)$ irb
+     >> require 'yaml'
+     => true
+     >> YAML::load( File.open( 'RELEASE' ) )
+     => {"status"=>"Syck is about 60% compliant ..."}
+
+  To load this document in PHP: |
+
+     ($:~)$ php -a
+     Interactive mode enabled
+
+     <? dl( 'syck.so' ); print_r( syck_load( implode( '', file( 'RELEASE' ) ) ) ); ?>
+  
+     .. php then outputs ..
+
+     X-Powered-By: PHP/4.2.3
+     Content-type: text/html
+     
+     Array
+     (   
+         [released] => Array
+             (   
+                 [name] => Syck
+                 [version] => 0.54
+             )
+
+     .. and so on ..
+
+  To load this document in Python: |
+
+     ($:~)$ python
+     Python 2.1.3 (#1, Jul 11 2002, 17:52:24) 
+     [GCC 2.95.3 20010315 (release) [FreeBSD]] on freebsd4
+     Type "copyright", "credits" or "license" for more information.
+     >>> import syck
+     >>> f = open( 'RELEASE' )
+     >>> syck.load( f.read() )
+     {'by': 'why the lucky stiff', ... }
+