sexpr 0.2.0 → 0.3.0

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 0.3.0 / 2012-02-21
+
+* Breaking changes
+
+  * `Sexpr.load` only takes one argument, merging both the rules and the options inside a
+    unique Hash object (or something coercible to a Hash, such as YAML).
+  * The YAML grammar format now requires rules to be specified under a "rules" entry. See
+    the README for an example.
+
+* Major enhancements
+
+  * A lexical parser can now be specified under a "parser" entry. Only Citrus is supported
+    for now.
+  * A loaded grammar (i.e. returned by `Sexpr.load`) is now a module. Therefore assigning
+    the result to a constant makes perfect sense and benefits from the ruby's magic naming
+    feature.
+  * A loaded grammar now respond to a :sexpr method that parses (if needed) and returns a
+    s-expression. The latter, and all its sub-expressions are automatically tagged with the
+    Sexpr module, as well as with user-defined modules. The latter are automatically discovered
+    with a convention over configuration heuristics that associates rule names to module names.
+    That convention may however be overridden with specific grammar methods (see the BoolExpr
+    example).
+
 # 0.2.0 / 2012-02-21
 
 * Enhancements
@@ -10,4 +33,4 @@
 
 * Enhancements
 
-  * Birthday!
+  * Birthday!

data/Gemfile

@@ -2,6 +2,7 @@ source 'http://rubygems.org'
 
 group :development do
   gem "epath", "~> 0.0.1"
+  gem "citrus", "~> 2.4"
   gem "rake", "~> 0.9.2"
   gem "rspec", "~> 2.8.0"
   gem "wlang", "~> 0.10.2"

data/Gemfile.lock

@@ -1,6 +1,7 @@
 GEM
   remote: http://rubygems.org/
   specs:
+    citrus (2.4.1)
     diff-lcs (1.1.3)
     epath (0.0.1)
     rake (0.9.2.2)
@@ -19,6 +20,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  citrus (~> 2.4)
   epath (~> 0.0.1)
   rake (~> 0.9.2)
   rspec (~> 2.8.0)

data/LICENCE.md

@@ -19,4 +19,4 @@
     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.
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -5,6 +5,7 @@ CHANGELOG.md
 Gemfile
 Gemfile.lock
 bin/**/*
+examples/**/*
 lib/**/*
 LICENCE.md
 Manifest.txt

data/README.md

@@ -4,43 +4,58 @@ A ruby compilation framework around s-expressions.
 
 ## Example
 
+    # Let load a grammar defined in YAML
     grammar = SexpGrammar.load(<<-YAML)
-
-      # alternative rule
-      bool_expr:
-        - bool_and
-        - bool_or
-        - bool_not
-        - var_ref
-        - literal
-
-      # non-terminal
-      bool_and:
-        - [ bool_expr, bool_expr ]
-      bool_or:
-        - [ bool_expr, bool_expr ]
-      bool_not:
-        - [ bool_expr ]
-      literal:
-        - [ truth_value ]
-      var_ref:
-        - [ var_name ]
-
-      # terminals
-      var_name:
-        !ruby/regexp /^[a-z]+$/
-      truth_value:
-        - true
-        - false
-
+      rules:
+        # alternative rule
+        bool_expr:
+          - bool_and
+          - bool_or
+          - bool_not
+          - var_ref
+          - bool_lit
+
+        # non-terminal
+        bool_and:
+          - [ bool_expr, bool_expr ]
+        bool_or:
+          - [ bool_expr, bool_expr ]
+        bool_not:
+          - [ bool_expr ]
+        bool_lit:
+          - [ truth_value ]
+        var_ref:
+          - [ var_name ]
+
+        # terminals
+        var_name:
+          !ruby/regexp /^[a-z]+$/
+        truth_value:
+          - true
+          - false
     YAML
 
-    grammar === [:bool_and, [:bool_not, [:var_ref, "x"]], [:literal, true]]
+### Checking the structure of s-expressions
+
+    # the grammar can be used to verify the structure of s-expressions
+    grammar === [:bool_and, [:bool_not, [:var_ref, "x"]], [:bool_lit, true]]
     # => true
 
-    grammar === [:bool_and, [:literal, "true"]]
+    grammar === [:bool_and, [:bool_lit, "true"]]
     # => false (second term is missing)
 
+### Including s-expression tools
+
+    # the grammar can also be used to automatically have support on top of
+    # such s-expressions
+    expr = grammar.sexpr([:bool_lit, true])
+
+    expr.sexpr_type
+    # => :bool_lit
+
+    expr.sexpr_body
+    # => [true]
+
 ## Links
 
-https://github.com/blambeau/sexpr
+https://github.com/blambeau/sexpr

data/examples/bool_expr/bool_expr.citrus

