parsanol 3.0.0

data/example/ini/basic.rb

@@ -0,0 +1,154 @@
+# INI Parser Example - RubyTransform
+#
+# This example demonstrates parsing INI configuration files.
+# Shows section headers, key-value pairs, and comments.
+#
+# Run with: ruby -Ilib example/ini_ruby_transform.rb
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol'
+
+# Step 1: Define the INI file grammar
+class IniParser < Parsanol::Parser
+  root :ini
+
+  rule(:ini) {
+    (section | key_value | comment).repeat
+  }
+
+  # Section header: [section_name]
+  rule(:section) {
+    (space? >> str('[') >> section_name.as(:name) >> str(']') >> space? >> str("\n").maybe).as(:section)
+  }
+
+  rule(:section_name) {
+    (match('[^]\n]').repeat(1))
+  }
+
+  # Key-Value pair: key = value
+  rule(:key_value) {
+    (space? >> key.as(:key) >> space? >> str('=') >> space? >> value.as(:value) >> space? >> str("\n").maybe).as(:kv)
+  }
+
+  rule(:key) {
+    match('[^\s=]').repeat(1)
+  }
+
+  rule(:value) {
+    (match('[^\n]').repeat)
+  }
+
+  # Comment: # or ; at start of line
+  rule(:comment) {
+    (space? >> (str('#') | str(';')) >> match('[^\n]').repeat >> str("\n").maybe).as(:comment)
+  }
+
+  rule(:space?) { match('\s').repeat }
+end
+
+# Step 2: INI data structures
+class IniFile
+  attr_reader :sections
+
+  def initialize
+    @sections = {}
+    @current_section = nil
+  end
+
+  def set_section(name)
+    @current_section = name
+    @sections[name] ||= {}
+  end
+
+  def set_key_value(key, value)
+    section = @sections[@current_section] || {}
+    section[key.to_s.strip] = value.to_s.strip
+    @sections[@current_section] = section
+  end
+
+  def get(section, key = nil)
+    if key
+      @sections[section]&.[](key)
+    else
+      @sections[section] || {}
+    end
+  end
+
+  def to_h
+    @sections
+  end
+end
+
+# Step 3: Parse and transform
+def parse_ini(input)
+  parser = IniParser.new
+  tree = parser.parse(input)
+
+  puts "Parse tree: #{tree.inspect[0..500]}..."
+
+  ini = IniFile.new
+
+  tree.each do |item|
+    case item
+    when Hash
+      if item[:section]
+        name = item[:section][:name].to_s.strip
+        ini.set_section(name)
+        puts "  Section: [#{name}]"
+      elsif item[:kv]
+        key = item[:kv][:key].to_s
+        value = item[:kv][:value].to_s
+        ini.set_key_value(key, value)
+        puts "  #{key} = #{value}"
+      elsif item[:comment]
+        # Skip comments
+      end
+    end
+  end
+
+  ini
+end
+
+# Example usage
+if __FILE__ == $0
+  puts "=" * 60
+  puts "INI Parser - RubyTransform"
+  puts "=" * 60
+  puts
+
+  ini_content = <<~INI
+    # This is a comment
+    ; This is also a comment
+
+    [database]
+    host = localhost
+    port = 5432
+
+    [server]
+    host = 0.0.0.0
+    port = 8080
+    debug = true
+
+    [cache]
+    enabled = true
+    ttl = 3600
+  INI
+
+  puts "Input:"
+  puts "-" * 40
+  puts ini_content
+  puts
+  puts "Parsed:"
+  puts "-" * 40
+
+  ini = parse_ini(ini_content)
+
+  puts
+  puts "=" * 60
+  puts "Accessing parsed data:"
+  puts "=" * 60
+  puts "database.host: #{ini.get('database', 'host')}"
+  puts "database.port: #{ini.get('database', 'port')}"
+  puts "server.debug: #{ini.get('server', 'debug')}"
+end

data/example/ini/basic.rb.md

