walrus 0.1

data/lib/walrus/diff.rb

@@ -0,0 +1,89 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+require 'open3'
+require 'pathname'
+require 'tempfile'
+
+# Simple wrapper for diff(1).
+class Diff
+  
+  def initialize(left, right)
+    raise ArgumentError.new('left may not be nil') unless left
+    raise ArgumentError.new('right may not be nil') unless right
+    
+    # keep a copy of the parameters (used by the diff method)
+    @left   = left.clone
+    @right  = right.clone
+    
+    if left.kind_of? Pathname and right.kind_of? Pathname
+      @output = self.compare_pathname_with_pathname(left, right)
+    elsif left.kind_of? String and right.kind_of? Pathname
+      @output = self.compare_string_with_pathname(left, right)
+    elsif left.kind_of? Pathname and right.kind_of? String
+      @output = self.compare_pathname_with_string(left, right)
+    elsif left.kind_of? String and right.kind_of? String
+      @output = self.compare_string_with_string(left, right)
+    else
+      raise ArgumentError.new('unsupported argument types (%s, %s)' % [left.class.to_s, right.class.to_s])
+    end
+    
+  end
+  
+  def compare_pathname_with_pathname(left, right)
+    self.diff(left.realpath, right.realpath)
+  end
+  
+  def compare_string_with_pathname(left, right)
+    # will pipe left in over standard input
+    self.diff('-', right.realpath)
+  end
+  
+  def compare_pathname_with_string(left, right)
+    # will pipe right in over standard input
+    self.diff(left.realpath, '-')
+  end
+  
+  # This is the least secure comparison method because it requires the creation of a temporary file and Ruby's builtin Tempfile class is not secure.
+  def compare_string_with_string(left, right)
+    # incorporate a psuedo-random component to make race conditions more difficult to exploit
+    tempfile = Tempfile.new('walrus-%s' % rand(100000).to_s)
+    tempfile.unlink  # shut the race condition vulnerability window as soon as possible
+    tempfile.write(left)
+    tempfile.close
+    self.diff(tempfile.path, "-")
+  end
+  
+  # Actually runs diff(1) with the supplied arguments (pathnames). One but not both of the arguments may be "-" to indicate the standard input.
+  def self.diff(left, right)
+    raise ArgumentError.new('left may not be ni') unless left
+    raise ArgumentError.new('right may not be nil') unless right
+    raise ArgumentError.new('only one parameter may be "-"') if left == '-' and right == '-'
+    
+    # no shell involved, so no need to escape shell metacharacters
+    Open3.popen3('diff', '-u', left, right) do |stdin, stdout, stderr|
+      if left == '-'
+        stdin.write(@left)
+      elsif right == '-'
+        stdin.write(@right)
+      end
+      stdin.close_write
+      
+      # TODO: decide what to do with stderr output (if any)
+      stderr.read
+      return stdout.read
+    end
+    
+  end
+  
+  def to_s
+    @output
+  end
+  
+end

data/lib/walrus/document.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+#
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id: /mirrors/Walrus/trunk/walrus/lib/walrus/document.rb 6708 2007-04-10T05:38:35.035099Z wincent  $
+
+require 'walrus'
+require 'pathname'
+
+module Walrus
+  
+  # All compiled templates inherit from this class.
+  class Document
+    
+    def initialize
+      @internal_hash = {}
+    end
+    
+    def set_value(key, value)
+      @internal_hash[key.to_sym] = value
+    end
+    
+    def get_value(key)
+      @internal_hash[key.to_sym]
+    end
+    
+    def remove_value(key)
+      @internal_hash.delete(key.to_sym)
+    end
+    
+    # Expects a placeholder symbol or String.
+    # The parameters are optional.
+    def lookup_and_accumulate_placeholder(placeholder, *params)
+      output = lookup_and_return_placeholder(placeholder, *params)
+      accumulate(output) if output
+    end
+    
+    def lookup_and_return_placeholder(placeholder, *params)
+      # if exists a method responding to placeholder, call it
+      if respond_to? placeholder
+        @accumulators << nil                            # push new accumulator onto the stack
+        output = send(placeholder, *params)             # call method
+        accumulated = @accumulators.pop                 # pop last accumulator from the stack
+        if accumulated
+          return accumulated
+        elsif output
+          return output
+        end
+      else  # otherwise, try looking it up in the values hash
+        return get_value(placeholder)
+      end
+    end
+    
+    # Supports two calling methods:
+    #   - if passed a string it will be appended to the accumulator.
+    #   - if not passed a string but given a block will evaluate the block and append the (string) result to the accumulator.
+    def accumulate(string = nil)
+      if (@accumulators.last.nil?)  # accumulator will be nil if hasn't been used yet
+        @accumulators.pop           # replace temporary nil accumulator
+        @accumulators.push("")      # with proper string accumulator
+      end
+      if block_given?
+        @accumulators.last << yield.to_s
+      elsif not string.nil?
+        @accumulators.last << string.to_s
+      end
+    end
+    
+    # Fills (executes) the template body of the receiver and returns the result.
+    def fill
+      @accumulators = [nil]         # reset accumulators stack
+      template_body
+      @accumulators.last or ""
+    end
+    
+    # Prints to standard out the result of filling the receiver. Note that no trailing newline is printed. As a result, if running a template from the terminal be aware that the last line may not be visible or may be partly obscured by the command prompt that is drawn (starting at the first column) after execution completes.
+    def run
+      printf('%s', fill)
+      $stdout.flush
+    end
+    
+    # By default, there is nothing at all in the template body.
+    def template_body
+    end
+    
+    if __FILE__ == $0
+      self.new.run      # When run from the command line the default action is to call "run".
+    else
+      self.new.fill     # in other cases, evaluate 'fill' (if run inside an eval, will return filled content)
+    end
+    
+  end # class Document
+end # module Walrus
+

