sdl4r 0.9.2 → 0.9.3

data/lib/sdl4r/parser/reader.rb

@@ -1,3 +1,4 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
@@ -12,6 +13,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#++
 
 module SDL4R
 
@@ -20,7 +22,7 @@ module SDL4R
     # Gives access to the characters read to the Parser.
     # This class was designed to gather the handling of the UTF-8 issues in one place and shield the
     # Parser class from these problems.
-    class Reader
+    class Reader # :nodoc: all
 
       RUBY_1_8_OR_LESS = require 'jcode'
 

data/lib/sdl4r/parser/time_span_with_zone.rb

@@ -1,3 +1,4 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
@@ -12,6 +13,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#++
 
 module SDL4R
 
@@ -22,7 +24,7 @@ module SDL4R
     #
     # +seconds+ can have a fraction
     # +time_zone_offset+ is a fraction of a day (equal to nil if not specified)
-    class TimeSpanWithZone
+    class TimeSpanWithZone # :nodoc: all
 
       private
 

data/lib/sdl4r/parser/token.rb

@@ -1,3 +1,4 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
@@ -12,6 +13,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#++
 
 module SDL4R
   
@@ -23,7 +25,7 @@ module SDL4R
     #
     # @author Daniel Leuck, Philippe Vosges
     #
-    class Token
+    class Token # :nodoc: all
 
       def initialize(text, line = -1, position = -1)
         @text = text

data/lib/sdl4r/parser/tokenizer.rb

@@ -1,3 +1,4 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
@@ -12,6 +13,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#++
 
 
 module SDL4R
@@ -22,7 +24,7 @@ module SDL4R
   class Parser
 
     # Tokenizer of the SDL parser
