parsanol 3.0.0

data/example/string-literal/basic.rb.md

@@ -0,0 +1,128 @@
+# String Literal Parser - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/string-literal
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### String Literal Rule
+
+Strings are quoted with escape support:
+
+```ruby
+rule :string do
+  str('"') >>
+  (
+    (str('\\') >> any) |
+    (str('"').absent? >> any)
+  ).repeat.as(:string) >>
+  str('"')
+end
+```
+
+Escaped characters (including escaped quotes) are handled; otherwise quotes terminate.
+
+### Integer Literal Rule
+
+Integers are sequences of digits:
+
+```ruby
+rule :integer do
+  match('[0-9]').repeat(1).as(:integer)
+end
+```
+
+Simple repetition captures multi-digit numbers.
+
+### Literal Alternation
+
+Literals can be strings or integers:
+
+```ruby
+rule :literal do
+  (integer | string).as(:literal) >> space.maybe
+end
+```
+
+Order matters: try more specific patterns first.
+
+### File-Level Grammar
+
+Multiple literals separated by newlines:
+
+```ruby
+rule :literals do
+  (literal >> eol).repeat
+end
+
+rule :eol do
+  line_end.repeat(1)
+end
+```
+
+Each line contains one literal definition.
+
+### AST Node Classes
+
+Ruby structs represent AST nodes:
+
+```ruby
+class Lit < Struct.new(:text)
+  def to_s
+    text.inspect
+  end
+end
+class StringLit < Lit
+end
+class IntLit < Lit
+  def to_s
+    text
+  end
+end
+```
+
+Inheritance allows shared behavior with type-specific formatting.
+
+### Transform Rules
+
+Transform creates typed AST nodes:
+
+```ruby
+transform = Parsanol::Transform.new do
+  rule(:literal => {:integer => simple(:x)}) { IntLit.new(x) }
+  rule(:literal => {:string => simple(:s)}) { StringLit.new(s) }
+end
+```
+
+Pattern matching on content type determines node class.
+
+## Output Types
+
+```ruby
+# Parse tree:
+[
+  {:literal=>{:integer=>"42"@s}},
+  {:literal=>{:string=>"hello world"@s}}
+]
+
+# After transform:
+[IntLit.new("42"), StringLit.new("hello world")]
+```
+
+## Design Decisions
+
+### Why Handle Escapes in Strings?
+
+Real-world string literals support escape sequences. `\"` allows quotes inside strings.
+
+### Why Separate StringLit and IntLit?
+
+Type-specific classes enable different behavior (formatting, validation, evaluation).
+
+### Why Read from File?
+
+Demonstrates parsing external input, common in compiler frontends.

data/example/test.lit

@@ -0,0 +1,4 @@
+"THis is a string"
+"This is another string"
+"This string is escaped \"embedded quoted stuff \" "
+12 // an integer literal and a comment

data/example/toml/basic.rb

