parsanol 3.0.0

data/example/iso-8601/basic.rb.md

@@ -0,0 +1,149 @@
+# ISO 8601 Date/Time Parser - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/iso-8601
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Calendar Date Rule
+
+Standard YYYY-MM-DD format with optional separators:
+
+```ruby
+rule(:calendar_date) {
+  year >> date_separator >> month >> date_separator >> day
+}
+
+rule(:date_separator) { str('-').maybe }
+```
+
+The `.maybe` on the separator allows both `2024-01-15` and `20240115`.
+
+### Week Date Rule
+
+Year, week number, and weekday:
+
+```ruby
+rule(:week_date) {
+  year >> str('-W') >>
+  match('[0-9]').repeat(2, 2).as(:week) >>
+  str('-') >>
+  match('[1-7]').as(:weekday)
+}
+```
+
+Weekday is 1-7 (Monday to Sunday), per ISO 8601.
+
+### Ordinal Date Rule
+
+Year and day-of-year:
+
+```ruby
+rule(:ordinal_date) {
+  year >> str('-') >>
+  match('[0-9]').repeat(3, 3).as(:ordinal_day)
+}
+```
+
+Three-digit day number (001-366).
+
+### Time Rule
+
+Hours, minutes, seconds with optional fraction:
+
+```ruby
+rule(:time_basic) {
+  hour >> time_separator >> minute >> time_separator >> second >> fraction.maybe
+}
+
+rule(:fraction) { str('.') >> match('[0-9]').repeat(1).as(:fraction) }
+```
+
+Fraction supports arbitrary precision subseconds.
+
+### Timezone Rules
+
+UTC designator or offset:
+
+```ruby
+rule(:utc_designator) { str('Z').as(:utc) }
+
+rule(:tz_offset) {
+  tz_sign >> tz_hour >> tz_minute
+}
+
+rule(:timezone) { utc_designator | tz_offset | str('') }
+```
+
+Empty string allows local time without timezone.
+
+### DateTime Combination
+
+Date and time joined by `T`:
+
+```ruby
+rule(:datetime) {
+  (calendar_date | week_date | ordinal_date) >>
+  (str('T') | str(' ')) >>
+  time
+}
+```
+
+Space separator is allowed by some implementations.
+
+### Duration Rule
+
+P[nY][nM][nD][T[nH][nM][nS]] format:
+
+```ruby
+rule(:duration) {
+  str('P') >>
+  (
+    (match('[0-9]').repeat(1).as(:years) >> str('Y')).maybe >>
+    (match('[0-9]').repeat(1).as(:months) >> str('M')).maybe >>
+    (match('[0-9]').repeat(1).as(:days) >> str('D')).maybe >>
+    (str('T') >> (...)).maybe
+  )
+}
+```
+
+Every component is optional; at least one is required.
+
+## Output Types
+
+```ruby
+# Calendar date
+IsoDate.new("2024", "01", "15", nil, nil, nil)
+# to_s => "2024-01-15"
+
+# Time with timezone
+IsoTime.new("10", "30", "00", nil, "Z", nil, nil)
+# to_s => "10:30:00Z"
+
+# Duration
+IsoDuration.new("1", "2", "3", "4", "5", "6")
+# to_s => "P1Y2M3DT4H5M6S"
+# to_seconds => 36993906
+```
+
+## Design Decisions
+
+### Why Separate Date/Time/Duration Classes?
+
+Each ISO 8601 type has distinct fields and semantics. Separate classes provide type safety and appropriate methods.
+
+### Why Maybe on Separators?
+
+ISO 8601 allows both basic (no separators) and extended (with separators) formats. The grammar handles both.
+
+### Why Empty String in Timezone Alternative?
+
+Local time without timezone is valid ISO 8601. The empty string matches when neither Z nor offset is present.
+
+### Why to_seconds for Duration?
+
+Duration calculations often need total seconds. The method approximates using average month/year lengths.

data/example/json/basic.rb