-    class Tokenizer
+    class Tokenizer # :nodoc: all
 
       TOKEN_TYPES = [
         :IDENTIFIER,

data/lib/sdl4r/sdl.rb

@@ -1,3 +1,4 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
@@ -12,24 +13,16 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
+#++
 
 require 'jcode'
 require 'base64'
 require 'rational'
 require 'date'
 
-# Various SDL related utility methods
+# Gathers 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)
@@ -42,8 +35,7 @@ module SDL4R
   # Creates an SDL string representation for a given object and returns it.
   # 
   # +o+:: the object to format
-  # +add_quotes+:: indicates whether quotes will be added to Strings and characters
-  #   (true by default)
+  # +add_quotes+:: indicates whether quotes will be added to Strings and characters (true by default)
   # +line_prefix+:: the line prefix to use ("" by default)
   # +indent+:: the indent string to use ("\t" by default)
   #
@@ -130,7 +122,10 @@ module SDL4R
     end
   end
     
-  # This method was kept from the Java code but it is not sure if it should have a usefulness yet.
+  # Coerce the type to a standard SDL type or raises an ArgumentError.
+  #
+  # For the time being, just returns +o+ thus allowing to add anything to the SDL tags. This might
+  # not be allowed in the future.
   #
   def self.coerce_or_fail(o)
     return o
@@ -138,10 +133,10 @@ module SDL4R
   
   # Validates an SDL identifier String.  SDL Identifiers must start with a
   # Unicode letter or underscore (_) and contain only unicode letters,
-  # digits, underscores (_), and dashes(-).
+  # digits, underscores (_), dashes(-) and periods (.).
   # 
-  # @param identifier The identifier to validate
-  # @throws IllegalArgumentException if the identifier is not legal
+  # == Raises
+  # ArgumentError if the identifier is not legal
   #
   # TODO: support UTF-8 identifiers
   #
@@ -173,8 +168,36 @@ module SDL4R
     end
   end
 
+  # Creates and returns a tag named "root" and add all the tags specified in the given +input+.
+  #
+  # +input+:: String, IO, Pathname or URI.
+  #
+  #   root = SDL4R::read(<<EOF
+  #   planets {
+  #     earth area_km2=510900000
+  #     mars
+  #   }
+  #   EOF
+  #   )
+  #
+  #   root = SDL4R::read(Pathname.new("my_dir/my_file.sdl"))
+  #
+  #   IO.open("my_dir/my_file.sdl", "r") { |io|
+  #     root = SDL4R::read(io)
+  #   }
+  #   
+  #   root = SDL4R::read(URI.new("http://my_site/my_file.sdl"))
+  #
+  def self.read(input)
+    Tag.new("root").read(input)
+  end
+
   # Parses and returns the value corresponding with the specified SDL literal.
   #
+  #   SDL4R.to_value("\"abcd\"") # => "abcd"
+  #   SDL4R.to_value("1") # => 1
+  #   SDL4R.to_value("null") # => nil
+  #
   def self.to_value(s)
     raise ArgumentError, "'s' cannot be null" if s.nil?
     return read(s).child.value
@@ -185,7 +208,7 @@ module SDL4R
 	#
 	# Example
 	#
-	#   array = SDL4R.to_values("1 true 12:24:01")
+	#   array = SDL4R.to_value_array("1 true 12:24:01")
 	#
 	# Will return an int, a boolean, and a time span.
 	#
@@ -201,7 +224,7 @@ module SDL4R
 	# 
 	#   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
+	#   # { "value" => 1, "debugging" => true, "time" => SdlTimeSpan.new(12, 24, 01) }
 	#
   def self.to_attribute_map(s)
     raise ArgumentError, "'s' cannot be null" if s.nil?

data/lib/sdl4r/sdl_binary.rb

@@ -1,3 +1,4 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
@@ -12,12 +13,13 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#++
 
 
 module SDL4R
 
-  #
   # Represents a binary value.
+  # 
   # This class was introduced to avoid the confusion between a Ruby String and a binary literal.
   #
   class SdlBinary
@@ -35,9 +37,7 @@ module SDL4R
       return self.bytes == o.bytes
     end
 
-    def eql?(o)
-      self == o
-    end
+    alias_method :eql?, :==
 
     def hash
       return bytes.hash

data/lib/sdl4r/sdl_parse_error.rb

@@ -1,8 +1,9 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
-# This program is free software. You can distribute or modify it under the 
-# terms of the GNU Lesser General Public License version 2.1 as published by  
+# This program is free software. You can distribute or modify it under the
+# terms of the GNU Lesser General Public License version 2.1 as published by
 # the Free Software Foundation.
 #
 # This program is distributed AS IS and WITHOUT WARRANTY. OF ANY KIND,
@@ -12,6 +13,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#++
 
 
 module SDL4R

data/lib/sdl4r/sdl_time_span.rb

@@ -1,8 +1,9 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
-# This program is free software. You can distribute or modify it under the 
-# terms of the GNU Lesser General Public License version 2.1 as published by  
+# This program is free software. You can distribute or modify it under the
+# terms of the GNU Lesser General Public License version 2.1 as published by
 # the Free Software Foundation.
 #
 # This program is distributed AS IS and WITHOUT WARRANTY. OF ANY KIND,
@@ -12,6 +13,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#++
 
 
 module SDL4R
@@ -123,120 +125,91 @@ module SDL4R
     
     # Get the total number of hours in this time span.  For example, if
     # this time span represents two days, this method will return 48.
-    # 
-    # @return This timespan in hours
     #
     def total_hours
       return sign * (@totalMilliseconds.abs / MILLISECONDS_IN_HOUR)
     end
     
-    #
     # Get the total number of minutes in this time span.  For example, if
     # this time span represents two hours, this method will return 120.
-    # 
-    # @return This timespan in minutes
     #
     def total_minutes
       return sign * (@totalMilliseconds.abs / MILLISECONDS_IN_MINUTE)
     end
     
-    #
     # Get the total number of seconds in this time span.  For example, if
     # this time span represents three minutes, this method will return 180.
-    # 
-    # @return This timespan in seconds
     #
     def total_seconds
       return sign * (@totalMilliseconds.abs / MILLISECONDS_IN_SECOND)
     end
     
-    #
     # Get the total number of milliseconds in this time span.  For example, if
     # this time span represents 4 seconds, this method will return 4000.
-    # 
-    # @return This timespan in milliseconds
     #
     def total_milliseconds
       return @totalMilliseconds
     end
     
-    #
     # Returns an new SdlTimeSpan instance that is the opposite of this
     # instance
-    # 
-    # @return An instance representing the inverse of this instance
     #
     def negate
       SdlTimeSpan.new(-@totalMilliseconds)
     end
     
-    #
     # Return a new instance with the days adjusted by the given amount.
-    # Positive numbers add days.  Negative numbers remove days.
+    # Positive numbers add days. Negative numbers remove days.
     # 
-    # @param days The adjustment (days to add or subtract)
-    # @return A new instance with the given adjustment.
+    # +days+:: The adjustment (days to add or subtract)
     #
     def roll_days(days)
       SdlTimeSpan.new(@totalMilliseconds + (days * MILLISECONDS_IN_DAY))
     end
     
-    #
     # Return a new instance with the hours adjusted by the given amount.
     # Positive numbers add hours.  Negative numbers remove hours.
     # 
-    # @param hours The adjustment (hours to add or subtract)
-    # @return A new instance with the given adjustment.
+    # +hours+:: The adjustment (hours to add or subtract)
     #
     def roll_hours(hours)
       SdlTimeSpan.new(@totalMilliseconds + (hours * MILLISECONDS_IN_HOUR))
     end
     
-    #
     # Return a new instance with the minutes adjusted by the given amount.
     # Positive numbers add minutes.  Negative numbers remove minutes.
     # 
-    # @param minutes The adjustment (minutes to add or subtract)
-    # @return A new instance with the given adjustment.
+    # +minutes+:: The adjustment (minutes to add or subtract)
     #
     def roll_minutes(minutes)
       SdlTimeSpan.new(@totalMilliseconds + (minutes * MILLISECONDS_IN_MINUTE))
     end
     
-    #
     # Return a new instance with the seconds adjusted by the given amount.
     # Positive numbers add seconds.  Negative numbers remove seconds.
     # 
-    # @param seconds The adjustment (seconds to add or subtract)
-    # @return A new instance with the given adjustment.
+    # +seconds+:: The adjustment (seconds to add or subtract)
     #
     def roll_seconds(seconds)
       SdlTimeSpan.new(@totalMilliseconds + (seconds * MILLISECONDS_IN_SECOND))
     end
     
-    #
     # Return a new instance with the milliseconds adjusted by the given amount.
     # Positive numbers add milliseconds.  Negative numbers remove milliseconds.
     # 
-    # @param milliseconds The adjustment (milliseconds to add or subtract)
-    # @return A new instance with the given adjustment.
+    # +milliseconds+:: The adjustment (milliseconds to add or subtract)
     #
     def roll_milliseconds(milliseconds)
       SdlTimeSpan.new(@totalMilliseconds + milliseconds)
     end
     
-    #
     # A hashcode based on the canonical string representation.
-    # 
-    # @return A hashcode for this time span
     #
     def hash
       to_s.hash
     end
     
     # Tests for equivalence.
-    # 
-    # @return true If the given object is equivalent
     #
     def eql?(other)
       other.is_a?(SdlTimeSpan) and @totalMilliseconds == other.total_milliseconds
@@ -249,27 +222,22 @@ module SDL4R
       @totalMilliseconds <=> other.total_milliseconds
     end
     
-    # <p>Returns an SDL representation of this time span using the format:<p>
+    # Returns an SDL representation of this time span using the format:
     # 
-    # <pre>
-    # (days:)hours:minutes:seconds(.milliseconds)
-    # </pre>
+    #   (days:)hours:minutes:seconds(.milliseconds)
     # 
-    # <p>(parenthesis indicate optional components)
+    # (parenthesis indicate optional components)
     # 
-    # <p>The days and milliseconds components will not be included if they 
-    # are set to 0.  Days must be suffixed with "d" for clarity.</p>
+    # The days and milliseconds components will not be included if they 
+    # are set to 0.  Days must be suffixed with "d" for clarity.
     # 
-    # <p>Hours, minutes, and seconds will be zero paded to two characters.</p>
+    # Hours, minutes, and seconds will be zero paded to two characters.
+    # 
+    # Examples:
     # 
-    # <p>Examples:</p>
-    # <pre>
     #     23:13:00 (12 hours and 13 minutes)
     #     24d:12:13:09.234 (24 days, 12 hours, 13 minutes, 9 seconds,
     #         234 milliseconds)
-    # </pre>
-    # 
-    # @return an SDL representation of this time span
     #
     def to_s
       _days = days

data/lib/sdl4r/tag.rb

@@ -1,3 +1,4 @@
+#--
 # Simple Declarative Language (SDL) for Ruby
 # Copyright 2005 Ikayzo, inc.
 #
@@ -12,6 +13,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program; if not, contact the Free Software Foundation, Inc.,
 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+#++
 
 
 module SDL4R
@@ -23,306 +25,81 @@ module SDL4R
   require File.dirname(__FILE__) + '/sdl'
   require File.dirname(__FILE__) + '/parser'
 
-  # SDL (Simple Declarative Language) documents are made up of Tags. A Tag
-  # contains
-  # 
-  # * a name (if not present, the name "content" is used)
-  # * a namespace (optional)
-  # * 0 or more values (optional)
-  # * 0 or more attributes (optional)
-  # * 0 or more children (optional)
-  # 
-  # For the SDL code:
-  # 
-  #   size 4
-  #   smoker false
-  # 
-  # 
-  # Assuming this code is in a file called values.sdl, the values can be read 
-  # using the following code (ignoring exceptions):
-  # 
-  #     root = Tag.new("root").read(new File("values.sdl"));
-  #     int size = root.getChild("size").intValue();
-  #     boolean smoker = root.getChild("smoker").booleanValue();
-  # 
-  # A tag is basically a data structure with a list of values, a map of
-  # attributes, and (if it has a body) child tags.  In the example above, the
-  # "values.sdl" file is read into a tag called "root".  It has two children
-  # (tags) called "size" and "smoker".  Both these children have one value, no 
-  # attributes, and no bodies.
-  # 
-  # SDL is often used for simple key-value mappings.  To simplify things Tag  
-  # has the methods getValue and setValue which operate on the first element in 
-  # the values list.  Also notice SDL understands types which are determined
-  # using type inference.
-  # 
-  # The example above used the simple format common in property files:
-  # 
-  #     name value
-  # 
-  # The full SDL tag format is:
-  # 
-  #     namespace:name value_list attribute_list {
-  #         children_tags
-  #     }
-  # 
-  # where value_list is zero or more space separated SDL literals and 
-  # attribute_list is zero or more space separated (namespace:)key=value pairs. 
-  # The name, namespace, and keys are SDL identifiers.  Values are SDL literals.
-  # Namespace is optional for both tag names and attributes.  Tag bodies are also
-  # optional.  SDL identifiers begin with a unicode letter or an underscore (_)
-  # followed by zero or more unicode letters, numbers, underscores (_) and
-  # dashes (-).
-  # 
-  # SDL also supports anonymous tags which are assigned the name "content".  
-  # An annoymous tag starts with a literal and is followed by zero or more 
-  # additional literals and zero or more attributes.  The examples section below
-  # demonstrates the use of anonymous tags.
-  # 
-  # Tags without bodies are terminated by a new line character (\n) and may be
-  # continue onto the next line by placing a backslash (\) at the end of the
-  # line.  Tags may be nested to an arbitrary depth.  SDL ignores all other white
-  # space characters between tokens.  Although nested blocks are indented by 
-  # convention, tabs have no significance in the language.
-  # 
-  # There are two ways to write String literals.
-  # 
-  # 1. Starting and ending with double quotes (").  Double quotes, backslash
-  #    characters (\), and new lines (\n) within this type of String literal
-  #    must be escaped like so:
-  # 
-  #     file "C:\\folder\\file.txt"
-  #     say "I said \"something\""
-  # 
-  # This type of String literal can be continued on the next line by placing a
-  # backslash (\) at the end of the line like so:
-  # 
-  #     line "this is a \
-  #          long string of text"
-  # 
-  # White space before the first character in the second line will be ignored.
-  # 
-  # 2. Starting and ending with a backquote (`).  This type of string literal
-  #    can only be ended with a second backquote (`).  It is not necessary (or
-  #    possible) to escape any type of character within a backquote string
-  #    literal. This type of literal can also span lines. All white spaces are
-  #    preserved including new lines.
-  # 
-  # Examples:
-  # 
-  #     file `C:\folder\file.txt`
-  #     say `I said "something"`
-  #     regex `\w+\.suite\(\)`
-  #     long_line `This is
-  #         a long line
-  #         fee fi fo fum`
-  # 
-  # Note: SDL interprets new lines in `` String literals as a single new line
-  # character (\n) regarless of the platform.
-  # 
-  # Binary literals use base64 characters enclosed in square brackets ([]).
-  # The binary literal type can also span lines.  White space is ignored.
-  # 
-  # 
-  # Examples:
-  #     key [sdf789GSfsb2+3324sf2] name="my key"
-  #     image [
-  #         R3df789GSfsb2edfSFSDF
-  #         uikuikk2349GSfsb2edfS
-  #         vFSDFR3df789GSfsb2edf
-  #     ]
-  #     upload from="ikayzo.com" data=[
-  #         R3df789GSfsb2edfSFSDF
-  #         uikuikk2349GSfsb2edfS
-  #         vFSDFR3df789GSfsb2edf
-  #     ]
-  # 
-  # SDL supports date, time span, and date/time literals.  Date and Date/Time
-  # literals use a 24 hour clock (0-23).  If a timezone is not specified, the
-  # default locale's timezone will be used.
+  # SDL documents are made of Tags.
   #
-  # Examples:
-  # 
-  #     # create a tag called "date" with a date value of Dec 5, 2005
-  #     date 2005/12/05
-  #     
-  #     # various time span literals
-  #     hours 03:00:00
-  #     minutes 00:12:00
-  #     seconds 00:00:42
-  #     short_time 00:12:32.423 # 12 minutes, 32 seconds, 423 milliseconds
-  #     long_time 30d:15:23:04.023 # 30 days, 15 hours, 23 mins, 4 secs, 23 millis 
-  #     before -00:02:30 # 2 hours and 30 minutes ago
-  #     
-  #     # a date time literal
-  #     in_japan 2005/12/05 14:12:23.345-JST    
-  # 
-  # 
-  # SDL 1.0 has thirteen literal types (parenthesis indicate optional components)
-  # 
-  #     1. string (unicode) - examples: "hello" or `aloha`
-  #     2. character (unicode) - example: '/'
-  #            Note: \uXXXX style unicode escapes are not supported (or
-  #            needed because sdl files are UTF8)
-  #     3. integer (32 bits signed) - example: 123
-  #     4. long integer (64 bits signed) - examples: 123L or 123l
-  #     5. float (32 bits signed) - examples 123.43F 123.43f 
-  #     6. double float (64 bits signed) - example: 123.43 or 123.43d or 123.43D
-  #     7. decimal (128+ bits signed) - example: 123.44BD or 123.44bd
-  #     8. boolean - examples: true or false or on or off
-  #     9. date yyyy/mm/dd - example 2005/12/05
-  #     10. date time yyyy/mm/dd hh:mm(:ss)(.xxx)(-ZONE)
-  #            example - 2005/12/05 05:21:23.532-JST
-  #            notes: uses a 24 hour clock (0-23), only hours and minutes are
-  #                   mandatory
-  #     11. time span using the format (d:)hh:mm:ss(.xxx)
-  #            notes: if the day component is included it must be suffixed with
-  #                   a lower case 'd'
-  #            examples 12:14:42 (12 hours, 14 minutes, 42 seconds)
-  #                     00:09:12 (9 minutes, 12 seconds)
-  #                     00:00:01.023 (1 second, 23 milliseconds)
-  #                     23d:05:21:23.532 (23 days, 5 hours, 21 minutes,
-  #                         23 seconds, 532 milliseconds)
-  #     12. binary [base64] exmaple - [sdf789GSfsb2+3324sf2]
-  #     13. null
-  # 
-  # 
-  # Timezones must be specified using a valid time zone ID (ex. America/Los_Angeles), three letter
-  # abbreviation (ex. HST), or GMT(+/-)hh(:mm) formatted custom timezone (ex. GMT+02 or GMT+02:30)
-  # 
-  # Note: SDL 1.1 will likely add a reference literal type.
-  # 
-  # These types are designed to be portable across Java, .NET, and other 
-  # popular platforms.
-  # 
-  # 
-  # SDL supports four comment types.
-  # 
-  #   1. // single line comments identicle to those used in Java, C, etc. // style
-  #     comments can occur anywhere in a line.  All text after // up to the new line
-  #     will be ignored.
-  #   2. # property style comments.  They work the same way as //
-  #   3. -- separator comments useful for visually dividing content.  They work the same way as //
-  #   4. Slash star (/*) style multiline comments.  These begin with a slash
-  #     star and end with a star slash.  Everything in between is ignored.
-  # 
-  # 
-  # 
-  # An example SDL file:
-  # 
-  #     # a tag having only a name
-  #     my_tag
-  # 
-  #     # three tags acting as name value pairs
-  #     first_name "Akiko"
-  #     last_name "Johnson"
-  #     height 68
-  #     
-  #     # a tag with a value list
-  #     person "Akiko" "Johnson" 68
-  #     
-  #     # a tag with attributes
-  #     person first_name="Akiko" last_name="Johnson" height=68
-  #     
-  #     # a tag with values and attributes
-  #     person "Akiko" "Johnson" height=60
-  #     
-  #     # a tag with attributes using namespaces
-  #     person name:first-name="Akiko" name:last-name="Johnson"
-  #     
-  #     # a tag with values, attributes, namespaces, and children
-  #     my_namespace:person "Akiko" "Johnson" dimensions:height=68 {
-  #         son "Nouhiro" "Johnson"
-  #         daughter "Sabrina" "Johnson" location="Italy" {
-  #             hobbies "swimming" "surfing"
-  #             languages "English" "Italian"
-  #             smoker false
-  #         }
-  #     }   
-  #     
-  #     ------------------------------------------------------------------
-  #     // (notice the separator style comment above...)
-  #     
-  #     # a log entry
-  #     #     note - this tag has two values (date_time and string) and an 
-  #     #            attribute (error)
-  #     entry 2005/11/23 10:14:23.253-GMT "Something bad happened" error=true
-  #     
-  #     # a long line
-  #     mylist "something" "another" true "shoe" 2002/12/13 "rock" \
-  #         "morestuff" "sink" "penny" 12:15:23.425
-  #     
-  #     # a long string
-  #     text "this is a long rambling line of text with a continuation \
-  #        and it keeps going and going..."
-  #        
-  #    # anonymous tag examples
-  #    
-  #    files {
-  #        "/folder1/file.txt"
-  #        "/file2.txt"
-  #    }
-  #        
-  #    # To retrieve the files as a list of strings
-  #    #
-  #    #     List files = tag.getChild("files").getChildrenValues("content");
-  #    # 
-  #    # We us the name "content" because the files tag has two children, each of 
-  #    # which are anonymous tags (values with no name.)  These tags are assigned
-  #    # the name "content"
-  #        
-  #    matrix {
-  #        1 2 3
-  #        4 5 6
-  #    }
-  #    
-  #    # To retrieve the values from the matrix (as a list of lists)
-  #    #
-  #    #     List rows = tag.getChild("matrix").getChildrenValues("content");
-  #        
-  # 
-  # Example of getting the "location" attribute from the "daughter" tag
-  # above (ignoring exceptions)
-  #  
-  #      Tag root = new Tag("root").read("myfile.sdl");
-  #      Tag daughter = root.getChild("daughter", true); // recursive search
-  #      String location = daughter.getAttribute("location").toString();
-  # 
-  # SDL is normally stored in a file with the .sdl extension.  These files 
-  # should always be encoded using UTF8.  SDL fully supports unicode in 
-  # identifiers and literals.
-  # 
-  # @author Daniel Leuck
+  # Do not assume that methods returning sets (Hash, Array, etc) of children/values/attributes/etc
+  # in this class returns copies or implementations. It can be one or the other depending on the
+  # method. The implementations are designed to be fast and correct, not too protect the Tag
+  # instances from ill-use of the returned values.
+  #
+  # See the README[link:files/README.html] for a longer explanation on SDL documents.
+  #
+  # == Authors
+  # Daniel Leuck, Philippe Vosges
   #
   class Tag
     
-    #
     # the name of this Tag
     #
     attr_reader :name
     
-    #
-    # the namespace of this Tag or an empty string when there is no namespace.
+    # the namespace of this Tag or an empty string when there is no namespace (i.e. default
+    # namespace).
     #
     attr_reader :namespace
+
+    # Convenient method to check and handle a pair of parameters namespace/name where, in some
+    # cases, only one is specified (i.e. the name only).
+    #
+    # Use at the beginning of a method in order to have correctly defined parameters:
+    #   def foo(namespace, name = nil)
+    #     namespace, name = to_nns namespace, name
+    #   end
+    #
+    def to_nns(namespace, name)
+      if name.nil? and not namespace.nil?
+        name = namespace
+        namespace = ""
+      end
+      return namespace, name
+    end
+    private :to_nns
     
-    # Creates an empty tag in the given namespace.  If the +namespace+ is null
+    # Creates an empty tag in the given namespace.  If the +namespace+ is nil
     # it will be coerced to an empty String.
     #
-    # +namespace+:: the namespace for this tag
-    # +name+:: the name of this tag
-    # 
-    # Throws ArgumentError if the name is not a legal SDL identifier
-    # (see SDL#validate_identifier) or the namespace is non-blank
+    #   tag = Tag.new("name")
+    #   tag = Tag.new("namespace", "name")
+    #
+    #   tag = Tag.new("fruit") do
+    #     add_value 2
+    #     new_child("orange") do
+    #       set_attribute("quantity", 2)
+    #     end
+    #   end
+    #
+    # which builds the following SDL structure
+    #
+    #   fruit 2 {
+    #     orange quantity=2
+    #   }
+    #
+    # ==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.
     #
-    def initialize(name, namespace = "", &block)
-      namespace = namespace.to_s
+    def initialize(namespace, name = nil, &block)
+      namespace, name = to_nns namespace, name
+
+      raise ArgumentError, "tag namespace must be a String" unless namespace.is_a? String
+      raise ArgumentError, "tag name must be a String" unless name.is_a? String
+
       SDL4R.validate_identifier(namespace) unless namespace.empty?
       @namespace = namespace
       
       name = name.to_s.strip
-      raise ArgumentError, "Tag name cannot be null or empty" if name.empty?
+      raise ArgumentError, "Tag name cannot be nil or empty" if name.empty?
       SDL4R.validate_identifier(name)
       @name = name
       
@@ -366,9 +143,26 @@ 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)
+    #
+    #   tag << Tag.new("child")
+    #   tag << 123                          # new integer value
+    #   tag << "islamabad"                  # new string value
+    #   tag << { "metric:length" => 1027 }  # new attribute (with namespace)
+    #   tag << [nil, 456, "abc"]            # several values added
+    #
+    #   tag = Tag.new("tag")
+    #   tag << [[1, 2, 3], [4, 5, 6]]       # tag {
+    #                                       #   1 2 3
+    #                                       #   4 5 6
+    #                                       # }
     #
     # Returns +self+.
     #
