rparsec 0.4 → 0.4.1

data/rparsec/id_monad.rb

@@ -0,0 +1,11 @@
+class IdMonad
+  def value v
+    v
+  end
+  def bind prev
+    yield prev
+  end
+  def mplus a, b
+    a
+  end
+end

data/rparsec/keywords.rb

@@ -0,0 +1,90 @@
+require 'rparsec/parser'
+
+#
+# This class helps building lexers and parsers for keywords.
+# 
+class Keywords
+  extend Parsers
+  private_class_method :new
+  attr_reader :keyword_symbol, :lexer
+  #
+  # Do we lex case sensitively?
+  # 
+  def case_sensitive?
+    @case_sensitive
+  end
+  #
+  # To create an instance that lexes the given keywords
+  # case sensitively. 
+  # _default_lexer_ is used to lex a token first, the token text is then compared with
+  # the given keywords. If it matches any of the keyword, a keyword token is generated instead
+  # using _keyword_symbol_.
+  # The _block_ parameter, if present, is used to convert the token text to another object
+  # when the token is recognized during grammar parsing phase.
+  # 
+  def self.case_sensitive(words, default_lexer=word.token(:word), keyword_symbol=:keyword, &block)
+    new(words, true, default_lexer, keyword_symbol, &block)
+  end
+  #
+  # To create an instance that lexes the given keywords
+  # case insensitively. 
+  # _default_lexer_ is used to lex a token first, the token text is then compared with
+  # the given keywords. If it matches any of the keyword, a keyword token is generated instead
+  # using _keyword_symbol_.
+  # The _block_ parameter, if present, is used to convert the token text to another object
+  # when the token is recognized during parsing phase.
+  # 
+  def self.case_insensitive(words, default_lexer=word.token(:word), keyword_symbol=:keyword, &block)
+    new(words, false, default_lexer, keyword_symbol, &block)
+  end
+  # scanner has to return a string
+  def initialize(words, case_sensitive, default_lexer, keyword_symbol, &block)
+    @default_lexer, @case_sensitive, @keyword_symbol = default_lexer, case_sensitive, keyword_symbol
+    # this guarantees that we have copy of the words array and all the word strings.
+    words = copy_words(words, case_sensitive)
+    @name_map = {}
+    @symbol_map = {}
+    word_map = {}
+    words.each do |w|
+      symbol = "#{keyword_symbol}:#{w}".to_sym
+      word_map[w] = symbol
+      parser = Parsers.token(symbol, &block)
+      @symbol_map["#{w}".to_sym] = parser
+      @name_map[w] = parser
+    end
+    @lexer = make_lexer(default_lexer, word_map)
+  end
+  #
+  # Get the parser that recognizes the token of the given keyword during the parsing phase.
+  #
+  def parser(key)
+    result = nil
+    if key.kind_of? String
+      name = canonical_name(key)
+      result = @name_map[name]
+    else
+      result = @symbol_map[key]
+    end
+    raise ArgumentError, "parser not found for #{key}" if result.nil?
+    result
+  end
+  alias [] parser
+  private
+  def make_lexer(default_lexer, word_map)
+    default_lexer.map do |tok|
+      text,ind = tok.text, tok.index
+      key = canonical_name(text)
+      my_symbol = word_map[key]
+      case when my_symbol.nil? : tok
+        else Token.new(my_symbol, text, ind) end
+    end
+  end
+  def canonical_name(name)
+    case when @case_sensitive: name else name.downcase end
+  end
+  def copy_words(words, case_sensitive)
+    words.map do |w|
+      case when case_sensitive: w.dup else w.downcase end
+    end
+  end
+end

data/rparsec/locator.rb

@@ -0,0 +1,32 @@
+require 'rparsec/misc'
+
+class CodeLocator
+  extend DefHelper
+  def_readable :code
+  LF = ?\n
+  def locate(ind)
+    return _locateEof if ind >= code.length
+    line, col = 1,1
+    return line,col if ind<=0
+    for i in (0...ind)
+      c = code[i]
+      if c == LF
+        line, col = line+1, 1
+      else
+        col = col+1
+      end
+    end
+    return line, col
+  end
+  def _locateEof
+    line, col = 1, 1
+    code.each_byte do |c|
+      if c == LF
+        line, col = line+1, 1 
+      else
+        col = col+1
+      end
+    end
+    return line, col
+  end
+end

data/rparsec/misc.rb

