citrus 1.0.0

data/README

@@ -0,0 +1,86 @@
+
+
+                                  ~* Citrus *~
+
+                          Parsing Expressions for Ruby
+
+
+Citrus is a compact and powerful parsing library for Ruby that combines the
+elegance and expressiveness of the language with the simplicity and power of
+parsing expression grammars.
+
+Citrus grammars look very much like Treetop grammars but take a completely
+different approach. Instead of generating parsers from your grammars, Citrus
+evaluates grammars and rules in memory as Ruby modules. In fact, you can even
+define your grammars as Ruby modules in the first place, entirely skipping the
+parsing/evaluation step.
+
+Terminals are represented as either strings or regular expressions. Support for
+sequences, choices, labels, repetition, and lookahead (both positive and
+negative) are all included, as well as character classes and the dot-matches-
+anything symbol.
+
+To try it out, fire up an IRB session from the root of the project and run one
+of the examples.
+
+    $ irb -Ilib
+    > require 'citrus'
+     => true
+    > Citrus.load 'examples/calc'
+     => [Calc]
+    > match = Calc.parse '1 + 5'
+     => #<Citrus::Match ...
+    > match.value
+     => 6
+
+Be sure to try requiring `citrus/debug' (instead of just `citrus') if you'd like
+some better visualization of the match results.
+
+The code base is very small and it's well-documented and tested, so it should be
+fairly easy to understand for anyone who is familiar with parsing expressions.
+
+
+  ** Links **
+
+
+http://pdos.csail.mit.edu/~baford/packrat/
+http://en.wikipedia.org/wiki/Parsing_expression_grammar
+http://treetop.rubyforge.org/index.html
+
+
+  ** Installation **
+
+
+Via RubyGems:
+
+    $ sudo gem install citrus
+
+From a local copy:
+
+    $ git clone git://github.com/mjijackson/citrus.git
+    $ cd citrus
+    $ rake package && sudo rake install
+
+
+  ** License **
+
+
+Copyright 2010 Michael Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,67 @@
+require 'rake/clean'
+require 'rake/testtask'
+
+task :default => :test
+
+# TESTS #######################################################################
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/*_test.rb']
+end
+
+# DOCS ########################################################################
+
+desc "Generate API documentation"
+task :api => 'lib/citrus.rb' do |t|
+  output_dir = ENV['OUTPUT_DIR'] || 'api'
+  rm_rf output_dir
+  sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
+  hanna
+    --op #{output_dir}
+    --promiscuous
+    --charset utf8
+    --fmt html
+    --inline-source
+    --line-numbers
+    --accessor option_accessor=RW
+    --main Citrus
+    --title 'Citrus API Documentation'
+    #{t.prerequisites.join(' ')}
+  SH
+end
+
+CLEAN.include 'api'
+
+# PACKAGING & INSTALLATION ####################################################
+
+if defined?(Gem)
+  $spec = eval("#{File.read('citrus.gemspec')}")
+
+  directory 'dist'
+
+  def package(ext='')
+    "dist/#{$spec.name}-#{$spec.version}" + ext
+  end
+
+  file package('.gem') => %w< dist > + $spec.files do |f|
+    sh "gem build citrus.gemspec"
+    mv File.basename(f.name), f.name
+  end
+
+  file package('.tar.gz') => %w< dist > + $spec.files do |f|
+    sh "git archive --format=tar HEAD | gzip > #{f.name}"
+  end
+
+  desc "Build packages"
+  task :package => %w< .gem .tar.gz >.map {|e| package(e) }
+
+  desc "Build and install as local gem"
+  task :install => package('.gem') do |t|
+    sh "gem install #{package('.gem')}"
+  end
+
+  desc "Upload gem to rubygems.org"
+  task :release => package('.gem') do |t|
+    sh "gem push #{package('.gem')}"
+  end
+end

data/citrus.gemspec

@@ -0,0 +1,29 @@
+Gem::Specification.new do |s|
+  s.name = 'citrus'
+  s.version = '1.0.0'
+  s.date = '2010-05-13'
+
+  s.summary = 'Parsing Expressions for Ruby'
+  s.description = 'Parsing Expressions for Ruby'
+
+  s.author = 'Michael Jackson'
+  s.email = 'mjijackson@gmail.com'
+
+  s.require_paths = %w< lib >
+
+  s.files = Dir['lib/**/*.rb'] +
+    Dir['examples/**/*'] +
+    Dir['test/*.rb'] +
+    %w< citrus.gemspec Rakefile README >
+
+  s.test_files = s.files.select {|path| path =~ /^test\/.*_test.rb/ }
+
+  s.add_dependency('builder')
+  s.add_development_dependency('rake')
+
+  s.has_rdoc = true
+  s.rdoc_options = %w< --line-numbers --inline-source --title Citrus --main Citrus >
+  s.extra_rdoc_files = %w< README >
+
+  s.homepage = 'http://github.com/mjijackson/citrus'
+end

data/examples/calc.citrus