+    # Use other accessors for a stricter and less "magical" behavior.
+    #
     def <<(o)
       if o.is_a?(Tag)
         add_child(o)
@@ -376,7 +170,16 @@ module SDL4R
         o.each_pair { |key, value|
           namespace, key = key.split(/:/) if key.match(/:/)
           namespace ||= ""
-          set_attribute(key, value, namespace)
+          set_attribute(namespace, key, value)
+        }
+      elsif o.is_a? Array
+        o.each { |item|
+          if item.is_a? Array
+            anonymous = new_child("content")
+            anonymous << item
+          else
+            self << item
+          end
         }
       else
         add_value(o)
@@ -424,16 +227,34 @@ module SDL4R
       @children.size
     end
 
-    # Returns an Array of the children Tags of this Tag.
+    #   children(recursive)
+    #   children(recursive, name)
+    #   children(recursive, namespace, name)
+    #   
+    #   children(recursive) { |child| ... }
+    #   children(recursive, name) { |child| ... }
+    #   children(recursive, namespace, name) { |child| ... }
+    #
+    # 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+:: if not nil, only children having this namespace will be returned.
-    #   Nil by default.
+    # +namespace+:: use nil for all namespaces and "" for the default one. Nil by default.
     #
-    def children(recursive = false, name = nil, namespace = nil, &block)
+    #   tag.children # => array of the children
+    #   tag.children(true) { |descendant| ... }
+    #
+    #   tag.children(false, "name") # => children of name "name"
+    #   tag.children(false, "ns", nil) # => children of namespace "ns"
+    #
+    def children(recursive = false, namespace = nil, name = :DEFAULT, &block) # :yields: child
+      if name == :DEFAULT
+        name = namespace
+        namespace = nil
+      end
+
       if block_given?