@@ -0,0 +1,226 @@
+# TOML Parser - Ruby Implementation
+#
+# Parse TOML configuration files: key-value pairs, tables, arrays.
+#
+# Run with: ruby example/toml/basic.rb
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol/parslet'
+
+# TOML parser
+class TomlParser < Parsanol::Parser
+  root :document
+
+  # Document is a sequence of entries
+  rule(:document) { (comment | table | key_value | newline).repeat.as(:document) }
+
+  # Comment: # to end of line
+  rule(:comment) {
+    (str('#') >> (newline.absent? >> any).repeat).as(:comment) >> newline
+  }
+
+  # Table: [name] or [name.sub]
+  rule(:table) {
+    (str('[') >>
+     table_name.as(:name) >>
+     str(']') >>
+     newline).as(:table)
+  }
+
+  rule(:table_name) {
+    (match('[a-zA-Z0-9_]') | str('.') | str('-')).repeat(1)
+  }
+
+  # Key-value pair: key = value
+  rule(:key_value) {
+    (key.as(:key) >>
+     space? >>
+     str('=') >>
+     space? >>
+     value.as(:value) >>
+     newline).as(:key_value)
+  }
+
+  rule(:key) {
+    (match('[a-zA-Z_]') >> match('[a-zA-Z0-9_]').repeat).as(:key)
+  }
+
+  # Value types
+  rule(:value) {
+    string |
+    integer |
+    float |
+    boolean |
+    array |
+    inline_table
+  }
+
+  # String: basic "..." or literal '...'
+  rule(:string) {
+    basic_string | literal_string
+  }
+
+  rule(:basic_string) {
+    (str('"') >>
+     (str('\\').ignore >> any | str('"').absent? >> any).repeat.as(:string) >>
+     str('"')).as(:basic_string)
+  }
+
+  rule(:literal_string) {
+    (str("'") >>
+     (str("'").absent? >> any).repeat.as(:string) >>
+     str("'")).as(:literal_string)
+  }
+
+  # Integer: +/-digits
+  rule(:integer) {
+    (str('+') | str('-')).maybe >>
+    match('[0-9]').repeat(1).as(:integer)
+  }
+
+  # Float: digits.digits or scientific notation
+  rule(:float) {
+    ((str('+') | str('-')).maybe >>
+     match('[0-9]').repeat(1) >>
+     str('.') >>
+     match('[0-9]').repeat(1) >>
+     (match('[eE]') >> (str('+') | str('-')).maybe >> match('[0-9]').repeat(1)).maybe).as(:float)
+  }
+
+  # Boolean: true or false
+  rule(:boolean) {
+    (str('true') | str('false')).as(:boolean)
+  }
+
+  # Array: [...]
+  rule(:array) {
+    (str('[') >>
+     space? >>
+     (value >> (comma >> value).repeat).maybe.as(:elements) >>
+     space? >>
+     str(']').as(:array)
+  }
+
+  # Inline table: {...}
+  rule(:inline_table) {
+    (str('{') >>
+     space? >>
+     (key_value_inline >> (comma >> key_value_inline).repeat).maybe.as(:pairs) >>
+     space? >>
+     str('}')).as(:inline_table)
+  }
+
+  rule(:key_value_inline) {
+    key.as(:key) >> space? >> str('=') >> space? >> value.as(:value)
+  }
+
+  # Helpers
+  rule(:space?) { match('\s').repeat }
+  rule(:comma) { str(',') >> space? }
+  rule(:newline) { match('\n') | match('\r\n') }
+end
+
+# TOML result classes
+TomlDocument = Struct.new(:entries) do
+  def to_h
+    result = {}
+    current_table = nil
+
+    entries.each do |entry|
+      case entry
+      when TomlTable
+        current_table = entry.name
+        result[current_table] ||= {}
+      when TomlKeyValue
+        if current_table
+          result[current_table][entry.key] = entry.value
+        else
+          result[entry.key] = entry.value
+        end
+      end
+    end
+
+    result
+  end
+end
+
+TomlTable = Struct.new(:name)
+TomlKeyValue = Struct.new(:key, :value)
+TomlComment = Struct.new(:text)
+
+# Transform parse tree to AST
+class TomlTransform < Parsanol::Transform
+  rule(document: sequence(:entries)) { TomlDocument.new(entries) }
+
+  rule(table: { name: simple(:n) }) { TomlTable.new(n.to_s) }
+
+  rule(key_value: { key: simple(:k), value: simple(:v) }) {
+    TomlKeyValue.new(k.to_s, v)
+  }
+
+  rule(comment: simple(:c)) { TomlComment.new(c.to_s) }
+
+  # Value transformations
+  rule(basic_string: simple(:s)) { s.to_s }
+  rule(literal_string: simple(:s)) { s.to_s }
+  rule(integer: simple(:i)) { i.to_s.to_i }
+  rule(float: simple(:f)) { f.to_s.to_f }
+  rule(boolean: simple(:b)) { b.to_s == 'true' }
+  rule(array: { elements: simple(:e) }) { [e] }
+  rule(array: { elements: sequence(:es) }) { es }
+  rule(inline_table: { pairs: simple(:p) }) { { p[:key] => p[:value] } }
+  rule(inline_table: { pairs: sequence(:ps) }) {
+    ps.each_with_object({}) { |p, h| h[p[:key]] = p[:value] }
+  }
+end
+
+# Parse TOML string
+def parse_toml(str)
+  parser = TomlParser.new
+  transform = TomlTransform.new
+
+  tree = parser.parse(str)
+  transform.apply(tree)
+rescue Parsanol::ParseError => e
+  puts "Parse error: #{e.message}"
+  nil
+end
+
+# Main demo
+if __FILE__ == $0
+  puts "TOML Parser"
+  puts "=" * 50
+  puts
+
+  toml = <<~TOML
+    # This is a comment
+    title = "TOML Example"
+
+    [database]
+    host = "localhost"
+    port = 5432
+    enabled = true
+    connection_timeout = 30.5
+
+    [server]
+    hosts = ["alpha", "beta", "gamma"]
+    ports = [8080, 8081, 8082]
+  TOML
+
+  puts "Input:"
+  puts "-" * 50
+  puts toml
+  puts "-" * 50
+  puts
+
+  result = parse_toml(toml)
+
+  if result
+    puts "Parsed AST:"
+    pp result
+    puts
+    puts "Hash Output:"
+    pp result.to_h
+  end
+end

data/example/toml/basic.rb.md

@@ -0,0 +1,173 @@
+# TOML Parser - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/toml
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Document Structure
+
+A TOML document contains entries in sequence:
+
+```ruby
+rule(:document) { (comment | table | key_value | newline).repeat.as(:document) }
+```
+
+Order matters: comments and tables appear where they are in the source.
+
+### Comment Rule
+
+Hash-prefixed comments to end of line:
+
+```ruby
+rule(:comment) {
+  (str('#') >> (newline.absent? >> any).repeat).as(:comment) >> newline
+}
+```
+
+Comments are captured but typically ignored in output.
+
+### Table Rule
+
+Square-bracketed section headers:
+
+```ruby
+rule(:table) {
+  (str('[') >>
+   table_name.as(:name) >>
+   str(']') >>
+   newline).as(:table)
+}
+
+rule(:table_name) {
+  (match('[a-zA-Z0-9_]') | str('.') | str('-')).repeat(1)
+}
+```
+
+Dotted names like `[database.server]` create nested tables.
+
+### Key-Value Rule
+
+Assignment with various value types:
+
+```ruby
+rule(:key_value) {
+  (key.as(:key) >>
+   space? >>
+   str('=') >>
+   space? >>
+   value.as(:value) >>
+   newline).as(:key_value)
+}
+```
+
+Keys are alphanumeric with underscores.
+
+### String Rules
+
+Basic strings with escapes and literal strings:
+
+```ruby
+rule(:basic_string) {
+  (str('"') >>
+   (str('\\').ignore >> any | str('"').absent? >> any).repeat.as(:string) >>
+   str('"')).as(:basic_string)
+}
+
+rule(:literal_string) {
+  (str("'") >>
+   (str("'").absent? >> any).repeat.as(:string) >>
+   str("'")).as(:literal_string)
+}
+```
+
+Basic strings process escapes; literal strings don't.
+
+### Numeric Rules
+
+Integers and floating-point numbers:
+
+```ruby
+rule(:integer) {
+  (str('+') | str('-')).maybe >>
+  match('[0-9]').repeat(1).as(:integer)
+}
+
+rule(:float) {
+  ((str('+') | str('-')).maybe >>
+   match('[0-9]').repeat(1) >>
+   str('.') >>
+   match('[0-9]').repeat(1) >>
+   (match('[eE]') >> ...).maybe).as(:float)
+}
+```
+
+Scientific notation is supported for floats.
+
+### Array Rule
+
+Square-bracketed value lists:
+
+```ruby
+rule(:array) {
+  (str('[') >>
+   space? >>
+   (value >> (comma >> value).repeat).maybe.as(:elements) >>
+   space? >>
+   str(']')).as(:array)
+}
+```
+
+Arrays can contain any value type, mixed.
+
+### Inline Table Rule
+
+Curly-braced key-value pairs:
+
+```ruby
+rule(:inline_table) {
+  (str('{') >>
+   space? >>
+   (key_value_inline >> (comma >> key_value_inline).repeat).maybe.as(:pairs) >>
+   space? >>
+   str('}')).as(:inline_table)
+}
+```
+
+Inline tables are compact single-line objects.
+
+## Output Types
+
+```ruby
+# Document with entries
+TomlDocument.new([
+  TomlComment.new(" comment"),
+  TomlKeyValue.new("title", "TOML Example"),
+  TomlTable.new("database"),
+  TomlKeyValue.new("host", "localhost")
+])
+
+# to_h produces:
+{
+  "title" => "TOML Example",
+  "database" => { "host" => "localhost" }
+}
+```
+
+## Design Decisions
+
+### Why Track Current Table in to_h?
+
+TOML key-value pairs belong to the most recent table. The transformation tracks this context.
+
+### Why Two String Types?
+
+TOML specification defines basic strings (with escapes) and literal strings (raw). Different rules handle them correctly.
+
+### Why Separate Integer and Float?
+
+Type distinction matters for configuration values. Separate rules preserve type information.