sdl4r 0.9.1 → 0.9.2

data/lib/sdl4r/sdl.rb

@@ -22,6 +22,14 @@ require 'date'
 # Various SDL related utility methods
 # 
 module SDL4R
+
+  # Creates and returns a tag named "root" and add all the tags specified in the given +input+.
+  #
+  # +input+:: String, IO, Pathname or URI.
+  #
+  def self.read(input)
+    Tag.new("root").read(input)
+  end
   
   MAX_INTEGER_32 = 2**31 - 1
   MIN_INTEGER_32 = -(2**31)
@@ -29,15 +37,6 @@ module SDL4R
   MAX_INTEGER_64 = 2**63 - 1
   MIN_INTEGER_64 = -(2**63)
 
-  
-  # Returns the milliseonds part of a DateTime (by translating the +sec_fraction+ part) as an
-  # integer.
-  def self.get_date_milliseconds(date)
-    sec_fraction = date.sec_fraction() # in days
-    # 86400000 is the number of milliseconds in a day
-    return (sec_fraction * 86400000).round()
-  end
-
   BASE64_WRAP_LINE_LENGTH = 72
 
   # Creates an SDL string representation for a given object and returns it.
@@ -130,72 +129,6 @@ module SDL4R
       return o.to_s
     end
   end
-
-  # Wraps lines in "s" (by modifying it). This method only supports 1-byte character strings.
-  #
-  def self.wrap_lines_in_ascii(s, line_length, line_prefix = nil)
-    # We could use such code if it supported any value for "line_prefix": unfortunately it is capped
-    # at 64 in the regular expressions.
-    #
-    # return "#{line_prefix}" + encoded_o.scan(/.{1,#{line_prefix}}/).join("#{$/}#{line_prefix}")
-
-    eol_size = "#{$/}".size
-
-    i = 0
-    while i < s.size
-      if i > 0
-        s.insert(i, $/)
-        i += eol_size
-      end
-
-      if line_prefix
-        s.insert(i, line_prefix)
-        i += line_prefix.size
-      end
-
-      i += line_length
-    end
-  end
-
-  ESCAPED_QUOTES = {
-    "\"" => "\\\"",
-    "'" => "\\'",
-    "`" => "\\`",
-  }
-
-  ESCAPED_CHARS = {
-    "\\" => "\\\\",
-    "\t" => "\\t",
-    "\r" => "\\r",
-    "\n" => "\\n",
-  }
-  ESCAPED_CHARS.merge!(ESCAPED_QUOTES)
-
-  # Returns an escaped version of +s+ (i.e. where characters which need to be
-  # escaped, are escaped).
-  #
-  def self.escape(s, quote_char = nil)
-    escaped_s = ""
-
-    s.each_char { |c|
-      escaped_char = ESCAPED_CHARS[c]
-      if escaped_char
-        if ESCAPED_QUOTES.has_key?(c)
-          if quote_char && c == quote_char
-            escaped_s << escaped_char
-          else
-            escaped_s << c
-          end
-        else
-            escaped_s << escaped_char
-        end
-      else
-        escaped_s << c
-      end
-    }
-    
-    return escaped_s
-  end
     
   # This method was kept from the Java code but it is not sure if it should have a usefulness yet.
   #
@@ -226,7 +159,7 @@ module SDL4R
         "an underscore (_)."
     end
     
-    unless identifier.length == 1 or identifier =~ /^[a-zA-Z_][a-zA-Z_0-9\-]*$/
+    unless identifier.length == 1 or identifier =~ /^[a-zA-Z_][a-zA-Z_0-9\-\.]*$/
       for i in 1..identifier.length
         unless identifier[i..i] =~ /^[a-zA-Z_0-9\-]$/
           raise ArgumentError,
@@ -239,4 +172,121 @@ module SDL4R
       end
     end
   end