@@ -0,0 +1,72 @@
+#
+# This is a Citrus grammar for boolean expressions.
+#
+# The parser is automatically loaded under the BoolExpr::Parser constant by Citrus
+# itself. It is also automatically registered under BoolExpr::Grammar.parser by
+# `Sexpr.load` when invoked on the bool_expr.sexp.yml file.
+#
+# The coupon codes returns s-expressions that correctly refer to the abstract grammar
+# definition in that file (AST).
+#
+grammar BoolExpr::Parser
+
+  rule bool_expr
+    bool_or
+  end
+
+  rule bool_or
+      (l:bool_and spaces 'or' spaces r:bool_or){
+        [:bool_or, l.value, r.value]
+      }
+    | bool_and
+  end
+
+  rule bool_and
+      (l:bool_not spaces 'and' spaces r:bool_and){
+        [:bool_and, l.value, r.value]
+      }
+    | bool_not
+  end
+
+  rule bool_not
+      ('not' spacing e:bool_not){
+        [:bool_not, e.value]
+      }
+    | bool_term
+  end
+
+  rule bool_term
+    bool_paren | bool_lit | var_ref
+  end
+
+  rule bool_paren
+    ('(' spacing e:bool_or spacing ')'){
+      e.value
+    }
+  end
+
+  rule bool_lit
+    ("true" | "false"){ 
+      [:bool_lit, ::Kernel.eval(strip) ]
+    }
+  end
+
+  rule var_ref
+    (!(keyword spacing) [a-z]+){
+      [:var_ref, strip]
+    }
+  end
+
+  rule spacing
+    [ \t]+ | &'(' | !.
+  end
+
+  rule spaces
+    [ \t]+
+  end
+  
+  rule keyword
+    "true" | "false" | "or" | "and" | "not"
+  end
+
+end

data/examples/bool_expr/bool_expr.rb

@@ -0,0 +1,86 @@
+require 'sexpr'
+
+# Let load the grammar from the .yml definition file.
+BoolExpr = Sexpr.load File.expand_path('../bool_expr.sexp.yml', __FILE__)
+
+# A Sexpr grammar is simply a module. Ruby allows us to re-open it later.
+module BoolExpr
+
+  # These are the modules automatically installed on the s-expressions
+  # that the grammar produces
+  module And;     end
+  module Or;      end
+  module Not;     end
+  module Lit;     end
+  module VarRef;  end
+
+  # The two following methods allows converting rule names (e.g. bool_and)
+  # to module names (And). A default implementation is provided by Sexpr
+  # that enforces convention over configuration (BoolAnd <-> bool_and). We
+  # override the methods here for the sake of the example/documentation.
+
+  def rule2modname(rule)
+    (rule.to_s =~ /^bool_(.*)$/) ? $1.capitalize.to_sym : super
+  end
+
+  def mod2rulename(mod)
+    rule = super
+    (rule.to_s =~ /^bool_(.*)$/) ? const_get($1.to_sym) : rule
+  end
+
+end
+
+describe BoolExpr do
+  subject{ BoolExpr }
+
+  describe "the parsing feature" do
+
+    it 'parses boolean expressions without error' do
+      subject.parse("x and y").should be_a(Citrus::Match)
+    end
+
+    it 'provides a shortcut to get s-expressions directly' do
+      subject.sexpr("x and y").should eq([:bool_and, [:var_ref, "x"], [:var_ref, "y"]])
+    end
+
+  end # parsing
+
+  describe "the tagging feature" do
+
+    it 'tags parsing results with the Sexpr module' do
+      sexpr = subject.sexpr("x and y")
+      sexpr.should be_a(Sexpr)
+      sexpr.sexpr_type.should eq(:bool_and)
+      sexpr.sexpr_body.should eq([[:var_ref, "x"], [:var_ref, "y"]])
+    end
+
+    it 'tags parsing results with user modules' do
+      subject.sexpr("x and y").should be_a(BoolExpr::And)
+    end
+
+    it 'allows tagging manually' do
+      subject.sexpr([:bool_lit, true]).should be_a(BoolExpr::Lit)
+    end
+
+    it 'applies tagging recursively' do
+      sexpr = subject.sexpr([:bool_not, [:bool_lit, true]])
+      sexpr.last.should be_a(BoolExpr::Lit)
+    end
+
+  end # taggging
+
+  describe 'the validation feature' do
+
+    it 'validates s-expressions' do
+      subject.match?([:bool_lit, true]).should be_true
+      subject.match?([:bool_lit, "x"]).should be_false
+    end
+
+    it 'validates s-expressions against specific rules' do
+      subject[:bool_lit].match?([:bool_lit, true]).should be_true
+      subject[:bool_and].match?([:bool_lit, true]).should be_false
+    end
+
+  end # validating
+
+end if defined?(RSpec)

data/examples/bool_expr/bool_expr.sexp.yml

@@ -0,0 +1,23 @@
+parser:
+  bool_expr.citrus
+rules:
+  bool_expr:
+    - bool_and
+    - bool_or
+    - bool_not
+    - var_ref
+    - bool_lit
+  bool_and:
+    - [ bool_expr+ ]
+  bool_or:
+    - [ bool_expr+ ]
+  bool_not:
+    - [ bool_expr ]
+  bool_lit:
+    - [ literal ]
+  var_ref:
+    - [ var_name ]
+  var_name:
+    !ruby/regexp /^[a-z]+$/
+  literal:
+    [true, false]

