udat 1.0.0

data/LICENSE

@@ -0,0 +1,23 @@
+# Copyright (c) 2007 FlexiGuided GmbH, Berlin
+#
+# Author: Jan Behrens
+#
+# Website: http://www.flexiguided.de/publications.flexirecord.en.html
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.

data/lib/udat.rb

@@ -0,0 +1,803 @@
+#!/usr/bin/env ruby
+
+require 'monitor'
+
+
+# Copyright (c) 2007 FlexiGuided GmbH, Berlin
+#
+# Author: Jan Behrens
+#
+# Website: http://www.flexiguided.de/publications.udat.en.html
+#
+# -----
+#
+# 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.
+#
+# UDAT objects can most easily 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.
+class Udat
+
+  include MonitorMixin
+
+  # A string containing an UDAT example document.
+  ExampleDocument = <<-'END_OF_EXAMPLE'
+    This file contains several UDAT objects (each of them enclosed by
+    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]
+
+
+    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.
+
+
+    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] ]
+        ]
+      ]
+
+
+  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 escape_string(string)
+    string.to_s.gsub /([<>\[\]|\\])/, "\\\\\\1"
+  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 : 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
+  end
+
+  # Returns the data (including it's tag) encoded in the UDAT format.
+  #
+  # 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
+    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 a hash key used by ruby's Hash'es.
+  def hash
+    to_s.hash
+  end
+  # Returns true, if class, tag and content 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?.
+  def ==(other)
+    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 = ""
+    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
+        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 "|"
+        if tag
+          raise UdatParseError, "Multiple occurrences of pipe symbol."
+        end
+        tag = string
+        string = ""
+        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
+        else
+          collection.append_value(value)
+        end
+        pos += 1
+      when "]"
+        break
+      else
+        string << char
+        pos += 1
+      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, until changed.
+  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
+
+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
+
+  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
+    clear
+    unless content.nil?
+      if content.respond_to? :to_ary
+        content = content.to_ary
+      else
+        content = [content]
+      end
+      content.each { |entry| self << entry }
+    end
+  end
+
+  # Deletes the internal index hashes.
+  def index_void!
+    synchronize do
+      @key_to_value = nil
+      @value_to_key = nil
+    end
+    return self
+  end
+  # Checks, if the internal index hashes are existent
+  # (and therefore up to date).
+  def index_void?
+    synchronize do
+      return @key_to_value.nil?
+    end
+  end
+  # Creates index hashes, if they are not existent.
+  def require_index
+    synchronize do
+      if index_void?
+        @key_to_value = {}
+        @value_to_key = {}
+        @entries.each do |key, value|
+          unless key.nil?
+            @key_to_value[key] = value unless @key_to_value.has_key? key
+            @value_to_key[value] = key unless @value_to_key.has_key? value
+          end
+        end
+      end
+    end
+    return self
+  end
+  private :index_void!, :index_void?, :require_index
+
+  # Empties the collection.
+  def clear
+    @entries = []
+    @key_to_value = {}
+    @value_to_key = {}
+    return self
+  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 }
+      index_void!
+    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 }
+      index_void!
+    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
+      @entries << [key, value]
+      unless index_void?
+        @key_to_value[key] = value unless @key_to_value.has_key? key
+        @value_to_key[value] = key unless @value_to_key.has_key? value
+      end
+    end
+    return self
+  end
+  # Appends a new value.
+  def append_value(value)
+    value = value.to_udat
+    synchronize do
+      @entries << [nil, value]
+    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 (responds to 'to_ary') 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.respond_to? :to_ary
+      value = value.to_ary
+      unless value.length == 2
+        raise ArgumentError,
+          "#{value.length} array elements found, while 2 were expected."
+      end
+      return append_pair(value[0], value[1])
+    else
+      return append_value(value)
+    end
+  end
+  # Same as UdatCollection#set_value_for_key.
+  def []=(key, value)
+    set_value_for_key(key, value)
+  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
+    end
+  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
+    end
+  end
+  # Returns the first value having a given key.
+  def value_by_key(key)
+    synchronize do
+      require_index
+      return @key_to_value[key.to_udat]
+    end
+  end
+  # Returns the first key having a given value.
+  def key_by_value(value)
+    synchronize do
+      require_index
+      @value_to_key[value.to_udat]
+    end
+  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)
+    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."
+      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 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
+    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 }
+    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 }
+    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 }
+    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
+  # 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)
+        end
+      end
+    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)
+    end
+    return self
+  end
+
+  # 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.collect do |key, value|
+          if key
+            "<#{key.encode}>[#{value.encode}]"
+          else
+            "[#{value.encode}]"
+          end
+        end.join
+      )
+    end
+  end
+
+  # Same as UdatCollection#ordered?.
+  def ordered
+    synchronize do
+      return @ordered
+    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
+      index_void!
+      if ordered == false
+        @ordered = false
+      else
+        @ordered = true
+      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
+
+  # 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}}"
+    end
+  end
+
+  # Returns a hash key used by ruby's Hash'es.
+  def hash
+    hash = 0
+    @entries.each do |key, value|
+      hash += key.hash
+      hash += value.hash
+    end
+    return hash
+  end
+  # Returns true, if class, tag and content are matching another object.
+  # The order of the content is ignored, if this or the other object has
+  # the 'ordered' attribute set to false.
+  def eql?(other)
+    if self.class == other.class and self.tag == other.tag
+      if self.ordered? and other.ordered?
+        return self.to_s == other.to_s
+      else
+        own_pairs = self.key_value_pairs
+        other_pairs = other.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
+        end
+        return true
+      end
+    else
+      return false
+    end
+  end
+
+end
+
+
+# Class of UDAT objects holding scalar values (stored as a String).
+class UdatScalar < Udat
+
+  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
+  def content=(content)
+    @content = content.to_s
+  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 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
+  # Calls Udat.construct(tag, self).
+  def to_udat(tag = nil)
+    Udat.construct(tag, self)
+  end
+end
+
+class String
+  # Calls Udat.parse(self).
+  def parse_udat
+    Udat.parse(self)
+  end
+end
+

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: udat
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2007-05-22 00:00:00 +00:00
+summary: Parser and generator for UDAT documents, a generic data format similar to XML or YAML.
+require_paths: 
+- lib/
+email: jan.behrens@flexiguided.de
+homepage: http://www.flexiguided.de/publications.udat.en.html
+rubyforge_project: 
+description: 
+autorequire: udat
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Jan Behrens
+files: 
+- ./LICENSE
+- lib/udat.rb
+test_files: []
+
+rdoc_options: 
+- --title
+- UDAT Documentation
+- --main
+- Udat
+- --line-numbers
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+