@@ -0,0 +1,102 @@
+#
+# Helpers for defining ctor.
+#
+module DefHelper
+  def def_ctor(*vars)
+    define_method(:initialize) do |*params|
+      vars.each_with_index do |var, i|
+        instance_variable_set("@"+var.to_s, params[i])
+      end
+    end
+  end
+
+  def def_readable(*vars)
+    attr_reader(*vars)
+    def_ctor(*vars)
+  end
+
+  def def_mutable(*vars)
+    attr_accessor(*vars)
+    def_ctor(*vars)
+  end
+end
+
+#
+# To type check method parameters.
+# 
+module TypeChecker
+  private
+  def nth n
+    th = case n when 0: 'st' when 1: 'nd' else 'th' end
+    "#{n+1}#{th}"
+  end
+  public
+  def check_arg_type expected, obj, mtd, n=0
+    unless obj.kind_of? expected
+      raise ArgumentError,
+        "#{obj.class} assigned to #{expected} for the #{nth n} argument of #{mtd}."
+    end
+  end
+  def check_arg_array_type elem_type, arg, mtd, n=0
+    check_arg_type Array, arg, mtd, n
+    arg.each_with_index do |x, i|
+      unless x.kind_of? elem_type
+        raise ArgumentError,
+          "#{x.class} assigned to #{elem_type} for the #{nth i} element of the #{nth n} argument of #{mtd}."
+      end
+    end
+  end
+  def check_vararg_type expected, args, mtd, n = 0
+    (n...args.length).each do |i|
+      check_arg_type expected, args[i], mtd, i
+    end
+  end
+  extend self
+end
+
+#
+# To add declarative signature support.
+# 
+module Signature
+  # Signatures = {}
+  def def_sig sym, *types
+    types.each_with_index do |t,i|
+      unless t.kind_of? Class
+        TypeChecker.check_arg_type Class, t, :def_sig, i unless t.kind_of? Array
+        TypeChecker.check_arg_type Class, t, :def_sig, i unless t.length <= 1
+        TypeChecker.check_arg_array_type Class, t, :def_sig, i
+      end
+    end
+    # Signatures[sym] = types
+    __intercept_method_to_check_param_types__(sym, types)
+  end
+  private
+  
+  def __intercept_method_to_check_param_types__(sym, types)
+    mtd = instance_method(sym)
+    helper = "_#{sym}_param_types_checked_helper".to_sym
+    define_method(helper) do |*params|
+      star_type, star_ind = nil, nil
+      types.each_with_index do |t, i|
+        t = star_type unless star_type.nil?
+        arg = params[i]
+        if t.kind_of? Class
+          TypeChecker.check_arg_type t, arg, sym, i
+        elsif t.empty?
+          TypeChecker.check_arg_type Array, arg, sym, i
+        else
+          star_type, star_ind = t[0], i
+          break
+        end
+      end
+      TypeChecker.check_vararg_type star_type, params, sym, star_ind unless star_ind.nil?
+      mtd.bind(self)
+    end
+    module_eval """
+    def #{sym}(*params, &block)
+      #{helper}(*params).call(*params, &block)
+    end
+    """
+  end
+end
+

data/rparsec/monad.rb

@@ -0,0 +1,52 @@
+#
+# module for Monad
+#
+module Monad
+  attr_reader :this
+  #
+  # To initialize with a monad implementation and an object that obeys the monad law.
+  #
+  def initMonad(m, v)
+    raise ArgumentError, 'monad cannot be nil' if m.nil?
+    @monad = m;
+    @this = v;
+  end
+  #
+  # To create a value based on the monad impl.
+  # 
+  def value v
+    @monad.value v
+  end
+  #
+  # Run the _bind_ operation on the encapsulated object following the monad law.
+  # 
+  def bind(&binder)
+    @monad.bind(@this, &binder)
+  end
+  #
+  # Run the _seq_ operation on the encapsulated object following the monad law.
+  # If _seq_ is not defined by the monad impl, use _bind_ to implement.
+  # 
+  def seq(other)
+    if @monad.respond_to? :seq
+      @monad.seq(other)
+    else bind {|x|other}
+    end
+  end
+  #
+  # Run the _map_ operation on the encapsulated object following the monad law.
+  # _bind_ is used to implement.
+  # 
+  def map(&mapper)
+    bind do |v|
+      result = mapper.call v;
+      value(result);
+    end
+  end
+  #
+  # Run the _plus_ operation on the encapsulated object following the MonadPlus law.
+  # 
+  def plus other
+    @monad.mplus(@this, other.this)
+  end
+end

data/rparsec/operators.rb

