sdl4r 0.9.6 → 0.9.7

data/lib/sdl4r/sdl_parse_error.rb

@@ -36,10 +36,10 @@ module SDL4R
 		def initialize(description, line_no, position, line = nil)
 			super(
 				"#{description} Line " + ((line_no.nil? or line_no < 0)? "unknown" : line_no.to_s) +
-					", Position " + ((position.nil? or position < 0)? "unknown" : position.to_s) + "\n" +
+					", Position " + ((position.nil? or position < 0)? "unknown" : position.to_s) + $/ +
           (line ? line + (position ? " " * (position - 1) : "") + "^" : ""))
           
-			@lineNo = line_no
+			@line = line_no
 			@position = position
 		end
 		

data/lib/sdl4r/tag.rb

@@ -87,7 +87,18 @@ module SDL4R
     #     orange quantity=2
     #   }
     #
-    # ==Raises
+    # If you provide a block that takes an argument, you will write the same example, as follows:
+    #
+    #   tag = Tag.new("fruit") do |t|
+    #     t.add_value 2
+    #     t.new_child("orange") do
+    #       set_attribute("quantity", 2)
+    #     end
+    #   end
+    #
+    # In this case, the current context is not the new Tag anymore but the context of your code.
+    #
+    # === Raises
     # ArgumentError if the name is not a legal SDL identifier
     # (see SDL4R#validate_identifier) or the namespace is non-blank
     # and is not a legal SDL identifier.
@@ -113,7 +124,13 @@ module SDL4R
       # The default namespace is represented by an empty string.
       @attributesByNamespace = {}
 
-      instance_eval(&block) if block_given?
+      if block_given?
+        if block.arity > 0
+          block[self]
+        else
+          instance_eval(&block)
+        end
+      end
     end
 
     # Creates a new child tag.
@@ -125,7 +142,15 @@ module SDL4R
     #     end
     #   end
     #
-    # The context of execution of the given block is the child instance
+    # The context of execution of the given block is the child instance.
+    # If you provide a block that takes a parameter (see below), the context is the context of your
+    # code:
+    #
+    #   car = Tag.new("car") do |child|
+    #     child.new_child("wheels") do |grandchild|
+    #       grandchild << 4
+    #     end
+    #   end
     #
     # Returns the created child Tag.
     #
@@ -135,7 +160,7 @@ module SDL4R
   
     # Add a child to this Tag.
     # 
-    # +child+:: The child to add
+    # _child_:: The child to add
     # 
     # Returns the added child.
     #
@@ -146,9 +171,9 @@ module SDL4R
 
     # Adds the given object as a child if it is a +Tag+, as an attribute if it is a Hash
     # {key => value} (supports namespaces), or as a value otherwise.
-    # If it is an array, each of its elements is added to this Tag via this operator. If any of its
-    # elements is itself an array, then an anonymous tag is created and the array is passed to it
-    # via this operator (see the examples below)
+    # If it is an Enumerable (e.g. Array), each of its elements is added to this Tag via this
+    # operator. If any of its elements is itself an Enumerable, then an anonymous tag is created and
+    # the Enumerable is passed to it via this operator (see the examples below).
     #
     #   tag << Tag.new("child")
     #   tag << 123                          # new integer value
@@ -162,9 +187,13 @@ module SDL4R
     #                                       #   4 5 6
     #                                       # }
     #
+    # Of course, despite the fact that String is an Enumerable, it is considered as the type of
+    # values.
+    #
     # Returns +self+.
     #
-    # Use other accessors for a stricter and less "magical" behavior.
+    # Use other accessors (#add_child, #add_value, #attributes, etc) for a stricter and less
+    # "magical" behavior.
     #
     def <<(o)
       if o.is_a?(Tag)
@@ -175,9 +204,11 @@ module SDL4R
           namespace ||= ""
           set_attribute(namespace, key, value)
         }