-        each_child(recursive, name, namespace, &block)
+        each_child(recursive, namespace, name, &block)
         
       else
         unless recursive or name or namespace
@@ -441,7 +262,7 @@ module SDL4R
           
         else
           result = []
-          each_child(recursive, name, namespace) { |child|
+          each_child(recursive, namespace, name) { |child|
             result << child
           }
           return result
@@ -450,7 +271,7 @@ module SDL4R
     end
 
     # Returns the values of all the children with the given +name+. If the child has
-    # more than one value, all the values will be added as a list. If the child
+    # 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).
@@ -469,6 +290,10 @@ module SDL4R
       return children_values
     end
 
+    #   child
+    #   child(name)
+    #   child(recursive, name)
+    #
     # 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
@@ -476,7 +301,12 @@ module SDL4R
     # 
     # Returns the first child tag having the given name or +nil+ if no such child exists
     #
-    def child(name = nil, recursive = false)
+    def child(recursive = false, name = nil)
+      if name.nil?
+        name = recursive
+        recursive = false
+      end
+      
       unless name
         return @children.first
       else
@@ -502,17 +332,22 @@ module SDL4R
     # providing it the child as parameter.
     #
     # +recursive+:: if true, enumerate grand-children, etc, recursively
-    # +name+:: if not nil, indicates the name of the children to enumerate
     # +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, name = nil, namespace = nil, &block)
+    def each_child(recursive = false, namespace = nil, name = :DEFAULT, &block)
+      if name == :DEFAULT
+        name = namespace
+        namespace = nil
+      end
+
       @children.each do |child|
         if (name.nil? or child.name == name) and
             (namespace.nil? or child.namespace == namespace)
           yield child
         end
 
-        child.children(recursive, name, namespace, &block) if recursive
+        child.children(recursive, namespace, name, &block) if recursive
       end
       return nil
     end
@@ -556,14 +391,11 @@ module SDL4R
       return hash
     end
     
-    # Adds a value to this Tag. The allowable types are String, Number,
-    # Boolean, Character, byte[], Byte[] (coerced to byte[]), Calendar,
-    # Date (coerced to Calendar), and null.  Passing any other type will
-    # result in an IllegalArgumentException.
-    # 
+    # Adds a value to this Tag. See SDL4R#coerce_or_fail to know about the allowable types.
+    #
     # +v+:: The value to add
     #
-    # Raises a +ArgumentError+ if the value is not a legal SDL type
+    # Raises an +ArgumentError+ if the value is not a legal SDL type
     #
     def add_value(v)
       @values.push(SDL4R::coerce_or_fail(v))
@@ -575,14 +407,19 @@ module SDL4R
       @values.include?(v)
     end
     
-    # Remove a value from this Tag.
+    # Removes the first occurence of the specified value from this Tag.
     # 
     # +v+:: The value to remove
     #
     # Returns true If the value exists and is removed
     #
     def remove_value(v)
-      return !@values.delete(v).nil?
+      index = @values.index(v)
+      if index
+        return !@values.delete_at(index).nil?
+      else
+        return false
+      end
     end
 
     # Removes all values.
@@ -591,8 +428,12 @@ module SDL4R
       @values = []
     end
     
-    # Returns an Array of the values of this Tag
-    def values
+    # Returns an Array of the values of this Tag or enumerates them.
+    #
+    #   tag.values # => [123, "spices"]
+    #   tag.values { |value| puts value }
+    #
+    def values # :yields: value
       if block_given?
         @values.each { |v| yield v }
       else
@@ -616,23 +457,36 @@ module SDL4R
       }
     end
   
