meta_parse 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35a61cdea68ccbca473d11440d4f21a6c0b19569
-  data.tar.gz: b13deef76ec7cbfe70b7177616b9326d9a51ebd8
+  metadata.gz: a5afbd35c216415e4d640838f26fa0e7b30d5d1f
+  data.tar.gz: d7051bc1eb8ae1cbd7fa716ad631ac79c4dadcd8
 SHA512:
-  metadata.gz: 991234302ec3a0309825a005feb0328e968324363d5881082e3188c5288b68c056ff857f53d1c08b28fc98bb86919e1a3045c28a37d914d8f67ead924b369c44
-  data.tar.gz: 123ec7e2bfde4e868fda6d93c3692b45dd449e37da1aa2cadf46269a89b132e4b0ab28dce160890846737fe0cc456929cd18cb4ee318016907d73264ae402da9
+  metadata.gz: 1ffc733a1a70f6105b86c0651dee9b4f3307b0d8c4402810038c307ebb2375d54f06eeaed0c46874ff17a646b048c669427c9e472398a2378005a486f55c81e6
+  data.tar.gz: 9b069986342c3e21b1346be532d973d4097daead288dcf876e06ec18b23151c020fbb63e39786906abd65ad20104e49d3b9fd6da2468422e050743dc3efc832d

data/lib/meta_parse.rb

@@ -1,40 +1,51 @@
 require 'strscan'
 
+##
+# This module contains the classes which implement parsers and, when included,
+# provides class methods for defining custom parsers.
+
 module MetaParse
 
+  ##
+  # Extend including class with ClassMethods.
+  
   def self.included(base)
     base.extend ClassMethods
   end
 
-  ### Begin Interface
-
+  ##
+  # Parse string using an instance method previously defined by MetaParse::ClassMethodss::match_method.
+  
   def parse_with_method(method_name, string)    
     self.send(method_name, string.meta(self), self)
   end
 
-  module ClassMethods    
-    # Defined a method which takes a scanner.
+  module ClassMethods
+    ##
+    # Defines a method which takes a scanner from provided block.
     # The block passed should return a Matcher or Matcher spec, which is compiled to a Matcher if necessary.
     # The result of calling the defined method is the same as calling match? on the resulting Matcher.
+
     def match_method(name, &block)
       match_spec = yield
       matcher = MetaParse::Matcher.compile(match_spec)
       
       define_matcher_method(name, matcher)
     end
-    
-    def define_matcher_method(name, matcher)
-      self.send(:define_method, name) do |scanner, context=nil|
-        matcher.match scanner, context
-      end
-    end
-        
+
+    ##
+    # Returns a RepetitionMatcher which matches the pattern specified by its arguments zero-or-more-times.
+
     def rep(*args, &block)
       Matcher.compile([:*, *args])
     end
-    
-    # Return a sequential matcher.  If block is supplied, it defines a function which will be passed an array
+
+    ##
+    # Return a SequentialMatcher.  If block is supplied, it defines a function which will be passed an array
     # of all matched values and which should return a non-nil result for the match as a whole.