-      elsif o.is_a? Array
+      elsif o.is_a? String
+        add_value(o)
+      elsif o.is_a? Enumerable
         o.each { |item|
-          if item.is_a? Array
+          if item.is_a? Enumerable and not item.is_a? String
             anonymous = new_child("content")
             anonymous << item
           else
@@ -192,7 +223,7 @@ module SDL4R
     
     # Remove a child from this Tag
     # 
-    # +child+:: the child to remove
+    # _child_:: the child to remove
     #
     # Returns true if the child exists and is removed
     #
@@ -208,14 +239,14 @@ module SDL4R
     end
     
     #
-    # A convenience method that sets the first value in the value list.  See
-    # {@link #addValue(Object)} for legal types.
+    # A convenience method that sets the first value in the value list.
+    # See # #add_value for legal types.
     # 
-    # +value+:: The value to be set.
+    # _value_:: The value to be set.
     #
     # === Raises
     #
-    # +ArgumentError+:: if the value is not a legal SDL type
+    # _ArgumentError_:: if the value is not a legal SDL type
     #
     def value=(value)
       @values[0] = SDL4R.coerce_or_fail(value)
@@ -245,9 +276,9 @@ module SDL4R
     #
     # Returns an Array of the children Tags of this Tag or enumerates them.
     #
-    # +recursive+:: if true children and all descendants will be returned. False by default.
-    # +name+:: if not nil, only children having this name will be returned. Nil by default.
-    # +namespace+:: use nil for all namespaces and "" for the default one. Nil by default.
+    # _recursive_:: if true children and all descendants will be returned. False by default.
+    # _name_:: if not nil, only children having this name will be returned. Nil by default.
+    # _namespace_:: use nil for all namespaces and "" for the default one. Nil by default.
     #
     #   tag.children # => array of the children
     #   tag.children(true) { |descendant| ... }
@@ -283,7 +314,7 @@ module SDL4R
     # more than one value, all the values will be added as an array. If the child
     # has no value, +nil+ will be added. The search is not recursive.
     #
-    # +name+:: if nil, all children are considered (nil by default).
+    # _name_:: if nil, all children are considered (nil by default).
     def children_values(name = nil)
       children_values = []
       each_child(false, name) { |child|
@@ -305,7 +336,7 @@ module SDL4R
     #
     # Get the first child with the given name, optionally using a recursive search.
     # 
-    # +name+:: the name of the child Tag. If +nil+, the first child is returned (+nil+ if there are
+    # _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
@@ -325,7 +356,7 @@ module SDL4R
 
     # Indicates whether the child Tag of given name exists.
     #
-    # +name+:: name of the searched child Tag
+    # _name_:: name of the searched child Tag
     #
     def has_child?(name)
       !child(name).nil?
@@ -340,9 +371,9 @@ module SDL4R
     # Enumerates the children +Tag+s of this Tag and calls the given block
     # providing it the child as parameter.
     #
-    # +recursive+:: if true, enumerate grand-children, etc, recursively
-    # +namespace+:: if not nil, indicates the namespace of the children to enumerate
-    # +name+:: if not nil, indicates the name of the children to enumerate
+    # _recursive_:: if true, enumerate grand-children, etc, recursively
+    # _namespace_:: if not nil, indicates the namespace of the children to enumerate
+    # _name_:: if not nil, indicates the name of the children to enumerate
     #
     def each_child(recursive = false, namespace = nil, name = :DEFAULT, &block)
       if name == :DEFAULT
@@ -402,7 +433,7 @@ module SDL4R
     
     # Adds a value to this Tag. See SDL4R#coerce_or_fail to know about the allowable types.
     #
-    # +v+:: The value to add
+    # _v_:: The value to add
     #
     # Raises an +ArgumentError+ if the value is not a legal SDL type
     #
@@ -419,7 +450,7 @@ module SDL4R
     
     # Removes the first occurence of the specified value from this Tag.
     # 
-    # +v+:: The value to remove
+    # _v_:: The value to remove
     #
     # Returns true If the value exists and is removed
     #
@@ -453,12 +484,11 @@ module SDL4R
       end
     end
     
-    # Set the values for this tag.  See {@link #addValue(Object)} for legal
-    # value types.
+    # Set the values for this tag.  See #add_value for legal value types.
     # 
-    # +values+:: The new values
-    # @throws IllegalArgumentException if the collection contains any values
-    #     which are not legal SDL types
+    # _values_:: The new values
+    #
+    # Raises an +ArgumentError+ if the collection contains any values which are not legal SDL types.
     #
     def values=(someValues)
       @values.clear()
@@ -473,17 +503,15 @@ module SDL4R
     #   set_attribute(namespace, key, value)
     #
     # Set an attribute in the given namespace for this tag.  The allowable
-    # attribute value types are the same as those allowed for
-    # {@link #addValue(Object)}
-    # 
-    # +namespace+:: The namespace for this attribute
-    # +key+:: The attribute key
-    # +value+:: The attribute value
+    # attribute value types are the same as those allowed for #add_value.
     # 
-    # @throws IllegalArgumentException if the key is not a legal SDL
-    #     identifier (see {@link SDL4R#validateIdentifier(String)}), or the
-    #     namespace is non-blank and is not a legal SDL identifier, or the
-    #     value is not a legal SDL type
+    # _namespace_:: The namespace for this attribute
+    # _key_:: The attribute key
+    # _value_:: The attribute value
+    #
+    # Raises +ArgumentError+ if the key is not a legal SDL identifier (see
+    # SDL4R#validate_identifier), or the namespace is non-blank and is not a legal SDL identifier,
+    # or thevalue is not a legal SDL type
     #
     def set_attribute(namespace, key, value = :default)
       if value == :default
@@ -549,7 +577,7 @@ module SDL4R
     #     p "#{namespace}:#{key} = #{value}"
     #   end
     #
-    # +namespace+::
+    # _namespace_::
     # namespace of the returned attributes. If nil, all attributes are returned with
     # qualified names (e.g. "meat:color"). If "", attributes of the default namespace are returned.
     #
@@ -579,8 +607,8 @@ module SDL4R
     #
     # Removes the attribute, whose name and namespace are specified.
     #
-    # +key+:: name of the removed atribute
-    # +namespace+:: namespace of the removed attribute (equal to "", default namespace, by default)
+    # _key_:: name of the removed atribute
+    # _namespace_:: namespace of the removed attribute (equal to "", default namespace, by default)
     #
     # Returns the value of the removed attribute or +nil+ if it didn't exist.
     #
@@ -627,12 +655,11 @@ module SDL4R
     # previous attributes of the specified +namespace+ are removed.
     # See #set_attribute for allowable attribute value types.
     # 
-    # +attributes+:: a Hash where keys are attribute keys
-    # +namespace+:: "" (default namespace) by default
+    # _attributes_:: a Hash where keys are attribute keys
+    # _namespace_:: "" (default namespace) by default
     # 
-    # Raises an +ArgumentError+ if any key in the map is not a legal SDL
-    #     identifier (see SDL4R#validate_identifier), or any value
-    #     is not a legal SDL type.
+    # Raises an +ArgumentError+ if any key in the map is not a legal SDL identifier
+    # (see SDL4R#validate_identifier), or any value is not a legal SDL type.
     #
     def set_attributes(namespace, attribute_hash = nil)
       if attribute_hash.nil?
@@ -655,7 +682,7 @@ module SDL4R
     # Sets all the attributes of the default namespace for this Tag in one
     # operation.
     # 
-    # See #set_attributes
+    # See #set_attributes.
     #
     def attributes=(attribute_hash)
       set_attributes(attribute_hash)
@@ -663,9 +690,9 @@ module SDL4R
   
     # Sets the name of this Tag.
     # 
-    # Raises +ArgumentError+ if the name is not a legal SDL
-    #     identifier (see SDL4R#validate_identifier)
-    
+    # Raises +ArgumentError+ if the name is not a legal SDL identifier
+    # (see SDL4R#validate_identifier).
+    #
     def name=(a_name)
       a_name = a_name.to_s
       SDL4R.validate_identifier(a_name)
@@ -675,8 +702,8 @@ module SDL4R
     # The namespace to set. +nil+ will be coerced to the empty string.
     # 
     # Raises +ArgumentError+ if the namespace is non-blank and is not
-    #     a legal SDL identifier (see {@link SDL4R#validate_identifier(String)})
-    
+    # a legal SDL identifier (see SDL4R#validate_identifier)
+    #
     def namespace=(a_namespace)
       a_namespace = a_namespace.to_s
       SDL4R.validate_identifier(a_namespace) unless a_namespace.empty?
@@ -725,7 +752,7 @@ module SDL4R
     # Write this tag out to the given IO or StringIO or String (optionally clipping the root.)
     # Returns +output+.
     # 
-    # +output+:: an IO or StringIO or a String to write to
+    # _output_:: an IO or StringIO or a String to write to
     # +include_root+:: if true this tag will be written out as the root element, if false only the
     #   children will be written. False by default.
     #
@@ -756,10 +783,9 @@ module SDL4R
       output
     end
   
-    #
     # Get a String representation of this SDL Tag.  This method returns a
     # complete description of the Tag's state using SDL (i.e. the output can
-    # be parsed by {@link #read(String)})
+    # be parsed by #read)
     # 
     # Returns A string representation of this tag using SDL
     #
@@ -767,8 +793,7 @@ module SDL4R
       to_string
     end
     
-    #
-    # +linePrefix+:: A prefix to insert before every line.
+    # _linePrefix_:: A prefix to insert before every line.
     # Returns A string representation of this tag using SDL
     # 
     # TODO: break up long lines using the backslash
@@ -825,8 +850,8 @@ module SDL4R
 
     # Returns a string representation of the children tags.
     #
-    # +linePrefix+:: A prefix to insert before every line.
-    # +s+:: a String that receives the string representation
+    # _linePrefix_:: A prefix to insert before every line.
+    # _s_:: a String that receives the string representation
     #
     # TODO: break up long lines using the backslash
     #
@@ -857,19 +882,45 @@ module SDL4R
     
     # Returns a string containing an XML representation of this tag.  Values
     # will be represented using _val0, _val1, etc.
-    # 
-    # +line_prefix+:: A prefix to insert before every line.
-    # +uri_by_namespace+:: a Hash giving the URIs for the namespaces. Nil to ignore this.
     #
-    def to_xml_string(line_prefix = "", uri_by_namespace = nil)
-      line_prefix ||= ""
-  
+    # _options_:: a hash of the options
+    #
+    # === options:
+    #
+    # [:line_prefix] a text prefixing each line (default: "")
+    # [:uri_by_namespace] a Hash giving the URIs for the namespaces
+    # [:indent] text specifying one indentation (default: "\t")
+    # [:eol] end of line expression (default: "\n")
+    # [:omit_null_attributes]
+    #   if true, null/nil attributes are not exported (default: false). Otherwise, they are exported
+    #   as follows:
+    #     tag attr="null"
+    #
+    def to_xml_string(options = {})
+      options = {
+        :uri_by_namespace => nil,
+        :indent => "\t",
+        :line_prefix => "",
+        :eol => "\n",
+        :omit_null_attributes => false
+      }.merge(options)
+      _to_xml_string(options[:line_prefix], options)
+    end
+
+    protected
+
+    # Implementation of #to_xml_string but without the extra-treatment on parameters for default
+    # values.
+    def _to_xml_string(line_prefix, options)
+      eol = options[:eol]
+
       s = ""
       s << line_prefix << ?<
       s << "#{namespace}:" unless namespace.empty?
       s << name
 
       # output namespace declarations
+      uri_by_namespace = options[:uri_by_namespace]
       if uri_by_namespace
         uri_by_namespace.each_pair do |namespace, uri|
           if namespace
@@ -891,19 +942,22 @@ module SDL4R
       
       # output attributes
       if has_attribute?
+        omit_null_attributes = options[:omit_null_attributes]
         attributes do |attribute_namespace, attribute_name, attribute_value|
-          s << " "
-          s << "#{attribute_namespace}:" unless attribute_namespace.empty?
-          s << attribute_name << "=\"" << SDL4R.format(attribute_value, false) << ?"
+          unless omit_null_attributes and attribute_value.nil?
+            s << " "
+            s << "#{attribute_namespace}:" unless attribute_namespace.empty?
+            s << attribute_name << "=\"" << SDL4R.format(attribute_value, false) << ?"
+          end
         end
       end
   
       if @children.empty?
         s << "/>"
       else
-        s << ">\n"
+        s << ">" << eol
         @children.each do |child|
-          s << child.to_xml_string(line_prefix + "    ") << ?\n
+          s << child._to_xml_string(line_prefix + options[:indent], options) << eol
         end
         
         s << line_prefix << "</"

data/test/sdl4r/parser_test.rb

@@ -86,12 +86,12 @@ module SDL4R
       assert_equal("d`e`f", values[1], "values[1]")
       assert_equal("g\"h\"i", values[2], "values[2]")
       assert_equal("j\\k+l", values[3], "values[3]")
-      assert_equal("m\\\nn\\\n \t o\n", values[4], "values[4]")
+      assert_equal("m\\\nn\\\n \t o\r", values[4], "values[4]")
     end
 
     def test_tag_with_base64_values
       tag1 = parse_one_tag1(
-        <<EOF
+        <<EOS
 tag1 [V2VsY29tZSB0byB0aGUgY3J1ZWwgd29ybGQu] [
     SG9wZSB5
     b3UnbGwg
@@ -99,7 +99,7 @@ tag1 [V2VsY29tZSB0byB0aGUgY3J1ZWwgd29ybGQu] [
     b3VyIHdh
     eS4=
 ]
-EOF
+EOS
         )
       assert_not_nil(tag1, "tag1")
       values = tag1.values
@@ -117,6 +117,11 @@ EOF
       attributes = tag1.attributes
       assert_equal(1, attributes.size, "attribute count")
       assert_equal(99, attributes["attr1"], "attr1")
+
+      # check the parsing with line continuations
+      tag1 = parse_one_tag1("tag1\\\nattr1=\\\n99")
+      assert_not_nil(tag1, "tag1")
+      assert_equal(99, tag1.attribute("attr1"), "attr1")
     end
 
     def test_tag_with_attributes
@@ -208,6 +213,16 @@ EOF
       assert_equal(BigDecimal("171.8"), values[9])
       assert_equal(BigDecimal("1.920"), values[10])
       assert_equal(BigDecimal("12345678901234567890"), values[11])
+
+      assert_raise SdlParseError do
+        parse_one_tag1("tag1 123.2.2")
+      end
+      assert_raise SdlParseError do
+        parse_one_tag1("tag1 123.2e")
+      end
+      assert_raise SdlParseError do
+        parse_one_tag1("tag1 +-123.2")
+      end
     end
 
     def test_booleans
@@ -230,7 +245,7 @@ EOF
     def test_comments
       root = Tag.new("root")
       root.read(
-              <<EOF
+              <<EOS
 tag1 123
 #tag2 456
 tag3 789
@@ -241,7 +256,7 @@ tag7 901
 /*tag8 234
 tag9 567*/
 tag10 890
-EOF
+EOS
       )
       children = root.children
       assert_equal(5, children.size, "children count")
@@ -259,7 +274,7 @@ EOF
 
     def test_double_quote_strings
       root = SDL4R::read(
-<<EOF
+<<EOS
 tag1 "cheese and cherry jam"
 tag2 "cheese and \\
       cherry jam"
@@ -271,7 +286,7 @@ tag5 "Even my dog wouldn't\\thave\\tit!"
 tag6 "\\"\\t\\r\\n\\\\"
 tag7 equation="is not x=y*z" color="blue \\
                                     and yellow"
-EOF
+EOS
       )
 
       assert_equal "cheese and cherry jam", root.child("tag1").value, "double-quote string"
@@ -288,8 +303,32 @@ EOF
       assert_equal "blue and yellow", root.child("tag7").attribute("color")
     end
 
+    def test_characters
+      root = SDL4R::read "tag1 ' ' 'a' '\\\\' '\\t' '\\n' '\\r'"
+      assert_equal [" ", "a", "\\", "\t", "\n", "\r"], root.child("tag1").values
+
+      assert_raise SdlParseError do
+        SDL4R::read "tag1 '"
+      end
+      assert_raise SdlParseError do
+        SDL4R::read "tag1 'a"
+      end
+      assert_raise SdlParseError do
+        SDL4R::read "tag1 'abc'"
+      end
+      assert_raise SdlParseError do
+        SDL4R::read "tag1 ''"
+      end
+      assert_raise SdlParseError do
+        SDL4R::read "tag1 '\\'"
+      end
+      assert_raise SdlParseError do
+        SDL4R::read "tag1 '\\"
+      end
+    end
+
     def test_backquote_strings
-      root = SDL4R::read <<EOF
+      root = SDL4R::read <<EOS
 winfile `c:\\directory\\myfile.xls`
 talk `I said "something"`
 xml `
@@ -298,7 +337,7 @@ xml `
 </product>
 `
 regex `\\w+\\.suite\\(\\)`
-EOF
+EOS
 
       assert_equal "c:\\directory\\myfile.xls", root.child("winfile").value
       assert_equal 'I said "something"', root.child("talk").value
@@ -308,7 +347,7 @@ EOF
     end
 
     def test_sub_tags
-      root = SDL4R::read <<EOF
+      root = SDL4R::read <<EOS
 wax {
 }
 steack {
@@ -322,7 +361,7 @@ steack {
   }
 }
 peanut.butter
-EOF
+EOS
 
       expected = Tag.new("root") do
         new_child("wax")
@@ -341,8 +380,67 @@ EOF
       assert_equal expected, root
     end
 
+    def test_parse_error
+      # WARNING: the line and col of an error is not accurate science. The goal here is to point to
+      # coordinates that are useful to the user.
+      # Exampe for a string litteral that spans over several line, some errors could be point to
+      # the start or to the end without too much ambiguity.
+      # Consequently, feel free to change the coordinates, if a change in the implementation
+      # modifies the x/y of the error and they still make sense.
+      assert_error_xy "=", 1, 1
+      assert_error_xy "tag1 xyz", 1, 6
+      assert_error_xy "tag1 \\\nxyz", 2, 1
+      assert_error_xy "tag1 \\\n   xyz", 2, 4
+      
+      source = <<EOS
+-- my comment
+=
+EOS
+      assert_error_xy source, 2, 1
+
+      source = <<EOS
+murder_plot 123 \\
+      weight=456 \\
+      * \\
+      length=789
+EOS
+      assert_error_xy source, 3, 6
+
+      assert_error_xy 'tag1 "text\\"', 1, 13
+
+      source = <<EOS
+murder_plot "abcd\\
+      efghij\\
+      kl\\
+      mnopq
+EOS
+      assert_error_xy source, 4, 13
+    end
+
     private
 
+    def assert_error_xy source, expected_line, expected_pos
+      error = get_parse_error_or_fail source
+      begin
+        assert_equal expected_line, error.line, "line"
+        assert_equal expected_pos, error.position, "position"
+      rescue
+        puts "Expected error: #{error}"
+        puts error.backtrace
+        raise $!
+      end
+    end
+
+    def get_parse_error_or_fail source
+      begin
+        SDL4R::read source
+
+      rescue
+        return $! if $!.is_a? SdlParseError
+        raise AssertionFailedError, "was expecting a SdlParseError"
+      end
+    end
+
     # Creates and returns a DateTime where an unspecified +zone_offset+ means 'the local zone
     # offset' (contrarily to DateTime#civil())
     def local_civil_date(year, month, day, hour = 0, min = 0, sec = 0, zone_offset = nil)