@@ -0,0 +1,103 @@
+# A grammar for mathematical formulas that apply the basic four operations to
+# non-negative numbers (integers and floats), respecting operator precedence and
+# ignoring whitespace.
+grammar Calc
+  rule term
+    (additive | factor) {
+      def value
+        first.value
+      end
+    }
+  end
+
+  rule additive
+    (factor operator:additive_op term) {
+      def value
+        operator.apply(factor.value, term.value)
+      end
+    }
+  end
+
+  rule factor
+    (multiplicative | primary) {
+      def value
+        first.value
+      end
+    }
+  end
+
+  rule multiplicative
+    (primary operator:multiplicative_op factor) {
+      def value
+        operator.apply(primary.value, factor.value)
+      end
+    }
+  end
+
+  rule primary
+    (term_paren | number) {
+      def value
+        first.value
+      end
+    }
+  end
+
+  rule term_paren
+    (lparen term rparen) {
+      def value
+        term.value
+      end
+    }
+  end
+
+  rule additive_op
+    (plus | minus) {
+      def apply(factor, term)
+        text.strip == '+' ? factor + term : factor - term
+      end
+    }
+  end
+
+  rule multiplicative_op
+    (star | slash) {
+      def apply(primary, factor)
+        text.strip == '*' ? primary * factor : primary / factor
+      end
+    }
+  end
+
+  rule number
+    (float | integer) {
+      def value
+        first.value
+      end
+    }
+  end
+
+  rule float
+    ([0-9]+ '.' [0-9]+ space) {
+      def value
+        text.strip.to_f
+      end
+    }
+  end
+
+  rule integer
+    ([0-9]+ space) {
+      def value
+        text.strip.to_i
+      end
+    }
+  end
+
+  rule lparen  '(' space  end
+  rule rparen  ')' space  end
+  rule plus    '+' space  end
+  rule minus   '-' space  end
+  rule star    '*' space  end
+  rule slash   '/' space  end
+
+  rule space
+    [ \t\n\r]*
+  end
+end

data/examples/calc.rb

@@ -0,0 +1,95 @@
+require 'citrus'
+
+# A grammar for mathematical formulas that apply the basic four operations to
+# non-negative numbers (integers and floats), respecting operator precedence and
+# ignoring whitespace.
+module Calc
+  include Citrus::Grammar
+
+  module FirstValue
+    def value
+      first.value
+    end
+  end
+
+  rule :term do
+    ext(any(:additive, :factor), FirstValue)
+  end
+
+  rule :additive do
+    all(:factor, label(:additive_op, :operator), :term) {
+      def value
+        operator.apply(factor.value, term.value)
+      end
+    }
+  end
+
+  rule :factor do
+    ext(any(:multiplicative, :primary), FirstValue)
+  end
+
+  rule :multiplicative do
+    all(:primary, label(:multiplicative_op, :operator), :factor) {
+      def value
+        operator.apply(primary.value, factor.value)
+      end
+    }
+  end
+
+  rule :primary do
+    ext(any(:term_paren, :number), FirstValue)
+  end
+
+  rule :term_paren do
+    all(:lparen, :term, :rparen) {
+      def value
+        term.value
+      end
+    }
+  end
+
+  rule :additive_op do
+    any(:plus, :minus) {
+      def apply(factor, term)
+        text.strip == '+' ? factor + term : factor - term
+      end
+    }
+  end
+
+  rule :multiplicative_op do
+    any(:star, :slash) {
+      def apply(primary, factor)
+        text.strip == '*' ? primary * factor : primary / factor
+      end
+    }
+  end
+
+  rule :number do
+    ext(any(:float, :integer), FirstValue)
+  end
+
+  rule :float do
+    all(/[0-9]+/, '.', /[0-9]+/, :space) {
+      def value
+        text.strip.to_f
+      end
+    }
+  end
+
+  rule :integer do
+    all(/[0-9]+/, :space) {
+      def value
+        text.strip.to_i
+      end
+    }
+  end
+
+  rule :lparen, ['(', :space]
+  rule :rparen, [')', :space]
+  rule :plus,   ['+', :space]
+  rule :minus,  ['-', :space]
+  rule :star,   ['*', :space]
+  rule :slash,  ['/', :space]
+
+  rule :space,  /[ \t\n\r]*/
+end

data/examples/calc_sugar.rb

@@ -0,0 +1,94 @@
+require 'citrus/sugar'
+
+# A grammar for mathematical formulas that apply the basic four operations to
+# non-negative numbers (integers and floats), respecting operator precedence and
+# ignoring whitespace.
+Calc = Citrus::Grammar.new {
+
+  module FirstValue
+    def value
+      first.value
+    end
+  end
+
+  rule term do
+    ext(any(additive, factor), FirstValue)
+  end
+
+  rule additive do
+    all(factor, label(additive_op, operator), term) {
+      def value
+        operator.apply(factor.value, term.value)
+      end
+    }
+  end
+
+  rule factor do
+    ext(any(multiplicative, primary), FirstValue)
+  end
+
+  rule multiplicative do
+    all(primary, label(multiplicative_op, operator), factor) {
+      def value
+        operator.apply(primary.value, factor.value)
+      end
+    }
+  end
+
+  rule primary do
+    ext(any(term_paren, number), FirstValue)
+  end
+
+  rule term_paren do
+    all(lparen, term, rparen) {
+      def value
+        term.value
+      end
+    }
+  end
+
+  rule additive_op do
+    any(plus, minus) {
+      def apply(factor, term)
+        text.strip == '+' ? factor + term : factor - term
+      end
+    }
+  end
+
+  rule multiplicative_op do
+    any(star, slash) {
+      def apply(primary, factor)
+        text.strip == '*' ? primary * factor : primary / factor
+      end
+    }
+  end
+
+  rule number do
+    ext(any(float, integer), FirstValue)
+  end
+
+  rule float do
+    all(/[0-9]+/, '.', /[0-9]+/, space) {
+      def value
+        text.strip.to_f
+      end
+    }
+  end
+
+  rule integer do
+    all(/[0-9]+/, space) {
+      def value
+        text.strip.to_i
+      end
+    }
+  end
+
+  rule lparen, ['(', space]
+  rule rparen, [')', space]
+  rule plus,   ['+', space]
+  rule minus,  ['-', space]
+  rule star,   ['*', space]
+  rule slash,  ['/', space]
+
+  rule space,  /[ \t\n\r]*/
+}