+    #   set_attribute(key, value)
+    #   set_attribute(namespace, key, value)
     #
-    # Set an attribute in the given namespace for this tag.  The allowable  
+    # 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
+    # 
     # @throws IllegalArgumentException if the key is not a legal SDL
-    #     identifier (see {@link SDL#validateIdentifier(String)}), or the
+    #     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
     #
-    def set_attribute(key, value, namespace = "")
+    def set_attribute(namespace, key, value = nil)
+      if value.nil?
+        value = key
+        key = namespace
+        namespace = ""
+      end
+
+      raise ArgumentError, "attribute namespace must be a String" unless namespace.is_a? String
+      raise ArgumentError, "attribute key must be a String" unless key.is_a? String
+      raise ArgumentError, "attribute key cannot be empty" if key.empty?
+
       SDL4R.validate_identifier(namespace) unless namespace.empty?
       SDL4R.validate_identifier(key)
-      
+
       attributes = @attributesByNamespace[namespace]
       
       if attributes.nil?
@@ -643,31 +497,51 @@ module SDL4R
       attributes[key] = SDL4R.coerce_or_fail(value)
     end
     
+    #   attribute(key)
+    #   attribute(namespace, key)
+    #
     # Returns the attribute of the specified +namespace+ of specified +key+ or +nil+ if not found.
     #