@@ -0,0 +1,110 @@
+require 'rparsec/parser'
+
+#
+# utility functions for string manipulations.
+#
+module StringUtils
+  #
+  # Does _str_ starts with the _sub_ string?
+  # 
+  def self.starts_with? str, sub
+    return true if sub.nil?
+    len = sub.length
+    return false if len > str.length
+    for i in (0...len)
+      return false if str[i] != sub[i]
+    end
+    true
+  end
+end
+
+#
+# This class helps building lexer and parser for operators.
+# The case that one operator (++ for example) contains another operator (+)
+# is automatically handled so client code don't have to worry about ambiguity.
+# 
+class Operators
+  #
+  # To create an instance of Operators for the given operators.
+  # The _block_ parameter, if present, is used to convert the token text to another object
+  # when the token is recognized during grammar parsing phase.
+  #
+  def initialize(ops, &block)
+    @lexers = {}
+    @parsers = {}
+    sorted = Operators.sort(ops)
+    lexers = sorted.map do |op|
+      symbol = op.to_sym
+      result = nil
+      if op.length == 1
+        result = Parsers.char(op)
+      else
+        result = Parsers.str(op)
+      end
+      result = result.token(symbol)
+      @lexers[symbol] = result
+      @parsers[symbol] = Parsers.token(symbol, &block)
+      result
+    end
+    @lexer = Parsers.sum(*lexers)
+  end
+  #
+  # Get the parser for the given operator.
+  #
+  def parser(op)
+    result = @parsers[op.to_sym]
+    raise ArgumentError, "parser not found for #{op}" if result.nil?
+    result
+  end
+  alias [] parser
+  #
+  # Get the lexer that lexes operators.
+  # If an operator is specified, the lexer for that operator is returned.
+  #
+  def lexer(op=nil)
+    return @lexer if op.nil?
+    @lexers[op.to_sym]
+  end
+  #
+  # Sort an array of operators so that contained operator appears after containers.
+  # When no containment exist between two operators, the shorter one takes precedence.
+  #
+  def self.sort(ops)
+    #sort the array by longer-string-first.
+    ordered = ops.sort {|x, y|y.length <=> x.length}
+    suites = []
+    # loop from the longer to shorter string
+    ordered.each do |s|
+      populate_suites(suites, s)
+    end
+    # suites are populated with bigger suite first
+    to_array suites
+  end
+  private
+  def self.populate_suites(suites, s)
+    # populate the suites so that bigger suite first
+    # this way we can use << operator for non-contained strings.
+    
+    # we need to start from bigger suite. So loop in reverse order
+    for suite in suites
+      return if populate_suite(suite, s)
+    end
+    suites << [s]
+  end
+  def self.populate_suite(suite, s)
+    # loop from the tail of the suite
+    for i in (1..suite.length)
+      ind = suite.length - i
+      cur = suite[ind]
+      if StringUtils.starts_with? cur, s
+        suite.insert(ind+1, s) unless cur == s
+        return true
+      end
+    end
+    false
+  end
+  def self.to_array suites
+    result = []
+    suites.reverse!.flatten!
+  end
+end

data/rparsec/parser.rb

