pratt_parser 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e0997841c5a281d0c96da0544ba921381e27bf0
-  data.tar.gz: bd6594ea8c4174a973c62270e1c06d17edb45db8
+  metadata.gz: 26194f8a48f5f675a6f72f56f0e7759a8b65befa
+  data.tar.gz: d6c21b23737c64c889f78798b5bacd4c150aa6f3
 SHA512:
-  metadata.gz: 2c9fea5f8b437b4b6a1487d3b5123eab152f7a1aa068ba5ded4340f52a69adb9353419cabc07f275bb4012916248a60aa28b3fe196a546e49a09682cec52c6d5
-  data.tar.gz: fb381c4cf7553639cfa6d4581d0101c62a90cc0603a29629bb5b16550567f624d75185ec1943de14233caa5ff9f7b88426aaf8958d9121fcb3cdacd558f24fb6
+  metadata.gz: 61f4baf7f9cacdd579dceaf19e861eca48f56a94256ad942f11d24cb0075ae08c428818cda0a53419f26b3a11d699952f7e619e67c88ea3cc1531551bfd30199
+  data.tar.gz: 08aaae2ea30912fbe9d52ae9860ebd870440d3772a4cda43bf8c0b64566a450872ca9ad83aad295229988637738144ab5279d80a77994e54e65c727af11ef45d

data/{CHANGELOG → CHANGELOG.md}

@@ -1,3 +1,7 @@
+## 0.1.1 ##
+
+  * Better rdoc-compliant comments.
+
 ## 0.1.0 ##
 
   * Add postfix factorial operator to examples.

data/lib/pratt_parser.rb

@@ -1,40 +1,53 @@
-# A Pratt parser.  Similar to a recursive decent parser but instead of
+# A Pratt parser.  Similar to a recursive descent parser but instead of
 # coding a function for each production, the syntax is coded in a set
 # of token objects that are yielded by the lexer.  New operators and
-# statements can be slipped in to the language with the proper
+# statements can be slipped into the language with the proper
 # precedence by adding new token objects to the lexer without altering
 # the code for existing tokens.  Pretty cool.
 #
-# lexer is an enumerator with an each method that returns token objects
-# with three methods:
-# lbp: return the operator precedence.  Higher numbers bind more tightly.
-# nud(parser): called when the token is the first token in an expression,
-#   including a recursive call to expresssion (i.e., subexpression).  For
-#   Example, this would be called for a unary operator, a literal, or for
-#   the "if" in the construct "if <cond> then <expr>".
-#   It is the token's responsibility to call parser.expression, parser.expect,
-#   and/or parser.if? to handle the remainder of the expression, if any.
-# led(parser, left): called when the token is preceeded by a subexpression,
-#   left.  The token may be postfix or infix.
-#   It is the token's responsibility to call parser.expression, parser.expect,
-#   and/or parser.if? to handle the remainder of the expression, if any,
-#   and combine it with left.
-# Only lbp is mandatory.  nud and led will be called only when necessary, if
-# ever.
-# nud and lcd can call parser.expression(rbp) to recursively parse the
-# right expression.  rbp should be the token's lbp for left-associativity,
-# lbp-1 for right.
+# lexer is must have an +#each+ method that returns token objects.  A token
+# has three methods:
+# lbp::
+#   Returns the operator precedence.  Higher numbers bind more tightly.
+# nud(parser)::
+#   Called when the token is the first token in an expression,
+#   including a recursive call to +expresssion+ (i.e., subexpression).
+#   For example, +nud+ would be called for a unary operator, a literal,
+#   or for the "if" in the construct "if <cond> then <expr>".  It is
+#   the token's responsibility to call +parser.expression+,
+#   +parser.expect+, and/or =parser.if?+ to handle the remainder of the
+#   (sub)expression, if any.
+# led(parser, left)::
+#   Called when the token is preceeded by a subexpression, passed in
+#   as +left+.  The token may be postfix or infix.  It is the token's
+#   responsibility to call +parser.expression+, +parser.expect+,
+#   and/or +parser.if?+ to handle the remainder of the expression, if
+#   any, and combine it with +left+.
 #
