udat 1.2.1 → 1.3.0

data/example.udat

@@ -0,0 +1,242 @@
+This is an example for a UDAT document.
+
+[UDAT example|
+
+
+Sample configuration file:
+
+  [sample config v1.0|
+
+    <network> [
+      <max connections> [256]
+      <reverse lookups> [yes]
+    ]
+
+    <locale> [
+      <language> [de]    german language
+      <timezone> [CET]   and CET timezone
+      Comments can appear almost anywhere.
+    ]
+
+    <access control> [
+      <allowed> [
+        [user|martin]
+        [user|max]
+        [group|admins]
+        [ip4network|
+          <address> [192.168.0.0]
+          <netmask> [255.255.255.0]
+        ]
+      ]
+      <blocked> [~]   The tilde symbol denotes an empty collection.
+    ]
+
+    <misc> [
+      <symbol for homedir> [\~]   Not an empty collection but the scalar
+                                  value "~".
+    ]
+
+    <address mappings> [
+
+      <email|
+        <user>   [jan.behrens]
+        <domain> [flexiguided.de]
+      >
+      [mbox|jan]
+
+      <email|
+        <user>   [glob|*]
+        <domain> [flexiguided.de]
+      >
+      [mbox|catchall]
+
+    ]
+
+    <logging> [
+      <verbosity>   [high]
+  \## <verbosity>   [debug] ##   Uncomment this for debug output.
+      <destination> [file|/var/log/sample.log]
+    ]
+
+  ]
+
+
+General Information:
+
+  Every UDAT node can either be a scalar or a collection. Scalars have
+  content represented by a single string, while collections contain other
+  UDAT nodes.
+
+  Every UDAT node may be tagged, that means a meta-information in form of
+  a string is added. This information can be seen as type information.
+
+  Comments may appear anywhere in the document except in tags or scalars.
+
+  The following 7 characters are to be escaped with a backslash, unless
+  being used for their special meaning:
+
+  \< \> \[ \] \| \~ \\
+
+
+Scalar values:
+
+  Any string without square or angle brackets or the tilde symbol is
+  considered to be a scalar:
+
+  [Hello World!]
+
+  You may add an additional tag, by preceding the string with the tag and
+  the pipe symbol:
+
+  [UTF-8|Hello World!]
+
+  Interpretation of tags is task of the application, there are no standard
+  tags defined.
+
+  Numbers are stored as strings too.
+
+  [23]
+
+  But they may be tagged for example with "integer", to clarify, that they
+  are integer numbers.
+
+  [integer|23]
+
+  You could store rational numbers like this:
+
+  [rational|2/3]
+
+
+Collections:
+
+  Any string which includes either square or angle brackets or a tilde
+  symbol is considered to be a collection. Each entry in a collection
+  consists of a value and optionally a key associated with that value.
+  The key is written in angle brackets and being followed by the value in
+  square brackets. If the value has no key, the angle brackets are not
+  written.
+
+  Collection without keys: [ [1] [2] [3] ]
+  Collection with keys:    [ <A>[1] <B>[2] <C>[3] ]
+
+  Collections may also contain both values with and without keys:
+
+  [ [0] <A>[1] <B>[2] <C>[3] ]   ("0" has no key associated with it.)
+
+  Tags for collections are provided in the same way as for scalars:
+
+  [map| [0] <A>[1] <B>[2] <C>[3] ]   (A collection tagged with "map")
+
+  Comments are allowed between the entries in brackets (as long as
+  characters with a special meaning are escaped):
+
+  [ comment [1] comment [2] comment [3] \[comment\] ]
+
+  Empty collections must include the tilde symbol, to avoid ambiguity with
+  scalars:
+
+  [   ]                  scalar containing three spaces
+  [ ~ ]                  empty collection
+  [list of numbers| ~ ]  empty collection, tagged with "list of numbers"
+  [ ~ comment ]          empty collection with a comment
+  [ comment ~ ]          another empty collection with a comment
+  [~~]                   empty collection too (multiple ~ are allowed)
+
+  It is also allowed to write a tilde symbol in non-empty arrays. In that
+  case the tilde symbol is ignored.
+
+  [~ [1] [2] [3] ]       Array containing "1", "2" and "3"
+
+  So the tilde symbol can be seen as a marker for collections, which is
+  mandatory in empty collections and optional in non-empty collections.
+
+  There is no standardized way to express, whether the order of a
+  collection is significant or not. It is task of the application to decide
+  that, so [[1][2][3]] could be seen as an ordered list of numbers or as a
+  set of numbers where the order is not significant. An application can use
+  tags to store the information, if neccessary, for example:
+  [set|[1][2][3]] vs. [array|[1][2][3]]
+
+  Examples of more complicated collections:
+
+  [group| <name>[Sample group] <members> [
+    [person| <firstname>[Max]    <lastname>[Mustermann] ]
+    [person| <firstname>[Martin] <lastname>[html|M&uuml;ller] ]
+  ] ]
+
+  [  <&>  [html|&amp;]
+     <">  [html|&quot;]
+     <\<> [html|&lt;]
+     <\>> [html|&gt;]    ]
+
+  [  <color combination|[red][blue]>    [nice]
+     <color combination|[red][magenta]> [ugly]  ]
+
+  [  < <red>[on]  <yellow>[off] <green>[off] >  [stop]
+     < <red>[on]  <yellow>[on]  <green>[off] >  [attention]
+     < <red>[off] <yellow>[off] <green>[on]  >  [go]
+     < <red>[off] <yellow>[on]  <green>[off] >  [prepare to stop]  ]
+
+
+Structured meta information:
+
+  Don't abuse tags to store complicated meta information like this:
+
+  \#WRONG#  [string charset=ISO-8859-1 language=EN|Hello World!]  #WRONG#
+
+  If you need to store more complicated meta information, you should do
+  that by using ordinary key/value pairs:
+
+  [string/w/metainfo v1.0|
+    <charset>  [ISO-8859-1]
+    <language> [en]
+    <style>    [folded]
+    [
+      Hello
+      World!
+    ]
+  ]
+
+  The tag "string/w/metainfo v1.0" is used only as the basic type
+  information (for the meta data and payload) here, the meta-data itself is
+  stored in key/value pairs, while the content is a value without key. An
+  application could interpret the "style" = "folded" information as a hint
+  to remove indentation and single line breaks, similar to folded scalars
+  in YAML, however this is application dependent and not part of the UDAT
+  format specification.
+
+
+Binary safe parts and commenting-out:
+
+  There are two alternatives to disable interpretation of special
+  characters, without needing to add a backslash before each epecial
+  character:
+
+  Escape for a fixed length of bytes (useful to include binary blobs):
+
+    \$4$<>[]
+
+  Escape until boundary:
+
+    \## Here, no interpretation of <>[]|~\ is done. ##
+
+    \#boundary#
+      Same as above, but ## may be contained
+      and end is marked with: #boundary#
+
+  By using the \## ... ## syntax you can easily comment out parts of a
+  document:
+
+    [sample config v1.0|
+      <access control> [
+        <allowed> [ [user|martin] \##[user|max]## [group|admins] ]
+      ]
+    ]
+
+  But note that you have to specify a different boundary, if ## is
+  contained at any place (including scalar values) inside the commented-out
+  part.
+
+
+]
+

data/lib/udat.rb

@@ -2,7 +2,6 @@
 
 require 'monitor'
 
-
 # Copyright (c) 2007 FlexiGuided GmbH, Berlin
 #
 # Author: Jan Behrens
@@ -11,1002 +10,1109 @@ require 'monitor'
 #
 # -----
 #
-# Abstract class of an UDAT object. UDAT objects basically consist of a tag
-# and the content. The tag can be a String or be nil. The content is either
-# a scalar value stored as a String, or an ordered/unordered collection of
-# values (where each value can optionally have a key associated with it).
-# Keys and values of collections are always UDAT objects too.
+# This module provides data structures to represent nodes of UDAT
+# documents, a data format offering a generic basis for data storage and
+# transmission, while being both easily readable by humans and machines.
+# The format is comparable to formats like XML or YAML, but due to its
+# simplicity is much more easy to parse.
 #
-# UDAT objects can most easily be constructed from other ruby objects by
-# using the Object#to_udat method.
+# UDAT documents can be generated by converting any Object to a Udat::Node,
+# by calling Object#to_udat, and then encoding them by calling
+# Udat::Node#encode_document.
 #
-# By calling the method Udat#encode, the UDAT object is encoded in a both
-# easily human readable and easily machine readable format. The output can
-# be later parsed by String#parse_udat, or if it is enclosed in square
-# brackets by IO#read_udat.
-class Udat
+# UDAT documents can be parsed by calling String#parse_udat_document.
+module Udat
 
-  include MonitorMixin
+  # Error raised by Udat::Collection#fetch,
+  # when a fetched value doesn't have the expected tag (i.e. type).
+  class UdatTagMismatch < StandardError; end
+  # Error raised by Udat::Collection#fetch,
+  # when a fetched value is a collection instead of a scalar or vice versa.
+  class UdatTypeMismatch < StandardError; end
+  # UDAT parsing error
+  class ParseError < StandardError; end
 
-  # Special argument passed to Udat#to_udat, if the tag is to be kept.
+  # Special argument passed to Udat::Node#to_udat, if the tag is to be
+  # kept.
   KeepTag = Object.new
 
   # A string containing an UDAT example document.
   ExampleDocument = <<-'END_OF_EXAMPLE'
-    This file contains several UDAT objects (each of them enclosed in
-    square brackets), serving as an example for the UDAT format:
-
-
-    Scalar values:
-
-      [Hello World!]
-
-      [UTF-8|Hello World!]  This object has a tag "UTF-8".
-                            Intepretation of tags is task of the
-                            application, there are no standard tags
-                            defined.
-
-      [23]
-
-      [integer|23]
-
-      [rational|2/3]
-
-      The following 7 characters must be escaped with a backslash, when
-      being part of a tag or being part of the content of a scalar:
-
-      \< \> \[ \] \| \~ \\
-
-
-    Arrays (or sets):
-
-      [ [1] [2] [3] ]
-
-      [ [1] [2] Comments are allowed here! (and alomost everywhere) [3] ]
-
-      [ [person| <firstname>[Max]    <lastname>[Mustermann] ]
-        [person| <firstname>[Martin] <lastname>[html|M&uuml;ller] ]
-        [group| <name>[Sample group] <members> [
-          [person| <firstname>[Max]    <lastname>[Mustermann] ]
-          [person| <firstname>[Martin] <lastname>[html|M&uuml;ller] ]
-        ] ]                                                            ]
-
-      References like in YAML with &id and *id
-      are not directly supported by UDAT.
-
-      Empty arrays, sets or maps must contain the ~ character, to avoid
-      ambiguity with scalars:
-
-      [   ]                  scalar containing three spaces
-      [ ~ ]                  empty array
-      [list of numbers| ~ ]  empty array, tagged with "list of numbers"
-      [ ~ comment ]          empty array with a comment
-      [ comment ~ ]          another empty array with a comment
-      [ ~~ ]                 empty array too (multiple ~ are allowed)
-
-      It is also allowed to write ~ in non-empty arrays. In that case the ~
-      symbol is ignored.
-
-      [~ [1] [2] [3] ]       Array containing "1", "2" and "3"
-
-
-    Ordered or unordered maps:
-
-      [ <&>  [html|&amp;]
-        <">  [html|&quot;]
-        <\<> [html|&lt;]
-        <\>> [html|&gt;]   ]
-
-      [ <color combination|[red][blue]>    [nice]
-        <color combination|[red][magenta]> [ugly] ]
-
-      [  < <red>[on]  <yellow>[off] <green>[off] >  [stop]
-         < <red>[on]  <yellow>[on]  <green>[off] >  [attention]
-         < <red>[off] <yellow>[off] <green>[on]  >  [go]
-         < <red>[off] <yellow>[on]  <green>[off] >  [prepare to stop]  ]
-
-
-    Sample configuration file:
-
-      [sample config v1.0|
-        <locale> [
-          <language> [de]
-          <timezone> [CET]
-        ]
-        <logging> [
-          <verbosity>   [high]
-          <destination> [file|/var/log/sample.log]
-        ]
-        <network> [
-          <max connections> [256]
-          <reverse lookups> [yes]
-        ]
-        <access control> [
-          <allowed> [ [user|martin] [user|max] [group|admins] ]
+  [sample config v1.0|
+
+    <network> [
+      <max connections> [256]
+      <reverse lookups> [yes]
+    ]
+
+    <locale> [
+      <language> [de]    german language
+      <timezone> [CET]   and CET timezone
+      Comments can appear almost anywhere.
+    ]
+
+    <access control> [
+      <allowed> [
+        [user|martin]
+        [user|max]
+        [group|admins]
+        [ip4network|
+          <address> [192.168.0.0]
+          <netmask> [255.255.255.0]
         ]
       ]
+      <blocked> [~]   The tilde symbol denotes an empty collection.
+    ]
 
+    <misc> [
+      <symbol for homedir> [\~]   Not an empty collection but the scalar
+                                  value "~".
+    ]
 
-      Don't abuse tags to store complicated meta information like this:
+    <address mappings> [
 
-      WRONG!  [string charset=ISO-8859-1 language=EN|Hello World!]  WRONG!
+      <email|
+        <user>   [jan.behrens]
+        <domain> [flexiguided.de]
+      >
+      [mbox|jan]
 
+      <email|
+        <user>   [glob|*]
+        <domain> [flexiguided.de]
+      >
+      [mbox|catchall]
 
-      If you need to store more complicated meta information, you should do
-      that by using ordinary key/value pairs:
-
-      [string with metainfo v1.0|
-        <charset>  [ISO-8859-1]
-        <language> [en]
-        <content>  [Hello World!]
-      ]
+    ]
 
+    <logging> [
+      <verbosity>   [high]
+  \## <verbosity>   [debug] ##   Uncomment this for debug output.
+      <destination> [file|/var/log/sample.log]
+    ]
 
+  ]
   END_OF_EXAMPLE
 
-  # Error raised by UdatCollection#fetch,
-  # when a fetched value doesn't have the expected tag (i.e. type).
-  class UdatTagMismatch < StandardError; end
-  # Error raised by UdatCollection#fetch,
-  # when a fetched value is a collection instead of a scalar or vice versa.
-  class UdatTypeMismatch < StandardError; end
-  # UDAT parsing error
-  class UdatParseError < StandardError; end
-
-  private_class_method :new
-  # Creates a new Udat object with a given tag (which may be nil).
-  # This method is private,
-  # Udat#initialize is only called through supercalls.
-  def initialize(tag)
-    super()
-    self.tag = tag
-  end
-
-  # Returns an escaped version of a string, where backslashes are preceding
-  # certain reserved characters.
-  def self.escape_string(string)
-    string.to_s.gsub /([<>\[\]|~\\])/, "\\\\\\1"
-  end
-  # Calls Udat.escape_string.
+  # Returns an escaped version of a string, where backslashes are
+  # preceding certain reserved characters.
   def escape_string(string)
-    self.class.escape_string(string)
-  end
-  private :escape_string
-
-  # Tag (i.e. type of the content).
-  attr_reader :tag
-  # Sets the tag (i.e. type of the content).
-  def tag=(tag)
-    synchronize do
-      @tag = tag ? tag.to_s.dup.freeze : nil
-    end
-    return tag
-  end
-
-  # Returns true, if the UDAT object represents a scalar value.
-  def scalar?
-    kind_of? UdatScalar
-  end
-  # Returns true, if the UDAT object represents a collection.
-  def collection?
-    kind_of? UdatCollection
+    string.to_s.gsub /([<>\[\]|~\\])/, "\\\\\\1"
   end
+  module_function :escape_string
 
-  # Returns the data (including it's tag) encoded in the UDAT format.
+  # The abstract class to represent any UDAT data is a Udat::Node.
+  # Udat::Node's basically consist of a tag and the content. The tag can be
+  # a String or be nil. The content is either a scalar value stored as a
+  # String, or an ordered/unordered collection of values (where each value
+  # can optionally have a key associated with it). Keys and values of
+  # collections are always Udat::Node's too.
   #
-  # Note: The UDAT format doesn't contain information, whether contained
-  # collections are ordered or unordered. This information is lost during
-  # the encoding process, and has to be restored in an application
-  # specific way, if neccessary.
-  def encode
-    synchronize do
-      if tag
-        return "#{escape_string tag}|#{encoded_content}"
-      else
-        return encoded_content
-      end
+  # Udat::Node's can most easily be constructed from other ruby objects by
+  # using the Object#to_udat method.
+  #
+  # By calling the method Udat::Node#encode_document, the Node and its
+  # children are encoded in a both easily human readable and easily machine
+  # readable format. The output can be later parsed by
+  # String#parse_udat_document or IO#read_udat.
+  class Node
+
+    include MonitorMixin
+
+    private_class_method :new
+    # Creates a new Udat::Node with a given tag (which may be nil). This
+    # method is private, Udat::Node#initialize is only called through
+    # supercalls.
+    def initialize(tag)
+      super()
+      self.tag = tag
     end
-  end
-  # Here the method does the same as Udat#encode, but this method is
-  # overwritten in UdatScalar!
-  def to_s
-    encode
-  end
-  # Does the same as Udat#encode, but encloses the results in curly
-  # brackets and preceds them with the string "udat".
-  def inspect
-    "udat{#{self.encode}}"
-  end
 
-  # Returns self, or a duplicate of self with a different tag set, if an
-  # argument is passed.
-  def to_udat(tag = KeepTag)
-    if tag == KeepTag
-      return self
-    else
-      obj = nil
+    # Tag (i.e. type of the content).
+    attr_reader :tag
+    # Sets the tag (i.e. type of the content).
+    def tag=(tag)
       synchronize do
-        obj = self.dup
+        @tag = tag ? tag.to_s.dup.freeze : nil
       end
-      obj.tag = tag
-      return obj
+      return tag
     end
-  end
 
-  # Returns a hash key used by ruby's Hash'es.
-  def hash
-    to_s.hash
-  end
-  # Returns true, if class, tag and content (including it's order in case
-  # of a UdatCollection) are matching another object.
-  def eql?(other)
-    self.class == other.class and
-      self.tag == other.tag and
-      self.to_s == other.to_s
-  end
-  # Same as Udat#eql?, but behaves differently in UdatCollection.
-  def ==(other)
-    self.eql? other
-  end
+    # Returns true, if the Udat::Node represents a scalar value.
+    # Shortcut for Udat::Node#kind_of? Udat::Scalar.
+    def scalar?
+      kind_of? Scalar
+    end
+    # Returns true, if the Udat::Node represents a collection.
+    # Shortcut for Udat::Node#kind_of? Udat::Collection.
+    def collection?
+      kind_of? Collection
+    end
 
-  # Internal parsing function.
-  def self.parse_intern(input, start_pos = 0)
-    string = ""
-    tag = nil
-    key = nil
-    collection = nil
-    pos = start_pos
-    while pos < input.length
-      char = input[pos, 1]
-      case char
-      when "\\"
-        pos += 1
-        char = input[pos, 1]
-        if char.empty?
-          raise UdatParseError, "Backslash at end of input."
-        end
-        if char =~ /([<>\[\]|~\\])/
-          string << char if string
-        elsif char == "\n"
-        elsif char == "\r"
-          next_char = input[pos + 1, 1]
-          pos += 1 if next_char == "\n"
-        else
-          raise UdatParseError, "Unknown escape sequence found."
-        end
-        pos += 1
-      when "|"
+    # Returns the data (including it's tag) encoded in the UDAT format. The
+    # result is not enclosed by square brackets, so not intended to be
+    # used externally. This method is public for backwards compatiblity
+    # only, and will be declared protected in future.
+    # Use Udat::Node#encode_document instead.
+    def encode_part
+      synchronize do
         if tag
-          raise UdatParseError, "Multiple occurrences of pipe symbol."
-        end
-        unless string
-          raise UdatParseError, "Unexpected occurrence of pipe symbol."
-        end
-        tag = string
-        string = ""
-        pos += 1
-      when "~"
-        collection ||= UdatCollection.new(tag, [])
-        string = nil
-        pos += 1
-      when "<"
-        if key
-          raise UdatParseError, "Unexpected opening angle bracket."
-        end
-        key, pos = parse_intern(input, pos + 1)
-        unless input[pos, 1] == ">"
-          raise ArgumentError, "Closing angle bracket not found."
-        end
-        pos += 1
-      when ">"
-        break
-      when "["
-        value, pos = parse_intern(input, pos + 1)
-        unless input[pos, 1] == "]"
-          raise UdatParseError, "Closing square bracket not found."
-        end
-        collection ||= UdatCollection.new(tag, [])
-        if key
-          collection.append_pair(key, value)
-          key = nil
+          return "#{Udat::escape_string tag}|#{encoded_content}"
         else
-          collection.append_value(value)
+          return encoded_content
         end
-        pos += 1
-      when "]"
-        break
+      end
+    end
+    # Returns the data (including it's tag) encoded in the UDAT format and
+    # enclosed in square brackets. This is the preferred form of encoding,
+    # when storing the data in files or over streams.
+    #
+    # Note: The UDAT format doesn't contain information, whether contained
+    # collections are ordered or unordered. This information is lost during
+    # the encoding process, and has to be restored in an application
+    # specific way, if neccessary.
+    def encode_document
+      "[#{encode_part}]"
+    end
+    # Deprecated. This method is an alias for Udat::Node#encode_part, but
+    # it is planned to be changed to Udat::Node#encode_document.
+    def encode
+      encode_part
+    end
+    # Here the method does the same as Udat::Node#encode_part, but this
+    # method is overwritten in Udat::Scalar! It is also planned to change
+    # the behaviour to Udat::Node#encode_document in future.
+    def to_s
+      encode_part
+    end
+    # Does the same as Udat::Node#encode_document, but preceds the result
+    # with "udat".
+    def inspect
+      "udat#{self.encode_document}"
+    end
+
+    # Returns self, or a duplicate of self with a different tag set, if an
+    # argument is passed.
+    def to_udat(tag = KeepTag)
+      if tag == KeepTag
+        return self
       else
-        string << char if string
-        pos += 1
+        obj = nil
+        synchronize do
+          obj = self.dup
+        end
+        obj.tag = tag
+        return obj
       end
     end
-    raise UdatParseError, "Key without value." if key
-    return (collection ? collection : string.to_udat(tag)), pos
-  end
-  private_class_method :parse_intern
 
-  # Parses a given string and returns a structure of Udat objects.
-  #
-  # Note: When parsing UDAT data, no information is gained, whether
-  # collections are ordered or unordered. After parsing, all collections
-  # will be marked as unordered, unless changed later by the application.
-  def self.parse(input)
-    input = input.to_s
-    result, pos = parse_intern(input)
-    if pos < input.length
-      raise UdatParseError, "Closing bracket without opening bracket."
-    end
-    return result
-  end
+    # Returns a hash key used by ruby's Hash'es.
+    def hash
+      to_s.hash
+    end
+    # Returns true, if class, tag and content (including it's order in case
+    # of a Udat::Collection) are matching another object.
+    def eql?(other)
+      self.class == other.class and
+        self.tag == other.tag and
+        self.to_s == other.to_s
+    end
+    # Same as Udat::Node#eql?, but behaves differently in Udat::Collection.
+    def ==(other)
+      self.eql? other
+    end
 
-  # Reads an encoded UDAT object from a stream.
-  # The object must be enclosed in square brackets.
-  def self.read_from_stream(io)
-    begin
-      begin
-        char = io.read(1)
-        return nil if char.nil? or char.length < 1
-        if char == "\\"
-          char = io.read(1)
-          return nil if char.nil? or char.length < 1
-        end
-      end while char != "[" and char != "<"
-      buffer = (char == "[") ? "" : nil
-      level = 1
+    # Internal parsing function.
+    def self.parse_intern(mode, end_char, &input_reader)
+      string = ""
+      tag = nil
+      collection = nil
+      key = nil
+      redo_char = false
       while true
-        char = io.read(1)
-        if char.nil? or char.length < 1
-          return EOFError, "Unexpected end of file in UDAT stream."
+        if redo_char
+          redo_char = false
+        else
+          char = input_reader.call
         end
-        if char == "\\"
-          buffer << char if buffer
-          char = io.read(1)
-          if char.nil? or char.length < 1
-            return EOFError, "Unexpected end of file in UDAT stream."
+        case char
+        when nil
+          if end_char.nil? and not key
+            break
+          else
+            raise EOFError, "Unexpected end of UDAT input."
+          end
+        when "\\"
+          char = input_reader.call
+          if char.nil?
+            raise EOFError, "Unexpected end of UDAT input."
+          end
+          if char =~ /([<>\[\]|~\\])/
+            string << char if string
+          elsif char == "\n"
+          elsif char == "\r"
+            char = input_reader.call
+            unless char == "\n"
+              redo_char = true
+              redo
+            end
+          elsif char == "#"
+            boundary = ""
+            while true
+              char = input_reader.call
+              if char.nil?
+                raise EOFError, "Unexpected end of UDAT input."
+              end
+              if char == "#"
+                break
+              else
+                boundary << char
+              end
+            end
+            while true
+              char = input_reader.call
+              if char.nil?
+                raise EOFError,
+                  "Unexpected end of UDAT input " <<
+                  "before ending boundary."
+              end
+              if char == "#"
+                boundary_end = ""
+                while true
+                  char = input_reader.call
+                  if char.nil?
+                    raise EOFError,
+                      "Unexpected end of UDAT input " <<
+                      "before ending boundary."
+                  end
+                  if char == "#"
+                    if boundary_end == boundary
+                      break
+                    else
+                      string << "#" << boundary_end if string
+                      boundary_end = ""
+                      redo
+                    end
+                  else
+                    boundary_end << char
+                  end
+                end
+                break
+              else
+                string << char if string
+              end
+            end
+          elsif char == "$"
+            length = 0
+            while true
+              char = input_reader.call
+              if char.nil?
+                raise EOFError, "Unexpected end of UDAT input."
+              elsif char =~ /[0-9]/
+                length *= 10
+                length += char.to_i
+              elsif char == "$"
+                break
+              else
+                raise ParseError,
+                  "Illegal character in length information of UDAT input."
+              end
+            end
+            length.times do
+              char = input_reader.call
+              if char.nil?
+                raise EOFError,
+                  "Unexpected end of UDAT input in binary part."
+              end
+              string << char if string
+            end
+          else
+            raise ParseError, "Unknown escape sequence in UDAT input."
+          end
+        when "|"
+          if tag or not string
+            raise ParseError, "Unexpected pipe symbol in UDAT input."
+          end
+          tag = string
+          string = ""
+        when "~"
+          collection ||= Collection.new(tag, [])
+          string = nil
+        when "<"
+          if key
+            raise ParseError,
+              "Unexpected opening angle bracket in UDAT input."
+          end
+          key = parse_intern(:normal, ">", &input_reader)
+          string = nil
+        when ">"
+          if end_char == ">" and not key
+            break
+          else
+            raise ParseError,
+              "Unexpected closing angle bracket in UDAT input."
+          end
+        when "["
+          value = parse_intern(:normal, "]", &input_reader)
+          return value if mode == :one_value
+          collection ||= Collection.new(tag, [])
+          if key
+            collection.append_pair(key, value)
+            key = nil
+          else
+            collection.append_value(value)
+          end
+          string = nil
+        when "]"
+          if end_char == "]" and not key
+            break
+          else
+            raise ParseError,
+              "Unexpected closing square bracket in UDAT input."
           end
-        elsif char == "[" or char == "<"
-          level += 1
-        elsif char == "]" or char == ">"
-          level -= 1
-        end
-        if level > 0
-          buffer << char if buffer
         else
-          break
+          string << char if string
         end
       end
-    end while buffer.nil?
-    return parse(buffer)
-  end
+      return nil if mode == :one_value
+      return collection ? collection : string.to_udat(tag)
+    end
+    private_class_method :parse_intern
+
+    # Deprecated. Parses a string encoded by Udat::Node#encode_part. This
+    # method might be removed in future versions. Use
+    # Udat::Node#encode_document in combination with
+    # Udat::Node.parse_document instead.
+    def self.parse_part(input)
+      input = input.to_s
+      pos = 0
+      begin
+        return (
+          parse_intern(:normal, nil) do
+            char = input[pos, 1]
+            pos += 1
+            next char.empty? ? nil : char
+          end
+        )
+      rescue EOFError
+        raise ParseError, $!.message
+      end
+    end
+    # Parses a given UDAT document string and returns a structure of
+    # Udat::Node's. It does the same as Udat::Node.parse_part(input).first.
+    #
+    # Note: When parsing UDAT data, no information is gained, whether
+    # collections are ordered or unordered. After parsing, all collections
+    # will be marked as unordered, unless changed later by the application.
+    def self.parse_document(input)
+      parse(input).first or raise ParseError, "No UDAT object found."
+    end
+    # Deprecated. This method is an alias for Udat::Node.parse_part, but
+    # in future it might be changed to Udat::Node.parse_document.
+    def self.parse(input)
+      parse_part(input)
+    end
 
-  # Encodes an UDAT object and writes it enclosed by square brackets to a
-  # stream.
-  def write_to_stream(io)
-    io << "[#{self.to_udat}]"
-    return self
-  end
+    # Reads Udat::Node encoded by Udat::Node#encode_document from a stream.
+    def self.read_from_stream(io)
+      return (
+        parse_intern(:one_value, nil) do
+          io.read(1)
+        end
+      )
+    end
 
-end
+    # Encodes an object by calling Object#to_udat followed by
+    # Udat::Node#encode_document, and writes it to a stream. Returns self.
+    def write_to_stream(io)
+      io << self.to_udat.encode_document
+      return self
+    end
 
+  end
 
-# Class of UDAT objects holding an ordered or unordered collection of
-# values (where each value can optionally have a key associated with it).
-# Keys and values of collections are always UDAT objects too.
-# UdatCollection's can be interpreted as maps, arrays, sets or any other
-# non-scalar data structure.
-#
-# Note: Keys and values are always implicitly casted by all instance
-# methods of this class to Udat objects using Object#to_udat.
-class UdatCollection < Udat
 
-  # Internally used wrapper class for Udat objects, to lookup
-  # UdatCollection's in Hash'es, while ignoring the order of their content.
-  class UdatUnorderedWrapper
-    def initialize(content)
-      @content = content
-    end
-    attr_accessor :content
-    def hash
-      if content.kind_of? UdatCollection
-        hash = 0
-        content.key_value_pairs.each do |key, value|
-          hash += key.hash
-          hash += value.hash
+  # Class of Udat::Node's holding an ordered or unordered collection of
+  # values (where each value can optionally have a key associated with it).
+  # Keys and values of collections are always Udat::Node's too.
+  # Udat::Collection's can be interpreted as maps, arrays, sets or any
+  # other non-scalar data structure.
+  #
+  # Note: Keys and values are always implicitly casted by all instance
+  # methods of this class to Udat::Node's using Object#to_udat.
+  class Collection < Node
+
+    # Internally used wrapper class for Udat::Node's, to lookup
+    # Udat::Collection's in Hash'es, while ignoring the order of their
+    # content.
+    class UnorderedWrapper
+      def initialize(content)
+        @content = content
+      end
+      attr_accessor :content
+      def hash
+        if content.kind_of? Collection
+          hash = 0
+          content.key_value_pairs.each do |key, value|
+            hash += key.hash
+            hash += value.hash
+          end
+          return hash
+        else
+          return content.hash
         end
-        return hash
-      else
-        return content.hash
       end
-    end
-    def eql?(other)
-      return false unless self.class == other.class
-      if self.content.class == other.content.class and
-          self.content.tag == other.content.tag
-        if self.content.kind_of? UdatCollection
-          own_pairs = self.content.key_value_pairs
-          other_pairs = other.content.key_value_pairs
-          own_pairs.each do |own_pair|
-            catch :found do
-              other_pairs.each_index do |index|
-                if own_pair.eql? other_pairs[index]
-                  other_pairs.delete_at index
-                  throw :found
+      def eql?(other)
+        return false unless self.class == other.class
+        unless self.content.kind_of? Node and
+            other.content.kind_of? Node
+          return self.content.eql?(other.content)
+        end
+        if self.content.class == other.content.class
+            self.content.tag == other.content.tag
+          if self.content.kind_of? Collection
+            own_pairs = self.content.key_value_pairs
+            other_pairs = other.content.key_value_pairs
+            own_pairs.each do |own_pair|
+              catch :found do
+                other_pairs.each_index do |index|
+                  if own_pair.eql? other_pairs[index]
+                    other_pairs.delete_at index
+                    throw :found
+                  end
                 end
+                return false
               end
-              return false
             end
+            return true
+          else
+            return self.content.eql?(other.content)
           end
-          return true
         else
-          return self.content.eql?(other.content)
+          return false
         end
-      else
-        return false
+      end
+      def ==(other)
+        self.eql? other
       end
     end
-    def ==(other)
-      self.eql? other
-    end
-  end
 
-  public_class_method :new
-  # Creates a new Udat object with a given tag (which may be nil) and a
-  # given content, represented by a nested Array structure. See the source
-  # code for details. It is not recommended to use this method. Use
-  # Object#to_udat instead.
-  def initialize(tag, content)
-    super tag
-    @ordered = true
-    @entries = []
-    require_index_hashes
-    content.to_ary.each { |entry| self << entry }
-  end
+    public_class_method :new
+    # Creates a new Udat::Collection with a given tag (which may be nil)
+    # and a given content, represented by a nested Array structure. It is
+    # not recommended to use this method. Use Object#to_udat instead.
+    def initialize(tag, content)
+      super tag
+      @ordered = true
+      @entries = []
+      require_index_hashes
+      content.to_ary.each { |entry| self << entry }
+    end
 
-  # Deletes the internal index hashes.
-  # They are automatically reconstructed once a lookup is done.
-  # This method should be called by the user, if contained Udat objects
-  # have changed, AFTER being added to this collection (similar to
-  # Hash#rehash).
-  def rehash
-    synchronize do
-      @key_indicies = nil
-      @value_indicies = nil
-      @unordered_key_indicies = nil
-      @unordered_value_indicies = nil
-      @all_unordered_key_indicies = nil
-      @all_unordered_value_indicies = nil
+    # Deletes the internal index hashes.
+    # They are automatically reconstructed once a lookup is done.
+    # This method should be called by the user, if contained Udat objects
+    # have changed, AFTER being added to this collection (similar to
+    # Hash#rehash).
+    # Returns self.
+    def rehash
+      synchronize do
+        @key_indicies = nil
+        @value_indicies = nil
+        @unordered_key_indicies = nil
+        @unordered_value_indicies = nil
+        @all_unordered_key_indicies = nil
+        @all_unordered_value_indicies = nil
+      end
+      return self
     end
-    return self
-  end
 
-  # Returns true, if the internal index hashes are not existent.
-  def index_hashes_void?
-    synchronize do
-      return @key_indicies.nil?
+    # Returns true, if the internal index hashes are not existent.
+    def index_hashes_void?
+      synchronize do
+        return @key_indicies.nil?
+      end
     end
-  end
-  private :index_hashes_void?
-  # Registers a key value pair in the index.
-  def add_to_index_hashes(index, key, value)
-    @key_indicies[key] ||= []
-    @key_indicies[key] << index
-    @value_indicies[value] ||= []
-    @value_indicies[value] << index
-    if key.kind_of? UdatCollection and key.unordered?
-      @unordered_key_indicies[UdatUnorderedWrapper.new(key)] ||= []
-      @unordered_key_indicies[UdatUnorderedWrapper.new(key)] << index
-    end
-    if value.kind_of? UdatCollection and value.unordered?
-      @unordered_value_indicies[UdatUnorderedWrapper.new(value)] ||= []
-      @unordered_value_indicies[UdatUnorderedWrapper.new(value)] << index
-    end
-    @all_unordered_key_indicies[UdatUnorderedWrapper.new(key)] ||= []
-    @all_unordered_key_indicies[UdatUnorderedWrapper.new(key)] << index
-    @all_unordered_value_indicies[UdatUnorderedWrapper.new(value)] ||= []
-    @all_unordered_value_indicies[UdatUnorderedWrapper.new(value)] << index
-    return self
-  end
-  private :add_to_index_hashes
-  # Creates index hashes, if they are not existent.
-  def require_index_hashes
-    synchronize do
-      if index_hashes_void?
-        @key_indicies = {}
-        @value_indicies = {}
-        @unordered_key_indicies = {}
-        @unordered_value_indicies = {}
-        @all_unordered_key_indicies = {}
-        @all_unordered_value_indicies = {}
-        @entries.each_index do |index|
-          key_value_pair = @entries[index]
-          key = key_value_pair[0]
-          value = key_value_pair[1]
-          add_to_index_hashes(index, key, value) unless key.nil?
+    private :index_hashes_void?
+    # Registers a key value pair in the index.
+    # (The key argument may be nil for values without keys.)
+    def add_to_index_hashes(index, key, value)
+      unless index_hashes_void?
+        @key_indicies[key] ||= []
+        @key_indicies[key] << index
+        @value_indicies[value] ||= []
+        @value_indicies[value] << index
+        if key.kind_of? Collection and key.unordered?
+          @unordered_key_indicies[UnorderedWrapper.new(key)] ||= []
+          @unordered_key_indicies[UnorderedWrapper.new(key)] << index
+        end
+        if value.kind_of? Collection and value.unordered?
+          @unordered_value_indicies[UnorderedWrapper.new(value)] ||= []
+          @unordered_value_indicies[UnorderedWrapper.new(value)] << index
         end
+        @all_unordered_key_indicies[UnorderedWrapper.new(key)] ||= []
+        @all_unordered_key_indicies[UnorderedWrapper.new(key)] << index
+        @all_unordered_value_indicies[UnorderedWrapper.new(value)] ||= []
+        @all_unordered_value_indicies[UnorderedWrapper.new(value)] << index
       end
+      return self
     end
-    return self
-  end
-  private :require_index_hashes
+    private :add_to_index_hashes
+    # Creates index hashes, if they are not existent.
+    def require_index_hashes
+      synchronize do
+        if index_hashes_void?
+          @key_indicies = {}
+          @value_indicies = {}
+          @unordered_key_indicies = {}
+          @unordered_value_indicies = {}
+          @all_unordered_key_indicies = {}
+          @all_unordered_value_indicies = {}
+          @entries.each_index do |index|
+            key_value_pair = @entries[index]
+            key = key_value_pair[0]
+            value = key_value_pair[1]
+            add_to_index_hashes(index, key, value) unless key.nil?
+          end
+        end
+      end
+      return self
+    end
+    private :require_index_hashes
 
-  # Empties the collection.
-  def clear
-    synchronize do
-      @entries.clear
-      rehash
-      require_index_hashes
+    # Empties the collection. Returns self.
+    def clear
+      synchronize do
+        @entries.clear
+        rehash
+        require_index_hashes
+      end
+      return self
     end
-    return self
-  end
-  # Deletes the entry at the given numeric index.
-  # Returns the value, or nil if the index is out of bounds.
-  def delete_at(index)
-    index = index.to_int
-    synchronize do
-      key_value_pair = @entries.delete_at(index)
-      rehash
-      return key_value_pair ? key_value_pair[1] : nil
+    # Deletes the entry at the given numeric index.
+    # Returns the value, or nil if the index is out of bounds.
+    def delete_at(index)
+      index = index.to_int
+      synchronize do
+        key_value_pair = @entries.delete_at(index)
+        rehash
+        return key_value_pair ? key_value_pair[1] : nil
+      end
     end
-  end
-  # Deletes the first entry and returns its value.
-  def shift
-    delete_at(0)
-  end
-  # Deletes the last entry and returns its value.
-  def pop
-    delete_at(-1)
-  end
-  # Deletes all entries with a given key.
-  def delete_key(key)
-    key = key.to_udat
-    synchronize do
-      @entries.delete_if { |e_key, e_value| e_key == key }
-      rehash
+    # Deletes the first entry and returns its value.
+    def shift
+      delete_at(0)
     end
-    return self
-  end
-  # Deletes all entries with a given value.
-  def delete_value(value)
-    value = value.to_udat
-    synchronize do
-      @entries.delete_if { |e_key, e_value| e_value == value }
-      rehash
+    # Deletes the last entry and returns its value.
+    def pop
+      delete_at(-1)
+    end
+    # Deletes all entries with a given key. Returns self.
+    def delete_key(key)
+      key = key.to_udat
+      synchronize do
+        @entries.delete_if { |e_key, e_value| e_key == key }
+        rehash
+      end
+      return self
+    end
+    # Deletes all entries with a given value. Returns self.
+    def delete_value(value)
+      value = value.to_udat
+      synchronize do
+        @entries.delete_if { |e_key, e_value| e_value == value }
+        rehash
+      end
+      return self
     end
-    return self
-  end
 
-  # Appends a new key with a new value.
-  def append_pair(key, value)
-    key = key.to_udat
-    value = value.to_udat
-    synchronize do
-      index = @entries.length
-      @entries << [key, value]
-      add_to_index_hashes(index, key, value) unless index_hashes_void?
+    # Appends a new key with a new value. Returns self.
+    def append_pair(key, value)
+      key = key.to_udat
+      value = value.to_udat
+      synchronize do
+        index = @entries.length
+        @entries << [key, value]
+        add_to_index_hashes(index, key, value)
+      end
+      return self
     end
-    return self
-  end
-  # Appends a new value.
-  def append_value(value)
-    value = value.to_udat
-    synchronize do
-      @entries << [nil, value]
+    # Appends a new value. Returns self.
+    def append_value(value)
+      value = value.to_udat
+      synchronize do
+        index = @entries.length
+        @entries << [nil, value]
+        add_to_index_hashes(index, nil, value)
+      end
+      return self
+    end
+    # Deletes all key/value pairs where the given key matches,
+    # and appends a new key/value pair. Returns self.
+    def set_value_for_key(key, value)
+      delete_key(key)
+      append_pair(key, value)
+      return self
+    end
+    # Deletes all values or key/value pairs where the given value matches,
+    # and appends a new key/value pair. Returns self.
+    def set_key_for_value(key, value)
+      delete_value(value)
+      append_pair(key, value)
+      return self
     end
-    return self
-  end
-  # Deletes all key/value pairs where the given key matches,
-  # and appends a new key/value pair.
-  def set_value_for_key(key, value)
-    delete_key(key)
-    append_pair(key, value)
-    return self
-  end
-  # Deletes all values or key/value pairs where the given value matches,
-  # and appends a new key/value pair.
-  def set_key_for_value(key, value)
-    delete_value(value)
-    append_pair(key, value)
-    return self
-  end
 
-  # Behaves differently depending on the type of the argument. If the
-  # argument is an Array with 2 elements, a new key/value pair is added,
-  # with the key being the first element of the array, and the value being
-  # the second argument of the array. Arrays with any other number of
-  # elements cause an error. If the argument is not an array, then it is
-  # added as a value without a key.
-  def <<(value)
-    if value.kind_of? Array
-      unless value.length == 2
-        raise ArgumentError,
-          "#{value.length} array elements found where 2 were expected."
-      end
-      return append_pair(value[0], value[1])
-    else
-      return append_value(value)
+    # Behaves differently depending on the type of the argument. If the
+    # argument is an Array with 2 elements, a new key/value pair is added,
+    # with the key being the first element of the array, and the value
+    # being the second argument of the array. Arrays with any other number
+    # of elements cause an error. If the argument is not an array, then it
+    # is added as a value without a key.
+    def <<(value)
+      if value.kind_of? Array
+        unless value.length == 2
+          raise ArgumentError,
+            "#{value.length} array elements found where 2 were expected."
+        end
+        return append_pair(value[0], value[1])
+      else
+        return append_value(value)
+      end
+    end
+    # Same as Udat::Collection#set_value_for_key.
+    def []=(key, value)
+      set_value_for_key(key, value)
     end
-  end
-  # Same as UdatCollection#set_value_for_key.
-  def []=(key, value)
-    set_value_for_key(key, value)
-  end
 
-  # Returns the value at a numeric index, or nil, if the index is out of
-  # bounds.
-  def value_by_index(index)
-    index = index.to_int
-    synchronize do
-      entry = @entries[index]
-      return entry ? entry[1] : nil
+    # Returns the value at a numeric index, or nil, if the index is out of
+    # bounds.
+    def value_by_index(index)
+      index = index.to_int
+      synchronize do
+        entry = @entries[index]
+        return entry ? entry[1] : nil
+      end
     end
-  end
-  # Returns the key at a numeric index, or nil, if the index is out of
-  # bounds or at the given index there is only a value without key.
-  def key_by_index(index)
-    index = index.to_int
-    synchronize do
-      entry = @entries[index]
-      return entry ? entry[0] : nil
+    # Returns the key at a numeric index, or nil, if the index is out of
+    # bounds or at the given index there is only a value without key.
+    def key_by_index(index)
+      index = index.to_int
+      synchronize do
+        entry = @entries[index]
+        return entry ? entry[0] : nil
+      end
     end
-  end
-  # Returns an Array of values having a given key.
-  def values_by_key(key)
-    key = key.to_udat
-    synchronize do
-      require_index_hashes
-      if key.kind_of? UdatCollection and key.unordered?
-        indicies = @all_unordered_key_indicies[
-          UdatUnorderedWrapper.new(key)
-        ] || []
-      else
-        indicies = (@key_indicies[key] || []) + (
-          @unordered_key_indicies[UdatUnorderedWrapper.new(key)] || []
+    # Returns an Array of values having no key.
+    def values_without_key
+      synchronize do
+        require_index_hashes
+        return (
+          (@key_indicies[nil] || []).collect { |index| @entries[index][1] }
         )
-        indicies.uniq!
-        indicies.sort!
       end
-      return indicies.collect { |index| @entries[index][1] }
     end
-  end
-  # Returns an Array of keys having a given value.
-  def keys_by_value(value)
-    value = value.to_udat
-    synchronize do
-      require_index_hashes
-      if value.kind_of? UdatCollection and value.unordered?
-        indicies = @all_unordered_value_indicies[
-          UdatUnorderedWrapper.new(value)
-        ] || []
-      else
-        indicies = (value_indicies[key] || []) + (
-          @unordered_value_indicies[UdatUnorderedWrapper.new(value)] || []
-        )
-        indicies.uniq!
-        indicies.sort!
+    # Returns an Array of values having a given key.
+    def values_by_key(key)
+      key = key.to_udat
+      synchronize do
+        require_index_hashes
+        if key.kind_of? Collection and key.unordered?
+          indicies = @all_unordered_key_indicies[
+            UnorderedWrapper.new(key)
+          ] || []
+        else
+          indicies = (@key_indicies[key] || []) + (
+            @unordered_key_indicies[UnorderedWrapper.new(key)] || []
+          )
+          indicies.uniq!
+          indicies.sort!
+        end
+        return indicies.collect { |index| @entries[index][1] }
+      end
+    end
+    # Returns an Array of keys having a given value. The Array may contain
+    # nil's for values having no key.
+    def keys_by_value(value)
+      value = value.to_udat
+      synchronize do
+        require_index_hashes
+        if value.kind_of? Collection and value.unordered?
+          indicies = @all_unordered_value_indicies[
+            UnorderedWrapper.new(value)
+          ] || []
+        else
+          indicies = (@value_indicies[value] || []) + (
+            @unordered_value_indicies[UnorderedWrapper.new(value)] || []
+          )
+          indicies.uniq!
+          indicies.sort!
+        end
+        return indicies.collect { |index| @entries[index][0] }
+      end
+    end
+    # Returns the last value without key.
+    def value_without_key
+      values_without_key.last
+    end
+    # Returns the last value having a given key.
+    def value_by_key(key)
+      values_by_key(key).last
+    end
+    # Returns the last key having a given value.
+    def key_by_value(value)
+      keys_by_value(value).last
+    end
+    # Returns true, if the value is contained in the collection.
+    def include?(value)
+      value = value.to_udat
+      synchronize do
+        require_index_hashes
+        if value.kind_of? Collection and value.unordered?
+          return (@all_unordered_value_indicies[
+            UnorderedWrapper.new(value)
+          ] || []).empty? ? false : true
+        else
+          return ((@value_indicies[value] || []) + (
+            @unordered_value_indicies[UnorderedWrapper.new(value)] || []
+          )).empty? ? false : true
+        end
       end
-      return indicies.collect { |index| @entries[index][0] }
     end
-  end
-  # Returns the last value having a given key.
-  def value_by_key(key)
-    values_by_key(key).last
-  end
-  # Returns the last key having a given value.
-  def key_by_value(value)
-    keys_by_value(value).last
-  end
 
-  # Behaves differently depending on the type of the argument.
-  # If the argument is an Integer the method behaves same as
-  # UdatCollection#value_by_index.
-  # Otherwise the method behaves same as UdatCollection#value_by_key.
-  def [](key)
-    if key.kind_of? Integer
-      return value_by_index(key)
-    else
-      return value_by_key(key)
+    # Behaves differently depending on the type of the argument.
+    # If the argument is an Integer, the method behaves same as
+    # Udat::Collection#value_by_index. If the argument is nil, the method
+    # behaves like Udat::Collection#value_without_key. Otherwise the method
+    # behaves same as Udat::Collection#value_by_key.
+    def [](key)
+      if key.nil?
+        return value_without_key
+      elsif key.kind_of? Integer
+        return value_by_index(key)
+      else
+        return value_by_key(key)
+      end
     end
-  end
-  # Same as UdatCollection#[], but raises an error, if no value was found.
-  # If an additional second argument is passed, an error will also be
-  # raised if the tag (i.e. type) of the value is not equal to the second
-  # argument.
-  def fetch(*args)
-    if args.length == 1
-      value = self[args[0]]
-      unless value
-        raise IndexError, "Value for the given key or index not found."
+    # Same as Udat::Collection#[], but raises an error, if no value was
+    # found. If an additional second argument is passed, an error will also
+    # be raised if the tag (i.e. type) of the value is not equal to the
+    # second argument.
+    def fetch(*args)
+      if args.length == 1
+        value = self[args[0]]
+        unless value
+          raise IndexError, "Value for the given key or index not found."
+        end
+        return value
+      elsif args.length == 2
+        value = fetch(args[0])
+        unless value.tag == args[1]
+          raise UdatTagMismatch, "UDAT tag mismatch."
+        end
+        return value
+      else
+        raise ArgumentError, "Wrong number of arguments supplied."
+      end
+    end
+    # Same as Udat::Collection#fetch, but raises an error, if the value is
+    # not an Udat::Collection.
+    def fetch_collection(*args)
+      value = fetch(*args)
+      if value.scalar?
+        raise UdatTypeMismatch,
+          "Scalar value found, where a collection was expected."
       end
       return value
-    elsif args.length == 2
-      value = fetch(args[0])
-      unless value.tag == args[1]
-        raise UdatTagMismatch, "UDAT tag mismatch."
+    end
+    # Same as Udat::Collection#fetch, but raises an error, if the value is
+    # not an Udat::Scalar.
+    def fetch_scalar(*args)
+      value = fetch(*args)
+      if value.collection?
+        raise UdatTypeMismatch,
+          "Collection found, where a scalar value was expected."
       end
       return value
-    else
-      raise ArgumentError, "Wrong number of arguments supplied."
     end
-  end
-  # Same as UdatCollection#fetch, but raises an error, if the value is
-  # not an UdatCollection.
-  def fetch_collection(*args)
-    value = fetch(*args)
-    if value.scalar?
-      raise UdatTypeMismatch,
-        "Scalar value found, where a collection was expected."
-    end
-    return value
-  end
-  # Same as UdatCollection#fetch, but raises an error, if the value is
-  # not an UdatScalar.
-  def fetch_scalar(*args)
-    value = fetch(*args)
-    if value.collection?
-      raise UdatTypeMismatch,
-        "Collection found, where a scalar value was expected."
-    end
-    return value
-  end
-  # Returns the first value of the collection, or nil if empty.
-  def first
-    self[0]
-  end
-  # Returns the last value of the collection, or nil if empty.
-  def last
-    self[-1]
-  end
-
-  # Returns the number of values in the collection.
-  def length
-    synchronize do
-      @entries.length
+    # Returns the first value of the collection, or nil if empty.
+    def first
+      self[0]
     end
-  end
-  alias size length
-  # Returns true, if the collection is empty.
-  def empty?
-    length == 0
-  end
-  # Calls a given block for each numeric index.
-  def each_index
-    synchronize do
-      (0...length).each { |i| yield i }
+    # Returns the last value of the collection, or nil if empty.
+    def last
+      self[-1]
     end
-    return self
-  end
 
-  # Returns an Array containing the key/value pairs each as an Array of
-  # size 2. If there is no key, the first element of the sub Array is nil.
-  def key_value_pairs
-    synchronize do
-      return @entries.collect { |entry| entry.dup }
+    # Returns the number of values in the collection.
+    def length
+      synchronize do
+        @entries.length
+      end
     end
-  end
-  # Returns an Array containing all keys of the collection.
-  def keys
-    keys = nil
-    synchronize do
-      keys = @entries.collect { |key, value| key }
-    end
-    keys.compact!
-    return keys
-  end
-  # Returns an Array containing all values of the collection.
-  def values
-    synchronize do
-      return @entries.collect { |key, value| value }
+    alias size length
+    # Returns true, if the collection is empty.
+    def empty?
+      length == 0
+    end
+    # Calls a given block for each numeric index.
+    def each_index
+      synchronize do
+        (0...length).each { |i| yield i }
+      end
+      return self
     end
-  end
 
-  # Returns a hash, where each key is mapped to the respective value.
-  def to_hash
-    hash = {}
-    synchronize do
-      @entries.each do |key, value|
-        next if key.nil?
-        hash[key] = value unless hash.has_key? key
+    # Returns an Array containing the key/value pairs each as an Array of
+    # size 2. If there is no key, the first element of the sub Array is
+    # nil.
+    def key_value_pairs
+      synchronize do
+        return @entries.collect { |entry| entry.dup }
       end
     end
-    return hash
-  end
-  # Same as UdatCollection#values.
-  def to_ary
-    values
-  end
-  alias to_a values
-
-  # Appends the values (and corresponding keys) of another UdatCollection.
-  def concat(other)
-    synchronize do
-      other.key_value_pairs.each do |key, value|
-        if key.nil?
-          append_value(value)
-        else
-          append_pair(key, value)
+    # Returns an Array containing all keys of the collection.
+    def keys
+      keys = nil
+      synchronize do
+        keys = @entries.collect { |key, value| key }
+      end
+      keys.compact!
+      return keys
+    end
+    # Returns an Array containing all values of the collection.
+    def values
+      synchronize do
+        return @entries.collect { |key, value| value }
+      end
+    end
+
+    # Returns a hash, where each key is mapped to the respective value.
+    def to_hash
+      hash = {}
+      synchronize do
+        @entries.each do |key, value|
+          next if key.nil?
+          hash[key] = value unless hash.has_key? key
         end
       end
+      return hash
     end
-    return self
-  end
-  # Replaces the values (and corresponding keys) with the values/keys of
-  # another UdatCollection.
-  def replace(other)
-    synchronize do
-      clear
-      concat(other)
+    # Same as Udat::Collection#values.
+    def to_ary
+      values
     end
-    return self
-  end
+    alias to_a values
 
-  # Returns the encoded form of the content as a string.
-  # This method is used by Udat#encode, which returns the complete encoding
-  # of the data (including the tag).
-  def encoded_content
-    synchronize do
-      return (
-        @entries.empty? ? "~" :
-        @entries.collect do |key, value|
-          if key
-            "<#{key.encode}>[#{value.encode}]"
+    # Appends the values (and corresponding keys) of another
+    # Udat::Collection and returns self.
+    def concat(other)
+      synchronize do
+        other.key_value_pairs.each do |key, value|
+          if key.nil?
+            append_value(value)
           else
-            "[#{value.encode}]"
+            append_pair(key, value)
           end
-        end.join
-      )
+        end
+      end
+      return self
+    end
+    # Replaces the values (and corresponding keys) with the values/keys of
+    # another Udat::Collection and returns self.
+    def replace(other)
+      synchronize do
+        clear
+        concat(other)
+      end
+      return self
     end
-  end
 
-  # Same as UdatCollection#ordered?.
-  def ordered
-    synchronize do
-      return @ordered
+    # Returns the encoded form of the content as a string.
+    # This method is used by Udat::Node#encode_part and will be declared
+    # protected in future.
+    def encoded_content
+      synchronize do
+        return (
+          @entries.empty? ? "~" :
+          @entries.collect do |key, value|
+            if key
+              "<#{key.encode_part}>[#{value.encode_part}]"
+            else
+              "[#{value.encode_part}]"
+            end
+          end.join
+        )
+      end
     end
-  end
-  # Returns false, if the order of the contents of this collection is to be
-  # ignored for comparisons.
-  def ordered?
-    self.ordered
-  end
-  # Returns true, if the order of the contents of this collection is to be
-  # ignored for comparisons.
-  def unordered?
-    not self.ordered
-  end
-  # If set to false, the order of the contents of this collection will be
-  # ignored for comparisons.
-  def ordered=(ordered)
-    synchronize do
-      if ordered == false
-        @ordered = false
-      else
-        @ordered = true
+
+    # Same as Udat::Collection#ordered?.
+    def ordered
+      synchronize do
+        return @ordered
       end
     end
-  end
-  # Same as UdatCollection#ordered = false, but returns self.
-  def unordered!
-    self.ordered = false
-    return self
-  end
-  # Same as UdatCollection#ordered = true, but returns self.
-  def ordered!
-    self.ordered = true
-    return self
-  end
+    # Returns false, if the order of the contents of this collection is to
+    # be ignored for comparisons.
+    def ordered?
+      self.ordered
+    end
+    # Returns true, if the order of the contents of this collection is to
+    # be ignored for comparisons.
+    def unordered?
+      not self.ordered
+    end
+    # If set to false, the order of the contents of this collection will be
+    # ignored for comparisons.
+    def ordered=(ordered)
+      synchronize do
+        if ordered == false
+          @ordered = false
+        else
+          @ordered = true
+        end
+      end
+    end
+    # Same as Udat::Collection#ordered = false, but returns self.
+    def unordered!
+      self.ordered = false
+      return self
+    end
+    # Same as Udat::Collection#ordered = true, but returns self.
+    def ordered!
+      self.ordered = true
+      return self
+    end
 
-  # Same as Udat#inspect, but in case of unordered collections it prepends
-  # "udat-unordered" instead of just "udat".
-  def inspect
-    if ordered?
-      return super
-    else
-      "udat-unordered{#{self.encode}}"
+    # Same as Udat::Node#inspect, but in case of unordered collections it
+    # prepends "udat-unordered" instead of just "udat".
+    def inspect
+      if ordered?
+        return super
+      else
+        "udat-unordered#{self.encode_document}"
+      end
     end
-  end
 
-  def ==(other)
-    return false unless self.class == other.class
-    if self.unordered? or other.unordered?
-      return UdatUnorderedWrapper.new(self) ==
-        UdatUnorderedWrapper.new(other)
-    else
-      return super
+    # Returns true, if class, tag and content are matching another object.
+    # The order of the content is only significant for comparison, if both
+    # objects have the Udat::Collection#ordered attribute set to true.
+    def ==(other)
+      return false unless self.class == other.class
+      if self.unordered? or other.unordered?
+        return UnorderedWrapper.new(self) ==
+          UnorderedWrapper.new(other)
+      else
+        return super
+      end
     end
+
   end
 
-end
 
+  # Class of Udat::Node's holding scalar values (stored as a String).
+  class Scalar < Node
 
-# Class of UDAT objects holding scalar values (stored as a String).
-class UdatScalar < Udat
+    public_class_method :new
+    # Creates a new Udat::Scalar with a given tag (which may be nil) and a
+    # given content, which is transformed to a string (via Object#to_s).
+    # It is not recommended to use this method. Use Object#to_udat instead.
+    def initialize(tag, content)
+      super tag
+      self.content = content
+    end
 
-  public_class_method :new
-  # Creates a new Udat object with a given tag (which may be nil) and a
-  # given content, which is transformed to a string (via 'to_s').
-  # It is not recommended to use this method. Use Object#to_udat instead.
-  def initialize(tag, content)
-    super tag
-    self.content = content
-  end
+    # Content of the scalar (a String).
+    attr_reader :content
+    # Sets the content. The content is casted to a string.
+    def content=(content)
+      @content = content.to_s
+    end
 
-  # Content of the scalar (a String).
-  attr_reader :content
-  # Sets the content. The content is casted to a string.
-  def content=(content)
-    @content = content.to_s
-  end
+    # Same as Udat::Scalar#content.
+    def to_s
+      content
+    end
+    # Returns the content casted to an Integer.
+    def to_i
+      content.to_i
+    end
 
-  # Same as UdatScalar#content.
-  def to_s
-    content
-  end
-  # Returns the content casted to an Integer.
-  def to_i
-    content.to_i
-  end
+    # Returns true, if the (String representation of the) content is empty.
+    def empty?
+      self.to_s.empty?
+    end
 
-  # Returns true, if the (String representation of the) content is empty.
-  def empty?
-    self.to_s.empty?
-  end
+    # Returns the encoded form of the content as a string. In this case
+    # this is simply an escaped version of the String. This method will be
+    # declared protected in future versions.
+    def encoded_content
+      Udat::escape_string(self.to_s)
+    end
 
-  # Returns the encoded form of the content as a string.
-  # In this case this is simply an escaped version of the String.
-  # This method is used by Udat#encode, which returns the complete encoding
-  # of the data (including the tag).
-  def encoded_content
-    escape_string(self.to_s)
   end
 
 end
 
 
 class Object
-  # Casts the Object to a nUdatScalar object, optionally with a given tag.
-  # Unless overwritten by sub classes, only the string representation (as
-  # returned by Object#to_s) will be stored as content in the UdatScalar
-  # object.
+  # Casts the Object to an Udat::Scalar object, optionally with a given
+  # tag. Unless overwritten by sub classes, only the string representation
+  # (as returned by Object#to_s) will be stored as content in the
+  # Udat::Scalar object.
   def to_udat(tag = nil)
-    UdatScalar.new(tag, self)
+    Udat::Scalar.new(tag, self)
   end
 end
 
 class Array
-  # Casts the Array to an UdatCollection object, optionally with a given
-  # tag. The UdatCollection object is marked to be ordered. Each element of
-  # the array may be an Array of size 2, in which case the 2 entries are
+  # Casts the Array to an Udat::Collection object, optionally with a given
+  # tag. The Udat::Collection object is marked to be ordered. Each element
+  # of the array may be an Array of size 2, in which case the 2 entries are
   # used as key and value. If an element of the Array is not an Array, it
   # will be used as value without an associated key.
   def to_udat(tag = nil)
-    UdatCollection.new(tag, self)
+    Udat::Collection.new(tag, self)
   end
 end
 
 class Hash
-  # Casts the Hash to an UdatCollection object, optionally with a given
-  # tag. The UdatCollection object is marked to be unordered.
+  # Casts the Hash to an Udat::Collection object, optionally with a given
+  # tag. The Udat::Collection object is marked to be unordered.
   def to_udat(tag = nil)
-    UdatCollection.new(tag, self.to_a).unordered!
+    Udat::Collection.new(tag, self.to_a).unordered!
   end
 end
 
 class String
-  # Calls Udat.parse(self).
+  # Deprecated. Calls Udat::Node.parse_part(self).
+  # Use String#parse_udat_document instead.
   def parse_udat
-    Udat.parse(self)
+    Udat::Node.parse_part(self)
+  end
+  # Calls Udat::Node.parse_document(self).
+  def parse_udat_document
+    Udat::Node.parse_document(self)
   end
 end
 
 class IO
-  # Calls Udat.read_from_stream(self).
+  # Calls Udat::Node.read_from_stream(self).
   def read_udat
-    Udat.read_from_stream(self)
+    Udat::Node.read_from_stream(self)
   end
-  # Calls Udat#write_to_stream(self), after converting the object to an
-  # Udat object by calling Object#to_udat.
+  # Calls Udat::Node#write_to_stream(self), after converting the object to
+  # an Udat::Node by calling Object#to_udat. Returns self.
   def write_udat(object)
     object.to_udat.write_to_stream(self)
+    return self
   end
 end
 
+# Deprecated constant for backwards compatibility.
+UdatCollection = Udat::Collection
+
+# Deprecated constant for backwards compatibility.
+UdatScalar = Udat::Scalar
+
+
+