sdl4r 0.9.1 → 0.9.2

data/README

@@ -1,3 +1,298 @@
-== sdl4r
+== SDL (Simple Declarative Language)
 
+SDL 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 <tt>values.sdl</tt>, the values can be read
+using the following code (ignoring exceptions):
+
+  root = Tag.new("root").read(Pathname.new("values.sdl"))
+  size = root.child("size").value
+  smoker = root.child("smoker").value
+
+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
+<tt>values.sdl</tt> 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 <tt>(namespace:)key=value</tt> 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 (_),
+dashes (-) and periods (.).
+
+== Anonymous Tags
+
+SDL also supports anonymous tags which are assigned the name "content".
+An anonymous 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.
+
+== String literals
+
+There are two ways to write String literals.
+
+=== 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.
+
+=== 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
+
+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
+  ]
+
+== Date and Time Literals
+
+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.
+
+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
+
+== Literal Types
+
+SDL 1.0 has thirteen literal types (parenthesis indicate optional components)
+
+1. string (unicode) - examples: <tt>"hello"</tt> or <tt>`aloha`</tt>
+2. character (unicode) - example: <tt>'/'</tt>
+   Note: \uXXXX style unicode escapes are not supported (or needed because sdl files are UTF8)
+3. integer (32 bits signed) - example: <tt>123</tt>
+4. long integer (64 bits signed) - examples: <tt>123L</tt> or <tt>123l</tt>
+5. float (32 bits signed) - examples <tt>123.43F</tt> <tt>123.43f</tt>
+6. double float (64 bits signed) - example: <tt>123.43</tt> or <tt>123.43d</tt> or <tt>123.43D</tt>
+7. decimal (128+ bits signed) - example: <tt>123.44BD</tt> or <tt>123.44bd</tt>
+8. boolean - examples: <tt>true</tt> or <tt>false</tt> or <tt>on</tt> or <tt>off</tt>
+9. date yyyy/mm/dd - example <tt>2005/12/05</tt>
+10. date time yyyy/mm/dd hh:mm(:ss)(.xxx)(-ZONE)
+    example - <tt>2005/12/05 05:21:23.532-JST</tt>
+    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] example - <tt>[sdf789GSfsb2+3324sf2]</tt>
+13. <tt>null</tt>
+
+
+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)
+
+These types are designed to be portable across Java, .NET, and other popular platforms.
+
+== SDL Comments
+
+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.
+
+
+== Example
+
+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)
+
+     root = SDL4R.read(Pathname.new("myfile.sdl"))
+     daughter = root.child("daughter", true) // recursive search
+     location = daughter.attribute("location")
+
+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.
+
+== Ruby and SDL types
+
+The following list gives what types are used in Ruby in order to represent SDL types.
+
+*SDL*:: *Ruby*
+unicode string:: String
+unicode character:: single-character String
+integer (32 bits signed):: Integer (Fixnum or Bignum)
+long integer (64 bits signed):: Integer (Fixnum or Bignum)
+float (32 bits signed):: Float
+double float (64 bits signed):: Float
+decimal (128+ bits signed):: Flt::DecNum (if installed; see http://flt.rubyforge.org/), core numeric classes otherwise
+boolean:: true (TrueClass) and false (FalseClass)
+date (day):: Date
+date time:: DateTime
+time span:: SdlTimeSpan
+binary:: SdlBinary (to avoid confusion with simple strings)
+null:: nil (NilClass)
+
+TO FIX: the handling of floating numbers in Ruby being different from the Java world, the behavior
+of SDL4R at limits might not be perfect for the time being.

data/Rakefile

@@ -9,14 +9,14 @@ 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.version = '0.9.2'
   s.requirements << 'none'
   s.require_path = 'lib'
-  s.author = 'Philippe Vosges'
+  s.authors = ['Philippe Vosges', 'Daniel Leuck' ]
   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.files = FileList['lib/sdl4r/**/*.rb', 'bin/*', '[A-Z]*', 'test/**/*', 'doc/*'].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,
@@ -33,7 +33,10 @@ Rake::GemPackageTask.new(spec) do |pkg|
 end
 
 Rake::RDocTask.new do |rd|
-  rd.rdoc_files.include("lib/**/*.rb")
+  files = ['README', 'LICENSE', 'CHANGELOG',
+    'lib/sdl4r/**/*.rb', 'doc/**/*.rdoc', 'test/*.rb']
+  rd.main = 'README'
+  rd.rdoc_files.include(files)
   rd.rdoc_dir = "doc"
   rd.title = "Simple Declarative Language for Ruby"
 end

data/TODO.txt

@@ -27,16 +27,17 @@
     [x] Date + time test
     [x] Time zone tests
     [x] Number literal tests
-    [ ] Strings literals (especially with line continuations)
-    [ ] Sub tags tests
+    [x] Strings literals (especially with line continuations)
+    [x] 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] Use YARD in order to generate documentation ?
+    ==> alternatively, I tried to generate some RDoc templates but none worked in Rake...
+[x] 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
@@ -71,47 +72,58 @@
 [ ] 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
