jcrvalidator 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cc188a7903b23b3993edd4698a1236b3ae35d0d9
-  data.tar.gz: 81a988438d5eab9632868480125122995aee3cb6
+  metadata.gz: 0e68e95dd86cf0ba170eae8a3ead3acb7c44ab59
+  data.tar.gz: fe3a8c25bf2e420c43db8c32f33e764f7356d766
 SHA512:
-  metadata.gz: db91cb6666489b13f280b89fe852bf20fb4a0b0b284eeddbfe58b6d27f577677d6b84083eb172f17ca0a4604c4dbfc18f93e4e4c84476ed9ad49d6a0b5b94296
-  data.tar.gz: 1f7edd537bb8a90788ea8b28bdb2119590e7a43cbc814eab3b80c75ab7fab008ab327f2eb388a83ce49d8f9b49d7b53e1c388aaea8a807ca1eb8a9a82c8f84f4
+  metadata.gz: 6d8a19a053ff78eeb76b2b46ee0c48be126465a80825737e87881cbdf4c9f7e4e1b9dae9c15b0768ddb27f091f4196e761f44ab2c65cc19a19a86288bbdb8d51
+  data.tar.gz: ba031e433185f9857056a62759caee2d7edf396cc6067d35e1bd4d3114c9dc9b27985f0bc0a299bd2128095739f0b48724afdda750e14dad575040cdb78a7a0e

data/lib/jcr/check_groups.rb

@@ -27,8 +27,6 @@ module JCR
         check_groups( tree[:rule], mapping )
       elsif tree[:primitive_rule]
         check_value_for_group( tree[:primitive_rule], mapping )
-      elsif tree[:type_choice_signifier]
-        check_value_for_group( tree, mapping )
       elsif tree[:member_rule]
         check_member_for_group( tree[:member_rule], mapping )
       elsif tree[:array_rule]
@@ -40,7 +38,7 @@ module JCR
   end
 
   def self.check_value_for_group node, mapping
-    if node[:group_rule]
+    if node.is_a?( Hash ) && node[:group_rule]
       disallowed_group_in_value?( node[:group_rule], mapping )
     end
   end

data/lib/jcr/evaluate_array_rules.rb

@@ -47,6 +47,18 @@ module JCR
 
   def self.evaluate_array_rule jcr, rule_atom, data, econs, behavior = nil
 
+    push_trace_stack( econs, jcr )
+    trace( econs, "Evaluating array rule starting at #{slice_to_s(jcr)} against", data )
+    trace_def( econs, "array", jcr, data )
+    retval = evaluate_array( jcr, rule_atom, data, econs, behavior )
+    trace_eval( econs, "Array", retval )
+    pop_trace_stack( econs )
+    return retval
+
+  end
+
+  def self.evaluate_array jcr, rule_atom, data, econs, behavior = nil
+
     rules, annotations = get_rules_and_annotations( jcr )
 
     ordered = true
@@ -63,21 +75,21 @@ module JCR
     end
 
     # if the data is not an array
-    return evaluate_reject( annotations,
-      Evaluation.new( false, "#{data} is not an array at #{jcr} from #{rule_atom}") ) unless data.is_a? Array
+    return evaluate_not( annotations,
+      Evaluation.new( false, "#{data} is not an array #{raised_rule(jcr,rule_atom)}"), econs ) unless data.is_a? Array
 
     # if the array is zero length and there are zero sub-rules (it is suppose to be empty)
-    return evaluate_reject( annotations,
-      Evaluation.new( true, nil ) ) if rules.empty? && data.empty?
+    return evaluate_not( annotations,
+      Evaluation.new( true, nil ), econs ) if rules.empty? && data.empty?
 
     # if the array is not empty and there are zero sub-rules (it is suppose to be empty)
-    return evaluate_reject( annotations,
-      Evaluation.new( false, "Non-empty array at #{jcr} from #{rule_atom}" ) ) if rules.empty? && data.length != 0
+    return evaluate_not( annotations,
+      Evaluation.new( false, "Non-empty array for #{raised_rule(jcr,rule_atom)}" ), econs ) if rules.empty? && data.length != 0
 
     if ordered
-      return evaluate_reject( annotations, evaluate_array_rule_ordered( rules, rule_atom, data, econs, behavior ) )
+      return evaluate_not( annotations, evaluate_array_rule_ordered( rules, rule_atom, data, econs, behavior ), econs )
     else