-    # +namespace+:: the default namespace ("") by default
     #
-    def attribute(key, namespace = "")
+    def attribute(namespace, key = nil)
+      namespace, key = to_nns namespace, key
       attributes = @attributesByNamespace[namespace]
       return attributes.nil? ? nil : attributes[key]
     end
 
-    # Indicates whether the specified attribute exists in this Tag.
+    # Indicates whether there is at least an attribute in this Tag.
+    #   has_attribute?
     #
-    # +key+:: key of the attribute
-    # +namespace+:: namespace of the attribute ("", the default namespace, by default)
+    # Indicates whether there is the specified attribute exists in this Tag.
+    #   has_attribute?(key)
+    #   has_attribute?(namespace, key)
     #
-    def has_attribute?(key, namespace = "")
-      attributes = @attributesByNamespace[namespace]
-      return attributes.nil? ? false : attributes.has_key?(key)
+    def has_attribute?(namespace = nil, key = nil)
+      namespace, key = to_nns namespace, key
+
+      if namespace or key
+        attributes = @attributesByNamespace[namespace]
+        return attributes.nil? ? false : attributes.has_key?(key)
+
+      else
+        attributes { return true }
+        return false
+      end
     end
     
-    # Returns a copy of the Hash of the attributes of the specified +namespace+ (default is all).
+    # Returns a Hash of the attributes of the specified +namespace+ (default is all) or enumerates
+    # them.
     #