+[ ] FUTURE: 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] 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(?)
+[ ] FUTURE: 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
+[x] Try to move Reader, Tokenizer, etc to the private part of the SDL module
     ==> Doesn't seem to make a difference.
+    ==> Moved to the Parser namespace.
 [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).
+[A] BUG: test_tag_write_parse() does not work from the command line (ruby v1.8.7).
+    ==> This is normal provided that flt was not installed.
 [ ] 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?
+[x] Implement reading from a URL(?) Other sources idiomatic in Ruby?
+    ==> Strings, URIs, Pathnames, IOs
 [ ] 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
+[x] Move Tokenizer, Reader, etc into the Parser module/class or prefix by Sdl
+    ==> moved to sdl4r/parser
 [ ] 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] Make a Gem
+[x] 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?)
+[x] 1.2: Ensure that there is a SDL.read() that returns a Tag
+[x] 1.2: hasChild(), hasChildren() methods
+[x] 1.2: getChildMap(), getChildStringMap() methods
+[x] 1.3: periods in identifiers
+[A] Create a History.txt file ==> See CHANGELOG
+[x] Setup the Rubyforge website
+[A] See how both Subversion repositories can be handled (is it necessary?)
+    ==> No need for the Rubyforge project anymore, it seems (we use Rubygem and gemcutter directly)
+[x] Add info to README
+[x] Add LICENSE & CHANGELOG files
+[x] State in the README that without Flt, all the tests can't run.
+    ==> it's stated explicitely in the test
+[w] Make it so that each test appears separately in test.rb (if possible)
+[ ] Have the use of Flt be optional.
+[ ] Turn Rationals to Floats in coerc_or_fail()?

data/doc/created.rid

@@ -0,0 +1 @@
+Sat, 31 Jul 2010 01:26:33 +0900

data/doc/fr_class_index.html

@@ -0,0 +1,36 @@
+
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+
+    Classes
+
+  -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Classes</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <link rel="stylesheet" href="rdoc-style.css" type="text/css" />
+  <base target="docwin" />
+</head>
+<body>
+<div id="index">
+  <h1 class="section-bar">Classes</h1>
+  <div id="index-entries">
+    <a href="classes/SDL4R.html">SDL4R</a><br />
+    <a href="classes/SDL4R/Parser.html">SDL4R::Parser</a><br />
+    <a href="classes/SDL4R/Parser/Reader.html">SDL4R::Parser::Reader</a><br />
+    <a href="classes/SDL4R/Parser/TimeSpanWithZone.html">SDL4R::Parser::TimeSpanWithZone</a><br />
+    <a href="classes/SDL4R/Parser/Token.html">SDL4R::Parser::Token</a><br />
+    <a href="classes/SDL4R/Parser/Tokenizer.html">SDL4R::Parser::Tokenizer</a><br />
+    <a href="classes/SDL4R/SdlBinary.html">SDL4R::SdlBinary</a><br />
+    <a href="classes/SDL4R/SdlParseError.html">SDL4R::SdlParseError</a><br />
+    <a href="classes/SDL4R/SdlTimeSpan.html">SDL4R::SdlTimeSpan</a><br />
+    <a href="classes/SDL4R/Tag.html">SDL4R::Tag</a><br />
+  </div>
+</div>
+</body>
+</html>