sdl4r 0.9.1

data/README

@@ -0,0 +1,3 @@
+== sdl4r
+
+

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rubygems'
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Simple Declarative Language for Ruby library"
+  s.name = 'sdl4r'
+  s.version = '0.9.1'
+  s.requirements << 'none'
+  s.require_path = 'lib'
+  s.author = 'Philippe Vosges'
+  s.email = 'sdl-users@ikayzo.org'
+  s.rubyforge_project = 'sdl4r'
+  s.homepage = 'http://www.ikayzo.org/confluence/display/SDL/Home'
+  s.files = FileList['lib/**/*.rb', 'bin/*', '[A-Z]*', 'test/**/*'].to_a
+  s.test_files = FileList[ 'test/**/*test.rb' ].to_a
+  s.description = <<EOF
+  The Simple Declarative Language provides an easy way to describe lists, maps,
+  and trees of typed data in a compact, easy to read representation.
+  For property files, configuration files, logs, and simple serialization
+  requirements, SDL provides a compelling alternative to XML and Properties
+  files.
+EOF
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.rdoc_files.include("lib/**/*.rb")
+  rd.rdoc_dir = "doc"
+  rd.title = "Simple Declarative Language for Ruby"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*test.rb']
+  t.verbose = true
+end

data/TODO.txt