@@ -0,0 +1,129 @@
+# INI Parser - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/ini
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Section Header Rule
+
+Sections are enclosed in square brackets:
+
+```ruby
+rule(:section) {
+  (space? >> str('[') >> section_name.as(:name) >> str(']') >> space? >> str("\n").maybe).as(:section)
+}
+
+rule(:section_name) {
+  (match('[^]\n]').repeat(1))
+}
+```
+
+Section names exclude brackets and newlines for valid syntax.
+
+### Key-Value Pair Rule
+
+Configuration entries follow `key = value` format:
+
+```ruby
+rule(:key_value) {
+  (space? >> key.as(:key) >> space? >> str('=') >> space? >> value.as(:value) >> space? >> str("\n").maybe).as(:kv)
+}
+
+rule(:key) {
+  match('[^\s=]').repeat(1)
+}
+
+rule(:value) {
+  (match('[^\n]').repeat)
+}
+```
+
+Keys cannot contain whitespace or equals; values extend to end of line.
+
+### Comment Rule
+
+Comments start with `#` or `;`:
+
+```ruby
+rule(:comment) {
+  (space? >> (str('#') | str(';')) >> match('[^\n]').repeat >> str("\n").maybe).as(:comment)
+}
+```
+
+Both comment styles are common in INI files.
+
+### Top-Level Grammar
+
+The INI file is a sequence of sections, key-value pairs, and comments:
+
+```ruby
+rule(:ini) {
+  (section | key_value | comment).repeat
+}
+```
+
+Key-value pairs before any section header belong to no section.
+
+### IniFile Helper Class
+
+A helper class manages parsed data:
+
+```ruby
+class IniFile
+  attr_reader :sections
+
+  def initialize
+    @sections = {}
+    @current_section = nil
+  end
+
+  def set_section(name)
+    @current_section = name
+    @sections[name] ||= {}
+  end
+
+  def set_key_value(key, value)
+    section = @sections[@current_section] || {}
+    section[key.to_s.strip] = value.to_s.strip
+    @sections[@current_section] = section
+  end
+end
+```
+
+Track current section and build nested hash structure.
+
+## Output Types
+
+```ruby
+# Parse tree:
+[
+  {:section=>{:name=>"database"@s}},
+  {:kv=>{:key=>"host"@s, :value=>"localhost"@s}},
+  {:kv=>{:key=>"port"@s, :value=>"5432"@s}}
+]
+
+# After processing:
+{
+  "database" => {"host"=>"localhost", "port"=>"5432"},
+  "server" => {"host"=>"0.0.0.0", "port"=>"8080", "debug"=>"true"}
+}
+```
+
+## Design Decisions
+
+### Why Track Current Section in Helper Class?
+
+INI files are inherently sectioned; the helper maintains context as we iterate through parse results.
+
+### Why Allow Both Comment Prefixes?
+
+`#` is Unix-style, `;` is Windows-style. Supporting both maximizes compatibility.
+
+### Why Not Use Transform?
+
+Manual iteration provides more control for stateful processing (tracking current section).

data/example/ini/ruby_transform.rb

@@ -0,0 +1,154 @@
+# INI Parser Example - RubyTransform
+#
+# This example demonstrates parsing INI configuration files.
+# Shows section headers, key-value pairs, and comments.
+#
+# Run with: ruby -Ilib example/ini_ruby_transform.rb
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol'
+
+# Step 1: Define the INI file grammar
+class IniParser < Parsanol::Parser
+  root :ini
+
+  rule(:ini) {
+    (section | key_value | comment).repeat
+  }
+
+  # Section header: [section_name]
+  rule(:section) {
+    (space? >> str('[') >> section_name.as(:name) >> str(']') >> space? >> str("\n").maybe).as(:section)
+  }
+
+  rule(:section_name) {
+    (match('[^]\n]').repeat(1))
+  }
+
+  # Key-Value pair: key = value
+  rule(:key_value) {
+    (space? >> key.as(:key) >> space? >> str('=') >> space? >> value.as(:value) >> space? >> str("\n").maybe).as(:kv)
+  }
+
+  rule(:key) {
+    match('[^\s=]').repeat(1)
+  }
+
+  rule(:value) {
+    (match('[^\n]').repeat)
+  }
+
+  # Comment: # or ; at start of line
+  rule(:comment) {
+    (space? >> (str('#') | str(';')) >> match('[^\n]').repeat >> str("\n").maybe).as(:comment)
+  }
+
+  rule(:space?) { match('\s').repeat }
+end
+
+# Step 2: INI data structures
+class IniFile
+  attr_reader :sections
+
+  def initialize
+    @sections = {}
+    @current_section = nil
+  end
+
+  def set_section(name)
+    @current_section = name
+    @sections[name] ||= {}
+  end
+
+  def set_key_value(key, value)
+    section = @sections[@current_section] || {}
+    section[key.to_s.strip] = value.to_s.strip
+    @sections[@current_section] = section
+  end
+
+  def get(section, key = nil)
+    if key
+      @sections[section]&.[](key)
+    else
+      @sections[section] || {}
+    end
+  end
+
+  def to_h
+    @sections
+  end
+end
+
+# Step 3: Parse and transform
+def parse_ini(input)
+  parser = IniParser.new
+  tree = parser.parse(input)
+
+  puts "Parse tree: #{tree.inspect[0..500]}..."
+
+  ini = IniFile.new
+
+  tree.each do |item|
+    case item
+    when Hash
+      if item[:section]
+        name = item[:section][:name].to_s.strip
+        ini.set_section(name)
+        puts "  Section: [#{name}]"
+      elsif item[:kv]
+        key = item[:kv][:key].to_s
+        value = item[:kv][:value].to_s
+        ini.set_key_value(key, value)
+        puts "  #{key} = #{value}"
+      elsif item[:comment]
+        # Skip comments
+      end
+    end
+  end
+
+  ini
+end
+
+# Example usage
+if __FILE__ == $0
+  puts "=" * 60
+  puts "INI Parser - RubyTransform"
+  puts "=" * 60
+  puts
+
+  ini_content = <<~INI
+    # This is a comment
+    ; This is also a comment
+
+    [database]
+    host = localhost
+    port = 5432
+
+    [server]
+    host = 0.0.0.0
+    port = 8080
+    debug = true
+
+    [cache]
+    enabled = true
+    ttl = 3600
+  INI
+
+  puts "Input:"
+  puts "-" * 40
+  puts ini_content
+  puts
+  puts "Parsed:"
+  puts "-" * 40
+
+  ini = parse_ini(ini_content)
+
+  puts
+  puts "=" * 60
+  puts "Accessing parsed data:"
+  puts "=" * 60
+  puts "database.host: #{ini.get('database', 'host')}"
+  puts "database.port: #{ini.get('database', 'port')}"
+  puts "server.debug: #{ini.get('server', 'debug')}"
+end