@@ -0,0 +1,128 @@
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+#
+# MIT License - (c) 2011 John Mettraux
+#
+
+require 'rubygems'
+require 'parsanol/parslet' # gem install parslet
+
+
+module MyJson
+
+  class Parser < Parsanol::Parser
+
+    rule(:spaces) { match('\s').repeat(1) }
+    rule(:spaces?) { spaces.maybe }
+
+    rule(:comma) { spaces? >> str(',') >> spaces? }
+    rule(:digit) { match('[0-9]') }
+
+    rule(:number) {
+      (
+        str('-').maybe >> (
+          str('0') | (match('[1-9]') >> digit.repeat)
+        ) >> (
+          str('.') >> digit.repeat(1)
+        ).maybe >> (
+          match('[eE]') >> (str('+') | str('-')).maybe >> digit.repeat(1)
+        ).maybe
+      ).as(:number)
+    }
+
+    rule(:string) {
+      str('"') >> (
+        str('\\') >> any | str('"').absent? >> any
+      ).repeat.as(:string) >> str('"')
+    }
+
+    rule(:array) {
+      str('[') >> spaces? >>
+      (value >> (comma >> value).repeat).maybe.as(:array) >>
+      spaces? >> str(']')
+    }
+
+    rule(:object) {
+      str('{') >> spaces? >>
+      (entry >> (comma >> entry).repeat).maybe.as(:object) >>
+      spaces? >> str('}')
+    }
+
+    rule(:value) {
+      string | number |
+      object | array |
+      str('true').as(:true) | str('false').as(:false) |
+      str('null').as(:null)
+    }
+
+    rule(:entry) {
+      (
+         string.as(:key) >> spaces? >>
+         str(':') >> spaces? >>
+         value.as(:val)
+      ).as(:entry)
+    }
+
+    rule(:attribute) { (entry | value).as(:attribute) }
+
+    rule(:top) { spaces? >> value >> spaces? }
+
+    root(:top)
+  end
+
+  class Transformer < Parsanol::Transform
+
+    class Entry < Struct.new(:key, :val); end
+
+    rule(:array => subtree(:ar)) {
+      ar.is_a?(Array) ? ar : [ ar ]
+    }
+    rule(:object => subtree(:ob)) {
+      (ob.is_a?(Array) ? ob : [ ob ]).inject({}) { |h, e| h[e.key] = e.val; h }
+    }
+
+    rule(:entry => { :key => simple(:ke), :val => simple(:va) }) {
+      Entry.new(ke, va)
+    }
+
+    rule(:string => simple(:st)) {
+      st.to_s
+    }
+    rule(:number => simple(:nb)) {
+      nb.match(/[eE\.]/) ? Float(nb) : Integer(nb)
+    }
+
+    rule(:null => simple(:nu)) { nil }
+    rule(:true => simple(:tr)) { true }
+    rule(:false => simple(:fa)) { false }
+  end
+
+  def self.parse(s)
+
+    parser = Parser.new
+    transformer = Transformer.new
+
+    tree = parser.parse(s)
+    puts; p tree; puts
+    out = transformer.apply(tree)
+
+    out
+  end
+end
+
+
+s = %{
+  [ 1, 2, 3, null,
+    "asdfasdf asdfds", { "a": -1.2 }, { "b": true, "c": false },
+    0.1e24, true, false, [ 1 ] ]
+}
+
+out = MyJson.parse(s)
+
+p out; puts
+
+out == [
+  1, 2, 3, nil,
+  "asdfasdf asdfds", { "a" => -1.2 }, { "b" => true, "c" => false },
+  0.1e24, true, false, [ 1 ]
+] || raise("MyJson is a failure")

data/example/json/basic.rb.md

@@ -0,0 +1,121 @@
+# JSON Parser - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/json
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Number Rule Definition
+
+Numbers in JSON can be integers, floats, or scientific notation:
+
+```ruby
+rule(:number) {
+  (
+    str('-').maybe >> (
+      str('0') | (match('[1-9]') >> digit.repeat)
+    ) >> (
+      str('.') >> digit.repeat(1)
+    ).maybe >> (
+      match('[eE]') >> (str('+') | str('-')).maybe >> digit.repeat(1)
+    ).maybe
+  ).as(:number)
+}
+```
+
+The rule handles negative numbers, decimal points, and exponent notation like `1e24`.
+
+### String Rule Definition
+
+Strings support escape sequences with backslash:
+
+```ruby
+rule(:string) {
+  str('"') >> (
+    str('\\') >> any | str('"').absent? >> any
+  ).repeat.as(:string) >> str('"')
+}
+```
+
+The pattern `str('\\') >> any` matches any escaped character; `str('"').absent? >> any` matches non-quote characters.
+
+### Array and Object Rules
+
+Arrays and objects use recursive definitions:
+
+```ruby
+rule(:array) {
+  str('[') >> spaces? >>
+  (value >> (comma >> value).repeat).maybe.as(:array) >>
+  spaces? >> str(']')
+}
+
+rule(:object) {
+  str('{') >> spaces? >>
+  (entry >> (comma >> entry).repeat).maybe.as(:object) >>
+  spaces? >> str('}')
+}
+```
+
+Both support nested structures through the recursive `value` rule.
+
+### Value Rule
+
+The value rule combines all JSON types:
+
+```ruby
+rule(:value) {
+  string | number |
+  object | array |
+  str('true').as(:true) | str('false').as(:false) |
+  str('null').as(:null)
+}
+```
+
+Order matters: try specific types before generic ones.
+
+### Transform Rules
+
+The transformer converts parse tree to Ruby objects:
+
+```ruby
+rule(:string => simple(:st)) {
+  st.to_s
+}
+rule(:number => simple(:nb)) {
+  nb.match(/[eE\.]/) ? Float(nb) : Integer(nb)
+}
+rule(:null => simple(:nu)) { nil }
+rule(:true => simple(:tr)) { true }
+rule(:false => simple(:fa)) { false }
+```
+
+Pattern matching on tree labels produces typed Ruby values.
+
+## Output Types
+
+```ruby
+# JSON values become native Ruby types:
+String   # "hello" -> "hello"
+Integer  # 42 -> 42
+Float    # 3.14 -> 3.14
+TrueClass  # true -> true
+FalseClass # false -> false
+NilClass   # null -> nil
+Array    # [1,2,3] -> [1,2,3]
+Hash     # {"a":1} -> {"a"=>1}
+```
+
+## Design Decisions
+
+### Why Separate Parser and Transformer?
+
+Parslet's two-stage model separates syntax (parsing) from semantics (transformation). This makes grammars reusable and transformations customizable.
+
+### Why Pattern Matching in Transform?
+
+Pattern matching on tree structure is more maintainable than manual tree traversal. Each rule handles one case, making bugs easier to isolate.

