sdl4r 0.9.9 → 0.9.11

data/lib/sdl4r/relative_timezone.rb

@@ -0,0 +1,156 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+
+#--
+#
+# 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 'sdl4r/tz_abbreviation_db'
+
+  # Represents a Timezone which is distant from a standard timezone by a fixed offset.
+  #
+  class RelativeTimezone < TZInfo::Timezone
+
+    # Returns a timezone by its identifier (e.g. "Europe/London",
+    # "America/Chicago" or "UTC").
+    #
+    # Supports relative timezones in the following formats: "UTC+2", "GMT+01:30",
+    # "Europe/Paris-10:00".
+    #
+    # Raises InvalidTimezoneIdentifier if the timezone couldn't be found.
+    #
+    def self.get(identifier)
+      base_identifier, offset_text, offset = RelativeTimezone::parse_relative_identifier(identifier)
+
+      tz = TZAbbreviationDB.get_timezone(base_identifier)
+
+      offset ?
+        RelativeTimezone.new(base_identifier + offset_text.to_s, offset_text, offset, tz) :
+        tz
+    end
+
+    # Returns a proxy for the Timezone with the given identifier. The proxy
+    # will cause the real timezone to be loaded when an attempt is made to
+    # find a period or convert a time. get_proxy will not validate the
+    # identifier. If an invalid identifier is specified, no exception will be
+    # raised until the proxy is used.
+    #
+    # Supports relative timezones in the following format: "GMT+01:30", "CET-10:00".
+    #
+    def self.get_proxy(identifier)
+      base_identifier, offset_text, offset = RelativeTimezone::parse_relative_identifier(identifier)
+
+      proxy = TZAbbreviationDB.get_timezone_proxy(base_identifier)
+
+      offset ?
+        RelativeTimezone.new(base_identifier + offset_text.to_s, offset_text, offset, proxy) :
+        proxy
+    end
+
+    # Parses the specified identifier of the shape "GMT" or "CET+7" or "Asia/Shanghai-03:30" and
+    # returns an array containing respectively the simple zone identifier (e.g. "CET",
+    # "Asia/Shanghai"), the offset part (e.g. "-6", "+08:30") and the offset (seconds).
+    #
+    def self.parse_relative_identifier(identifier) # :nodoc:
+      offset = nil
+
+      if identifier =~ /^([a-zA-Z0-9\/_]+)(([+\-])(\d+)(?::(\d+))?)?$/
+        identifier, offset_text, sign_part, hour_part, minute_part = $1, $2, $3, $4, $5
+
+        if sign_part # relative offset
+          offset = 0
+          offset += 3600 * hour_part.to_i if hour_part
+          offset += 60 * minute_part.to_i if minute_part
+          offset = -offset if sign_part == '-'
+
+          offset = nil if offset == 0
+
+          # We regenerate/normalize the offset text "+7:3" ==> "+07:03".
+          offset_text = ""
+          if offset
+            offset_text << (offset >= 0 ? '+' : '-')
+
+            hours = offset.abs / 3600
+            minutes = (offset.abs % 3600) / 60
+            if minutes == 0
+              offset_text << hours.to_s
+            else
+              offset_text << sprintf("%02d:%02d", hours, minutes)
+            end
+          end
+        end
+      end
+
+      return identifier, offset_text, offset
+    end
+
+    def self.new(identifier, offset_text, offset, base_timezone)
+      o = super()
+      o.send(:_initialize, identifier, offset_text, offset, base_timezone)
+      o
+    end
+    
+    # _base_timezone_:: timezone on which this RelativeTimezone is based
+    # _offset_:: the fixed offset (seconds)
+    #
+    def _initialize(identifier, offset_text, offset, base_timezone) # :nodoc:
+      raise ArgumentError, 'identifier' if identifier.nil?
+      raise ArgumentError, 'offset' if offset.nil?
+      raise ArgumentError, 'base_timezone' if base_timezone.nil?
+
+      @identifier = identifier
+      @base_timezone =
+        base_timezone.is_a?(String) ? TZInfo::Timezone.get(base_timezone) : base_timezone
+      @relative_offset_text = offset_text
+      @relative_offset = offset
+    end
+    protected :_initialize
+    
+    attr_reader :identifier, :relative_offset
+
+    def period_for_utc(utc)
+      period = @base_timezone.period_for_utc(utc)
+
+      translated_offset =
+        period.offset ?
+          TZInfo::TimezoneOffsetInfo.new(
+            period.offset.utc_offset + @relative_offset,
+            period.offset.std_offset,
+            (period.offset.abbreviation.to_s + @relative_offset_text).to_sym) :
+          nil
+
+      return TZInfo::TimezonePeriod.new(nil, nil, translated_offset)
+    end
+
+    def periods_for_local(local)
+      periods = @base_timezone.periods_for_local(local)
+
+      return periods.collect { |period|
+        translated_offset =
+          period.offset ?
+            TZInfo::TimezoneOffsetInfo.new(
+              period.offset.utc_offset + @relative_offset,
+              period.offset.std_offset,
+              (period.offset.abbreviation.to_s + @relative_offset_text).to_sym) :
+            nil
+        TZInfo::TimezonePeriod.new(nil, nil, translated_offset)
+      }
+    end
+  end
+end