-    # +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.
+    #   tag.attributes # => { "length" => 123, "width" = 25.4, "orig:color" => "gray" }
+    #   tag.attributes("orig") do |namespace, key, value|
+    #     p "#{namespace}:#{key} = #{value}"
+    #   end
     #
-    def attributes(namespace = nil, &block)
+    # +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.
+    #
+    def attributes(namespace = nil, &block) # :yields: namespace, key, value
       if block_given?
         each_attribute(namespace, &block)
         
@@ -675,7 +549,7 @@ module SDL4R
         if namespace.nil?
           hash = {}
 
-          each_attribute(nil) do | key, value, namespace |
+          each_attribute do | namespace, key, value |
             qualified_name = namespace.empty? ? key : namespace + ':' + key
             hash[qualified_name] = value
           end
@@ -689,6 +563,9 @@ module SDL4R
       end
     end
 
+    #   remove_attribute(key)
+    #   remove_attribute(namespace, key)
+    #
     # Removes the attribute, whose name and namespace are specified.
     #
     # +key+:: name of the removed atribute
@@ -696,7 +573,8 @@ module SDL4R
     #
     # Returns the value of the removed attribute or +nil+ if it didn't exist.
     #
-    def remove_attribute(key, namespace = "")
+    def remove_attribute(namespace, key = nil)
+      namespace, key = to_nns namespace, key
       attributes = @attributesByNamespace[namespace]
       return attributes.nil? ? nil : attributes.delete(key)
     end
@@ -713,11 +591,9 @@ module SDL4R
     end
     
     # Enumerates the attributes for the specified +namespace+.
-    # If no +namespace+ is specified, enumerates the attribute of the default
-    # namespace. If +namespace+ is nil, enumerates the attributes of all
-    # namespaces.
+    # Enumerates all the attributes by default.
     #