@@ -0,0 +1,117 @@
+[x] Tag.each_attribute should allow to iterate on all namespaces if 'namespace' is nil
+[x] Tag.get_attributes(namespace)
+[x] Implementation of attributes=
+[x] Implementation of Sdl.format()
+[x] Handle milliseconds in Sdl.format()
+[x] Handle timezones in Sdl.format()
+[x] Handle the Time class in Sdl.format()
+[x] Handle SdlTimeSpan in Sdl.format() ==> via to_s()
+[x] Review SdlTimeSpan
+[x] Instead of calling Tag.each_attribute(), we could have another way of calling attributes:
+    with or without given block. Same goes for each_value(), etc.
+[x] Is Base64 really compatible with the format defined in the Java version ?
+    ==> Seems so after having implemented more of the standard tests.
+[ ] Support both DateTime and Time in parsing (see Parser#combine())
+[x] Use Date instead of DateTime if only day was specified in SDL (parser.rb)
+[x] Add a remove_all_children() to Tag
+[x] Rethink the interfaces to access sub-tags, values, attributes, etc
+    (it is currently difficult to retrieve all the values, or the number of
+     sub-tags, etc)
+    ==> to simplify access to values would be ok but attributes or children would be more difficult.
+[x] See whether there is such a need to shield users from the actual arrays of
+    values (we return a copy for the time being).
+    ==> We don't return copies anymore.
+[ ] Add more unit tests
+    [x] Attribute tests
+    [x] Date tests
+    [x] Date + time test
+    [x] Time zone tests
+    [x] Number literal tests
+    [ ] Strings literals (especially with line continuations)
+    [ ] Sub tags tests
+    [x] "null" value test
+    [x] Comment tests
+    [ ] Bad syntax tests
+[ ] Test write (unit tests)
+    [ ] Dates
+    [ ] Numbers
+[ ] Use YARD in order to generate documentation ?
+[ ] In the documentation, present a table giving the returned Ruby type for each SDL type.
+[A] Change the interface of SdlTimeSpan to look like the interfaces of Date, DateTime or Time
+    ==> Really? This is a timespan, not a date.
+[x] Have SdlTimeSpan implement Comparable
+[ ] BUG: the line number is too high by 1 (the column is correct).
+[x] PB: binary fields shouldn't be kept as Strings because they would not be saved as binaries but
+    as strings otherwise.
+    ==> We use SdlBinary now.
+[x] Change the module name to SDL4R? Something else?
+    ==> Changed to SDL4R.
+[/] Fix the differences between test_basic_types.sdl and what is generated from the parsed structure
+    [x] chars
+    [x] longs
+    [x] doubles
+    [x] decimals
+    [x] booleans
+    [x] null
+    [x] dates
+    [x] times
+        [x] negative times
+    [x] datetimes
+        [/] zone codes
+        ==> Time only works in UTC, which means that the original zone code is lost.
+        ==> DateTime doesn't give the zone code but only the offset.
+        [ ] Use TzTime? Use a custom object that knows whether a time zone was specified?
+[x] BUG: Base64 wrapped lines are 64 chars long and not 72 (traditionnal length)
+    ==> Because of a limitation in the regular expressions ==> find another algorithm
+[x] See whether we can do better for numbers of arbitrary precision (decimals).
+    ==> Ruby BigDecimal
+    ==> Ruby Decimal http://ruby-decimal.rubyforge.org/
+        ==> Now: http://flt.rubyforge.org/ : use this if the lib is available
+    ==> We use flt if available.
+[ ] See how Ruby floats relate to Java floats and doubles.
+[ ] Add tests for the SDL class
+[ ] Allow unicode characters in identifiers.
+[ ] It would probably be useful to allow people to replace the standard types by their own. This
+    could be useful for dates or numbers, for instance.
+[N] To install a gem in the Netbeans gems repository, it needs to run as an administrator.
+    Otherwise, it fails silently.
+[ ] Make it so that the tests pass (with errors or not), when Ftl (DecNum) is not available.
+[x] Fix the ParserTest test.
+[x] SDL 1.1:   tag1; tag2 "a value"; tag3 name="foo"
+    [x] Create a Tokenizer class
+[A] Test attributes with/without namespaces
+    ==> Guess this is done in test_structures...
+[ ] Propose to Dan that the top level is considered as a root tag that can't have values but
+    just attributes and sub-tags.
+[x] Fix Test.test_strings: support for Unicode
+    ==> Seems to work.
+[ ] Consider being able to read text files that are not UTF-8(?)
+[ ] BUG: the report on the line no in errors is off by 1 (at least in some cases)
+[ ] Try to move Reader, Tokenizer, etc to the private part of the SDL module
+    ==> Doesn't seem to make a difference.
+[x] Factorize "each_child..." methods in Tag and refactor "children(recursive, name)" consequently
+    + invert "name" and "recursive" in "children()"
+[ ] Return copies or original arrays in Tag?
+[ ] BUG: test_tag_write_parse() does not work from the command line (ruby v1.8.7).
+[ ] Tag.to_string(): break up long lines using the backslash
+[ ] Tag.hash: the implementation is not very efficient.
+[ ] Implement reading from a URL(?) Other sources idiomatic in Ruby?
+[ ] See the XML and YAML APIs to find enhancements.
+[ ] Check the XML functionalities of Tag.
+[ ] Add tests for Tag
+[ ] Maybe some methods in the SDL module are not so useful to the general user: make them protected?
+[ ] FUTURE: xpath, ypath ==> sdlpath(?)
+[ ] FUTURE: evenemential parsing(?)
+[ ] Move Tokenizer, Reader, etc into the Parser module/class or prefix by Sdl
+[ ] FUTURE: add a way to insert a tag after or before another(?)
+[ ] FUTURE: allow some way of generating YAML(?)
+[ ] FUTURE: allow to turn a YAML structure into a SDL one(?)
+[ ] Make a Gem
+[ ] Implement the convenience method of SDL (value(), list(), map())
+[x] Move the test files to a sdl4r subdir
+[ ] 1.2: Ensure that there is a SDL.read() that returns a Tag
+[ ] 1.2: hasChild(), hasChildren(), getChildMap(), getChildStringMap() methods
+[ ] 1.3: periods in identifiers
+[ ] Create a History.txt file
+[ ] Setup the Rubyforge website
+[ ] See how both Subversion repositories can be handled (is it necessary?)

data/lib/scratchpad.rb

@@ -0,0 +1,49 @@
+if RUBY_VERSION < '1.9.0'
+  $KCODE = 'u'
+  require 'jcode'
+end
+
+#require "rubygems"
+require "flt"
+#
+#puts "DecNum=" + Flt::DecNum("12345678901234567890").to_s
+#puts "DecNum precision=" + Flt::DecNum.context.precision.to_s
+
+puts "Flt::DecNum available" if defined? Flt::DecNum
+
+require 'time'
+require File.dirname(__FILE__) + '/sdl4r/sdl'
+require File.dirname(__FILE__) + '/sdl4r/tag'
+
+#if "+09:00" =~ /(?:-([a-zA-Z]+))|(?:([\+\-]\d+)(?::(\d+))?)/
+#  puts "matches " + $1.to_s + " " + $2.to_s
+#end
+
+#if "03:00-UTC-04" =~ /^([+-]?\d+):(\d+)(?::(\d+)(?:\.(\d+))?)?(?:(?:-([a-zA-Z]+))?(?:([\+\-]\d+)(?::(\d+))?)?)?$/i
+#  puts $~
+#end
+
+root = SDL4R::Tag.new("root")
+#open("D:\\dev\\sdl\\sdl4r\\test\\test_structures.sdl") do |io|
+#  root.read(io)
+#end
+##root.read(
+##<<EOF
+##matrix {
+#	1	2	3
+#	4	5	6
+#}
+##EOF
+##)
+root.read(
+<<EOF
+toto titi=null tata=2
+EOF
+)
+#local_offset = DateTime.now.offset
+#puts "local_offset=#{local_offset * 24}"
+#puts DateTime.civil(1980,12,5,12,30,0,local_offset)
+
+root.children { |child| puts child.to_s }
+
+puts root.to_s

data/lib/sdl4r/parser.rb

@@ -0,0 +1,678 @@
+# 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	
+# the Free Software Foundation.
+#
+# This program is distributed AS IS and WITHOUT WARRANTY. OF ANY KIND,
+# INCLUDING MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU Lesser General Public License for more details.
+#
+# 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
+
+  require 'base64'
+
+  begin
+    # Try to use the Flt library, which defines DecNum
+    require "flt"
+  rescue LoadError
+    # Well, shouganai.
+  end
+
+  require File.dirname(__FILE__) + '/sdl_binary'
+  require File.dirname(__FILE__) + '/sdl_time_span'
+  require File.dirname(__FILE__) + '/sdl_parse_error'
+  require File.dirname(__FILE__) + '/tokenizer'
+
+  # The SDL parser.
+  #
+  # Authors: Daniel Leuck, Philippe Vosges
+  #
+  # In Ruby 1.8, in order to enable UTF-8 support, you may have to declare the following lines:
+  #
+  #   $KCODE = 'u'
+  #   require 'jcode'
+  #
+  # This will give you correct input and output and correct UTF-8 "general" sorting.
+  # Alternatively you can use the following options when launching the Ruby interpreter:
+  #
+  #   /path/to/ruby -Ku -rjcode
+  #
+  class Parser
+			
+    # Passed to parse_error() in order to specify an error that occured on no specific position
+    # (column).
+    UNKNOWN_POSITION = -2
+	 	
+    # Creates an SDL parser on the specified +IO+.
+    def initialize(io)
+      raise ArgumentError, "io == nil" if io.nil?
+			
+      @tokenizer = Tokenizer.new(io)
+    end
+		
+    # Parses the underlying +IO+ and returns an +Array+ of +Tag+.
+    # 
+    # ==Errors
+    # [IOError] If a problem is encountered with the IO
+    # [SdlParseError] If the document is malformed
+    def parse
+      tags = []
+			
+      while tokens = @tokenizer.read_line_tokens()
+        if tokens.last.type == :START_BLOCK
+          # tag with a block
+          tag = construct_tag(tokens[0...-1])
+          add_children(tag)
+          tags << tag
+
+        elsif tokens.first.type == :END_BLOCK
+          # we found an block end token that should have been consumed by
+          # add_children() normally
+          parse_error(
+            "No opening block ({) for close block (}).",
+            tokens.first.line,
+            tokens.first.position)
+        else
+          # tag without block
+          tags << construct_tag(tokens)
+        end
+      end
+			
+      @tokenizer.close()
+			
+      return tags
+    end
+		
+    private
+		
+    # Parses the children tags of +parent+ until an end of block is found.
+    def add_children(parent)
+      while tokens = @tokenizer.read_line_tokens()
+        if tokens.first.type == :END_BLOCK
+          return
+					
+        elsif tokens.last.type == :START_BLOCK
+          # found a child with a block
+          tag = construct_tag(tokens[0...-1]);
+          add_children(tag)
+          parent.add_child(tag)
+					
+        else
+          parent.add_child(construct_tag(tokens))
+        end
+      end
+			
+      parse_error("No close block (}).", @tokenizer.line_no, UNKNOWN_POSITION)
+    end
+		
+    # Construct a Tag (but not its children) from a string of tokens
+    # 
+    # Throws SdlParseError if some bad syntax is found.
+    def construct_tag(tokens)
+      raise ArgumentError, "tokens == nil" if tokens.nil?
+      if tokens.empty?
+        parse_error("Internal Error: empty token list", @tokenizer.line_no, UNKNOWN_POSITION)
+      end
+			
+      first_token = tokens.first
+      if first_token.literal?
+        first_token = Token.new("content")
+        tokens.insert(0, first_token)
+				
+      elsif first_token.type != :IDENTIFIER
+        expecting_but_got(
+          "IDENTIFIER",
+          "#{first_token.type} (#{first_token.text})",
+          first_token.line,
+          first_token.position)
+      end
+			
+      tag = nil
+      if tokens.size == 1
+        tag = Tag.new(first_token.text)
+				
+      else
+        values_start_index = 1
+        second_token = tokens[1]
+				
+        if second_token.type == :COLON
+          if tokens.size == 2 or tokens[2].type != :IDENTIFIER
+            parse_error(
+              "Colon (:) encountered in unexpected location.",
+              second_token.line,
+              second_token.position)
+          end
+					
+          third_token = tokens[2];
+          tag = Tag.new(third_token.text, first_token.text)
+          values_start_index = 3
+					
+        else
+          tag = Tag.new(first_token.text)
+        end
+				
+        # read values
+        attribute_start_index = add_tag_values(tag, tokens, values_start_index)
+				
+        # read attributes
+        if attribute_start_index < tokens.size
+          add_tag_attributes(tag, tokens, attribute_start_index)
+        end
+      end
+			
+      return tag
+    end
+		
+    #
+    # @return The position at the end of the value list
+    #
+    def add_tag_values(tag, tokens, start)
+      size = tokens.size()
+      i = start;
+			
+      while i < size
+        token = tokens[i]
+				
+        if token.literal?
+          # if a DATE token is followed by a TIME token combine them
+          next_token = ((i + 1) < size)? tokens[i + 1] : nil
+          if token.type == :DATE && next_token && next_token.type == :TIME
+            date = token.object_for_literal()
+            time_zone_with_zone = next_token.object_for_literal()
+						
+            if time_zone_with_zone.day != 0
+              # as there are days specified, it can't be a full precision date
+              tag.add_value(date);
+              tag.add_value(
+                SdlTimeSpan.new(
+                  time_zone_with_zone.day,
+                  time_zone_with_zone.hour,
+                  time_zone_with_zone.min,
+                  time_zone_with_zone.sec))
+							
+							
+              if time_zone_with_zone.time_zone_offset
+                parse_error("TimeSpan cannot have a timeZone", t.line, t.position)
+              end
+							
+            else
+              tag.add_value(combine(date, time_zone_with_zone))
+            end
+						
+            i += 1
+						
+          else
+            value = token.object_for_literal()
+            if value.is_a?(TimeSpanWithZone)
+              # the literal looks like a time zone
+              if value.time_zone_offset
+                expecting_but_got(
+                  "TIME SPAN",
+                  "TIME (component of date/time)",
+                  token.line,
+                  token.position)
+              end
+							
+              tag.add_value(
+                SdlTimeSpan.new(
+                  value.day,
+                  value.hour,
+                  value.min,
+                  value.sec))
+            else
+              tag.add_value(value)
+            end
+          end
+        elsif token.type == :IDENTIFIER
+          break
+        else
+          expecting_but_got(
+            "LITERAL or IDENTIFIER", token.type, token.line, token.position)
+        end
+				
+        i += 1
+      end
+			
+      return i
+    end
+		
+    #
+    # Add attributes to the given tag
+    #
+    def add_tag_attributes(tag, tokens, start)
+      i = start
+      size = tokens.size
+			
+      while i < size
+        token = tokens[i]
+        if token.type != :IDENTIFIER
+          expecting_but_got("IDENTIFIER", token.type, token.line, token.position)
+        end
+        name_or_namespace = token.text;
+				
+        if i == (size - 1)
+          expecting_but_got(
+            "\":\" or \"=\" \"LITERAL\"",
+            "END OF LINE.",
+            token.line,
+            token.position)
+        end
+				
+        i += 1
+        token = tokens[i]
+        if token.type == :COLON
+          if i == (size - 1)
+            expecting_but_got(
+              "IDENTIFIER", "END OF LINE", token.line, token.position)
+          end
+					
+          i += 1
+          token = tokens[i]
+          if token.type != :IDENTIFIER
+            expecting_but_got(
+              "IDENTIFIER", token.type, token.line, token.position)
+          end
+          name = token.text
+					
+          if i == (size - 1)
+            expecting_but_got("\"=\"", "END OF LINE", token.line, token.position)
+          end
+					
+          i += 1
+          token = tokens[i]
+          if token.type != :EQUALS
+            expecting_but_got("\"=\"", token.type, token.line, token.position)
+          end
+					
+          if i == (size - 1)
+            expecting_but_got("LITERAL", "END OF LINE", token.line, token.position)
+          end
+					
+          i += 1
+          token = tokens[i]
+          if !token.literal?
+            expecting_but_got("LITERAL", token.type, token.line, token.position)
+          end
+					
+          if token.type == :DATE and (i + 1) < size and tokens[i + 1].type == :TIME
+            date = token.get_object_for_literal()
+            time_span_with_zone = tokens[i + 1].get_object_for_literal()
+						
+            if time_span_with_zone.days != 0
+              expecting_but_got(
+                "TIME (component of date/time) in attribute value",
+                "TIME SPAN",
+                token.line,
+                token.position)
+            else
+              tag.set_attribute(
+                name, combine(date, time_span_with_zone), name_or_namespace)
+            end
+						
+            i += 1
+          else
+            value = token.object_for_literal();
+            if value.is_a?(TimeSpanWithZone)
+              time_span_with_zone = value
+							
+              if time_span_with_zone.time_zone_offset
+                expecting_but_got(
+                  "TIME SPAN",
+                  "TIME (component of date/time)",
+                  token.line,
+                  token.position)
+              end
+							
+              time_span = SdlTimeSpan.new(
+                time_span_with_zone.day,
+                time_span_with_zone.hour,
+                time_span_with_zone.min,
+                time_span_with_zone.sec)
+							
+              tag.set_attribute(name, time_span, name_or_namespace)
+            else
+              tag.set_attribute(name, value, name_or_namespace);
+            end
+          end
+        elsif token.type == :EQUALS
+          if i == (size - 1)
+            expecting_but_got("LITERAL", "END OF LINE", token.line, token.position)
+          end
+					
+          i += 1
+          token = tokens[i]
+          if !token.literal?
+            expecting_but_got("LITERAL", token.type, token.line, token.position)
+          end
+					
+          if token.type == :DATE and (i + 1) < size and tokens[i + 1].type == :TIME
+            date = token.object_for_literal()
+            time_span_with_zone = tokens[i + 1].object_for_literal()
+						
+            if time_span_with_zone.day != 0
+              expecting_but_got(
+                "TIME (component of date/time) in attribute value",
+                "TIME SPAN",
+                token.line,
+                token.position)
+            end
+            tag.set_attribute(
+              name_or_namespace, combine(date, time_span_with_zone))
+						
+            i += 1
+          else
+            value = token.object_for_literal()
+            if value.is_a?(TimeSpanWithZone)
+              time_span_with_zone = value
+              if time_span_with_zone.time_zone_offset
+                expecting_but_got(
+                  "TIME SPAN",
+                  "TIME (component of date/time)",
+                  token.line,
+                  token.position)
+              end
+							
+              time_span = SdlTimeSpan.new(
+                time_span_with_zone.day,
+                time_span_with_zone.hour,
+                time_span_with_zone.min,
+                time_span_with_zone.sec)
+              tag.set_attribute(name_or_namespace, time_span)
+            else
+              tag.set_attribute(name_or_namespace, value);
+            end			
+          end
+        else
+          expecting_but_got(
+            "\":\" or \"=\"", token.type, token.line, token.position)
+        end
+				
+        i += 1
+      end
+    end
+		
+    # Combines a simple Date with a TimeSpanWithZone to create a DateTime
+    #
+    def combine(date, time_span_with_zone)
+      time_zone_offset = time_span_with_zone.time_zone_offset
+      time_zone_offset = TimeSpanWithZone.default_time_zone_offset if time_zone_offset.nil?
+			
+      return DateTime.new(
+        date.year,
+        date.month,
+        date.day,
+        time_span_with_zone.hour,
+        time_span_with_zone.min,
+        time_span_with_zone.sec,
+        time_zone_offset)
+    end
+		
+    # An intermediate object used to store a timeSpan or the time
+    # component of a date/time instance. The types are disambiguated at a later stage.
+    #
+    # +seconds+ can have a fraction
+    # +time_zone_offset+ is a fraction of a day (equal to nil if not specified)
+    class TimeSpanWithZone
+
+      private
+
+        SECONDS_IN_DAY = 24 * 60 * 60
+
+      public
+			
+      def initialize(day, hour, minute, second, time_zone_offset)
+        @day = day
+        @hour = hour
+        @min = minute
+        @sec = second
+        @time_zone_offset = time_zone_offset
+      end
+			
+      attr_reader :day, :hour, :min, :sec, :time_zone_offset
+
+      # Returns the UTC offset as a fraction of a day on the current machine
+      def TimeSpanWithZone.default_time_zone_offset
+        return Rational(Time.now.utc_offset, SECONDS_IN_DAY)
+      end
+    end
+		
+    private
+    ############################################################################
+    ## Parsers for types
+    ############################################################################
+		
+    def Parser.parse_string(literal)
+      unless literal =~ /(^`.*`$)|(^\".*\"$)/m
+        raise ArgumentError,
+          "Malformed string <#{literal}>." +
+          "	Strings must start and end with \" or `"
+      end
+			
+      return literal[1..-2]
+    end
+		
+    def Parser.parse_character(literal)
+      unless literal =~ /(^'.*'$)/
+        raise ArgumentError,
+          "Malformed character <#{literal}>." +
+          "	Character must start and end with single quotes"
+      end
+			
+      return literal[1]
+    end
+		
+    def Parser.parse_number(literal)
+      # we use the fact that Kernel.Integer() and Kernel.Float() raise ArgumentErrors
+      if literal =~ /(.*)(L)$/i
+        return Integer($1)
+      elsif literal =~ /([^BDF]*)(BD)$/i
+        return (defined? Flt::DecNum) ? Flt::DecNum($1) : Float($1)
+      elsif literal =~ /([^BDF]*)(F|D)$/i
+        return Float($1)
+      elsif literal.count(".e") == 0
+        return Integer(literal)
+      else
+        return Float(literal)
+      end
+    end
+		
+    # Parses the given literal into a returned array
+    # [days, hours, minutes, seconds, time_zone_offset].
+    # 'days', 'hours' and 'minutes' are integers.
+    # 'seconds' and 'time_zone_offset' are rational numbers.
+    # 'days' and 'seconds' are equal to 0 if they're not specified in ((|literal|)).
+    # 'time_zone_offset' is equal to nil if not specified.
+    #
+    # ((|allowDays|)) indicates whether the specification of days is allowed
+    # in ((|literal|))
+    # ((|allowTimeZone|)) indicates whether the specification of the timeZone is
+    # allowed in ((|literal|))
+    #
+    # All components are returned disregarding the values of ((|allowDays|)) and
+    # ((|allowTimeZone|)).
+    #
+    # Raises an ArgumentError if ((|literal|)) has a bad format.
+    def Parser.parse_time_span_and_time_zone(literal, allowDays, allowTimeZone)
+      overall_sign = (literal =~ /^-/)? -1 : +1
+
+      if literal =~ /^(([+\-]?\d+)d:)/
+        if allowDays
+          days = Integer($2)
+          days_specified = true
+          time_part = literal[($1.length)..-1]
+        else
+          # detected a day specification in a pure time literal
+          raise ArgumentError, "unexpected day specification in #{literal}"
+        end
+      else
+        days = 0;
+        days_specified = false
+        time_part = literal
+      end
+			
+      # We have to parse the string ourselves because AFAIK :
+      #	- strptime() can't parse milliseconds
+      #	- strptime() can't parse the time zone custom offset (CET+02:30)
+      #	- strptime() accepts trailing chars
+      #		(e.g. "12:24-xyz@" ==> "xyz@" is obviously wrong but strptime()
+      #		 won't mind)
+      if time_part =~ /^([+-]?\d+):(\d+)(?::(\d+)(?:\.(\d+))?)?(?:(?:-([a-zA-Z]+))?(?:([\+\-]\d+)(?::(\d+))?)?)?$/i
+        hours = $1.to_i
+        minutes = $2.to_i
+        # seconds and milliseconds are implemented as one rational number
+        # unless there are no milliseconds
+        millisecond_part = ($4)? $4.ljust(3, "0") : nil
+        if millisecond_part
+          seconds = Rational(($3 + millisecond_part).to_i, 10 ** millisecond_part.length)
+        else
+          seconds = ($3)? Integer($3) : 0
+        end
+				
+        if ($5 or $6) and not allowTimeZone
+          raise ArgumentError, "unexpected time zone specification in #{literal}"
+        end
+				
+        time_zone_code = $5 # might be nil
+
+        if $6
+          zone_custom_minute_offset = $6.to_i * 60
+          if $7
+            if zone_custom_minute_offset > 0
+              zone_custom_minute_offset = zone_custom_minute_offset + $7.to_i
+            else
+              zone_custom_minute_offset = zone_custom_minute_offset - $7.to_i
+            end
+          end
+        end
+
+        time_zone_offset = get_time_zone_offset(time_zone_code, zone_custom_minute_offset)
+				
+        if not allowDays and $1 =~ /^[+-]/
+          # unexpected timeSpan syntax
+          raise ArgumentError, "unexpected sign on hours : #{literal}"
+        end
+
+        # take the sign into account
+        hours *= overall_sign if days_specified # otherwise the sign is already applied to the hours
+        minutes *= overall_sign
+        seconds *= overall_sign
+				
+        return [ days, hours, minutes, seconds, time_zone_offset ]
+				
+      else
+        raise ArgumentError, "bad time component : #{literal}"
+      end
+    end
+		
+    # Parses the given literal (String) into a returned DateTime object.
+    #
+    # Raises an ArgumentError if ((|literal|)) has a bad format.
+    def Parser.parse_date_time(literal)
+      raise ArgumentError("date literal is nil") if literal.nil?
+			
+      begin
+        parts = literal.split(" ")
+        if parts.length == 1
+          return parse_date(literal)
+        else
+          date = parse_date(parts[0]);
+          time_part = parts[1]
+					
+          days, hours, minutes, seconds, time_zone_offset =
+            parse_time_span_and_time_zone(time_part, false, true)
+					
+          return DateTime.civil(
+            date.year,
+            date.month,
+            date.day,
+            hours,
+            minutes,
+            seconds,
+            time_zone_offset)
+        end
+				
+      rescue ArgumentError
+        raise ArgumentError, "Bad date/time #{literal} : #{$!.message}"
+      end
+    end
+
+    ##
+    # Returns the time zone offset (Rational) corresponding to the provided parameters as a fraction
+    # of a day. This method adds the two offsets if they are both provided.
+    # 
+    # +time_zone_code+: can be nil
+    # +custom_minute_offset+: can be nil
+    #
+    def Parser.get_time_zone_offset(time_zone_code, custom_minute_offset)
+      return nil unless time_zone_code or custom_minute_offset
+
+      time_zone_offset = custom_minute_offset ? Rational(custom_minute_offset, 60 * 24) : 0
+      
+      return time_zone_offset unless time_zone_code
+			
+      # we have to provide some bogus year/month/day in order to parse our time zone code
+      d = DateTime.strptime("1999/01/01 #{time_zone_code}", "%Y/%m/%d %Z")
+      # the offset is a fraction of a day
+      return d.offset() + time_zone_offset
+    end
+		
+    # Parses the +literal+ into a returned Date object.
+    #
+    # Raises an ArgumentError if +literal+ has a bad format.
+    
+    def Parser.parse_date(literal)
+      # here, we're being stricter than strptime() alone as we forbid trailing chars
+      if literal =~ /^(\d+)\/(\d+)\/(\d+)$/
+        begin
+          return Date.strptime(literal, "%Y/%m/%d")
+        rescue ArgumentError
+          raise ArgumentError, "Malformed Date <#{literal}> : #{$!.message}"
+        end
+      end
+
+      raise ArgumentError, "Malformed Date <#{literal}>"
+    end
+		
+    # Returns a String that contains the binary content corresponding to ((|literal|)).
+    #
+    # ((|literal|)) : a base-64 encoded literal (e.g.
+    # "[V2hvIHdhbnRzIHRvIGxpdmUgZm9yZXZlcj8=]")
+    def Parser.parse_binary(literal)
+      clean_literal = literal[1..-2] # remove square brackets
+      return SdlBinary.decode64(clean_literal)
+    end
+		
+    # Parses +literal+ (String) into the corresponding SDLTimeSpan, which is then
+    # returned.
+    #
+    # Raises an ArgumentError if the literal is not a correct timeSpan literal.
+    def Parser.parse_time_span(literal)
+      days, hours, minutes, seconds, time_zone_offset =
+        parse_time_span_and_time_zone(literal, true, false)
+			
+      milliseconds = ((seconds - seconds.to_i) * 1000).to_i
+      seconds = seconds.to_i
+			
+      return SDLTimeSpan.new(days, hours, minutes, seconds, milliseconds)
+			
+      raise ArgumentError,
+        "Malformed time span <#{literal}>. Time spans must use the format " +
+        "(d:)hh:mm:ss(.xxx) Note: if the day component is " +
+        "included it must be suffixed with lower case \"d\""
+    end
+
+    # Close the reader and throw a SdlParseError using the format
+    # Was expecting X but got Y.
+    #
+    def expecting_but_got(expecting, got, line, position)
+      @tokenizer.expecting_but_got(expecting, got, line, position)
+    end
+  end
+end