data/lib/sdl4r/sdl4r.rb

@@ -22,7 +22,12 @@ require 'base64'
 require 'bigdecimal'
 require 'date'
 
-# Gathers utility methods.
+require 'sdl4r/sdl4r_version'
+require 'sdl4r/serializer'
+
+# Utility methods and general constants for SDL4R.
+#
+# For more information about SDL4R, see the {link README file}[../../files/README.html]
 # 
 module SDL4R
   
@@ -47,10 +52,10 @@ module SDL4R
   def self.format(o, add_quotes = true, line_prefix = "", indent = "\t")
     case o
     when String
-      return format_string(o)
+      return format_string(o, add_quotes)
       
     when Symbol
-      return format_string(o.to_s)
+      return format_string(o.to_s, add_quotes)
       
     when Bignum
       return o.to_s + "BD"
@@ -99,46 +104,77 @@ module SDL4R
     # Below, we use "#{o.year}" instead of "%Y" because "%Y" always emit 4 chars at least even if
     # the date is before 1000.
     when DateTime, Time
-      milliseconds = get_datetime_milliseconds(o)
-
-      if milliseconds == 0
-        zone_part = o.strftime("%:z")
-        if zone_part and zone_part != "+00:00"
-          return o.strftime("#{o.year}/%m/%d %H:%M:%S#{zone_part}")
-        else
-          return o.strftime("#{o.year}/%m/%d %H:%M:%S")
-        end
-      else
-        ms_part = milliseconds.to_s.ljust(3, '0')
-        if zone_part and zone_part != "+00:00"
-          return o.strftime("#{o.year}/%m/%d %H:%M:%S." + ms_part + zone_part)
-        else
-          return o.strftime("#{o.year}/%m/%d %H:%M:%S." + ms_part)
-        end
-      end
-
+      return format_time(o)
+      
     when Date
-      return o.strftime("#{o.year}/%m/%d")
+      return "#{o.strftime("#{o.year}/%m/%d")}"
       
     else
       return o.to_s
     end
   end
 
-  # Creates and returns the object representing a datetime (DateTime in the default implementation).
-  # This method is, by default, called by the Parser class.
-  # It could be overriden as follows in order to get Time instances from all the SDL4R parsers.
+  def self.format_time(time)
+      s = "" # important as strftime() tends to return a US-ASCII string
+      s << time.strftime("#{time.year}/%m/%d %H:%M:%S") # %Y tends to return "88" for 1988 in many implementations
+
+      milliseconds = get_datetime_milliseconds(time)
+      s << sprintf(".%03d", milliseconds) if milliseconds != 0
+
+      zone_part = time.strftime("%z") # >> "+0130"  --  "%:z" is not supported by every interpreter
+      unless zone_part.nil? or zone_part.empty? or zone_part == "+0000" or not zone_part =~ /[+-]\d+/
+        zone_part.insert(3, ":")
+        s << "-GMT" << zone_part
+      end
+
+      return s
+  end
+
+  @@use_datetime = true
+
+  # Indicates whether DateTime is used to represent times. If false, Time is used instead. True by
+  # default.
+  def self.use_datetime?
+    @@use_datetime
+  end
+
+  # Sets whether DateTime should be used for representing times at parsing.
+  # If set to false, Time will be used instead (true by default).
+  #
+  def self.use_datetime=(bool)
+    @@use_datetime = bool
+  end
+
+  # Creates and returns the object representing a time (DateTime by default).
+  # This method is called by the Parser class.
   #
-  #   module SDL4R
-  #     def self.new_date_time(year, month, day, hour, min, sec, time_zone_offset)
-  #       Time.utc(year, month, day, hour, min, sec)
-  #     end
-  #   end
+  # See #use_datetime=
   #