-# PrattParser.new(lexer).eval will return the result of the parse.
+# Only +lbp+ is mandatory.  +nud+ and +led+ will be called only when
+# necessary, if ever.  For example, +nud+ will never be called for a
+# strictly infix token. If the token appears at the start of a
+# (sub)expression then an exception that isn't at al appropriate
+# to the abstraction will be thrown.
+#
+# +nud+ and +led+ can call +parser.expression+(+rbp+) to recursively
+# parse the right subexpression.  +rbp+ should be the token's +lbp+ for
+# left-associativity, +lbp-1+ for right.
+#
+# "PrattParser.new(lexer).eval" will return the result of the parse.
 #
 # Syntax errors aren't handled at the moment and will cause ridiculous
-# exceptions to be raised such as NoMethodError.
-
-# http://javascript.crockford.com/tdop/tdop.html
-# http://effbot.org/zone/simple-top-down-parsing.htm
-# http://journal.stuffwithstuff.com/2011/03/19/pratt-parsers-expression-parsing-made-easy/
+# exceptions to be raised such as +NoMethodError+.
+#
+# Further reading:
+# * http://javascript.crockford.com/tdop/tdop.html
+# * http://effbot.org/zone/simple-top-down-parsing.htm
+# * http://journal.stuffwithstuff.com/2011/03/19/pratt-parsers-expression-parsing-made-easy/
 
 class PrattParser
+  # Creates a new +PrattParser+.  +lexer+ is an +Enumerable+, or something
+  # with an +#each+ method.
+  #
   def initialize(lexer)
     @lexer = Enumerator.new do |y|
       lexer.each do |token|
@@ -46,11 +59,18 @@ class PrattParser
     @token = nil
   end
 
+  # Runs the tokens through the parse engine and returns the result,
+  # or throws some exception on parse error.
+  #
   def eval
     @token = @lexer.next
     expression(0)
   end
 
+  # For use by token +#led+ methods to parse subexpressions with
+  # binding power less than +rbp+.  Whatever that means.  Don't worry,
+  # it just does the Right Thing.
+  #
   def expression(rbp)
     t = @token
     @token = @lexer.next
@@ -63,6 +83,17 @@ class PrattParser
     left
   end
 
+  # Checks whether the lookahead token is of the
+  # +expected_token_class+ and raises an exception if it isn't.
+  # Alternatively a block may be given; the block is passed the
+  # lookahead token and should raise an exception if it's not an
+  # expected token.  In either case if no exception is raised then the
+  # lookahead token is consumed.
+  #
+  # +expect+ can be used to match the
+  # right parenthesis in a parenthesized expression, the colon in a
+  # "cond ? then : else" expression, etc.
+  #
   def expect(expected_token_class = nil, &block)
     block ||= lambda do |token|
       if token.class != expected_token_class
@@ -73,6 +104,15 @@ class PrattParser
     @token = @lexer.next
   end
 
+  # Checks whether the lookahead token is of the
+  # +token_class+.  If it is, consumes the lookahead token
+  # and returns truthy, else just returns falsy.
+  # Alternatively a block can be given which is passed the token
+  # and should return truthy or falssy.
+  #
+  # +if?+ can be used for optional tokens such as the +else+
+  # clause in "if cond then val1 [else val2] end".
+  #
   def if?(token_class, &block)
     block ||= lambda do |token|
       token.class == token_class

data/pratt_parser.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |gem|
   gem.test_files       = `git ls-files -- spec/*`.split("\n")
   gem.name             = "pratt_parser"
   gem.require_paths    = ["lib"]
-  gem.version          = "0.1.0"
+  gem.version          = "0.1.1"
   gem.license          = "MIT"
   # Needs Enumerator which was added in 1.9.
   gem.required_ruby_version = ">= 1.9"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pratt_parser
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Tom May
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-26 00:00:00.000000000 Z
+date: 2015-02-28 00:00:00.000000000 Z
 dependencies: []
 description: A Pratt parser.  Create token objects to define your language.  Create
   a lexer to return tokens.  Call the parser to grok the language.
@@ -20,7 +20,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
-- CHANGELOG
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.md