data/example/ip-address/basic.rb

@@ -0,0 +1,125 @@
+# This example is heavily inspired by citrus' ip.citrus. Have a look at both
+# of these to get some choice!
+
+# The grammars in this file conform to the ABNF given in Appendix A of RFC 3986
+# Uniform Resource Identifier (URI): Generic Syntax.
+#
+# See http://tools.ietf.org/html/rfc3986#appendix-A for more information.
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'pp'
+require 'parsanol/parslet'
+
+module IPv4
+  include Parsanol::Parslet
+  
+  # A host identified by an IPv4 literal address is represented in
+  # dotted-decimal notation (a sequence of four decimal numbers in the range 0
+  # to 255, separated by "."), as described in [RFC1123] by reference to
+  # [RFC0952].  Note that other forms of dotted notation may be interpreted on
+  # some platforms, as described in Section 7.4, but only the dotted-decimal
+  # form of four octets is allowed by this grammar.
+  rule(:ipv4) {
+    (dec_octet >> str('.') >> dec_octet >> str('.') >>
+      dec_octet >> str('.') >> dec_octet).as(:ipv4)
+  }
+  
+  rule(:dec_octet) {
+    str('25') >> match("[0-5]") |
+    str('2') >> match("[0-4]") >> digit |
+    str('1') >> digit >> digit |
+    match('[1-9]') >> digit |
+    digit
+  }
+  
+  rule(:digit) {
+    match('[0-9]')
+  }
+end
+
+# Must be used in concert with IPv4
+module IPv6 
+  include Parsanol::Parslet
+  
+  rule(:colon) { str(':') }
+  rule(:dcolon) { colon >> colon }
+  
+  # h16 :
+  def h16r(times)
+    (h16 >> colon).repeat(times, times)
+  end
+  
+  # : h16
+  def h16l(times)
+    (colon >> h16).repeat(0,times)
+  end
+  
+  # A 128-bit IPv6 address is divided into eight 16-bit pieces. Each piece is
+  # represented numerically in case-insensitive hexadecimal, using one to four
+  # hexadecimal digits (leading zeroes are permitted). The eight encoded
+  # pieces are given most-significant first, separated by colon characters.
+  # Optionally, the least-significant two pieces may instead be represented in
+  # IPv4 address textual format. A sequence of one or more consecutive
+  # zero-valued 16-bit pieces within the address may be elided, omitting all
+  # their digits and leaving exactly two consecutive colons in their place to
+  # mark the elision.
+  rule(:ipv6) {
+    (
+      (
+        h16r(6) |
+        dcolon >> h16r(5) | 
+        h16.maybe >> dcolon >> h16r(4) |
+        (h16 >> h16l(1)).maybe >> dcolon >> h16r(3) |
+        (h16 >> h16l(2)).maybe >> dcolon >> h16r(2) |
+        (h16 >> h16l(3)).maybe >> dcolon >> h16r(1) |
+        (h16 >> h16l(4)).maybe >> dcolon
+      ) >> ls32 |
+      (h16 >> h16l(5)).maybe >> dcolon >> h16 |
+      (h16 >> h16l(6)).maybe >> dcolon
+    ).as(:ipv6)
+  }
+  
+  rule(:h16) {
+    hexdigit.repeat(1,4)
+  }
+  
+  rule(:ls32) {
+    (h16 >> colon >> h16) |
+    ipv4
+  }
+
+  rule(:hexdigit) {
+    digit | match("[a-fA-F]")
+  }
+end
+
+class Parser
+  include IPv4
+  include IPv6
+  
+  def parse(str)
+    (ipv4 | ipv6).parse(str)
+  end
+end
+
+%W(
+  0.0.0.0
+  255.255.255.255
+  255.255.255
+  1:2:3:4:5:6:7:8
+  12AD:34FC:A453:1922::
+  12AD::34FC
+  12AD::
+  ::
+  1:2
+).each do |address|
+  parser = Parser.new
+  printf "%30s -> ", address
+  begin
+    result = parser.parse(address)
+    puts result.inspect
+  rescue Parsanol::ParseFailed => m
+    puts "Failed: #{m}"
+  end
+end