data/lib/walrus/grammar/additions/proc.rb

@@ -0,0 +1,20 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+class Proc
+  
+  include Walrus::Grammar::ParsletCombining
+  
+  # Returns a ProcParslet based on the receiver
+  def to_parseable
+    Walrus::Grammar::ProcParslet.new(self)
+  end
+  
+end # class Proc

data/lib/walrus/grammar/additions/regexp.rb

@@ -0,0 +1,21 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+class Regexp
+  
+  require 'walrus/grammar/parslet_combining'
+  include Walrus::Grammar::ParsletCombining
+  
+  # Returns a RegexpParslet based on the receiver
+  def to_parseable
+    Walrus::Grammar::RegexpParslet.new(self)
+  end
+  
+end # class Regexp

data/lib/walrus/grammar/additions/string.rb

@@ -0,0 +1,52 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+require 'jindex' # multibyte-friendly implementations of String#index and String#rindex
+
+# Additions to String class for Unicode support.
+class String
+  
+  # Returns an array of Unicode characters.
+  def chars
+    scan(/./m)
+  end
+  
+  alias old_range []
+  
+  # multi-byte friendly [] implementation
+  def [](range, other = Walrus::NoParameterMarker.instance)
+    if other == Walrus::NoParameterMarker.instance
+      if range.kind_of? Range
+        chars[range].join
+      else
+        old_range range
+      end
+    else
+      old_range range, other
+    end
+  end
+  
+  # Returns a character-level enumerator for the receiver.
+  def enumerator
+    Walrus::Grammar::StringEnumerator.new(self)
+  end
+  
+end # class String
+
+class String
+  
+  include Walrus::Grammar::ParsletCombining   # Rationale: it's ok to add "&" and "|" methods to string because they don't exist yet (they're not overrides).
+  
+  # Returns a StringParslet based on the receiver
+  def to_parseable
+    Walrus::Grammar::StringParslet.new(self)
+  end
+  
+end # class String

data/lib/walrus/grammar/additions/symbol.rb

@@ -0,0 +1,42 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+class Symbol
+  
+  include Walrus::Grammar::ParsletCombining
+  
+  # Returns a SymbolParslet based on the receiver.
+  # Symbols can be used in Grammars when specifying rules and productions to refer to other rules and productions that have not been defined yet.
+  # They can also be used to allow self-references within rules and productions (recursion); for example:
+  #   rule :thing & :thing.optional & :other_thing
+  # Basically these SymbolParslets allow deferred evaluation of a rule or production (deferred until parsing takes place) rather than being evaluated at the time a rule or production is defined.
+  def to_parseable
+    Walrus::Grammar::SymbolParslet.new(self)
+  end
+  
+  # Dynamically creates a subclass named after the receiver, with parent class superclass, taking params.
+  def build(superclass, *params)    
+    
+    # first use the continuation trick to find out what grammar (namespace) receiver is being messaged in
+    continuation  = nil
+    value         = callcc { |c| continuation = c }         
+    if value == continuation                                # first time that we're here
+      raise Walrus::Grammar::ContinuationWrapperException.new(continuation)  # give higher up a chance to help us
+    else # value is the Grammar instance passed to us from higher up using call on the continuation
+      grammar = value
+    end
+    
+    # actually create the subclass
+    grammar.const_get(superclass.to_s.to_class_name.to_s).subclass(self.to_s.to_class_name.to_s, grammar, *params)
+    self
+    
+  end
+  
+end # class Symbol

data/lib/walrus/grammar/and_predicate.rb

@@ -0,0 +1,40 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+module Walrus
+  class Grammar
+    
+    class AndPredicate < Predicate
+      
+      def parse(string, options = {})
+        raise ArgumentError if string.nil?
+        catch :ZeroWidthParseSuccess do
+          begin
+            parsed = @parseable.memoizing_parse(string, options)
+          rescue ParseError
+            raise ParseError.new('predicate not satisfied (expected "%s") while parsing "%s"' % [@parseable.to_s, string],
+                                 :line_end => options[:line_start], :column_end => options[:column_start])
+          end
+        end
+        
+        # getting this far means that parsing succeeded (just what we wanted)
+        throw :AndPredicateSuccess # pass succeeded
+      end
+      
+    private
+      
+      def hash_offset
+        12
+      end
+      
+    end
+    
+  end # class Grammar
+end # module Walrus

data/lib/walrus/grammar/array_result.rb

@@ -0,0 +1,19 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+module Walrus
+  class Grammar
+    class ArrayResult < Array
+      
+      include LocationTracking
+      
+    end # class ArrayResult
+  end # class Grammar
+end # module Walrus

data/lib/walrus/grammar/continuation_wrapper_exception.rb

@@ -0,0 +1,28 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+module Walrus
+  class Grammar
+    
+    class ContinuationWrapperException < Exception
+      
+      attr_reader :continuation
+      
+      def initialize(continuation)
+        raise ArgumentError if continuation.nil?
+        super self.class.to_s
+        @continuation = continuation
+      end
+      
+    end # class ContinuationWrapperException
+    
+  end # class Grammar
+end # module Walrus
+

data/lib/walrus/grammar/left_recursion_exception.rb

@@ -0,0 +1,27 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+module Walrus
+  class Grammar
+    
+    class LeftRecursionException < Exception
+      
+      attr_accessor :continuation
+       
+      def initialize(continuation = nil)
+        super self.class.to_s
+        @continuation = continuation
+      end
+      
+    end # class LeftRecursionException
+    
+  end # class Grammar
+end # module Walrus
+

data/lib/walrus/grammar/location_tracking.rb

@@ -0,0 +1,105 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id: /mirrors/Walrus/trunk/walrus/lib/walrus/grammar/location_tracking.rb 6704 2007-04-09T18:30:00.421185Z wincent  $
+
+require 'walrus'
+
+module Walrus
+  class Grammar
+    
+    # Methods for embedding location information in objects returned (or exceptions raised) from parse methods.
+    module LocationTracking
+      
+      attr_reader :source_text
+      
+      # For occasions where a single item must serve as a carrier for array-like information
+      # (that is, its own start, end and source_text, as well as the "outer" equivalents).
+      # This can happen where a single node appears in a list context surrounded only by skipped content.
+      attr_accessor :outer_start, :outer_end, :outer_source_text
+      
+      def source_text=(string)
+        @source_text = string.to_s.clone
+      end
+      
+      # Sets @column_start to col.
+      # Sets @column_start to 0 if passed nil (for ease of use, users of classes that mix-in this module don't have to worry about special casing nil values).
+      def column_start=(column_start)
+        @column_start = column_start.to_i
+      end
+      
+      # Returns 0 if @column_start is nil (for ease of use, users of classes that mix-in this module don't have to worry about special casing nil values).
+      def column_start
+        @column_start || 0
+      end
+      
+      # Sets @line_start to line.
+      # Sets @line_start to 0 if passed nil (for ease of use, users of classes that mix-in this module don't have to worry about special casing nil values).
+      def line_start=(line_start)
+        @line_start = line_start.to_i
+      end
+      
+      # Returns 0 if @line_start is nil (for ease of use, users of classes that mix-in this module don't have to worry about special casing nil values).
+      def line_start
+        @line_start || 0
+      end
+      
+      # Convenience method for getting both line_start and column_start at once.
+      def start
+        [self.line_start, self.column_start]
+      end
+      
+      # Convenience method for setting both line_start and column_start at once.
+      def start=(array)
+        raise ArgumentError if array.nil?
+        raise ArgumentError if array.length != 2
+        self.line_start    = array[0]
+        self.column_start  = array[1]
+      end
+      
+      def line_end=(line_end)
+        @line_end = line_end.to_i
+      end
+      
+      def line_end
+        @line_end || 0
+      end
+      
+      def column_end=(column_end)
+        @column_end = column_end.to_i
+      end
+      
+      def column_end
+        @column_end || 0
+      end
+      
+      # Convenience method for getting both line_end and column_end at once.
+      def end
+        [self.line_end, self.column_end]
+      end
+      
+      # Convenience method for setting both line_end and column_end at once.
+      def end=(array)
+        raise ArgumentError if array.nil?
+        raise ArgumentError if array.length != 2
+        self.line_end   = array[0]
+        self.column_end = array[1]
+      end
+      
+      # Given another object that responds to column_end and line_end, returns true if the receiver is rightmost or equal.
+      # If the other object is farther to the right returns false.
+      def rightmost?(other)
+        if self.line_end > other.line_end         : true
+        elsif other.line_end > self.line_end      : false
+        elsif self.column_end >= other.column_end : true
+        else                                        false
+        end
+      end
+      
+    end # module LocationTracking
+    
+  end # class Grammar
+end # module Walrus

data/lib/walrus/grammar/match_data_wrapper.rb

@@ -0,0 +1,65 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+module Walrus
+  class Grammar
+    
+    # Simple wrapper for MatchData objects that implements length, to_s and to_str methods.
+    # By implementing to_str, MatchDataWrappers can be directly compared with Strings using the == method.
+    # The original MatchData instance can be obtained using the match_data accessor.
+    # Upon creation a clone of the passed in MatchData object is stored; this means that the $~ global variable can be conveniently wrapped without having to worry that subsequent operations will alter the contents of the variable.
+    class MatchDataWrapper
+      
+      include Walrus::Grammar::LocationTracking
+      
+      attr_reader :match_data
+      
+      # Raises if data is nil.
+      def initialize(data)
+        raise ArgumentError if data.nil?
+        self.match_data = data
+      end
+      
+      # The definition of this method, in conjunction with the == method, allows automatic comparisons with String objects using the == method.
+      # This is because in a parser matches essentially are Strings (just like Exceptions and Pathnames); it's just that this class encapsulates a little more information (the match data) for those who want it.
+      def to_str
+        self.to_s
+      end
+      
+      # Although this method explicitly allows for MatchDataWrapper to MatchDataWrapper comparisons, not that all such comparisons will return false except for those between instances which were initialized with exactly the same match data instance; this is because the MatchData class itself always returns false when compared with other MatchData instances.
+      def ==(other)
+        if other.kind_of? MatchDataWrapper
+          self.match_data == other.match_data
+        elsif other.respond_to? :to_str
+          self.to_str == other.to_str
+        else
+          false
+        end
+      end
+      
+      def to_s
+        @match_data[0]
+      end
+      
+      def jlength
+        self.to_s.jlength
+      end
+      
+    private
+      
+      def match_data=(data)
+        @match_data = (data.clone rescue data)
+      end
+      
+    end # class MatchDataWrapper
+    
+  end # class Grammar
+end # module Walrus
+

data/lib/walrus/grammar/memoizing.rb

@@ -0,0 +1,41 @@
+# Copyright 2007 Wincent Colaiuta
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# in the accompanying file, "LICENSE.txt", for more details.
+#
+# $Id$
+
+require 'walrus'
+
+module Walrus
+  class Grammar
+    
+    module Memoizing
+      
+      # This method provides a clean, optional implementation of memoizing by serving as a wrapper for all parse invocations. Rather than calling the parse methods directly, this method should be called; if it is appropriate to use a memoizer then it will be invoked, otherwise control will fall through to the real parse method. Turning off memoizing is as simple as not parsing a value with the :memoizer key in the options hash.
+      # This method defined is in a separate module so that it can easily be mixed in with all Parslets, ParsletCombinations and Predicates.
+      def memoizing_parse(string, options = {})
+        
+        # Will use memoizer if available and not instructed to ignore it
+        if options.has_key?(:memoizer) and not (options.has_key?(:ignore_memoizer) and options[:ignore_memoizer])
+          options[:parseable] = self
+          options[:memoizer].parse(string, options)
+        else # otherwise will proceed as normal
+          options[:ignore_memoizer] = false
+          parse(string, options)
+        end
+        
+      end
+      
+      # Can only check for left recursion if memoizing is turned on (the help of the memoizer is needed).
+      def check_left_recursion(parseable, options = {})
+        return unless options.has_key?(:memoizer)
+        options[:memoizer].check_left_recursion(parseable, options)
+      end
+      
+    end # module Memoizing
+    
+  end # class Grammar
+end # module Walrus
+