+    # Sequential matching with terminal block is the mechanism by which arbitrary values can be produced at
+    # any step in parsing.
+    
     def seq(*args, &block)
       if block_given?
         wrapped = lambda { |scanner, context|
@@ -46,27 +57,49 @@ module MetaParse
       end
       Matcher.compile([:and, *args])
     end
+
+    ##
+    # Return an AlternativeMatcher.
     
     def alt(*args)
       Matcher.compile([:or, *args])
     end
+
+    ##
+    # Compile a Matcher spec into corresponding matcher.
     
     def comp(spec)
       Matcher.compile(spec)
     end
-    
+
+    private
+
+    ##
+    # Define a match method using supplied Matcher.
+    # Used by ::match_method, which should be used instead.
+
+    def define_matcher_method(name, matcher)
+      self.send(:define_method, name) do |scanner, context=nil|
+        matcher.match scanner, context
+      end
+    end
   end
-  ### End Interface
 
   class MetaScanner < StringScanner
     attr_accessor :parser
 
+    ##
+    # Initialize MetaScanner with supplied string as input.
+    # Optionally-supplied parser will be receiver of Symbol message sent by subclass, FunctionMatcher.
     def initialize(string, parser=nil)
       super string
       @parser = parser
     end
 
-    # This is a special case and could actually be handled by match_string if necessary.
+    ##
+    # Match and return a single character or return nil, updating internal position on match.
+    
+    # NOTE: This is a special case and could actually be handled by match_string if necessary.
     def match_char(char)
       c = peek(1)
       if c == char
@@ -75,6 +108,9 @@ module MetaParse
       end
     end
 
+    ##
+    #  Match and return a string or return nil, updating internal position on match.
+    
     def match_string(str, position2=0)
       if (string.equal_at(pos, str, position2))
         self.pos += str.length
@@ -82,6 +118,9 @@ module MetaParse
       end
     end
 
+    ##
+    # Scan for a Regexp or string, returning any match, or nil, and updating internal position on match.
+    
     def scan(spec)
       case spec
       when Regexp
@@ -97,9 +136,16 @@ module MetaParse
     end
   end
 
+  ##
+  # General class to match a simple pattern against a scanner.
+  # Subclasses implement compound matching.
+  
   class Matcher
     attr_accessor :spec
 
+    ##
+    # Compile a Matcher specification into a concrete Matcher or subclass.
+    
     def self.compile(spec)
       case spec
       when Matcher
@@ -130,8 +176,11 @@ module MetaParse
       end
     end
 
-    def initialize(data)
-      @spec = data
+    ##
+    # Initialize Matcher with Matcher spec.
+    
+    def initialize(spec)
+      @spec = spec
     end
 
     def show
@@ -142,6 +191,11 @@ module MetaParse
       "<match #{show}>"
     end
 
+    ##
+    # Try to match own pattern/combination against supplied scanner. Context is unused.
+    #
+    # Subclasses should implement match? but not call it on peers.
+    
     def match?(scanner, context=nil)
       case scanner
       when MetaScanner
@@ -156,52 +210,80 @@ module MetaParse
       end
     end
 
+    ##
+    # Like match? but clone self first if stateful.
+    #
+    # Subclasses should not implement match, but should call it on peers.
+    
     def match(scanner, context=nil)
       (stateful ? clone : self).match? scanner, context
     end
 
+    ##
+    # Is this Matcher stateful? A class attribute which may be overriden by subclasses.
+    
     def stateful
       false
     end
 
+    ##
+    # Syntactic sugar to create MetaScanner and match? self against string.
+    
     def m?(string)
       match? MetaScanner.new(string)
     end
 
+    ##
+    # Syntactic sugar to create MetaScanner and match self against string.
+
     def m(string)
       match MetaScanner.new(string)
     end
 
   end
 
+  ##
+  # Matcher subclass matching sub_match repeatedly.
+  
   class RepetitionMatcher < Matcher
-    attr_accessor :min, :max, :reducer
+    # Match at least min times, if min is present.
+    attr_accessor :min
+
+    # Match at most max times, if max is present.   
+    attr_accessor :max
+
+    # A proc used to combine match results as by inject, if present.
+    attr_accessor :reducer
     
     def initialize(sub_match, min=0, max=nil, reducer=nil, initial_value=[])
       @spec, @min, @max, @reducer, @initial_value = sub_match, min, max, reducer, initial_value
     end
 
+    ##
+    # RepetitionMatcher is stateful.
+    
     def stateful
       true
     end
 
-    def match?(scanner, context=nil)
-      matches = []
-      while (!max || (matches.count < max)) && (match = spec.match(scanner))
-        matches << match
-      end
+
+    # def match?(scanner, context=nil)
+    #   matches = []
+    #   while (!max || (matches.count < max)) && (match = spec.match(scanner))
+    #     matches << match
+    #   end
       
-      unless min && (matches.count < min)
-        case finalizer
-        when Proc
-          finalizer.call(matches, *finalizer_args)
-        when Symbol
-          send(finalizer, matches, *finalizer_args)
-        when nil 
-          matches
-        end
-      end
-    end
+    #   unless min && (matches.count < min)
+    #     case finalizer
+    #     when Proc
+    #       finalizer.call(matches, *finalizer_args)
+    #     when Symbol
+    #       send(finalizer, matches, *finalizer_args)
+    #     when nil 
+    #       matches
+    #     end
+    #   end
+    # end
     
     def match?(scanner, context=nil)
       # Need to copy the initial value since it is potentially destructively modified (if an array, for example).
@@ -229,6 +311,9 @@ module MetaParse
     end
   end
 
+  ##
+  # Matcher subclass matching first of alternative submatches.
+  
   class AlternativeMatcher < Matcher
     def match?(scanner, context=nil)
       spec.each do |alternative|
@@ -243,13 +328,23 @@ module MetaParse
     end
   end
 
+  ##
+  # Matcher subclass matching submatches sequentially.
+  
   class SequentialMatcher < Matcher
     attr_accessor :matches
+
+
+    ##
+    # SequentialMatcher is stateful.
     
     def stateful
       true
     end
 
+    ##
+    # Match submatch patterns against scanner sequentially, accumulating results in @matches.
+    
     def match?(scanner, context = nil)
       @matches = []
       initial_position = scanner.pos
@@ -266,14 +361,23 @@ module MetaParse
       return last_match
     end
 
+    ##
+    # Remove most recent sequential match from result stack (@matches), returning it (pop).
+    
     def pop
       @matches.pop
     end
 
+    ##
+    # Add (push) value to result stack (@matches).
+    
     def push(value)
       @matches.push(value)
     end
 
+    ##
+    # Reset result stack (@matches) to be empty.
+    
     def clear
       @matches = []
     end
@@ -283,11 +387,15 @@ module MetaParse
     end
   end  
 
+  ##
   # Arbitrary predicate, particularly useful for generating final return value from SequentialMatchers.
   # Context is the containing matcher, and in the case of SequentialMatcher includes access to accumulated matches.
   class FunctionMatcher < Matcher
     include MetaParse
 
+    ##
+    # Try to match against scanner using arbitrary predicated specified as Proc or Symbol naming method of Matcher's parser.
+    
     def match?(scanner, context=nil)
       case spec
       when Proc
@@ -298,20 +406,32 @@ module MetaParse
     end
   end
 
+  ##
+  # Extract matches from context and return them, resetting context's matches to be empty.
+  
   def all_matches(scanner, context)
     matches_so_far = context.matches
     context.matches = []
     matches_so_far
   end
 
+  ##
+  # Join all matches as extracted by #all_matches.
+  
   def all_matches_joined(scanner, context)
     all_matches(scanner,context).join
   end
 
+  ##
+  # Joins's string args. Helper function for use in assembling parse results.
+  
   def join_strings(array, *args)
     array.join(*args)
   end
 
+  ##
+  # Apply block to context's matches stack, then clear context, returning result.
+  
   def collapse(&block)
     lambda { |scanner, context|
       stack = context.matches
@@ -323,14 +443,24 @@ module MetaParse
 end
 
 class String
+
+  ##
+  # Returns true iff receiver (String) is equal to string at index, position, of receiver.
+  # If position2 is supplied, begin comparison of string at that index position.
+  
   def equal_at(position, string, position2=0)
     for i in position2..(position2 + string.length - 1) do
+      puts "#{position}-#{i}"
+      puts "#{self[position]}-#{string[i]}"
       return nil unless self[position] == string[i] 
       position += 1
     end
     return true
   end
 
+  ##
+  # Return scanner using receiver (String) as source.
+
   def meta(parser=nil)
     MetaParse::MetaScanner.new(self, parser)
   end

data/lib/util.rb

@@ -1,33 +1,20 @@
 # require 'util'
 
 module Util
+  ##
+  # Sugar to allow calling mgsub as instance method.
+  
   def mgsub(string, substitution_hash)
     Util::mgsub(string, substitution_hash)
   end
 
-  # We can't use a closure (for now) because JRuby (as of 1.7.14) doesn't handle return correctly in lambdas.
-  # It returns from the containing function. Here we depend on an early return from the actual function only.
-  def self.make_substitution_function(regexp_hash)
-    ->(matched_string) {
-      result = nil # Poor man's early return because of JRuby bug.
-      
-      regexp_hash.each do |regexp, substitution|
-        if !result && matched_string.match(regexp)
-          match_data = Regexp.last_match
-          result = case substitution
-                   when String
-                     substitution
-                   else
-                     substitution.call(match_data)
-                   end
-        end
-      end
-
-      result
-    }
-  end
+  ##
+  # Multiple Global Substitution.
+  #
+  # substitution_hash contains pattern (regexp or string) keys and corresponding substitution.
+  # Substitution can either be a string or a function of regexp MatchData.
+  # The latter allows for arbitrary substitution based on matched content.
 
-  # mgsub == multiple, global substitution.
   def self.mgsub(string, substitution_hash)
     all_regexps = []
     regexp_hash = {}
@@ -46,6 +33,11 @@ module Util
     string.gsub(combined_regexp, &substitution_function)
   end
 
+  private
+
+  ##
+  # Return corresponding regexp, escaping string if necessary. Regexp returns itself.
+  
   def self.to_regexp(spec)
     case spec
     when Regexp
@@ -53,51 +45,39 @@ module Util
     when String
       Regexp.escape(spec)
     end
-  end
-end
-
-module Util
-  class Maybe < BasicObject
-    def initialize(object, default = nil)
-      @object = object
-      @default = default
-      @block = block
-    end
-
-
-    def send(method, *args, &block)
-      if @object.respond_to?(method)
-        @object.send(method, *args, &block) 
-      else
-        @default
+  end  
+  
+  # We can't use a closure (for now) because JRuby (as of 1.7.14) doesn't handle return correctly in lambdas.
+  # It returns from the containing function. Here we depend on an early return from the actual function only.
+  def self.make_substitution_function(regexp_hash)
+    ->(matched_string) {
+      result = nil # Poor man's early return because of JRuby bug.
+      
+      regexp_hash.each do |regexp, substitution|
+        if !result && matched_string.match(regexp)
+          match_data = Regexp.last_match
+          result = case substitution
+                   when String
+                     substitution
+                   else
+                     substitution.call(match_data)
+                   end
+        end
       end
-    end
 
-    def method_missing(method, *args, &block)
-      send(method, *args, &block)
-    end
+      result
+    }
   end
 end
 
-class Object
-  def self
-    self
-  end
-
-  def maybe(default = nil)
-    Util::Maybe.new(self, default)
-  end
-    
-  def perhaps(default = self)
-    maybe(default)
-  end
 
 class String < Object
-  def mgsub(substitution_hash)
-    Util::mgsub(self, substitution_hash)
-  end
+    def mgsub(substitution_hash)
+      Util::mgsub(self, substitution_hash)
+    end
 end
-  
+
+#end
 =begin
 
 Perhaps is intended especially for type coercions, like:
@@ -108,5 +88,3 @@ def whatever(input)
 end
 
 =end
-
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: meta_parse
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Chhi'mèd Künzang
@@ -32,7 +32,7 @@ extra_rdoc_files: []
 files:
 - lib/meta_parse.rb
 - lib/util.rb
-homepage: 
+homepage: https://github.com/clkunzang/meta_parse
 licenses:
 - MIT
 metadata: {}