-  def self.new_date_time(year, month, day, hour, min, sec, time_zone_offset)
-    DateTime.civil(year, month, day, hour, min, sec, time_zone_offset)
+  def self.new_time(year, month, day, hour, min, sec, msec, timezone_code)
+    if @@use_datetime
+      timezone_code ||= Time.now.zone
+      sec_msec = (msec == 0)? sec : Rational(sec * 1000 + msec, 1000)
+      return DateTime.civil(year, month, day, hour, min, sec_msec, timezone_code)
+
+    else
+      if timezone_code =~ /\A(?:GMT|UTC)([+-]\d+:\d+)\Z/
+        timezone_code = $1
+      end
+      timezone_offset = Time.zone_offset(timezone_code, year) if timezone_code
+      if timezone_offset
+        timezone_offset_hour = timezone_offset.abs / 3600
+        timezone_offset_min = (timezone_offset.abs % 3600) / 60
+        return Time.xmlschema(
+          sprintf(
+            "%d-%02d-%02dT%02d:%02d:%02d.%03d#{timezone_offset >= 0 ? '+' : '-'}%02d:%02d",
+            year, month, day, hour, min, sec, msec, timezone_offset_hour, timezone_offset_min))
+
+      else
+        return Time.local(year, month, day, hour, min, sec, msec * 1000)
+      end
+    end
   end
-    
+  
   # Coerce the type to a standard SDL type or raises an ArgumentError.
   #
   # Returns +o+ if of the following classes:
@@ -175,7 +211,7 @@ module SDL4R
     raise ArgumentError, "#{o.class.name} is not coercible to an SDL type"
   end
 
-  # Indicates whether 'o' is coercible to a SDL litteral type.
+  # Indicates whether 'o' is coercible to a SDL literal type.
   # See #coerce_or_fail
   #
   def self.is_coercible?(o)
@@ -187,6 +223,42 @@ module SDL4R
       false
     end
   end
+
+  # We disable the warnings as Ruby 1.8.7 prints one for the tested regex. We don't need this
+  # warning as we are precisely testing whether this regular expression works.
+  # Unfortunately, creating the regex with Regexp.new() doesn't help: we would have liked getting a
+  # RegexpError.
+  begin
+    old_verbose, $VERBOSE = $VERBOSE, nil
+    @@UNICODE_REGEXP_SUPPORTED = ('é' =~ Regexp.new("\\p{Alnum}")) != nil
+  ensure
+    $VERBOSE = old_verbose
+  end
+
+  def self.supports_unicode_identifiers?
+    @@UNICODE_REGEXP_SUPPORTED
+  end
+
+  IDENTIFIER_START_CLASS = @@UNICODE_REGEXP_SUPPORTED ? '[\\p{Alpha}_]' : '[a-zA-Z_]'
+
+  # Matches the first character of a valid SDL identifier.
+  IDENTIFIER_START_REGEXP =
+    @@UNICODE_REGEXP_SUPPORTED ? /\A#{IDENTIFIER_START_CLASS}/u : /\A#{IDENTIFIER_START_CLASS}/
+
+  IDENTIFIER_PART_CLASS =
+    @@UNICODE_REGEXP_SUPPORTED ? '[\\p{Alnum}_\\-\\.$]' : '[\\w\\-\\.$]'
+
+  # Matches characters of a valid SDL identifier after the first one.
+  # Works with one character long strings.
+  IDENTIFIER_PART_REGEXP =
+    @@UNICODE_REGEXP_SUPPORTED ?
+      /\A#{IDENTIFIER_PART_CLASS}\Z/u :
+      /\A#{IDENTIFIER_PART_CLASS}\Z/
+
+  # Matches a valid SDL identifier (start to end).
+  IDENTIFIER_REGEXP = @@UNICODE_REGEXP_SUPPORTED ?
+    /\A#{IDENTIFIER_START_CLASS}#{IDENTIFIER_PART_CLASS}*\Z/u :
+    /\A#{IDENTIFIER_START_CLASS}#{IDENTIFIER_PART_CLASS}*\Z/
   
   # Validates an SDL identifier String.  SDL Identifiers must start with a
   # Unicode letter or underscore (_) and contain only unicode letters,
@@ -203,17 +275,17 @@ module SDL4R
     end
 
     # in Java, was if(!Character.isJavaIdentifierStart(identifier.charAt(0)))