data/lib/sexpr.rb

@@ -1,31 +1,38 @@
 require_relative "sexpr/version"
 require_relative "sexpr/loader"
+require_relative "sexpr/errors"
 #
 # A helper to manipulate sexp grammars
 #
 module Sexpr
 
-  def self.load(input, options = {})
-    case input
-    when lambda{|x| x.respond_to?(:to_path)}
-      require 'yaml'
-      load(YAML.load_file(input.to_path), options)
-    when String
-      require 'yaml'
-      load(YAML.load(input), options)
-    when Hash
-      Grammar.new(input, options)
-    else
-      raise ArgumentError, "Invalid argument for Sexpr::Grammar: #{input}"
-    end
+  PathLike = lambda{|x|
+    x.respond_to?(:to_path) or (x.is_a?(String) and File.exists?(x))
+  }
+
+  def self.load(input)
+    defn = case input
+            when PathLike
+              require 'yaml'
+              path = input.respond_to?(:to_path) ? input.to_path : input.to_s
+              YAML.load_file(path).merge(:path => input)
+            when String
+              require 'yaml'
+              YAML.load(input)
+            when Hash
+              input
+            else
+              raise ArgumentError, "Invalid argument for Sexpr::Grammar: #{input}"
+            end
+    Grammar.new defn
+  end
+
+  def self.sexpr(arg)
+    Object.new.extend(Sexpr::Grammar::Tagging).sexpr(arg)
   end
 
 end # module Sexpr
+require_relative "sexpr/node"
 require_relative "sexpr/grammar"
-require_relative "sexpr/element"
-require_relative "sexpr/alternative"
-require_relative "sexpr/many"
-require_relative "sexpr/reference"
-require_relative "sexpr/rule"
-require_relative "sexpr/sequence"
-require_relative "sexpr/terminal"
+require_relative "sexpr/matcher"
+require_relative "sexpr/parser"

data/lib/sexpr/errors.rb

@@ -0,0 +1,15 @@
+module Sexpr
+
+  class Error < StandardError
+  end
+
+  class UnrecognizedParserError < Error
+  end
+
+  class InvalidParseSourceError < Error
+  end
+
+  class NoParserError < Error
+  end
+
+end

data/lib/sexpr/grammar.rb

@@ -1,82 +1,26 @@
+require_relative 'grammar/options'
+require_relative 'grammar/matching'
+require_relative 'grammar/parsing'
+require_relative 'grammar/tagging'
 module Sexpr
-  class Grammar
-
-    attr_reader :rules, :options
-
-    def initialize(rules = {}, options = {})
-      @rules   = compile_rules(rules)
-      @options = options
-    end
-
-    def [](rule_name)
-      @rules[rule_name]
-    end
-
-    def root
-      @root ||= begin
-        root = options[:root] || rules.keys.first
-        root = self[root] if root.is_a?(Symbol)
-      end
-    end
-
-    def parser
-      options[:parser]
-    end
-
-    def parse(input)
-      case input
-      when lambda{|x| x.respond_to?(:to_path)}
-        parse(File.read(input.to_path))
-      when IO
-        parse(input.read)
-      when String
-        unless p = parser
-          raise NoParserError, "No parser set.", caller
-        end
-        p.parse(input).value
-      end
-    end
-
-    def match?(sexp)
-      root.match?(sexp)
-    end
-    alias :=== :match?
-
-    private
-
-    def compile_rules(rules)
-      Hash[rules.map{|k,v|
-        [k.to_sym, compile_rule(k.to_sym, v)]
-      }]
-    end
-
-    def compile_rule(name, defn)
-      case rule = compile_rule_defn(defn)
-      when Terminal, Alternative
-        rule
-      else
-        Rule.new(name, rule)
-      end
-    end
-
-    def compile_rule_defn(arg)
-      case arg
-      when Element
-        arg
-      when Regexp, TrueClass, FalseClass, NilClass
-        Terminal.new arg
-      when lambda{|x| x.is_a?(Array) && x.size == 1 && x.first.is_a?(Array)}
-        Sequence.new arg.first.map{|s| compile_rule_defn(s) }
-      when Array
-        Alternative.new arg.map{|s| compile_rule_defn(s)}
-      when /([\?\+\*])$/
-        Many.new compile_rule_defn($`), $1
-      when /^[a-z][a-z_]+$/
-        Reference.new arg.to_sym, self
-      else
-        raise ArgumentError, "Invalid rule definition: #{arg.inspect}", caller
+  module Grammar
+    include Options
+    include Matching
+    include Parsing
+    include Tagging
+
+    def self.new(options = {})
+      unless options.is_a?(Hash)
+        raise ArgumentError, "Invalid grammar definition: #{options.inspect}"
       end
+      Module.new.tap{|g|
+        g.instance_eval{
+          include(Grammar)
+          extend(self)
+          install_options(options)
+        }
+      }
     end
 
-  end # class Grammar
+  end # module Grammar
 end # module Sexpr