sdl.rb in sdl4r-0.9.3

- old
+ new

@@ -1,5 +1,6 @@
+#--
 # 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  
@@ -10,28 +11,20 @@
 # 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.
+#++
 
-
 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)
   
   MAX_INTEGER_64 = 2**63 - 1
@@ -40,12 +33,11 @@
   BASE64_WRAP_LINE_LENGTH = 72
 
   # 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)
   #
   def self.format(o, add_quotes = true, line_prefix = "", indent = "\t")
     if o.is_a?(String)
@@ -128,22 +120,25 @@
     else
       return o.to_s
     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
   end
   
   # 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
   #
   def self.validate_identifier(identifier)
     if identifier.nil? or identifier.empty?
@@ -171,23 +166,51 @@
         end
       end
     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
   end
 
   # Parse the string of values and return a list.  The string is handled
   # as if it is the values portion of an SDL tag.
 	#
 	# Example
 	#
-	#   array = SDL4R.to_values("1 true 12:24:01")
+	#   array = SDL4R.to_value_array("1 true 12:24:01")
 	#
 	# Will return an int, a boolean, and a time span.
 	#
   def self.to_value_array(s)
     raise ArgumentError, "'s' cannot be null" if s.nil?
@@ -199,10 +222,10 @@
 	#
 	# Example
 	# 
 	#   hash = SDL4R.to_attribute_hash("value=1 debugging=on time=12:24:01");
 	#
-	# Will return a map containing value=1, debugging=true, and time=12:24:01
+	#   # { "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?
     return read("atts " + s).child.attributes
   end
\ No newline at end of file