+
+  # Parses and returns the value corresponding with the specified SDL literal.
+  #
+  def self.to_value(s)
+    raise ArgumentError, "'s' cannot be null" if s.nil?
+    return read(s).child.value
+  end
+
+  # Parse the string of values and return a list.  The string is handled
+  # as if it is the values portion of an SDL tag.
+	#
+	# Example
+	#
+	#   array = SDL4R.to_values("1 true 12:24:01")
+	#
+	# Will return an int, a boolean, and a time span.
+	#
+  def self.to_value_array(s)
+    raise ArgumentError, "'s' cannot be null" if s.nil?
+    return read(s).child.values
+  end
+
+	# Parse a string representing the attributes portion of an SDL tag
+	# and return the results as a map.
+	#
+	# Example
+	# 
+	#   hash = SDL4R.to_attribute_hash("value=1 debugging=on time=12:24:01");
+	#
+	# Will return a map containing value=1, debugging=true, and time=12:24:01
+	#
+  def self.to_attribute_map(s)
+    raise ArgumentError, "'s' cannot be null" if s.nil?
+    return read("atts " + s).child.attributes
+  end
+
+  # The following is a not so readable way to implement module private methods in Ruby: we add
+  # private methods to the singleton class of +self+ i.e. the SDL4R module.
+  class << self
+    private
+
+    # Wraps lines in "s" (by modifying it). This method only supports 1-byte character strings.
+    #
+    def wrap_lines_in_ascii(s, line_length, line_prefix = nil)
+      # We could use such code if it supported any value for "line_prefix": unfortunately it is capped
+      # at 64 in the regular expressions.
+      #
+      # return "#{line_prefix}" + encoded_o.scan(/.{1,#{line_prefix}}/).join("#{$/}#{line_prefix}")
+
+      eol_size = "#{$/}".size
+
+      i = 0
+      while i < s.size
+        if i > 0
+          s.insert(i, $/)
+          i += eol_size
+        end
+
+        if line_prefix
+          s.insert(i, line_prefix)
+          i += line_prefix.size
+        end
+
+        i += line_length
+      end
+    end
+
+    ESCAPED_QUOTES = {
+      "\"" => "\\\"",
+      "'" => "\\'",
+      "`" => "\\`",
+    }
+
+    ESCAPED_CHARS = {
+      "\\" => "\\\\",
+      "\t" => "\\t",
+      "\r" => "\\r",
+      "\n" => "\\n",
+    }
+    ESCAPED_CHARS.merge!(ESCAPED_QUOTES)
+
+    # Returns an escaped version of +s+ (i.e. where characters which need to be
+    # escaped, are escaped).
+    #
+    def escape(s, quote_char = nil)
+      escaped_s = ""
+
+      s.each_char { |c|
+        escaped_char = ESCAPED_CHARS[c]
+        if escaped_char
+          if ESCAPED_QUOTES.has_key?(c)
+            if quote_char && c == quote_char
+              escaped_s << escaped_char
+            else
+              escaped_s << c
+            end
+          else
+              escaped_s << escaped_char
+          end
+        else
+          escaped_s << c
+        end
+      }
+
+      return escaped_s
+    end
+
+    # Returns the milliseonds part of a DateTime (by translating the +sec_fraction+ part) as an
+    # integer.
+    def get_date_milliseconds(date)
+      sec_fraction = date.sec_fraction() # in days
+      # 86400000 is the number of milliseconds in a day
+      return (sec_fraction * 86400000).round()
+    end
+
+  end
+
 end

data/lib/sdl4r/tag.rb

@@ -16,6 +16,8 @@
 
 module SDL4R
 
+  require 'pathname'
+  require 'open-uri'
   require 'stringio'
   
   require File.dirname(__FILE__) + '/sdl'
@@ -314,7 +316,7 @@ module SDL4R
     # (see SDL#validate_identifier) or the namespace is non-blank
     # and is not a legal SDL identifier.
     #
-    def initialize(name, namespace = "")
+    def initialize(name, namespace = "", &block)
       namespace = namespace.to_s
       SDL4R.validate_identifier(namespace) unless namespace.empty?
       @namespace = namespace
@@ -330,6 +332,25 @@ module SDL4R
       # a Hash of Hash : {namespace => {name => value}}
       # The default namespace is represented by an empty string.
       @attributesByNamespace = {}
+
+      instance_eval(&block) if block_given?
+    end
+
+    # Creates a new child tag.
+    # Can take a block so that you can write something like:
+    #
+    #   car = Tag.new("car") do
+    #     new_child("wheels") do
+    #       self << 4
+    #     end
+    #   end
+    #
+    # The context of execution of the given block is the child instance
+    #
+    # Returns the created child Tag.
+    #
+    def new_child(*args, &block)
+      return add_child Tag.new(*args, &block)
     end
   
     # Add a child to this Tag.
@@ -453,7 +474,7 @@ module SDL4R
     # +name+:: the name of the child Tag. If +nil+, the first child is returned (+nil+ if there are
     # no children at all).
     # 
-    # Returns The first child tag having the given name or +nil+ if no such child exists
+    # Returns the first child tag having the given name or +nil+ if no such child exists
     #
     def child(name = nil, recursive = false)
       unless name
@@ -463,6 +484,20 @@ module SDL4R
       end
     end
 
+    # Indicates whether the child Tag of given name exists.
+    #
+    # +name+:: name of the searched child Tag
+    #
+    def has_child?(name)
+      !child(name).nil?
+    end
+
+    # Indicates whether there are children Tag.
+    #
+    def has_children?
+      !@children.empty?
+    end
+
     # Enumerates the children +Tag+s of this Tag and calls the given block
     # providing it the child as parameter.
     #
@@ -482,6 +517,44 @@ module SDL4R
       return nil
     end
     private :each_child
