udat 1.1.0 → 1.1.1

data/lib/udat.rb

@@ -17,19 +17,23 @@ require 'monitor'
 # values (where each value can optionally have a key associated with it).
 # Keys and values of collections are always UDAT objects too.
 #
-# UDAT objects can most easily constructed from other ruby objects by using
-# the Object#to_udat method.
+# UDAT objects can most easily be constructed from other ruby objects by
+# using the Object#to_udat method.
 #
 # 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.
+# be later parsed by String#parse_udat, or if it is enclosed in square
+# brackets by IO#read_udat.
 class Udat
 
   include MonitorMixin
 
+  # Special argument passed to Udat#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 by
+    This file contains several UDAT objects (each of them enclosed in
     square brackets), serving as an example for the UDAT format:
 
 
@@ -103,6 +107,21 @@ class Udat
       ]
 
 
+      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 with metainfo v1.0|
+        <charset>  [ISO-8859-1]
+        <language> [en]
+        <content>  [Hello World!]
+      ]
+
+
   END_OF_EXAMPLE
 
   # Error raised by UdatCollection#fetch,
@@ -139,7 +158,7 @@ class Udat
   # Sets the tag (i.e. type of the content).
   def tag=(tag)
     synchronize do
-      @tag = tag ? tag.to_s : nil
+      @tag = tag ? tag.to_s.dup.freeze : nil
     end
     return tag
   end
@@ -179,6 +198,21 @@ class Udat
     "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
+      synchronize do
+        obj = self.dup
+      end
+      obj.tag = tag
+      return obj
+    end
+  end
+
   # Returns a hash key used by ruby's Hash'es.
   def hash
     to_s.hash
@@ -195,45 +229,6 @@ class Udat
     self.eql? other
   end
 
-  # Casts a value to an Udat object. If two arguments are supplied,
-  # the first argument is a tag, while the second is the content.
-  # If just one argument is supplied, then the tag is assumed to be nil,
-  # and the argument given is the content.
-  # Interpretation of the content depends on the type: If the content is
-  # an Array (responds to 'to_ary') an ordered collection will be created,
-  # if the content is a Hash (responds to 'to_hash'), an unordered
-  # collection will be created. Otherwise the content will be casted to a
-  # String with 'to_s' to be stored as a scalar.
-  # If you pass an Array, each element of that 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.
-  # This method is called by Object#to_udat.
-  def self.construct(*args)
-    if args.length == 1
-      tag = nil
-      content = args[0]
-    elsif args.length == 2
-      tag = args[0]
-      content = args[1]
-    else
-      raise ArgumentError, "Wrong number of arguments supplied."
-    end
-    if content.kind_of? Udat
-      if tag
-        content = content.dup
-        content.tag = tag
-      end
-      return content
-    elsif content.respond_to? :to_ary
-      return UdatCollection.new(tag, content.to_ary)
-    elsif content.respond_to? :to_hash
-      return UdatCollection.new(tag, content.to_hash.to_a).unordered!
-    else
-      return UdatScalar.new(tag, content)
-    end
-  end
-
   # Internal parsing function.
   def self.parse_intern(input, start_pos = 0)
     string = ""
@@ -306,8 +301,8 @@ class Udat
   # 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, until changed.
+  # 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)
@@ -317,6 +312,44 @@ class Udat
     return result
   end
 
+  # Reads an encoded UDAT object from a stream.
+  # The object must be enclosed in square brackets.
+  def self.read_from_stream(io)
+    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 != "["
+    buffer = ""
+    level = 1
+    while true
+      char = io.read(1)
+      if char.nil? or char.length < 1
+        return EOFError, "Unexpected end of file in UDAT stream."
+      end
+      if char == "\\"
+        buffer << char
+        char = io.read(1)
+        if char.nil? or char.length < 1
+          return EOFError, "Unexpected end of file in UDAT stream."
+        end
+      elsif char == "[" or char == "<"
+        level += 1
+      elsif char == "]" or char == ">"
+        level -= 1
+      end
+      if level > 0
+        buffer << char
+      else
+        break
+      end
+    end
+    return parse(buffer)
+  end
+
 end
 
 
@@ -390,14 +423,7 @@ class UdatCollection < Udat
     @ordered = true
     @entries = []
     require_index_hashes
-    unless content.nil?
-      if content.respond_to? :to_ary
-        content = content.to_ary
-      else
-        content = [content]
-      end
-      content.each { |entry| self << entry }
-    end
+    content.to_ary.each { |entry| self << entry }
   end
 
   # Deletes the internal index hashes.
@@ -893,9 +919,31 @@ end
 
 
 class Object
-  # Calls Udat.construct(tag, self).
+  # 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.
+  def to_udat(tag = nil)
+    UdatScalar.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
+  # 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)
+  end
+end
+
+class Hash
+  # Casts the Hash to an UdatCollection object, optionally with a given
+  # tag. The UdatCollection object is marked to be unordered.
   def to_udat(tag = nil)
-    Udat.construct(tag, self)
+    UdatCollection.new(tag, self.to_a).unordered!
   end
 end
 
@@ -906,3 +954,10 @@ class String
   end
 end
 
+class IO
+  # Calls Udat.read_from_stream(self).
+  def read_udat
+    Udat.read_from_stream(self)
+  end
+end
+

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: udat
 version: !ruby/object:Gem::Version 
-  version: 1.1.0
+  version: 1.1.1
 date: 2007-05-23 00:00:00 +00:00
 summary: Parser and generator for UDAT documents, a generic data format similar to XML or YAML.
 require_paths: