Spectre 0.0.1

data/lib/spectre/base/node.rb

@@ -0,0 +1,393 @@
+# This is Spectre, a parser framework inspired by Boost.Spirit,
+# which can be found at http://spirit.sourceforge.net/.
+#
+# If you want to find out more or need a tutorial, go to
+# http://spectre.rubyforge.org/
+# You'll find a nice wiki there!
+#
+# Author::      Fabian Streitel (karottenreibe)
+# Copyright::   Copyright (c) 2009 Fabian Streitel
+# License::     Boost Software License 1.0
+#               For further information regarding this license, you can go to
+#               http://www.boost.org/LICENSE_1_0.txt
+#               or read the file LICENSE distributed with this software.
+# Homepage::    http://spectre.rubyforge.org/
+# Git repo::    http://rubyforge.org/scm/?group_id=7618
+#
+# Keeps the Node class the parse tree is composed of.
+#
+
+module Spectre
+
+    ##
+    # A Node in the parse tree. Nodes keep the parsing tree consistent by applying
+    # some control mechanisms to the parsing process and taking away responsibility
+    # from the Parsers.
+    # They keep the Closures and parent-child relations between the Parsers as well as
+    # the symbol-identified Parsers of the Grammars.
+    #
+    class Node
+
+        ##
+        # The semantic actions that are associated with this Node - Array.
+        attr_accessor :actions
+
+        ##
+        # The location the InputIterator was at, before the Parser started matching.
+        attr_accessor :backtrace
+
+        ##
+        # The left child Node of this Node or nil if none.
+        attr_accessor :left
+
+        ##
+        # The right child Node of this Node or nil if none.
+        attr_accessor :right
+
+        ##
+        # The parent Node of this Node.
+        attr_accessor :parent
+
+        ##
+        # The symbol-identified Parsers for this Node - Hash.
+        attr_accessor :symbols
+
+        ##
+        # The Parser that resides in this Node.
+        attr_accessor :parser
+
+        ##
+        # The policy that govern the Parser's behaviour - Hash.
+        # - :union => :normal|:shortest|:longest -- Evaluation unions: first, longest or shortest match
+        # - :actions => true|false -- Whether to call semantic actions on successful match
+        # - :min => _value_|nil -- Minimal value for successful match (parser dependant)
+        # - :max => _value_|nil -- Maximal value for successful match (parser dependant)
+        #
+        # Defaults are:
+        # - :union => :normal
+        # - :actions => true
+        # - :min => nil
+        # - :max => nil
+        attr_accessor :policy
+
+        ##
+        # Initializes the Node's +parser+ property and registers the Node with the
+        # given Parser, as well as the +left+ and +right+ child.
+        #
+        def initialize parser, left = nil, right = nil
+            if left
+                @left = left.to_p
+                @left.parent = self
+            end
+
+            if right
+                @right = right.to_p
+                @right.parent = self
+            end
+
+            @parser, @symbols, @actions = parser, {}, []
+            parser.node = self
+        end
+
+        ##
+        # Initializes a new Node by +dup+ping the +other+ Node's Parser, as well as its Closure
+        # and actions and the whole parse tree under it.
+        # The backtrace will not be copied.
+        #
+        def initialize_copy other
+            if other.parser
+                @parser = other.parser.dup
+                @parser.node = self
+            end
+            if other.closure?
+                @closure = other.closure.dup
+                @closure.node = self
+                @closure.parser = @parser
+            end
+            if other.symbols
+                @symbols = other.symbols.dup
+            end
+            if other.actions
+                @actions = other.actions.dup
+            end
+            if other.left
+                @left = other.left.dup
+                @left.parent = self
+            end
+            if other.right
+                @right = other.right.dup
+                @right.parent = self
+            end
+        end
+
+        ##
+        # Unlike +#initialize_copy+ this method does not +dup+ the elments contained in the +other+
+        # Node, but rather only copies references.
+        # The backtrace will not be copied.
+        #
+        def shallow_copy other
+            @parser, @closure, @symbols, @actions, @left, @right =
+                other.parser, other.closure, other.symbols, other.actions, other.left, other.right
+        end
+
+        ##
+        # Returns true, if this Node is the root Node, else false.
+        #
+        def root?
+            @parent.nil?
+        end
+
+        ##
+        # Returns true, if this Node is a leaf Node, else false.
+        #
+        def leaf?
+            @left.nil? and @right.nil?
+        end
+
+        ##
+        # Recursively ascends to the top of the parsing chain and returns the first
+        # closure it finds or nil if none.
+        #
+        def closure
+            @closure || ( @parent ? @parent.closure : nil )
+        end
+
+        ##
+        # Returns true if _this_ Node has a closure set, i.e. unlike +#closure+ it will not query
+        # the parent for it's closure.
+        #
+        def closure?
+            @closure ? true : false
+        end
+
+        ##
+        # Sets the closure and registers the Node and it's Parser with it.
+        #
+        def closure= clos
+            @closure = clos
+            clos.parser = @parser
+            clos.node = self
+        end
+
+        ##
+        # Recursively ascends to the top of the parsing chain and returns the first
+        # policy it finds or the default policy.
+        #
+        def policy
+            # only set those if nothing has been specified
+            std = { :union => :normal,
+                    :actions => true,
+                    :min => nil,
+                    :max => nil }
+            # replace if not specified in THIS node.
+            rep = { :min => nil,
+                    :max => nil }
+
+            pol = @policy
+
+            unless pol
+                pol = @parent ? @parent.policy || std : std
+                pol.merge! rep
+            end
+
+            pol.merge(std) { |k,o,n| o }
+        end
+
+        ##
+        # If parsing fails, the parent of the Node will instruct it to backtrack.
+        # I.e. it will return the InputIterator to the position before the failed
+        # parsing attempt.
+        # If no backtrace has been saved, nothing is done.
+        # Returns the modified InputIterator.
+        #
+        def backtrack iter
+            iter.to @backtrace.pos if @backtrace
+        end
+
+        ##
+        # Saves the backtrace and calls +#scan+ on the Parser to do the actual parsing of the
+        # InputIterator +iter+. This method will +backtrack+ automatically when the result of
+        # the Parser is +nil+.
+        #
+        # If +pre_skip+ is +false+, +InputIterator#skip!+ will not be called before the Parser
+        # invocation.
+        # Please note: +pre_skip+ being +true+ does not mean that pre-skipping is done. Other
+        # factors may prohibit that, e.g. a +LexemeDirective+.
+        #
+        def parse iter, pre_skip = true
+            @backtrace = iter.dup
+
+            iter.skip! if @parser.pre_skip? and pre_skip
+            ret = @parser.scan iter
+            backtrack iter unless ret
+            
+            pol = policy
+
+            ##TODO: simplify this?
+            # test on min and or max
+            if ret and ret.value
+                # min
+                if pol[:min]
+                    ret = nil if pol[:min] > ret.value
+                end
+
+                # max if not reset
+                if ret and pol[:max]
+                    ret = nil if pol[:max] < ret.value
+                end
+            # reset if value == nil and min or max specified
+            elsif ret
+                ret = nil if pol[:min] or pol[:max]
+            end
+
+            @actions ||= []
+            @actions.each { |action|
+                action.call ret, self.closure
+            } if ret and pol[:actions]
+
+            ret
+        end
+
+        ##
+        # Converts this Node to a Node, i.e. returns +self+.
+        #
+        def to_p
+            self
+        end
+
+        ##
+        # Replaces this Node with +rep+ and returns the modified replacement Node.
+        # If this is called during parsing process, the calling function should
+        # +#backtrack+ and call +#parse+ for the replacement Node.
+        #
+        def replace_with rep
+            rep.parent = @parent
+
+            if @parent
+                if self == @parent.left then @parent.left = rep
+                else @parent.right = rep
+                end
+            end
+
+            rep
+        end
+
+        ##
+        # Returns a multy-line String representing the parse-chain the current Parser is in.
+        #
+        def chain
+            ( @parent ? @parent.inspect + "\n  " : '' ) + 
+            self.inspect
+        end
+
+        ##
+        # Tries to find the Parser referenced by the symbol +sym+ by walking up the
+        # parse tree.
+        # If a Parser is found, it is +#dup+ped and returned, nil otherwise.
+        #
+        def find sym
+            ret = @symbols[sym] || ( @parent ? @parent.find(sym) : nil )
+            ret = ret.dup if ret
+            ret
+        end
+
+        ##
+        # Adds a semantic action to the Node.
+        # A semantic action is nothing but an object that implements the +call+ method (most simple
+        # example being a +lambda+ block), which will accept two parameters:
+        # The match made by the Parser and the Closure associated with the Parser.
+        #
+        def [] action
+            @actions ||= []
+
+            if action.is_a? Symbol then @actions << ClosureAction.new(action)
+            else @actions << action
+            end
+            
+            self
+        end
+
+        ##
+        # See Operators::Sequence.
+        #
+        def >> right
+            Node.new Operators::Sequence.new, self, right.to_p
+        end
+
+        ##
+        # See Operators::Union.
+        #
+        def | right
+            Node.new Operators::Union.new, self, right.to_p
+        end
+
+        ##
+        # See Operators::Intersection.
+        #
+        def & right
+            Node.new Operators::Intersection.new, self, right.to_p
+        end
+
+        ##
+        # See Operators::Difference.
+        #
+        def - right
+            Node.new Operators::Difference.new, self, right.to_p
+        end
+
+        ##
+        # See Operators::Xor.
+        #
+        def ^ right
+            Node.new Operators::Difference.new, self, right.to_p
+        end
+
+        ##
+        # See Operators::List.
+        #
+        def % right
+            Node.new Operators::List.new, self, right.to_p
+        end
+
+        ##
+        # See Operators::SequentialOr.
+        #
+        def ** right
+            Node.new Operators::SequentialOr.new, self, right.to_p
+        end
+
+        ##
+        # See Operators::KleeneStar.
+        #
+        def *
+            Node.new Operators::KleeneStar.new, self
+        end
+
+        ##
+        # See Operators::Positive.
+        #
+        def +
+            Node.new Operators::Positive.new, self
+        end
+
+        ##
+        # See Operators::Optional.
+        #
+        def -@
+            Node.new Operators::Optional.new, self
+        end
+
+        ##
+        # See Operators::Negation.
+        #
+        def ~@
+            Node.new Operators::Negation.new, self
+        end
+
+        def inspect
+            @parser.inspect
+        end
+
+    end
+end
+

data/lib/spectre/base/operators.rb

@@ -0,0 +1,342 @@
+# This is Spectre, a parser framework inspired by Boost.Spirit,
+# which can be found at http://spirit.sourceforge.net/.
+#
+# If you want to find out more or need a tutorial, go to
+# http://spectre.rubyforge.org/
+# You'll find a nice wiki there!
+#
+# Author::      Fabian Streitel (karottenreibe)
+# Copyright::   Copyright (c) 2009 Fabian Streitel
+# License::     Boost Software License 1.0
+#               For further information regarding this license, you can go to
+#               http://www.boost.org/LICENSE_1_0.txt
+#               or read the file LICENSE distributed with this software.
+# Homepage::    http://spectre.rubyforge.org/
+# Git repo::    http://rubyforge.org/scm/?group_id=7618
+#
+# Keeps the Operators used to compose Parsers/Nodes.
+#
+
+require 'spectre/base/parser'
+
+module Spectre
+
+    ##
+    # Keeps the Parsers that are used as wrapper around other Parsers.
+    # These are implemented as operators of class Node.
+    #
+    module Operators
+
+        module Op
+            include Parser
+            def pre_skip?; false; end
+        end
+
+        ##
+        # Takes the two Nodes it gets as parameters and tries to match them one
+        # after the other.
+        # +Sequence.new p1, p2+ is equal to +p1 >> p2+.
+        #
+        class Sequence
+            include Op
+
+            def scan iter
+                first = @node.left.parse iter
+                return nil unless first
+
+                second = @node.right.parse iter
+                return nil unless second
+
+                create_match iter, iter.concat(first.value, second.value)
+            end
+
+            def inspect
+                '(' + @node.left.inspect + ' >> ' + @node.right.inspect + ')'
+            end
+        end
+
+        ##
+        # Takes the two Nodes it gets as parameters and tries to match them one
+        # after the other, but if one of the two does not match, it doesn't matter
+        # +SequentialOr.new p1, p2+ is equal to +p1 ** p2+.
+        #
+        class SequentialOr
+            include Op
+
+            def scan iter
+                rep = ( @node.left.dup >> -@node.right.dup ) | @node.right.dup
+                rep = @node.replace_with rep
+                create_match iter, rep.parse(iter)
+            end
+
+            def inspect
+                '(' + @node.left.inspect + ' ** ' + @node.right.inspect + ')'
+            end
+        end
+
+        ##
+        # Matches either the first or the second Node it receives
+        # as parameters
+        # +Union.new p1, p2+ is equal to +p1 | p2+.
+        # This operator applies the tactics of short-circuiting, i.e.
+        # if p1 matches, p2 will not be tried at all.
+        #
+        class Union
+            include Op
+
+            def scan iter
+                first = @node.left.parse iter
+
+                if @node.policy[:union] == :normal
+                    if first
+                        create_match iter, first
+                    else
+                        backtrack iter
+                        create_match iter, @node.right.parse(iter)
+                    end
+                else
+                    fiter = iter.dup
+                    backtrack iter
+                    second = @node.right.parse iter
+                    siter = iter.dup
+                    backtrack iter
+
+                    if first and second
+                        mm = [[first,fiter], [second,siter]].minmax_by { |x| x[0].length }
+                        winner = @node.policy[:union] == :longest ? mm[1] : mm[0]
+
+                        iter.to winner[1].pos
+                        create_match iter, winner[0]
+                    elsif first
+                        iter.to fiter.pos
+                        create_match iter, first
+                    elsif second
+                        iter.to siter.pos
+                        create_match iter, second
+                    else
+                        nil
+                    end
+                end
+            end
+
+            def inspect
+                '(' + @node.left.inspect + ' | ' + @node.right.inspect + ')'
+            end
+        end
+
+        ##
+        # Matches if both Nodes it receives as parameters match
+        # from the current position.
+        # Goes to the position in the input stream returned by the Node
+        # that matched the bigger input.
+        # +Intersection.new p1, p2+ is equal to +p1 & p2+.
+        #
+        class Intersection
+            include Op
+
+            def scan iter
+                first = @node.left.parse iter
+                fiter = iter.dup
+                backtrack iter
+                return nil unless first
+
+                second = @node.right.parse iter
+                siter = iter.dup
+                backtrack iter
+
+                if first and second
+                    max = [[first,fiter], [second,siter]].max_by { |x| x[0].length }
+                    iter.to max[1].pos
+                    create_match iter, max[0]
+                else
+                    nil
+                end
+            end
+
+            def inspect
+                '(' + @node.left.inspect + ' & ' + @node.right.inspect + ')'
+            end
+        end
+
+        ##
+        # Matches if the first Node matches, but not the second or if
+        # both match and the first one's match is longer.
+        # +Difference.new p1, p2+ is equal to +p1 - p2+.
+        #
+        class Difference
+            include Op
+
+            def scan iter
+                first = @node.left.parse iter
+                fiter = iter.dup
+                backtrack iter
+                return nil unless first
+
+                second = @node.right.parse iter
+                backtrack iter
+
+                if ( first and not second ) or ( first.length > second.length )
+                    iter.to fiter.pos
+                    create_match iter, first
+                else
+                    nil
+                end
+            end
+
+            def inspect
+                '(' + @node.left.inspect + ' - ' + @node.right.inspect + ')'
+            end
+        end
+
+        ##
+        # Matches if either the first Node or the second matches, but
+        # not if both match.
+        # +Xor.new p1, p2+ is equal to +p1 ^ p2+.
+        #
+        class Xor
+            include Op
+
+            def scan iter
+                first = @node.left.parse iter
+                fiter = iter.dup
+                backtrack iter
+                second = @node.right.parse iter
+                siter = iter.dup
+                backtrack iter
+
+                if first and not second
+                    iter.to fiter.pos
+                    create_match iter, first
+                elsif second and not first
+                    iter.to siter.pos
+                    create_match iter, second
+                else
+                    nil
+                end
+            end
+
+            def inspect
+                '(' + @node.left.inspect + ' ^ ' + @node.right.inspect + ')'
+            end
+        end
+
+        ##
+        # Negates the Node it receives as a parameter.
+        # +Negation.new p+ is equal to +~p+.
+        # NOTE: This will only work for Nodes that implement the
+        # +negation+ singleton method that returns the class of the
+        # negation Parser to be used.
+        #
+        class Negation
+            include Parser
+
+            def scan iter
+                neg = @node.left.parser.respond_to? :negation
+                raise "no negation defined for parser class #{@node.left.parser.class}." unless neg
+                rep = Node.new @node.left.parser.negation
+                rep.left = @node.left
+                rep = @node.replace_with rep
+                create_match iter, rep.parse(iter)
+            end
+
+            def inspect
+                '(~' + @node.left.inspect  + ')'
+            end
+        end
+
+        ##
+        # Matches the given Node 0 or more times.
+        # +KleeneStar.new p+ is equal to +p.*+.
+        #
+        class KleeneStar
+            include Op
+
+            def scan iter
+                ret = true
+                val = iter.empty
+
+                while ret
+                    ret = @node.left.parse iter
+                    val = iter.concat(val, ret.value) if ret
+                end
+
+                @node.left.parser.backtrack iter
+                create_match iter, val
+            end
+
+            def inspect
+                '(' + @node.left.inspect + '.*)'
+            end
+        end
+
+        ##
+        # Matches the given Node 1 or more times.
+        # +Positive.new p+ is equal to +p.\++.
+        #
+        class Positive
+            include Op
+
+            def scan iter
+                ret = @node.left.parse iter
+                return nil unless ret
+
+                val = ret.value
+                while ret
+                    ret = @node.left.parse iter
+                    val = iter.concat val, ret.value if ret
+                end
+
+                create_match iter, val
+            end
+
+            def inspect
+                '(' + @node.left.inspect + '.+)'
+            end
+        end
+
+        ##
+        # Matches the given Node 0 or 1 times.
+        # +Optional.new p+ is equal to +-p+.
+        #
+        class Optional
+            include Op
+
+            def scan iter
+                ret = @node.left.parse iter
+                if ret
+                    create_match iter, ret
+                else
+                    backtrack iter
+                    create_match iter, iter.empty
+                end
+            end
+
+            def inspect
+                '(-' + @node.left.inspect + ')'
+            end
+        end
+
+        ##
+        # Matches a list of tokens matched by the first Node,
+        # separated by tokens matched by the second Node.
+        # The first Node must not match the second.
+        # +List.new p1 p2+ is equal to +p1 % p2+.
+        #
+        class List
+            include Op
+
+            def scan iter
+                rep = @node.left.dup >> ( @node.right.dup >> @node.left.dup ).*
+                rep = @node.replace_with rep
+                create_match iter, rep.parse(iter)
+            end
+
+            def inspect
+                "(#{@node.left.inspect} % #{@node.right.inspect})"
+            end
+        end
+
+    end
+
+end
+