data/example/ip-address/basic.rb.md

@@ -0,0 +1,139 @@
+# IP Address Parser - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/ip-address
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### IPv4 DecOctet Rule
+
+Each octet must be 0-255:
+
+```ruby
+rule(:dec_octet) {
+  str('25') >> match("[0-5]") |
+  str('2') >> match("[0-4]") >> digit |
+  str('1') >> digit >> digit |
+  match('[1-9]') >> digit |
+  digit
+}
+```
+
+Ordered alternatives ensure correct matching: 250-255, 200-249, 100-199, 10-99, 0-9.
+
+### IPv4 Address Rule
+
+Four octets separated by dots:
+
+```ruby
+rule(:ipv4) {
+  (dec_octet >> str('.') >> dec_octet >> str('.') >>
+    dec_octet >> str('.') >> dec_octet).as(:ipv4)
+}
+```
+
+This matches the dotted-decimal notation from RFC 1123.
+
+### IPv6 H16 Rule
+
+Hexadecimal groups are 1-4 digits:
+
+```ruby
+rule(:h16) {
+  hexdigit.repeat(1,4)
+}
+
+rule(:hexdigit) {
+  digit | match("[a-fA-F]")
+}
+```
+
+Case-insensitive hex matching follows RFC 3986.
+
+### IPv6 Address Rule
+
+IPv6 allows zero compression with `::`:
+
+```ruby
+rule(:ipv6) {
+  (
+    (
+      h16r(6) |
+      dcolon >> h16r(5) |
+      h16.maybe >> dcolon >> h16r(4) |
+      # ... more patterns
+    ) >> ls32 |
+    (h16 >> h16l(5)).maybe >> dcolon >> h16 |
+    (h16 >> h16l(6)).maybe >> dcolon
+  ).as(:ipv6)
+}
+```
+
+Multiple alternatives handle different compression positions.
+
+### LS32 Rule
+
+The least-significant 32 bits can be IPv4 or two h16 groups:
+
+```ruby
+rule(:ls32) {
+  (h16 >> colon >> h16) |
+  ipv4
+}
+```
+
+IPv4-mapped IPv6 addresses are supported.
+
+### Module Composition
+
+Grammar modules are mixed into the parser:
+
+```ruby
+module IPv4
+  include Parsanol::Parslet
+  # IPv4 rules...
+end
+
+module IPv6
+  include Parsanol::Parslet
+  # IPv6 rules...
+end
+
+class Parser
+  include IPv4
+  include IPv6
+end
+```
+
+Modular organization keeps complex grammar manageable.
+
+## Output Types
+
+```ruby
+# IPv4:
+{:ipv4=>"192.168.1.1"@s}
+
+# IPv6:
+{:ipv6=>"2001:db8::1"@s}
+
+# Invalid:
+# Raises Parsanol::ParseFailed
+```
+
+## Design Decisions
+
+### Why Separate IPv4 and IPv6 Modules?
+
+RFC 3986 defines them separately; modules allow independent testing and reuse.
+
+### Why So Many IPv6 Alternatives?
+
+Zero compression (`::`) can appear at any position; each alternative represents a valid compression point.
+
+### Why Ordered Alternatives for DecOctet?
+
+PEG parsers try alternatives in order. Largest ranges must come first to prevent premature matching.