-    unless identifier =~ /^[a-zA-Z_]/
+    unless identifier =~ IDENTIFIER_START_REGEXP
       raise ArgumentError,
-        "'" + identifier[0..0] +
+        "'" + identifier[/^./] +
         "' is not a legal first character for an SDL identifier. " +
         "SDL Identifiers must start with a unicode letter or " +
-        "an underscore (_)."
+        "an underscore (_). (identifier=<#{identifier}>)"
     end
-    
-    unless identifier.length == 1 or identifier =~ /^[a-zA-Z_][a-zA-Z_0-9\-\.\$]*$/
+
+    unless identifier.length == 1 or identifier =~ IDENTIFIER_REGEXP
       for i in 1..identifier.length
-        unless identifier[i..i] =~ /^[a-zA-Z_0-9\-\.\$]$/
+        unless identifier[i..i] =~ IDENTIFIER_PART_REGEXP
           raise ArgumentError,
             "'" + identifier[i..i] + 
             "' is not a legal character for an SDL identifier. " +
@@ -225,16 +297,23 @@ module SDL4R
     end
   end
 
+  # Returns whether the specified SDL identifier is valid.
+  # See SDL4R#validate_identifier.
+  #
+  def self.valid_identifier?(identifier)
+    !IDENTIFIER_REGEXP.match(identifier).nil?
+  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
+  #   root = SDL4R::read(<<EOS
   #   planets {
   #     earth area_km2=510900000
   #     mars
   #   }
-  #   EOF
+  #   EOS
   #   )
   #
   #   root = SDL4R::read(Pathname.new("my_dir/my_file.sdl"))
@@ -288,11 +367,74 @@ module SDL4R
     return read("atts " + s).child.attributes
   end
 
+  # Loads the specified 'input' and deserializes into the returned object.
+  #
+  # _input_:: an input as accepted by SDL4R#read or a Tag.
+  #
+  # example:
+  #
+  #   top = SDL4R::load(<<EOS
+  #   food name="chili con carne" {
+  #     ingredient "beans"
+  #     ingredient "chili"
+  #     ingredient "cheese"
+  #     note 8.9
+  #   }
+  #   EOS
+  #   )
+  #
+  #   top.food.name # => "chili con carne"
+  #   top.food.ingredient # => ["beans", "chili", "cheese"]
+  #   top.food.note # => 8.9
+  #
+  def self.load(input)
+    if input.is_a? Tag
+      tag = input
+    else
+      tag = read(input)
+    end
+
+    return Serializer.new.deserialize(tag)
+  end
+
+  # Dumps the specified object to a given output or returns the corresponding SDL string if output
+  # is +nil+.
+  #
+  # _o_:: the root object (equivalent to a root SDL tag, therefore it's values and attributes are
+  #   NOT dumped. See below for an example.)
+  # _output_:: an output as accepted by Tag#write or +nil+ in order to convert to a SDL string.
+  #
+  # example:
+  #
+  #   food = OpenStruct.new(:name => 'french fries', 'comment' => 'eat with bier')
+  #   food.fan = OpenStruct.new(:firstname => 'Homer')
+  #
+  #   puts SDL4R::dump(:food => food)
+  #
+  # gives us
+  #
+  #   food comment="eat with bier" name="french fries" {
+  #     fan firstname="Homer"
+  #   }
+  #
+  def self.dump(o, output = nil)
+    tag = Serializer.new.serialize(o)
+
+    if output.nil?
+      tag.children_to_string
+    else
+      tag.write(output)
+      output
+    end
+  end
+
   # The following is a not so readable way to implement module private methods in Ruby: we add
   # private methods to the singleton class of +self+ i.e. the SDL4R module.
   class << self
     private
 
+    SECONDS_IN_DAY = 24 * 3600 # :nodoc:
+
     # Returns the specified string 's' formatted as a SDL string.
     # See SDL4R#format.
     #
@@ -384,12 +526,12 @@ module SDL4R
     # least, some revisions of Ruby 1.9.
     #
     def get_datetime_milliseconds(datetime)
-      if defined?(datetime.usec)
-        return (datetime.usec / 1000).round
+      if datetime.respond_to?(:usec)
+        return (datetime.usec / 1000.0).round
       else
         # Here don't believe that we could use '%3N' to get the milliseconds directly: the "3" is
         # ignored for DateTime.strftime() in Ruby 1.8.
-        nanoseconds = Integer(datetime.strftime("%N"))
+        nanoseconds = datetime.strftime("%N").to_i
         return (nanoseconds / 1000000).round
       end
     end