-    def each_attribute(namespace = "", &block)
+    def each_attribute(namespace = nil, &block) # :yields: namespace, key, value
       if namespace.nil?
         @attributesByNamespace.each_key { |a_namespace| each_attribute(a_namespace, &block) }
         
@@ -725,37 +601,43 @@ module SDL4R
         attributes = @attributesByNamespace[namespace]
         unless attributes.nil?
           attributes.each_pair do |key, value|
-            yield key, value, namespace
+            yield namespace, key, value
           end
         end
       end
     end
     private :each_attribute
     
-    # Sets all the attributes of a +namespace+ for this Tag in one operation.
-    # See # #add_value for allowable attribute value types.
+
+    #   set_attributes(attribute_hash)
+    #   set_attributes(namespace, attribute_hash)
+    #
+    # Sets the attributes specified by a Hash in the given +namespace+ in one operation. The
+    # 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
     # 
     # Raises an +ArgumentError+ if any key in the map is not a legal SDL
-    #     identifier (see SDL#validate_identifier), or any value
+    #     identifier (see SDL4R#validate_identifier), or any value
     #     is not a legal SDL type.
     #
-    def set_attributes(attribute_hash, namespace = "")
-      return if attribute_hash.nil? or attribute_hash.empty?
-      
-      attributes = @attributesByNamespace[namespace]
-      if attributes.nil?
-        attributes = {}
-        @attributesByNamespace[namespace] = attributes
-      else
-        attributes.clear()
+    def set_attributes(namespace, attribute_hash = nil)
+      if attribute_hash.nil?
+        attribute_hash = namespace
+        namespace = ""
       end
       
+      raise ArgumentError, "namespace can't be nil" if namespace.nil?
+      raise ArgumentError, "attribute_hash should be a Hash" unless attribute_hash.is_a? Hash
+
+      namespace_attributes = @attributesByNamespace[namespace]
+      namespace_attributes.clear if namespace_attributes
+      
       attribute_hash.each_pair do |key, value|
           # Calling set_attribute() is required to ensure validations
-          set_attribute(key, value)
+          set_attribute(namespace, key, value)
       end
     end
     
@@ -765,13 +647,13 @@ module SDL4R
     # See #set_attributes
     #
     def attributes=(attribute_hash)
-      set_attributes(attribute_hash, "")
+      set_attributes(attribute_hash)
     end
   
     # Sets the name of this Tag.
     # 
     # Raises +ArgumentError+ if the name is not a legal SDL
-    #     identifier (see SDL#validate_identifier)
+    #     identifier (see SDL4R#validate_identifier)
     
     def name=(a_name)
       a_name = a_name.to_s
@@ -779,10 +661,10 @@ module SDL4R
       @name = a_name
     end
   
-    # The namespace to set.  null will be coerced to the empty string.
+    # 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 SDL#validate_identifier(String)})
+    #     a legal SDL identifier (see {@link SDL4R#validate_identifier(String)})
     
     def namespace=(a_namespace)
       a_namespace = a_namespace.to_s
@@ -892,7 +774,7 @@ module SDL4R
 
       # output attributes
       unless @attributesByNamespace.empty?
-        all_attributes_hash = attributes(nil)
+        all_attributes_hash = attributes
         all_attributes_array = all_attributes_hash.sort { |a, b|
           namespace1, name1 = a[0].split(':')
           namespace1, name1 = "", namespace1 if name1.nil?
@@ -952,18 +834,27 @@ module SDL4R
     # Returns a string containing an XML representation of this tag.  Values
     # will be represented using _val0, _val1, etc.
     # 
-    # Returns An XML String describing this Tag
-    # +linePrefix+:: A prefix to insert before every line.
-    # 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(linePrefix = "")
-      linePrefix = "" if linePrefix.nil?
+    def to_xml_string(line_prefix = "", uri_by_namespace = nil)
+      line_prefix ||= ""
   
       s = ""
-      s << linePrefix << ?<
+      s << line_prefix << ?<
       s << "#{namespace}:" unless namespace.empty?
       s << name
+
+      # output namespace declarations
+      if uri_by_namespace
+        uri_by_namespace.each_pair do |namespace, uri|
+          if namespace
+            s << " xmlns:#{namespace}=\"#{uri}\""
+          else
+            s << " xmlns=\"#{uri}\""
+          end
+        end
+      end
       
       # output values
       unless @values.empty?
@@ -975,10 +866,9 @@ module SDL4R
       end
       
       # output attributes
-      unless @attributes.empty?
-        @attributes.each do |attribute_name, attribute_value|
+      if has_attribute?
+        attributes do |attribute_namespace, attribute_name, attribute_value|
           s << " "
-          attribute_namespace = @attributeToNamespace[attribute_name]
           s << "#{attribute_namespace}:" unless attribute_namespace.empty?
           s << attribute_name << "=\"" << SDL4R.format(attribute_value, false) << ?"
         end
@@ -989,10 +879,10 @@ module SDL4R
       else
         s << ">\n"
         @children.each do |child|
-          s << child.to_xml_string(linePrefix + "    ") << ?\n
+          s << child.to_xml_string(line_prefix + "    ") << ?\n
         end
         
-        s << linePrefix << "</"
+        s << line_prefix << "</"
         s << "#{namespace}:" unless namespace.empty?
         s << name << ?>
       end