-      return evaluate_reject( annotations, evaluate_array_rule_unordered( rules, rule_atom, data, econs, behavior ) )
+      return evaluate_not( annotations, evaluate_array_rule_unordered( rules, rule_atom, data, econs, behavior ), econs )
     end
   end
 
@@ -97,7 +109,7 @@ module JCR
         break
       end
 
-      repeat_min, repeat_max = get_repetitions( rule )
+      repeat_min, repeat_max, repeat_step = get_repetitions( rule, econs )
 
       # group rules must be evaluated differently
       # groups require the effects of the evaluation to be discarded if they are false
@@ -110,7 +122,7 @@ module JCR
         else
           for i in 1..repeat_min do
             if array_index == data.length
-              return Evaluation.new( false, "array is not large enough for #{jcr} from #{rule_atom}" )
+              return Evaluation.new( false, "array is not large enough for #{raised_rule(jcr,rule_atom)}" )
             else
               group_behavior = ArrayBehavior.new( behavior )
               group_behavior.last_index = array_index
@@ -146,7 +158,7 @@ module JCR
         else
           for i in 1..repeat_min do
             if array_index == data.length
-              return Evaluation.new( false, "array is not large enough for #{jcr} from #{rule_atom}" )
+              return Evaluation.new( false, "array is not large enough for #{raised_rule(jcr,rule_atom)}" )
             else
               retval = evaluate_rule( rule, rule_atom, data[ array_index ], econs, nil )
               break unless retval.success
@@ -166,12 +178,16 @@ module JCR
 
       end # end if grule else
 
+      if repeat_step && array_index % repeat_step != 0
+        retval = Evaluation.new( false, "Matches (#{array_index }) do not meat repetition step for #{repeat_max} % #{repeat_step}")
+      end
+
     end
 
     behavior.last_index = array_index
 
     if data.length > array_index && behavior.extra_prohibited
-      retval = Evaluation.new( false, "More itmes in array than specified for #{jcr} from #{rule_atom}" )
+      retval = Evaluation.new( false, "More itmes in array than specified for #{raised_rule(jcr,rule_atom)}" )
     end
 
     return retval
@@ -196,7 +212,7 @@ module JCR
         break
       end
 
-      repeat_min, repeat_max = get_repetitions( rule )
+      repeat_min, repeat_max, repeat_step = get_repetitions( rule, econs )
 
       # group rules must be evaluated differently
       # groups require the effects of the evaluation to be discarded if they are false
@@ -220,11 +236,13 @@ module JCR
         end
 
         if successes == 0 && repeat_min > 0