+
+    # Returns a new Hash where the children's names as keys and their values as the key's value.
+    # Example:
+    #
+    #   child1 "toto"
+    #   child2 2
+    #
+    # would give
+    #
+    #   { "child1" => "toto", "child2" => 2 }
+    #
+    def to_child_hash
+      hash = {}
+      children { |child| hash[child.name] = child.value }
+      return hash
+    end
+
+    # Returns a new Hash where the children's names as keys and their values as the key's value.
+    # Values are converted to Strings. +nil+ values become empty Strings.
+    # Example:
+    #
+    #   child1 "toto"
+    #   child2 2
+    #   child3 null
+    #
+    # would give
+    #
+    #   { "child1" => "toto", "child2" => "2", "child3" => "" }
+    #
+    def to_child_string_hash
+      hash = {}
+      children do |child|
+        # FIXME: it is quite hard to be sure whether we should mimic the Java version
+        # as there might be a lot of values that don't translate nicely to Strings.
+        hash[child.name] = child.value.to_s
+      end
+      return hash
+    end
     
     # Adds a value to this Tag. The allowable types are String, Number,
     # Boolean, Character, byte[], Byte[] (coerced to byte[]), Calendar,
@@ -498,7 +571,7 @@ module SDL4R
 
     # Returns true if +v+ is a value of this Tag's.
     #
-    def has_value(v)
+    def has_value?(v)
       @values.include?(v)
     end
     
@@ -584,7 +657,7 @@ module SDL4R
     # +key+:: key of the attribute
     # +namespace+:: namespace of the attribute ("", the default namespace, by default)
     #
-    def has_attribute(key, namespace = "")
+    def has_attribute?(key, namespace = "")
       attributes = @attributesByNamespace[namespace]
       return attributes.nil? ? false : attributes.has_key?(key)
     end
@@ -716,64 +789,45 @@ module SDL4R
       SDL4R.validate_identifier(a_namespace) unless a_namespace.empty?
       @namespace = a_namespace
     end
-    
-    #
-    # Add all the tags specified in the file at the given URL to this Tag.
-    # 
-    # +url+:: A UTF8 encoded .sdl file
-    # @throws IOException If there is an IO problem reading the source 
-    # @throws ParseException If the SDL input is malformed
-    # Returns This tag after adding all the children read from the reader
-    #
-  #  public Tag read(URL url) throws IOException, SDLParseException {
-  #    return read(new InputStreamReader(url.openStream(), "UTF8"));
-  #  }  
-    
-    #
-    # Add all the tags specified in the given file to this Tag.
-    # 
-    # +file+:: A UTF8 encoded .sdl file
-    # @throws IOException If there is an IO problem reading the source 
-    # @throws ParseException If the SDL input is malformed
-    # Returns This tag after adding all the children read from the reader
-    #
-  #  public Tag read(File file) throws IOException, SDLParseException {
-  #    return read(new InputStreamReader(new FileInputStream(file), "UTF8"));
-  #  }  
-    
-    #
-    # Add all the tags specified in the given String to this Tag.
-    # 
-    # +text+:: An SDL string
-    # @throws ParseException If the SDL input is malformed
-    # Returns This tag after adding all the children read from the reader
-    #
-  #  public Tag read(String text) throws SDLParseException {
-  #    try {
-  #      return read(new StringReader(text));
-  #    } catch(IOException ioe) {
-  #      // Cannot happen
-  #      throw new InternalError("IOExceptio reading a String");
-  #    }
-  #  }
-    
-    # Adds all the tags specified in the given +IO+ or String to this Tag.
+        
+    # Adds all the tags specified in the given IO, String, Pathname or URI to this Tag.
     # 
-    # Returns this Tag after adding all the children read from _input_.
+    # Returns this Tag after adding all the children read from +input+.
     #
     def read(input)
-      if input.is_a?(String)
-        io = StringIO.new(input)
+      if input.is_a? String
+        read_from_io(true) { StringIO.new(input) }
+
+      elsif input.is_a? Pathname
+        read_from_io(true) { input.open("r") }
+
+      elsif input.is_a? URI
+        read_from_io(true) { input.open }
+
       else
-        io = input
+        read_from_io(false) { input }
       end
       
-      Parser.new(io).parse.each do |tag|
-        add_child(tag)
-      end
-
       return self
     end
+
+    # Reads and parses the +io+ returned by the specified block and closes this +io+ if +close_io+
+    # is true.
+    def read_from_io(close_io)
+      io = yield
+
+      begin
+        Parser.new(io).parse.each do |tag|
+          add_child(tag)
+        end
+
+      ensure
+        if close_io
+          io.close rescue IOError
+        end
+      end
+    end
+    private_methods :read_io
     
     # Write this tag out to the given IO or string (optionally clipping the root.)
     #