data/example/json/pattern.rb

@@ -0,0 +1,128 @@
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+#
+# MIT License - (c) 2011 John Mettraux
+#
+
+require 'rubygems'
+require 'parsanol/parslet' # gem install parslet
+
+
+module MyJson
+
+  class Parser < Parsanol::Parser
+
+    rule(:spaces) { match('\s').repeat(1) }
+    rule(:spaces?) { spaces.maybe }
+
+    rule(:comma) { spaces? >> str(',') >> spaces? }
+    rule(:digit) { match('[0-9]') }
+
+    rule(:number) {
+      (
+        str('-').maybe >> (
+          str('0') | (match('[1-9]') >> digit.repeat)
+        ) >> (
+          str('.') >> digit.repeat(1)
+        ).maybe >> (
+          match('[eE]') >> (str('+') | str('-')).maybe >> digit.repeat(1)
+        ).maybe
+      ).as(:number)
+    }
+
+    rule(:string) {
+      str('"') >> (
+        str('\\') >> any | str('"').absent? >> any
+      ).repeat.as(:string) >> str('"')
+    }
+
+    rule(:array) {
+      str('[') >> spaces? >>
+      (value >> (comma >> value).repeat).maybe.as(:array) >>
+      spaces? >> str(']')
+    }
+
+    rule(:object) {
+      str('{') >> spaces? >>
+      (entry >> (comma >> entry).repeat).maybe.as(:object) >>
+      spaces? >> str('}')
+    }
+
+    rule(:value) {
+      string | number |
+      object | array |
+      str('true').as(:true) | str('false').as(:false) |
+      str('null').as(:null)
+    }
+
+    rule(:entry) {
+      (
+         string.as(:key) >> spaces? >>
+         str(':') >> spaces? >>
+         value.as(:val)
+      ).as(:entry)
+    }
+
+    rule(:attribute) { (entry | value).as(:attribute) }
+
+    rule(:top) { spaces? >> value >> spaces? }
+
+    root(:top)
+  end
+
+  class Transformer < Parsanol::Transform
+
+    class Entry < Struct.new(:key, :val); end
+
+    rule(:array => subtree(:ar)) {
+      ar.is_a?(Array) ? ar : [ ar ]
+    }
+    rule(:object => subtree(:ob)) {
+      (ob.is_a?(Array) ? ob : [ ob ]).inject({}) { |h, e| h[e.key] = e.val; h }
+    }
+
+    rule(:entry => { :key => simple(:ke), :val => simple(:va) }) {
+      Entry.new(ke, va)
+    }
+
+    rule(:string => simple(:st)) {
+      st.to_s
+    }
+    rule(:number => simple(:nb)) {
+      nb.match(/[eE\.]/) ? Float(nb) : Integer(nb)
+    }
+
+    rule(:null => simple(:nu)) { nil }
+    rule(:true => simple(:tr)) { true }
+    rule(:false => simple(:fa)) { false }
+  end
+
+  def self.parse(s)
+
+    parser = Parser.new
+    transformer = Transformer.new
+
+    tree = parser.parse(s)
+    puts; p tree; puts
+    out = transformer.apply(tree)
+
+    out
+  end
+end
+
+
+s = %{
+  [ 1, 2, 3, null,
+    "asdfasdf asdfds", { "a": -1.2 }, { "b": true, "c": false },
+    0.1e24, true, false, [ 1 ] ]
+}
+
+out = MyJson.parse(s)
+
+p out; puts
+
+out == [
+  1, 2, 3, nil,
+  "asdfasdf asdfds", { "a" => -1.2 }, { "b" => true, "c" => false },
+  0.1e24, true, false, [ 1 ]
+] || raise("MyJson is a failure")