-          retval = Evaluation.new( false, "array does not contain #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "array does not contain #{rule} for #{raised_rule(jcr,rule_atom)}")
         elsif successes < repeat_min
-          retval = Evaluation.new( false, "array does not have enough #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "array does not have enough #{rule} for #{raised_rule(jcr,rule_atom)}")
         elsif successes > repeat_max
-          retval = Evaluation.new( false, "array has too many #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "array has too many #{rule} for #{raised_rule(jcr,rule_atom)}")
+        elsif repeat_step && successes % repeat_step != 0
+          retval = Evaluation.new( false, "array matches (#{successes}) do not meet repetition step of #{repeat_max} % #{repeat_step} with #{rule} for #{raised_rule(jcr,rule_atom)}")
         else
           retval = Evaluation.new( true, nil )
         end
@@ -245,11 +263,13 @@ module JCR
         end
 
         if successes == 0 && repeat_min > 0
-          retval = Evaluation.new( false, "array does not contain #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "array does not contain #{rule} for #{raised_rule(jcr,rule_atom)}")
         elsif successes < repeat_min
-          retval = Evaluation.new( false, "array does not have enough #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "array does not have enough #{rule} for #{raised_rule(jcr,rule_atom)}")
         elsif successes > repeat_max
-          retval = Evaluation.new( false, "array has too many #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "array has too many #{rule} for #{raised_rule(jcr,rule_atom)}")
+        elsif repeat_step && successes % repeat_step != 0
+          retval = Evaluation.new( false, "array matches (#{successes}) do not meet repetition step of #{repeat_max} % #{repeat_step} with #{rule} for #{raised_rule(jcr,rule_atom)}")
         else
           retval = Evaluation.new( true, nil)
         end
@@ -261,10 +281,14 @@ module JCR
     behavior.last_index = highest_index
 
     if data.length > behavior.checked_hash.length && behavior.extra_prohibited
-      retval = Evaluation.new( false, "More itmes in array than specified for #{jcr} from #{rule_atom}" )
+      retval = Evaluation.new( false, "More itmes in array than specified for #{raised_rule(jcr,rule_atom)}" )
     end
 
     return retval
   end
 
+  def self.array_to_s( jcr, shallow=true )
+    rules, annotations = get_rules_and_annotations( jcr )
+    return "#{annotations_to_s( annotations)} [ #{rules_to_s( rules, shallow )} ]"
+  end
 end

data/lib/jcr/evaluate_group_rules.rb

@@ -22,25 +22,43 @@ require 'big-phoney'
 require 'jcr/parser'
 require 'jcr/map_rule_names'
 require 'jcr/check_groups'
+require 'jcr/evaluate_rules'
 
 module JCR
 
   def self.evaluate_group_rule jcr, rule_atom, data, econs, behavior = nil
 
+    push_trace_stack( econs, jcr )
+    trace( econs, "Evaluating group rule against ", data )
+    trace_def( econs, "group", jcr, data )
+    retval = evaluate_group( jcr, rule_atom, data, econs, behavior )
+    trace_eval( econs, "Group", retval )
+    pop_trace_stack( econs )
+    return retval
+
+  end
+
+  def self.evaluate_group jcr, rule_atom, data, econs, behavior = nil
+
     rules, annotations = get_rules_and_annotations( jcr )
 
     retval = nil
 
     rules.each do |rule|
       if rule[:choice_combiner] && retval && retval.success
-        return evaluate_reject( annotations, retval ) # short circuit
+        return evaluate_not( annotations, retval, econs ) # short circuit
       elsif rule[:sequence_combiner] && retval && !retval.success
-        return evaluate_reject( annotations, retval ) # short circuit
+        return evaluate_not( annotations, retval, econs ) # short circuit
       end
       retval = evaluate_rule( rule, rule_atom, data, econs, behavior )
     end
 
-    return evaluate_reject( annotations, retval )
+    return evaluate_not( annotations, retval, econs )
+  end
+
+  def self.group_to_s( jcr, shallow=true)
+    rules, annotations = get_rules_and_annotations( jcr )
+    return "#{annotations_to_s( annotations)} ( #{rules_to_s(rules,shallow)} )"
   end
 
 end

data/lib/jcr/evaluate_member_rules.rb

@@ -27,10 +27,23 @@ module JCR
 
   def self.evaluate_member_rule jcr, rule_atom, data, econs
 
+    push_trace_stack( econs, jcr )
+    trace( econs, "Evaluating member rule for key '#{data[0]}' starting at #{slice_to_s(jcr)} against ", data[1])
+    trace_def( econs, "member", jcr, data )
+    retval = evaluate_member( jcr, rule_atom, data, econs )
+    trace_eval( econs, "Member", retval )
+    pop_trace_stack( econs )
+    return retval
+
+  end
+
+  def self.evaluate_member jcr, rule_atom, data, econs
+
     # unlike the other evaluate functions, here data is not just the json data.
     # it is an array, the first element being the member name or regex and the
     # second being the json data to be furthered on to other evaluation functions
 
+
     rules, annotations = get_rules_and_annotations( jcr )
     rule = rules[0]
 
@@ -50,12 +63,28 @@ module JCR
 
     if member_match
       e = evaluate_rule( rule, rule_atom, data[ 1 ], econs )
-      return evaluate_reject( annotations, e )
+      return evaluate_not( annotations, e, econs )
     end
 
-    return evaluate_reject( annotations,
-       Evaluation.new( false, "#{match_spec} does not match #{data[0]} for #{jcr} from #{rule_atom}" ) )
+    return evaluate_not( annotations,
+       Evaluation.new( false, "#{match_spec} does not match #{data[0]} for #{raised_rule( jcr, rule_atom)}" ), econs )
 
   end
 
+  def self.member_to_s( jcr, shallow=true )
+    rules, annotations = get_rules_and_annotations( jcr )
+    retval = ""
+    rule = rules[ 0 ]
+    case
+      when rule[:member_name]
+        retval = %Q|"#{rule[:member_name][:q_string].to_s}"|
+      when rule[:member_regex]
+        retval = "/#{rule[:member_regex][:regex].to_s}/"
+      else
+        retval = "** unknown member rule **"
+    end
+    retval = retval + " : " + rule_to_s( rule, shallow )
+    return annotations_to_s( annotations ) + retval
+  end
+
 end

data/lib/jcr/evaluate_object_rules.rb

@@ -29,19 +29,31 @@ module JCR
 
   def self.evaluate_object_rule jcr, rule_atom, data, econs, behavior = nil
 
+    push_trace_stack( econs, jcr )
+    trace( econs, "Evaluating object rule starting at #{slice_to_s(jcr)} against", data )
+    trace_def( econs, "object", jcr, data )
+    retval = evaluate_object( jcr, rule_atom, data, econs, behavior )
+    trace_eval( econs, "Object", retval )
+    pop_trace_stack( econs )
+    return retval
+
+  end
+
+  def self.evaluate_object jcr, rule_atom, data, econs, behavior = nil
+
     rules, annotations = get_rules_and_annotations( jcr )
 
     # if the data is not an object (Hash)
-    return evaluate_reject( annotations,
-      Evaluation.new( false, "#{data} is not an object at #{jcr} from #{rule_atom}") ) unless data.is_a? Hash
+    return evaluate_not( annotations,
+      Evaluation.new( false, "#{data} is not an object for #{raised_rule(jcr,rule_atom)}"), econs ) unless data.is_a? Hash
 
     # if the object has no members and there are zero sub-rules (it is suppose to be empty)
-    return evaluate_reject( annotations,
-      Evaluation.new( true, nil ) ) if rules.empty? && data.length == 0
+    return evaluate_not( annotations,
+      Evaluation.new( true, nil ), econs ) if rules.empty? && data.length == 0
 
     # if the object has members and there are zero sub-rules (it is suppose to be empty)
-    return evaluate_reject( annotations,
-      Evaluation.new( false, "Non-empty object at #{jcr} from #{rule_atom}" ) ) if rules.empty? && data.length != 0
+    return evaluate_not( annotations,
+      Evaluation.new( false, "Non-empty object for #{raised_rule(jcr,rule_atom)}" ), econs ) if rules.empty? && data.length != 0
 
     retval = nil
     behavior = ObjectBehavior.new unless behavior
@@ -52,10 +64,10 @@ module JCR
       if rule[:choice_combiner] && retval && retval.success
         next
       elsif rule[:sequence_combiner] && retval && !retval.success
-        return evaluate_reject( annotations, retval ) # short circuit
+        return evaluate_not( annotations, retval, econs ) # short circuit
       end
 
-      repeat_min, repeat_max = get_repetitions( rule )
+      repeat_min, repeat_max, repeat_step = get_repetitions( rule, econs )
 
       # Pay attention here:
       # Group rules need to be treated differently than other rules
@@ -67,8 +79,9 @@ module JCR
       if (grule = get_group(rule, econs))
 
         successes = 0
-        for i in 0..repeat_max
+        for i in 0..repeat_max-1
           group_behavior = ObjectBehavior.new
+          group_behavior.checked_hash.merge!( behavior.checked_hash )
           e = evaluate_rule( grule, rule_atom, data, econs, group_behavior )
           if e.success
             behavior.checked_hash.merge!( group_behavior.checked_hash )
@@ -79,29 +92,66 @@ module JCR
         end
 
         if successes == 0 && repeat_min > 0
-          retval = Evaluation.new( false, "object does not contain group #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "object does not contain group #{rule} for #{raised_rule(jcr,rule_atom)}")
         elsif successes < repeat_min
-          retval = Evaluation.new( false, "object does not have contain necessary number of group #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "object does not have contain necessary number of group #{rule} for #{raised_rule(jcr,rule_atom)}")
+        elsif repeat_step && successes % repeat_step != 0
+          retval = Evaluation.new( false, "object matches (#{successes}) do not have contain repetition #{repeat_max} % #{repeat_step} of group #{rule} for #{raised_rule(jcr,rule_atom)}")
         else
           retval = Evaluation.new( true, nil )
         end
 
       else # if not grule
 
-        repeat_results = data.select do |k,v|
-          unless behavior.checked_hash[k]
-            e = evaluate_rule(rule, rule_atom, [k, v], econs, nil)
-            behavior.checked_hash[k] = e.success
-            e.success
+        repeat_results = nil
+
+        # do a little lookahead for member rules defined by names
+        # if defined by a name, and not a regex, just pluck it from the object
+        # and short-circuit the enumeration
+
+        lookahead = get_leaf_rule( rule, econs )
+        lrules, lannotations = get_rules_and_annotations( lookahead[:member_rule] )
+        if lrules[0][:member_name]
+
+          repeat_results = {}
+          k = lrules[0][:member_name][:q_string].to_s
+          v = data[k]
+          if v
+            unless behavior.checked_hash[k]
+              e = evaluate_rule(rule, rule_atom, [k, v], econs, nil)
+              behavior.checked_hash[k] = e.success
+              repeat_results[ k ] = v if e.success
+            end
+          else
+            trace( econs, "No member '#{k}' found in object.")
+          end
+
+        else
+
+          trace( econs, "Scanning object.")
+          i = 0
+          repeat_results = data.select do |k,v|
+            unless behavior.checked_hash[k]
+              if i < repeat_max
+                e = evaluate_rule(rule, rule_atom, [k, v], econs, nil)
+                behavior.checked_hash[k] = e.success
+                i = i + 1 if e.success
+                e.success
+              end
+            end
           end
+
         end
 
+        trace( econs, "Found #{repeat_results.length} matching members repetitions in object with min #{repeat_min} and max #{repeat_max}" )
         if repeat_results.length == 0 && repeat_min > 0
-          retval = Evaluation.new( false, "object does not contain #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "object does not contain #{rule} for #{raised_rule(jcr,rule_atom)}")
         elsif repeat_results.length < repeat_min
-          retval = Evaluation.new( false, "object does not have enough #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "object does not have enough #{rule} for #{raised_rule(jcr,rule_atom)}")
         elsif repeat_results.length > repeat_max
-          retval = Evaluation.new( false, "object has too many #{rule} for #{jcr} from #{rule_atom}")
+          retval = Evaluation.new( false, "object has too many #{rule} for #{raised_rule(jcr,rule_atom)}")
+        elsif repeat_step && repeat_results.length % repeat_step != 0
+          retval = Evaluation.new( false, "object matches (#{repeat_results.length}) does not match repetition step of #{repeat_max} & #{repeat_step} for #{rule} for #{raised_rule(jcr,rule_atom)}")
         else
           retval = Evaluation.new( true, nil)
         end
@@ -109,7 +159,11 @@ module JCR
 
     end # end if grule else
 
-    return evaluate_reject( annotations, retval )
+    return evaluate_not( annotations, retval, econs )
   end
 
+  def self.object_to_s( jcr, shallow=true )
+    rules, annotations = get_rules_and_annotations( jcr )
+    return "#{annotations_to_s( annotations)} { #{rules_to_s(rules,shallow)} }"
+  end
 end

data/lib/jcr/evaluate_rules.rb

@@ -14,6 +14,7 @@
 
 require 'ipaddr'
 require 'time'
+require 'pp'
 require 'addressable/uri'
 require 'addressable/template'
 require 'email_address_validator'
@@ -52,9 +53,11 @@ module JCR
   end
 
   class EvalConditions
-    attr_accessor :mapping, :callbacks
-    def initialize mapping, callbacks
+    attr_accessor :mapping, :callbacks, :trace, :trace_stack
+    def initialize mapping, callbacks, trace = false
       @mapping = mapping
+      @trace = trace
+      @trace_stack = []
       if callbacks
         @callbacks = callbacks
       else
@@ -64,6 +67,13 @@ module JCR
   end
 
   def self.evaluate_rule jcr, rule_atom, data, econs, behavior = nil
+    if jcr.is_a?( Hash )
+      if jcr[:rule_name]
+        rn = slice_to_s( jcr[:rule_name] )
+        trace( econs, "Named Rule: #{rn}" )
+      end
+    end
+
     retval = Evaluation.new( false, "failed to evaluate rule properly" )
     case
       when behavior.is_a?( ArrayBehavior )
@@ -75,6 +85,7 @@ module JCR
       when jcr[:target_rule_name]
         target = econs.mapping[ jcr[:target_rule_name][:rule_name].to_s ]
         raise "Target rule not in mapping. This should have been checked earlier." unless target
+        trace( econs, "Referencing target rule #{slice_to_s(target)} from #{slice_to_s( jcr[:target_rule_name][:rule_name] )}" )
         retval = evaluate_rule( target, target, data, econs, behavior )
       when jcr[:primitive_rule]
         retval = evaluate_value_rule( jcr[:primitive_rule], rule_atom, data, econs)
@@ -113,19 +124,26 @@ module JCR
     elsif retval.is_a? String
       retval = Evaluation.new( false, retval )
     end
+    trace( econs, "Callback #{callback} given evaluation of #{e.success} and returned #{retval}")
     return retval
   end
 
-  def self.get_repetitions rule
+  def self.get_repetitions rule, econs
 
     repeat_min = 1
     repeat_max = 1
+    repeat_step = nil
     if rule[:optional]
       repeat_min = 0
       repeat_max = 1
     elsif rule[:one_or_more]
       repeat_min = 1
       repeat_max = Float::INFINITY
+      repeat_step = rule[:repetition_step].to_s.to_i if rule[:repetition_step]
+    elsif rule[:zero_or_more]
+      repeat_min = 0
+      repeat_max = Float::INFINITY
+      repeat_step = rule[:repetition_step].to_s.to_i if rule[:repetition_step]
     elsif rule[:specific_repetition] && rule[:specific_repetition].is_a?( Parslet::Slice )
       repeat_min = repeat_max = rule[:specific_repetition].to_s.to_i
     else
@@ -146,9 +164,16 @@ module JCR
           repeat_max = o.to_s.to_i
         end
       end
+      o = rule[:repetition_step]
+      if o
+        if o.is_a?( Parslet::Slice )
+          repeat_step = o.to_s.to_i
+        end
+      end
     end
 
-    return repeat_min, repeat_max
+    trace( econs, "rule repetition min = #{repeat_min} max = #{repeat_max} repetition step = #{repeat_step}" )
+    return repeat_min, repeat_max, repeat_step
   end
 
   def self.get_rules_and_annotations jcr
@@ -166,7 +191,7 @@ module JCR
           when sub[:unordered_annotation]
             annotations << sub
             i = i + 1
-          when sub[:reject_annotation]
+          when sub[:not_annotation]
             annotations << sub
             i = i + 1
           when sub[:root_annotation]
@@ -182,16 +207,17 @@ module JCR
     return rules, annotations
   end
 
-  def self.evaluate_reject annotations, evaluation
-    reject = false
+  def self.evaluate_not annotations, evaluation, econs
+    is_not = false
     annotations.each do |a|
-      if a[:reject_annotation]
-        reject = true
+      if a[:not_annotation]
+        is_not = true
         break
       end
     end
 
-    if reject
+    if is_not
+      trace( econs, "Not annotation changing result from #{evaluation.success} to #{!evaluation.success}")
       evaluation.success = !evaluation.success
     end
     return evaluation
@@ -203,9 +229,180 @@ module JCR
     if rule[:target_rule_name]
       target = econs.mapping[ rule[:target_rule_name][:rule_name].to_s ]
       raise "Target rule not in mapping. This should have been checked earlier." unless target
+      trace( econs, "Referencing target rule #{slice_to_s(target)} from #{slice_to_s( rule[:target_rule_name][:rule_name] )}" )
       return get_group( target, econs )
     end
     #else
     return false
   end
+
+  def self.get_leaf_rule rule, econs
+    if rule[:target_rule_name ]
+      target = econs.mapping[ rule[:target_rule_name][:rule_name].to_s ]
+      raise "Target rule not in mapping. This should have been checked earlier." unless target
+      trace( econs, "Referencing target rule #{slice_to_s(target)} from #{slice_to_s( rule[:target_rule_name][:rule_name] )}" )
+      return target
+    end
+    #else
+    return rule
+  end
+
+  def self.push_trace_stack econs, jcr
+    econs.trace_stack.push( find_first_slice( jcr ) )
+  end
+
+  def self.pop_trace_stack econs
+    econs.trace_stack.pop
+  end
+
+  def self.elide s
+    if s.length > 60
+      s = s[0..56]
+      s = s + " ..."
+    end
+    return s
+  end
+
+  def self.trace econs, message, data = nil
+    if econs.trace
+      if data
+        if data.is_a? String
+          s = '"' + data + '"'
+        else
+          s = data.pretty_print_inspect
+        end
+        message = "#{message} data: #{elide(s)}"
+      end
+      last = econs.trace_stack.last
+      pos = "#{last.line_and_column}@#{last.offset}" if last
+      puts "[ #{econs.trace_stack.length}:#{pos} ] #{message}"
+    end
+  end
+
+  def self.trace_def econs, type, jcr, data
+    if econs.trace
+      s = ""
+      case type
+        when "value"
+          s = elide( value_to_s( jcr ) )
+        when "member"
+          s = elide( member_to_s( jcr  ) )
+        when "object"
+          s = elide( object_to_s( jcr ) )
+        when "array"
+          s = elide( array_to_s( jcr ) )
+        when "group"
+          s = elide( group_to_s( jcr ) )
+        else
+          s = "** unknown rule **"
+      end
+      trace( econs, "#{type}: #{s}", data)
+    end
+  end
+
+  def self.trace_eval econs, message, evaluation
+    if evaluation.success
+      trace( econs, "#{message} evaluation is true" )
+    else
+      trace( econs, "#{message} evaluation failed: #{evaluation.reason}")
+    end
+  end
+
+  def self.find_first_slice slice
+    if slice.is_a? Parslet::Slice
+      return slice
+    elsif slice.is_a?( Hash ) && !slice.empty?
+      s = nil
+      slice.values.each do |v|
+        s = find_first_slice( v )
+        break if s
+      end
+      return s if s
+    elsif slice.is_a?( Array ) && !slice.empty?
+      s = nil
+      slice.each do |i|
+        s = find_first_slice( i )
+        break if s
+      end
+      return s if s
+    end
+    #else
+    return nil
+  end
+
+  def self.slice_to_s slice
+    s = find_first_slice( slice )
+    if s.is_a? Parslet::Slice
+      pos = s.line_and_column
+      retval = "'#{s.inspect}' ( line #{pos[0]} column #{pos[1]} )"
+    else
+      retval = slice.to_s
+    end
+    retval
+  end
+
+  def self.raised_rule jcr, rule_atom
+    " rule at #{slice_to_s(jcr)} [ #{jcr} ] from rule at #{slice_to_s(rule_atom)}"
+  end
+
+  def self.rule_to_s( rule, shallow=true)
+    if rule[:primitive_rule]
+      retval = value_to_s( rule[:primitive_rule] )
+    elsif rule[:member_rule]
+      retval = member_to_s( rule[:member_rule], shallow )
+    elsif rule[:object_rule]
+      retval = object_to_s( rule[:object_rule], shallow )
+    elsif rule[:array_rule]
+      retval = array_to_s( rule[:array_rule], shallow )
+    elsif rule[:group_rule]
+      retval = group_to_s( rule[:group_rule], shallow )
+    elsif rule[:target_rule_name]
+      retval = target_to_s( rule[:target_rule_name] )
+    elsif rule[:rule_name]
+      retval = "rule: #{rule[:rule_name].to_s}"
+    elsif rule[:rule]
+      retval = rule_to_s( rule[:rule], shallow )
+    else
+      retval = "** unknown rule definition **"
+    end
+    return retval
+  end
+
+  def self.rules_to_s( rules, shallow=true)
+    retval = ""
+    rules.each do |rule|
+      if rule[:rule_name]
+        next
+      elsif rule[:choice_combiner]
+        retval = retval + " | "
+      elsif rule[:sequence_combiner]
+        retval = retval + " , "
+      end
+      retval = retval + rule_to_s( rule, shallow )
+    end
+    return retval
+  end
+
+  def self.annotations_to_s( annotations )
+    retval = ""
+    annotations.each do |a|
+      case
+        when a[:unordered_annotation]
+          retval = retval + " @{unordered}"
+        when a[:not_annotation]
+          retval = retval + " @{not}"
+        when a[:root_annotation]
+          retval = retval + " @{root}"
+        else
+          retval = retval + " @{ ** unknown annotation ** }"
+      end
+    end if annotations
+    retval = retval + " " if retval.length != 0
+    return retval
+  end
+
+  def self.target_to_s( jcr )
+    return annotations_to_s( jcr[:annotations] ) + " target: " + jcr[:rule_name].to_s
+  end
+
 end