yaparc 0.0.7 → 0.0.8

data/README

@@ -1,10 +1,11 @@
 = Synopsis
 
-This is a yet another simple combinator parser library in ruby.
+There are several implementations of parser combinator in ruby. This is a yet another simple combinator parser libraryin ruby.
 
 = Requirements
 
 * Ruby (http://www.ruby-lang.org/)
+* RubyGem (http://rubyforge.org/projects/rubygems/)
 
 = Install
 
@@ -12,19 +13,182 @@ This is a yet another simple combinator parser library in ruby.
 
 = Usage
 
-  require 'rubygems'
-  require_gem 'yaparc'
+In combinator parser, each parser is construct as a function taking input string as arguments. Larger parsers are built from smaller parsers. Although combinators are higher-order functions in ordinary functional languages, they are constructed as classes in yaparc, because Ruby has more object-oriented than functional property.
 
+All parsers has 'parse' method, each of which takes input string as its arguments except SatisfyParser. All of them return an array of array as their result, with the empty array [] denoting faiilure, and a singleton array [[v, xs]] indicating success, with value v and uncosumed input xs as String instance.
 
-Please look at unit test files.
+== Primitive Parsers
 
+* SucceedParser
+* FailParser
+* ItemParser
+* SatisfyParser
 
-== Basic Parsers
+=== SucceedParser class
 
-== Combination Parsers
+The parser SucceedParser always succeeds with the result value, without consuming any of the input string.
+In the following example, SucceedParser#parse takes an input string "blah, blah, blah" and returns the singleton array [[1, "blah, blah, blah"]].
 
-=== Sequence Parser
-=== Alternate Parser
+    parser = SucceedParser.new(1)
+    parser.parse("blah, blah, blah")
+    => [[1, "blah, blah, blah"]]
 
+=== FailParser class
+
+The parser FailParser always fails, regardless of the contents of the input string.
+
+    parser = FailParser.new
+    parser.parse("abc")
+    => []
+
+=== ItemParser class
+
+The parser ItemParser fails if the input string is empty, and succeeds with the first character as the result value otherwise.
+
+    parser = ::Yaparc::ItemParser.new
+    parser.parse("abc")
+    => [["a", "bc"]]
+
+=== SatisfyParser class
+
+The parser SatisfyParser recognizes a single input via predicate which determines if an arbitrary input is suitable for the predicate.
+
+    is_integer = lambda do |i|
+      begin
+        Integer(i)
+        true
+      rescue
+        false
+      end
+    end
+    parser = SatisfyParser.new(is_integer)
+    parser.parse("123")
+    => [["1", "23"]]
+
+
+== Combining Parsers
+
+* AltParser
+* SeqParser
+* ManyParser
+* ManyOneParser
+
+
+  
+=== Sequencing parser
+
+The SeqParser corresponds to sequencing in BNF. The following parser recognizes anything that Symbol.new('+') or Natural.new would if placed in succession.
+
+  parser = SeqParser.new(Symbol.new('+'), Natural.new)
+  parser.parse("+321")
+  => [[321,""]]
+
+if a block given to SeqParser, it analyses input string to construct its logical structure.
+
+  parser = SeqParser.new(Symbol.new('+'), Natural.new) do | plus, nat|
+    nat
+  end
+  parser.parse("+1234")
+  => [[1234,""]]
+
+It produces a parse tree which expounds the semantic structure of the program.
+
+=== Alternation parser
+
+The parser AltParser class is an alternation parser, which returns the result of the first parser to succeed, and failure if neither does.
+
+
+  parser = AltParser.new(
+                          SeqParser.new(Symbol.new('+'), Natural.new) do | _, nat|
+                            nat
+                          end,
+                          Natural.new
+                         )
+  parser.parse("1234")
+  => [[1234,""]]
+  parser.parse("-1234")
+  => []
+
+
+=== ManyParser
+
+In ManyParser, zero or more applications of parser are admissible.
+
+    parser = ManyParser.new(SatisfyParser.new(lambda {|i| i > '0' and i < '9'}))
+    parser.parse("123abc")
+    => [["123", "abc"]]
+
+
+=== ManyOneParser
+
+The ManyOneParser requires at least one successfull application of parser.
+
+
+== Tokenized parser
+
+* Identifier
+
+  Parser for identifier
+
+* Natural
+
+  Parser for natural number
+
+* Symbol
+
+
+== Define your own parser
+
+
+There are two ways to construct parser. One is to inherit from Yaparc::ParserBase class.
+
+  class StringMatch < Yaparc::ParserBase
+
+    def initialize(literal)
+      @parser = Token.new(StringParser.new(literal))
+    end
+  end
+
+The other is to inherit from Yaparc::AbstractParser class.
+
+  class Identifier < Yaparc::AbstractParser
+    def initialize
+      @parser = lambda do
+        Token.new(Ident.new)
+      end
+    end
+  end
+
+If you want to nest the same parser class in the parser definition, you have to choose this way.
+In the following example, note that Expr class is instantiated inside Expr#initialize method.
+
+  class Expr < Yaparc::AbstractParser
+    def initialize
+      @parser = lambda do
+        Yaparc::AltParser.new(
+                              Yaparc::SeqParser.new(Term.new,
+                                                    Yaparc::Symbol.new('+'),
+                                                    Expr.new) do |term, _, expr|
+                                ['+', term,expr]
+                              end,
+                              Term.new
+                              )
+      end
+    end
+
+Constructing your parsers, it should be noted that left-recursion leads to non-termination of the parser.
+
+== Avoiding left-recursion
+
+ A ::= A B | C
+
+  is equivalent to
+
+ A ::= C B*
+
+
+== Tokenization
+
+When you want to tokenize input stream, use Token class.