@@ -0,0 +1,794 @@
+%w{
+monad misc error context locator token functors parser_monad
+}.each {|lib| require "rparsec/#{lib}"}
+require 'strscan'
+
+
+#
+# Represents a parser that parses a certain grammar rule.
+#
+class Parser
+  include Functors
+  include Monad
+  extend Signature
+  extend DefHelper
+  MyMonad = ParserMonad.new
+  attr_accessor :name
+  private
+  def initialize
+    initMonad(MyMonad, self)
+  end
+  def self.init(*vars)
+    parser_checker = {}
+    vars.each_with_index do |var, i|
+      name = var.to_s
+      parser_checker[i] = var if name.include?('parser') && !name.include?('parsers')
+    end
+    define_method(:initialize) do |*params|
+      super()
+      vars.each_with_index do |var, i|
+        param = params[i]
+        if parser_checker.include? i
+          TypeChecker.check_arg_type Parser, param, self, i
+        end
+        instance_variable_set("@"+var.to_s, param)
+      end
+    end
+  end
+  def _display_current_input(input, code, index)
+    return 'EOF' if input.nil?
+    c = input
+    case c when Fixnum: "'"<<c<<"'" when Token: c.text else c.to_s end
+  end
+  def _add_encountered_error(msg, encountered)
+    result = msg.dup
+    result << ', ' unless msg.strip.length == 0 || msg =~ /.*(\.|,)\s*$/
+    "#{result}#{encountered}"
+  end
+  def _add_location_to_error(locator, ctxt, msg, code)
+    line, col = locator.locate(ctxt.error.index)
+    msg << " at line #{line}, col #{col}."
+  end
+  public
+  #
+  # parses a string.
+  #
+  def parse(src)
+    ctxt = ParseContext.new(src)
+    return ctxt.result if _parse ctxt
+    ctxt.prepare_error
+    locator = CodeLocator.new(src)
+    raise ParserException.new(ctxt.error.index), 
+      _add_location_to_error(locator, ctxt, 
+        _add_encountered_error(ctxt.to_msg,
+           _display_current_input(ctxt.error.input, src, ctxt.index)), src)
+  end
+  #
+  # Set name for the parser.
+  # self is returned.
+  #
+  def setName(nm)
+    @name = nm
+    self
+  end
+  #
+  # a.map{|x|x+1} will first execute parser a, when it succeeds,
+  # the associated block is executed to transform the result to a new value
+  # (increment it in this case).
+  #
+  def map(&block)
+    return self unless block
+    MapParser.new(self, block)
+  end
+  #
+  # _self_ is first executed, the parser result is then passed as parameter to the associated block,
+  # which evaluates to another Parser object at runtime. This new Parser object is then executed
+  # to get the final parser result.
+  ##
+  # Different from _bind_, parser result of _self_ will be expanded first if it is an array.
+  #
+  def bindn(&block)
+    return self unless block
+    BoundnParser.new(self, block)
+  end
+  #
+  # a.mapn{|x,y|x+y} will first execute parser a, when it succeeds,
+  # the array result (if any) is expanded and passed as parameters
+  # to the associated block. The result of the block is then used
+  # as the parsing result.
+  #
+  def mapn(&block)
+    return self unless block
+    MapnParser.new(self, block)
+  end
+  
+  #
+  # Create a new parser that's atomic.,
+  # meaning that when it fails, input consumption is undone.
+  # 
+  def atomize
+    AtomParser.new(self).setName(@name)
+  end
+  #
+  # Create a new parser that looks at inputs whthout consuming them.
+  # 
+  def peek
+    PeekParser.new(self).setName(@name)
+  end
+  #
+  # To create a new parser that succeed only if self fails.
+  # 
+  def not(msg="#{self} unexpected")
+    NotParser.new(self, msg)
+  end
+  #
+  # To create a parser that does "look ahead" for n inputs.
+  # 
+  def lookahead n
+    self
+  end
+  #
+  # To create a parser that fails with a given error message.
+  # 
+  def expect msg
+    ExpectParser.new(self, msg)
+  end
+  #
+  # a.followed b will sequentially run a and b;
+  # result of a is preserved as the ultimate return value.
+  # 
+  def followed(other)
+    FollowedParser.new(self, other)
+  end
+  def_sig :followed, Parser
+  #
+  # To create a parser that repeats self for a minimum _min_ times,
+  # and maximally _max_ times.
+  # Only the return value of the last execution is preserved.
+  # 
+  def repeat_(min, max=min)
+    return Parsers.failure("min=#{min}, max=#{max}") if min > max
+    if(min==max)
+      return Parsers.one if max <= 0
+      return self if max == 1
+      Repeat_Parser.new(self, max)
+    else
+      Some_Parser.new(self, min, max)
+    end
+  end
+  #
+  # To create a parser that repeats self for a minimum _min_ times,
+  # and maximally _max_ times.
+  # All return values are collected in an array.
+  # 
+  def repeat(min, max=min)
+    return Parsers.failure("min=#{min}, max=#{max}") if min > max
+    if(min==max)
+      RepeatParser.new(self, max)
+    else
+      SomeParser.new(self, min, max)
+    end
+  end
+  # 
+  # To create a parser that repeats self for at least _least_ times.
+  # parser.many_ is equivalent to bnf notation "parser*".
+  # Only the return value of the last execution is preserved.
+  # 
+  def many_(least=0)
+    Many_Parser.new(self, least)
+  end
+  # 
+  # To create a parser that repeats self for at least _least_ times.
+  # All return values are collected in an array.
+  # 
+  def many(least=0)
+    ManyParser.new(self, least)
+  end
+  # 
+  # To create a parser that repeats self for at most _max_ times.
+  # Only the return value of the last execution is preserved.
+  # 
+  def some_(max)
+    repeat_(0, max)
+  end
+  # 
+  # To create a parser that repeats self for at most _max_ times.
+  # All return values are collected in an array.
+  # 
+  def some(max)
+    repeat(0, max)
+  end
+  #
+  # To create a parser that repeats self for unlimited times,
+  # with the pattern recognized by _delim_ as separator that separates each occurrence.
+  # self has to match for at least once.
+  # Return values of self are collected in an array.
+  #
+  def separated1 delim
+    rest = delim >> self
+    self.bind do |v0|
+      result = [v0]
+      (rest.map {|v| result << v}).many_ >> value(result)
+    end
+  end
+  #
+  # To create a parser that repeats self for unlimited times,
+  # with the pattern recognized by _delim_ as separator that separates each occurrence.
+  # Return values of self are collected in an array.
+  #
+  def separated delim
+    separated1(delim).plus value([])
+  end
+  #
+  # To create a parser that repeats self for unlimited times,
+  # with the pattern recognized by _delim_ as separator that separates each occurrence
+  # and also possibly ends the pattern.
+  # self has to match for at least once.
+  # Return values of self are collected in an array.
+  #
+  def delimited1 delim
+    rest = delim >> (self.plus Parsers.throwp(:__end_delimiter__))
+    self.bind do |v0|
+      result = [v0]
+      (rest.map {|v| result << v}).many_.catchp(:__end_delimiter__) >> value(result)
+    end
+  end
+  #
+  # To create a parser that repeats self for unlimited times,
+  # with the pattern recognized by _delim_ as separator that separates each occurrence
+  # and also possibly ends the pattern.
+  # Return values of self are collected in an array.
+  #
+  def delimited delim
+    delimited1(delim).plus value([])
+  end
+  #
+  # String representation
+  #
+  def to_s
+    return name unless name.nil?
+    self.class.to_s
+  end
+  # 
+  # a | b will run b when a fails.
+  # b is auto-boxed to Parser when it is not of type Parser.
+  #
+  def | other
+    AltParser.new([self, autobox_parser(other)])
+  end
+  #
+  # a.optional(default) is equivalent to a.plus(value(default))
+  #
+  def optional(default=nil)
+    self.plus(value(default))
+  end
+  #
+  # a.catchp(:somesymbol) will catch the :somesymbol thrown by a.
+  #
+  def catchp(symbol)
+    CatchParser.new(symbol, self)
+  end
+  #
+  # a.fragment will return the string matched by a.
+  #
+  def fragment
+    FragmentParser.new(self)
+  end
+  #
+  # a.nested b will feed the token array returned by parser a to parser b
+  # for a nested parsing.
+  #
+  def nested(parser)
+    NestedParser.new(self, parser)
+  end
+  #
+  # a.lexeme(delim) will parse _a_ for 0 or more times and ignore all
+  # patterns recognized by _delim_.
+  # Values returned by _a_ are collected in an array.
+  #
+  def lexeme(delim = Parsers.whitespaces)
+    delim = delim.many_
+    delim >> self.delimited(delim)
+  end
+  #
+  # For prefix unary operator.
+  # a.prefix op will run parser _op_ for 0 or more times and eventually run parser _a_
+  # for one time.
+  # _op_ should return a Proc that accepts one parameter.
+  # Proc objects returned by _op_ is then fed with the value returned by _a_
+  # from right to left.
+  # The final result is returned as return value.
+  #
+  def prefix(op)
+    Parsers.sequence(op.many, self) do |funcs, v|
+      funcs.reverse_each {|f|v=f.call(v)}
+      v
+    end
+  end
+  #
+  # For postfix unary operator.
+  # a.postfix op will run parser _a_ for once and then _op_ for 0 or more times.
+  # _op_ should return a Proc that accepts one parameter.
+  # Proc objects returned by _op_ is then fed with the value returned by _a_
+  # from left to right.
+  # The final result is returned as return value.
+  #
+  def postfix(op)
+    Parsers.sequence(self, op.many) do |v, funcs|
+      funcs.each{|f|v=f.call(v)}
+      v
+    end
+  end
+  #
+  # For non-associative infix binary operator.
+  # _op_ has to return a Proc that takes two parameters, who
+  # are returned by the _self_ parser as operands.
+  #
+  def infixn(op)
+    bind do |v1|
+      bin = Parsers.sequence(op, self) do |f, v2|
+        f.call(v1,v2)
+      end
+      bin | value(v1)
+    end
+  end
+  #
+  # For left-associative infix binary operator.
+  # _op_ has to return a Proc that takes two parameters, who
+  # are returned by the _self_ parser as operands.
+  #
+  def infixl(op)
+    Parsers.sequence(self, _infix_rest(op, self).many) do |v, rests|
+      rests.each do |r|
+        f, v1 = *r
+        v = f.call(v,v1)
+      end
+      v
+    end
+  end
+  #
+  # For right-associative infix binary operator.
+  # _op_ has to return a Proc that takes two parameters, who
+  # are returned by the _self_ parser as operands.
+  #
+  def infixr(op)
+    Parsers.sequence(self, _infix_rest(op, self).many) do |v, rests|
+      if rests.empty?
+        v
+      else
+        f, seed = *rests.last
+        for i in (0...rests.length-1)
+          cur = rests.length-2-i
+          f1, v1 = *rests[cur]
+          seed = f.call(v1, seed)
+          f = f1
+        end
+        f.call(v, seed)
+      end
+    end
+  end
+  #
+  # a.token(:word_token) will return a Token object when _a_ succeeds.
+  # The matched string (or the string returned by _a_, if any) is
+  # encapsulated in the token, together with the :word_token symbol and
+  # the starting index of the match.
+  #
+  def token(kind)
+    TokenParser.new(kind, self)
+  end
+  #
+  # a.seq b will sequentially run a then b.
+  # The result of b is preserved as return value.
+  # If a block is associated, values returned by _a_ and _b_
+  # are passed into the block and the return value of
+  # the block is used as the final result of the parser.
+  #
+  def seq(other, &block)
+    # TypeChecker.check_arg_type Parser, other, :seq
+    Parsers.sequence(self, other, &block)
+  end
+  def_sig :seq, Parser
+  #
+  # Similar to _seq_. _other_ is auto-boxed if it is not of type Parser.
+  #
+  def >> (other)
+    seq(autobox_parser(other))
+  end
+  private
+  def autobox_parser(val)
+    return Parsers.value(val) unless val.kind_of? Parser
+    val
+  end
+  def _infix_rest(operator, operand)
+    Parsers.sequence(operator, operand, &Idn)
+  end
+  public
+  alias ~ not
+  alias << followed
+  alias * repeat_
+  def_sig :plus, Parser
+  private
+  def _parse(ctxt)
+    false
+  end
+end
+#
+# This module provides all out-of-box parser implementations.
+#
+module Parsers
+  extend Signature
+  #
+  # A parser that always fails with the given error message.
+  #
+  def failure msg
+    FailureParser.new(msg)
+  end
+  #
+  # A parser that always succeeds with the given return value.
+  #
+  def value v
+    ValueParser.new(v)
+  end
+  #
+  # A parser that calls alternative parsers until one succeed,
+  # or any failure with input consumption beyond the current look-ahead.
+  #
+  def sum(*alts)
+    # TypeChecker.check_vararg_type Parser, alts, :sum
+    PlusParser.new(alts)
+  end
+  def_sig :sum, [Parser]
+  
+  #
+  # A parser that calls alternative parsers until one succeeds.
+  #
+  def alt(*alts)
+    AltParser.new(alts)
+  end
+  def_sig :alt, [Parser]
+  #
+  # A parser that succeeds when the given predicate returns true
+  # (with the current input as the parameter).
+  # _expected_ is the error message when _pred_ returns false.
+  #
+  def satisfies(expected, &pred)
+    SatisfiesParser.new(pred, expected)
+  end
+  #
+  # A parser that succeeds when the the current input is equal to the given value.
+  # _expected_ is the error message when _pred_ returns false.
+  #
+  def is(v, expected="#{v} expected")
+    satisfies(expected) {|c|c==v}
+  end
+  #
+  # A parser that succeeds when the the current input is not equal to the given value.
+  # _expected_ is the error message when _pred_ returns false.
+  #
+  def isnt(v, expected="#{v} unexpected")
+    satisfies(expected) {|c|c!=v}
+  end
+  #
+  # A parser that succeeds when the the current input is among the given values.
+  #
+  def among(*vals)
+    expected="one of [#{vals.join(', ')}] expected"
+    vals = as_list vals
+    satisfies(expected) {|c|vals.include? c}
+  end
+  #
+  # A parser that succeeds when the the current input is not among the given values.
+  #
+  def not_among(*vals)
+    expected = "one of [#{vals.join(', ')}] unexpected"
+    vals = as_list vals
+    satisfies(expected) {|c|!vals.include? c}
+  end
+  #
+  # A parser that succeeds when the the current input is the given character.
+  #
+  def char(c)
+    if c.kind_of? Fixnum
+      nm = c.chr
+      is(c, "'#{nm}' expected").setName(nm)
+    else
+      is(c[0], "'#{c}' expected").setName(c)
+    end
+  end
+  #
+  # A parser that succeeds when the the current input is not the given character.
+  #
+  def not_char(c)
+    if c.kind_of? Fixnum
+      nm = c.chr
+      isnt(c, "'#{nm}' unexpected").setName("~#{nm}")
+    else
+      isnt(c[0], "'#{c}' unexpected").setName("~#{c}")
+    end
+  end
+  
+  #
+  # A parser that succeeds when there's no input available.
+  #
+  def eof(expected="EOF expected")
+    EofParser.new(expected).setName('EOF')
+  end
+  #
+  # A parser that tries to match the current inputs one by one
+  # with the given values.
+  # It succeeds only when all given values are matched, in which case all the
+  # matched inputs are consumed.
+  #
+  def are(vals, expected="#{vals} expected")
+    AreParser.new(vals, expected)
+  end
+  #
+  # A parser that makes sure that the given values don't match
+  # the current inputs. One input is consumed if it succeeds.
+  #
+  def arent(vals, expected="#{vals} unexpected")
+    are(vals, '').not(expected) >> any
+  end
+  #
+  # A parser that matches the given string.
+  #
+  def string(str, msg = "\"#{str}\" expected")
+    are(str, msg).setName(str)
+  end
+  #
+  # A parser that makes sure that the current input doesn't match a string.
+  # One character is consumed if it succeeds.
+  #
+  def not_string(str, msg="\"#{str}\" unexpected")
+    string(str).not(msg) >> any
+  end
+  alias str string
+  #
+  # A parser that sequentially run the given parsers.
+  # The result of the last parser is used as return value.
+  # If a block is given, the results of the parsers are passed
+  # into the block as parameters, and the block return value
+  # is used as result instead.
+  #
+  def sequence(*parsers, &proc)
+    # TypeChecker.check_vararg_type Parser, parsers, :sequence
+    SequenceParser.new(parsers, proc)
+  end
+  def_sig :sequence, [Parser]
+  #
+  # A parser that returns the current input index (starting from 0).
+  #
+  def get_index
+    GetIndexParser.new.setName('get_index')
+  end
+  #
+  # A parser that moves the current input pointer to a certain index.
+  #
+  def set_index ind
+    SetIndexParser.new(ind).setName('set_index')
+  end
+  #
+  # A parser that tries all given alternative parsers
+  # and picks the one with the longest match.
+  #
+  def longest(*parsers)
+    # TypeChecker.check_vararg_type Parser, parsers, :longest
+    BestParser.new(parsers, true)
+  end
+  def_sig :longest, [Parser]
+  #
+  # A parser that tries all given alternative parsers
+  # and picks the one with the shortest match.
+  #
+  def shortest(*parsers)
+    # TypeChecker.check_vararg_type Parser, parsers, :shortest
+    BestParser.new(parsers, false)
+  end
+  def_sig :shortest, [Parser]
+  alias shorter shortest
+  alias longer longest
+  #
+  # A parser that consumes one input.
+  #
+  def any
+    AnyParser.new
+  end
+  #
+  # A parser that always fails.
+  #
+  def zero
+    ZeroParser.new
+  end
+  #
+  # A parser that always succeeds.
+  #
+  def one
+    OneParser.new
+  end
+  #
+  # A parser that succeeds if the current input is within a certain range.
+  #
+  def range(from, to, msg="#{as_char from}..#{as_char to} expected")
+    from, to = as_num(from), as_num(to)
+    satisfies(msg) {|c| c <= to && c >= from}
+  end
+  #
+  # A parser that throws a symbol.
+  #
+  def throwp(symbol)
+    ThrowParser.new(symbol)
+  end
+  #
+  # A parser that succeeds if the current inputs match
+  # the given regular expression.
+  # The matched string is consumed and returned as result.
+  #
+  def regexp(ptn, expected="/#{ptn.to_s}/ expected")
+    RegexpParser.new(as_regexp(ptn), expected).setName(expected)
+  end
+  #
+  # A parser that parses a word
+  # (starting with alpha or underscore, followed by 0 or more alpha, number or underscore).
+  # and return the matched word as string.
+  #
+  def word(expected='word expected')
+    regexp(/[a-zA-Z_]\w*/, expected)
+  end
+  #
+  # A parser that parses an integer
+  # and return the matched integer as string.
+  #
+  def integer(expected='integer expected')
+    regexp(/\d+(?!\w)/, expected)
+  end
+  #
+  # A parser that parses a number (integer, or decimal number)
+  # and return the matched number as string.
+  #
+  def number(expected='number expected')
+    regexp(/\d+(\.\d+)?/, expected)
+  end
+  #
+  # A parser that matches the given string, case insensitively.
+  #
+  def string_nocase(str, expected="'#{str}' expected")
+    StringCaseInsensitiveParser.new(str, expected).setName(str)
+  end
+  #
+  # A parser that succeeds when the current input
+  # is a token with one of the the given token kinds.
+  # If a block is given, the token text is passed to the block
+  # as parameter, and the block return value is used as result.
+  # Otherwise, the token object is used as result.
+  #
+  def token(*kinds, &proc)
+    expected="#{kinds.join(' or ')} expected"
+    recognizer = nil
+    if kinds.length==1
+      kind = kinds[0]
+      recognizer = satisfies(expected) do |tok|
+        tok.respond_to? :kind, :text and kind == tok.kind
+      end
+    else
+      recognizer = satisfies(expected) do |tok|
+        tok.respond_to? :kind, :text and kinds.include? tok.kind
+      end
+    end
+    recognizer = recognizer.map{|tok|proc.call(tok.text)} if proc
+    recognizer
+  end
+  #
+  # A parser that parses a white space character.
+  #
+  def whitespace(expected="whitespace expected")
+    satisfies(expected) {|c| Whitespaces.include? c}
+  end
+  #
+  # A parser that parses 1 or more white space characters.
+  #
+  def whitespaces(expected="whitespace(s) expected")
+    whitespace(expected).many_(1)
+  end
+  #
+  # A parser that parses a line started with _start_.
+  # nil is the result.
+  #
+  def comment_line start
+    string(start) >> not_char(?\n).many_ >> char(?\n).optional >> value(nil)
+  end
+  #
+  # A parser that parses a chunk of text started with _open_
+  # and ended by _close_.
+  # nil is the result.
+  #
+  def comment_block open, close
+    string(open) >> not_string(close).many_ >> string(close) >> value(nil)
+  end
+  #
+  # A lazy parser, when executed, calls the given block
+  # to get a parser object and delegate the call to this lazily
+  # instantiated parser.
+  #
+  def lazy(&block)
+    LazyParser.new(block)
+  end
+  #
+  # A parser that watches the current parser result without changing it.
+  # The following assert will succeed:
+  ##
+  # char(?a) >> watch{|x|assert_equal(?a, x)}
+  ##
+  # watch can also be used as a handy tool to print trace information,
+  # for example:
+  ##
+  # some_parser >> watch {puts "some_parser succeeded."}
+  #
+  def watch(&block)
+    return one unless block
+    WatchParser.new(block)
+  end
+  #
+  # A parser that watches the current parser result without changing it.
+  # The following assert will succeed:
+  ##
+  # char(?a).repeat(2) >> watchn{|x,y|assert_equal([?a,?a], [x,y])}
+  ##
+  # Slightly different from _watch_, _watchn_ expands the current parser result
+  # before passing it into the associated block.
+  #
+  def watchn(&block)
+    return one unless block
+    WatchnParser.new(block)
+  end
+  # 
+  # A parser that maps current parser result to a new result using
+  # the given block.
+  ##
+  # Different from Parser#map, this method does not need to be combined
+  # with any Parser object. It is rather an independent Parser object
+  # that maps the _current_ parser result.
+  ##
+  # parser1.map{|x|...} is equivalent to parser1 >> map{|x|...}
+  #
+  def map(&block)
+    return one unless block
+    MapCurrentParser.new(block)
+  end
+  # 
+  # A parser that maps current parser result to a new result using
+  # the given block. If the current parser result is an array, the array
+  # elements are expanded and then passed as parameters to the block.
+  ##
+  # Different from Parser#mapn, this method does not need to be combined
+  # with any Parser object. It is rather an independent Parser object
+  # that maps the _current_ parser result.
+  ##
+  # parser1.mapn{|x,y|...} is equivalent to parser1 >> mapn{|x,y|...}
+  #
+  def mapn(&block)
+    return one unless block
+    MapnCurrentParser.new(block)
+  end
+  private
+  #
+  # characters considered white space.
+  #
+  Whitespaces = " \t\r\n"
+  def as_regexp ptn
+    case ptn when String: Regexp.new(ptn) else ptn end
+  end
+  def as_char c
+    case c when String: c else c.chr end
+  end
+  def as_num c
+    case c when String: c[0] else c end
+  end
+  def as_list vals
+    return vals unless vals.length==1
+    val = vals[0]
+    return vals unless val.kind_of? String
+    val
+  end
+  extend self
+end
+