cml 1.4.2 → 1.5.0

data/lib/cml/logic.rb

@@ -0,0 +1,424 @@
+module CML
+  # Build and calculate things based on some CML's dependendency tree as
+  # dictated by `only-if` CML logic.
+  class LogicTree
+    attr_reader :root_nodes, :nodes, :parser, :errors
+    
+    DEPTH_LIMIT = 10
+    
+    def initialize( parser )
+      @parser = parser
+      @errors = []
+      # Hash of Node instances, keyed by tag names.
+      @nodes = @parser.tags.inject( {} ) do |memo, tag|
+        memo[tag.name] = Node.new( self, tag )
+        memo
+      end
+    end
+    
+    # Recursively determine the depth of a Node based on logic. For example:
+    # 
+    #         A
+    #        / \
+    #       B   C
+    #      / \
+    #     D   E
+    # 
+    # Which gives depths of:
+    # 
+    #     A = 1
+    #     B, C = 2
+    #     D, E = 3
+    # 
+    # If we've recursed 10 times, we're probably in a cycle, so we just return
+    # a max of 10 here.
+    def depth( node, recurse_depth = 1 )
+      return 1 unless node.has_logic? && recurse_depth < DEPTH_LIMIT
+      depth = 1 + node.depends_on.map do |depended_node|
+        self.depth( depended_node, recurse_depth + 1 )
+      end.max
+    end
+    
+    def max_depth
+      @nodes.values.map do |node|
+        node.depth
+      end.max
+    rescue CML::TagLogic::Error, CML::LogicTree::Graph::Error
+      # When logic contains errors, return depth of 1 (maintains backwards compatibility)
+      1
+    end
+    
+    def has_grouped_logic?
+      @nodes.values.any? {|node| node.has_grouped_logic? }
+    rescue CML::TagLogic::Error, CML::LogicTree::Graph::Error
+      # When logic contains errors, return no grouping (maintains backwards compatibility)
+      false
+    end
+    
+    def has_liquid_logic?
+      @nodes.values.any? {|node| node.has_liquid_logic? }
+    end
+    
+    def valid?
+      @errors = []
+      graph
+      true
+    rescue CML::TagLogic::Error, CML::LogicTree::Graph::Error => e
+      @errors << e.message
+      false
+    rescue
+      @errors << "CML only-if logic cannot be parsed."
+      false
+    end
+    
+    def graph
+      @graph ||= Graph.new(self)
+      @graph.structure
+    end
+    
+    # A node in CML::LogicTree, containing a CML::Tag in @tag
+    class Node
+      attr_reader :tag, :tree
+      
+      def initialize( tree, tag )
+        @tree = tree
+        @tag = tag
+        @tag.logic_tree = @tree
+        self
+      end
+      
+      def depth
+        @depth ||= @tree.depth( self )
+      end
+      
+      # Hash of tag dependency details (name/is_not/match_key) on (only-if logic)
+      def dependencies_on(&block)
+        if block_given?
+          @tag.dependencies_on_fields(&block)
+        else
+          @dependencies_on_nodes ||= @tag.dependencies_on_fields
+        end
+      end
+      
+      # Array of Node instances the tag depends on (only-if logic)
+      def depends_on
+        @depends_on_nodes ||= @tag.depends_on_fields.map do |field_name|
+          @tree.nodes[field_name]
+        end.compact.uniq
+      end
+      
+      def has_logic?
+        self.depends_on.size > 0
+      end
+      
+      def has_grouped_logic?
+        @tag.depends_on_fields
+        !!@tag.has_grouped_logic
+      end
+      
+      def has_liquid_logic?
+        @tag.depends_on_fields
+        !!@tag.has_liquid_logic
+      end
+    end
+  end
+  
+  # Logic behavior included in CML::Parser
+  module ParserLogic
+    def has_nested_logic?
+      self.logic_tree.max_depth > 2
+    end
+    
+    def has_grouped_logic?
+      self.logic_tree.has_grouped_logic?
+    end
+    
+    def has_liquid_logic?
+      self.logic_tree.has_liquid_logic?
+    end
+    
+    def logic_tree
+      @logic_tree ||= CML::LogicTree.new( self )
+    end
+  end
+  
+  # Logic behavior included in CML::Tag
+  module TagLogic
+    attr_accessor :logic_tree, :has_grouped_logic, :has_liquid_logic, :errors
+    
+    # These Errors cause CML::Parser#valid? failures; their messages are 
+    # end-user-facing and should help the user correct their mistakes.
+    class Error < StandardError; end
+    class NodeNotFound < Error; end
+    
+    # Override in Tags classes that should be omitted from the logic graph.
+    def in_logic_graph?
+      true
+    end
+    
+    def only_if
+      @only_if ||= @attrs["only-if"].to_s
+    end
+    
+    # For each only-if token, e.g, `omg`, `!omg`, `omg:[0]`, `omg:[wtf]`, etc.,
+    # call the block with args field_name, match_key & is_not.
+    def each_logic_token_in(logic_expression)
+      return unless block_given?
+      logic_expression.split( /\+\+|\|\|/ ).each do |logic_token|
+        field_name, match_key = logic_token.split( ":" )
+        
+        # prune the possibly-dangling open paren from logic grouping
+        field_name.gsub!( /^\(/, '' )
+        # prune the possibly-dangling close paren from logic grouping
+        match_key.gsub!( /\)$/, '') if match_key
+        
+        # detect NOT logic
+        is_not = if /^!/===field_name
+          field_name = field_name.gsub( /^!/, '' )
+          true
+        else
+          false
+        end
+        
+        yield field_name, match_key, is_not
+      end
+    end
+    
+    # Generate the full logic structure for an only-if.
+    #
+    # The optional block can be used as a flat collector of all fields; its return value is ignored.
+    #
+    def expand_logic(only_if, &block)
+      parsed = CML::TagLogic.parse_expression(only_if)
+      expand_parsed_expression(parsed, &block)
+    end
+    
+    # Generate the full logic structure for a parsed only-if.
+    # 
+    # The optional block can be used as a flat collector of all fields; its return value is ignored.
+    #
+    def expand_parsed_expression(parsed_expression, &block)
+      expanded_tree = {}
+      parsed_expression.each_with_index do |expression_array, i|
+        combinator, phrase = expression_array
+        combinator_key = CML::TagLogic.resolve_combinator(parsed_expression, i)
+        branch = expanded_tree[combinator_key] ||= []
+        
+        if Array===phrase
+          # Recurse for grouped logic
+          branch << expand_parsed_expression(phrase, &block)
+        else
+          name, descs = describe_logic_token(phrase)
+          yield(name, descs) if block_given?
+          value ||= descs
+          branch << { name => value }
+        end
+      end
+      expanded_tree
+    end
+    
+    Or = '||'.freeze
+    And = '&&'.freeze
+    CombinatorDefault = Or
+    CombinatorDict = {
+      '||' => Or,
+      '++' => And
+    }
+    
+    # Return the effective boolean combinator for the given index in the parsed logic.
+    #
+    def self.resolve_combinator(parsed_expression, i, parent_combinator=nil)
+      combinator = parsed_expression[i] && parsed_expression[i][0]
+      selected = if (combinator.nil? || combinator.size==0) && parent_combinator
+        CombinatorDict[parent_combinator]
+      elsif !combinator.nil? && combinator.size>0
+        # Use the current phrase's combinator.
+        CombinatorDict[combinator]
+      else
+        if parsed_expression[i+1]
+          # Use the next phrase's combinator
+          CombinatorDict[ parsed_expression[i+1][0] ]
+        else
+          CombinatorDefault
+        end
+      end
+      raise(RuntimeError, "Combinator for index #{i} could not be selected from: #{parsed_expression.inspect}") if 
+        selected.nil? || selected.size==0
+      selected
+    end
+    
+    CombinatorExp     = '(\+\+||\|\||)'.freeze
+    OrCombinatorExp     = '(\|\||)'.freeze
+    GroupExp          = '\(([^\(\)]+)\)'.freeze
+    AndPhraseExp          = '([^\(\)\|]+\+\+[^\(\)\|]+)'.freeze
+    TokenExp          = '([^\(\)\+\|]+)'.freeze
+    PrecedenceRegexp = /#{CombinatorExp}#{GroupExp}|#{CombinatorExp}#{AndPhraseExp}|#{CombinatorExp}#{TokenExp}/
+    TokenRegexp = /#{CombinatorExp}#{TokenExp}/
+    
+    def self.parse_expression(logic_expression)
+      parsed_expression = []
+      logic_expression.scan( PrecedenceRegexp ) do |group_combinator, group_phrase, and_combinator, and_phrase, combinator, token|
+        if group_phrase
+          parsed_expression << [group_combinator, parse_expression(group_phrase)]
+        elsif and_phrase
+          ands = []
+          and_phrase.scan( TokenRegexp ) do |precedence_combinator, precedence_token|
+            ands << [precedence_combinator, precedence_token]
+          end
+          parsed_expression << [and_combinator, ands]
+        else
+          parsed_expression << [combinator, token]
+        end
+      end
+      parsed_expression
+    end
+    
+    # A hash of the Tag's dependencies with "only-if" logic.
+    #
+    # Resolves indexed logic selector keys (e.g. `only-if="pick_a_number:[0]"`) 
+    # into actual values from parents.
+    #
+    # The optional block can be used as a flat collector of all fields; its return value is ignored.
+    #
+    def dependencies_on_fields(&block)
+      return @dependencies_on_fields if @dependencies_on_fields && !block_given?
+      @dependencies_on_fields = {}
+      
+      keep_merge!(dependencies_through_cml_group(&block), @dependencies_on_fields)
+      return @dependencies_on_fields if only_if.empty? || detect_liquid_logic(only_if) || @logic_tree.nil?
+      
+      detect_grouped_logic(only_if)
+      
+      expanded = expand_logic(only_if, &block)
+      
+      keep_merge!(expanded, @dependencies_on_fields)
+      @dependencies_on_fields
+    end
+    
+    # Returns array of field names that this tag depends on with "only-if"
+    # logic.
+    def depends_on_fields
+      return @depends_on_fields if @depends_on_fields
+      @depends_on_fields = []
+      
+      dependencies_on_fields do |name, descs|
+        @depends_on_fields << name
+      end
+      
+      @depends_on_fields
+    end
+    
+    # The <cml::group> only-if logic dependencies
+    #
+    # The optional block can be used as a flat collector of all fields; its return value is ignored.
+    #
+    def dependencies_through_cml_group(&block)
+      return @dependencies_through_cml_group if @dependencies_through_cml_group
+      @dependencies_through_cml_group = {}
+      
+      @logic_tree.parser.each_cml_group_descendant do |group_node, cml_tag, i|
+        next if group_node.attributes['only-if'].nil? || 
+          group_node.attributes['only-if'].value.size <= 0 || 
+            self != cml_tag
+        group_only_if = group_node.attributes['only-if'].value.to_s
+        
+        expanded = expand_logic(group_only_if, &block)
+        keep_merge!(expanded, @dependencies_through_cml_group)
+      end
+      
+      @dependencies_through_cml_group
+    end
+    
+    # For an only-if value, e.g, `omg`, `!omg`, `omg:[0]`, `omg:[wtf]`, etc.,
+    # return an array of the referenced name & an array of hashes of logic properties.
+    def describe_logic_token(logic_token)
+      field_name, match_key = logic_token.split( ":" )
+      
+      # detect NOT logic
+      is_not = if /^!/===field_name
+        field_name = field_name.gsub( /^!/, '' )
+        true
+      else
+        false
+      end
+      
+      unless @logic_tree.nodes[field_name]
+        raise CML::TagLogic::NodeNotFound, "CML element '#{name}' contains only-if logic that references a missing field '#{field_name}'."
+      end
+      
+      descs = []
+      
+      if match_key
+        # unwrap the match key from it's square brackets
+        match_key = match_key.gsub( /^\[([^\]]+)\]$/, "\\1")
+        
+        # when an integer index, set `match_key` to the literal value in the parent tag
+        if /^\d+$/===match_key 
+          unless @logic_tree.nodes[field_name].tag.children
+            raise CML::TagLogic::NodeNotFound, "CML element '#{name}' contains only-if logic that references a child index, '#{field_name}:[#{match_key}]', but '#{field_name}' contains no child elements."
+          end
+          if (tag_at_index = @logic_tree.nodes[field_name].tag.children[$~.to_s.to_i])
+            descs << { :is_not => is_not, :match_key => tag_at_index.value }
+          end
+          
+        # when 'unchecked' logic "is not the checkbox's value or any of the checkboxes/checkbox values";
+        # is_not logic gets inverted instead of just setting true, just incase we're notting a not
+        elsif 'unchecked'==match_key
+          if @logic_tree.nodes[field_name].tag.tag == 'checkbox'
+            checkbox = @logic_tree.nodes[field_name].tag
+            descs << { :is_not => !is_not, :match_key => checkbox.value }
+          else
+            unless @logic_tree.nodes[field_name].tag.children
+              raise CML::TagLogic::NodeNotFound, "CML element '#{name}' contains only-if logic that references a checked value, '#{field_name}:#{match_key}', but '#{field_name}' is not a checkbox nor contains checkboxes."
+            end
+            @logic_tree.nodes[field_name].tag.children.each do |child|
+              next unless child.tag == 'checkbox'
+              descs << { :is_not => !is_not, :match_key => child.value }
+            end
+          end
+        end
+      end
+      
+      if descs.empty?
+        # When matcher is nil, invert the is_not logic to be semantically accurate.
+        #
+        # i.e. a nil match key actually means "is not blank,"
+        # while a negated nil matcher actually means "is blank"
+        #
+        is_not_with_nil = match_key.nil? ? !is_not : is_not
+        descs << { :is_not => is_not_with_nil, :match_key => match_key }
+      end
+      
+      [field_name, descs]
+    end
+    
+    # Detect parenthetical grouping in only-if logic expressions
+    def detect_grouped_logic(only_if)
+      @errors ||= []
+      if /\([^\(\)]+\)/===only_if
+        @has_grouped_logic = true 
+      end
+    end
+    
+    # Detect Liquid tags in only-if logic expressions
+    def detect_liquid_logic(only_if)
+      @errors ||= []
+      if /\{\{/===only_if
+        @errors << "The logic tree cannot be constructed when only-if contains a Liquid tag: #{only_if}"
+        @has_liquid_logic = true 
+      end
+    end
+    
+    
+    def keep_merge!(hash, target)
+      hash.keys.each do |key|
+        if hash[key].is_a? Hash and self[key].is_a? Hash
+          target[key] = target[key].keep_merge(hash[key])
+          next
+        end
+        target.update(hash) { |key, *values| values.flatten.uniq }
+      end
+      target
+    end
+  end
+end

data/lib/cml/logic_tree/graph.rb

@@ -0,0 +1,107 @@
+module CML
+  class LogicTree
+    
+    # Generates a DAG, directed acyclic graph of the logic tree.
+    class Graph
+      
+      # These Errors cause CML::Parser#valid? failures; their messages are 
+      # end-user-facing and should help the user correct their mistakes.
+      class Error < StandardError; end
+      class UnresolvableDependency < Error; end
+      
+      attr_accessor :logic_tree, :structure
+      
+      def initialize(logic_tree)
+        raise(ArgumentError, "Requires a CML::LogicTree, instead got #{logic_tree.inspect}") unless CML::LogicTree===logic_tree
+        @logic_tree = logic_tree
+        create_structure
+      end
+      
+      # Generate a hash of field names with hashes of properties, e.g.: 
+      #   {
+      #     "omg"=>{
+      #       :outbound_count=>1, :outbound_names=>["w_t_f"] }, 
+      #     "w_t_f"=>{
+      #       :inbound_count=>1, :inbound_names=>["omg"], :inbound_matches=>{"||" => [{"omg"=>[{:match_key => nil, :is_not=>true}]}]} }
+      #   }
+      #
+      # For inbound matches, the match key tests the value of the remote vertex. Boolean combinators are represented here.
+      #
+      def create_structure
+        # First, inbound links.
+        @structure = map_dependencies do |field, cml_tag, dependency_names, dependencies|
+          if dependencies
+            dependency_names.uniq!
+            { :inbound_count => dependency_names.size, :inbound_names => dependency_names, :inbound_matches => dependencies }
+          else
+            {}
+          end
+        end
+        # Map outbound links by iterating over each node's inbound.
+        @structure.each do |vertex, props|
+          next if props.nil? || props[:inbound_names].nil?
+          props[:inbound_names].each do |inbound_name|
+            x = @structure[inbound_name]
+            c, n = x[:outbound_count], x[:outbound_names]
+            x[:outbound_names] = (n ? n<<vertex : [vertex]).sort.uniq
+            x[:outbound_count] = x[:outbound_names].size
+          end
+        end
+        @structure
+      end
+      
+      # Returns a hash of the logic tree's nodes.
+      #
+      # When a block is given, each node's entry is set to the return value of the block.
+      # 
+      def map_dependencies
+        structure = {}
+        deferred_vertex_procs = []
+        deferred_vertex_counts = Hash.new(0)
+        created_vertex_for_fields = []
+        @logic_tree.nodes.select {|k,v| v.tag.in_logic_graph? }.each do |field, cml_tag|
+        
+          # This proc is used to generate each vertex.
+          map_vertex = lambda do |cml_tag, dependency_names, dependencies|
+            if block_given?
+              structure[field] = yield(field, cml_tag, dependency_names, dependencies)
+            else
+              structure[field] = { :cml_tag => cml_tag, :dependency_names => dependency_names, :dependencies => dependencies }
+            end
+            created_vertex_for_fields << field
+          end
+          
+          # Expand dependencies & also collect a simple list of dependency names.
+          dependency_names = []
+          dependencies = cml_tag.dependencies_on {|name, descs| dependency_names << name }
+          
+          # Defer when a CML tag has unsatisfied dependencies, or just generate its vertex.
+          if dependency_names.empty?
+            map_vertex.call(cml_tag, nil, nil)
+          else
+            deferred_vertex_procs << lambda do |this_proc|
+              if dependency_names.all? {|name| created_vertex_for_fields.include? name }
+                map_vertex.call(cml_tag, dependency_names, dependencies)
+              else
+                # Push onto bottom of stack to try again last.
+                raise(UnresolvableDependency, "CML element '#{field}' contains invalid only-if logic.") if 
+                  deferred_vertex_counts[field] > DEPTH_LIMIT
+                deferred_vertex_counts[field] += 1
+                deferred_vertex_procs.unshift(this_proc)
+              end
+            end
+          end
+        end
+        
+        # Iterate through deferred dependencies, filling out the structure as dependencies are satisfied.
+        while !deferred_vertex_procs.empty? do
+          p = deferred_vertex_procs.pop
+          p.call(p) # pass the Proc itself, in case it needs to defer again
+        end
+        
+        structure
+      end
+      
+    end
+  end
+end

data/lib/cml/logic_tree/solver.rb

@@ -0,0 +1,43 @@
+module CML
+  class LogicTree
+    
+    # A utility to solve the logic structures provided by the logic tree.
+    #
+    class Solver
+      
+      # Traverse the tree in logic order, until a solution is found.
+      #
+      # A block is required to process each node, returning nil/false or a solution.
+      #
+      # Returns one value for a single-OR solution or an array for multiple-AND solutions.
+      #
+      def self.recurse(dependencies, dependent_name, &block)
+        solution = nil
+        dependencies.each do |k,v|
+          s = case k
+          when '||'
+            ss = nil
+            v.detect {|vv| ss = recurse(vv, dependent_name, &block) }
+            ss if ss
+          when '&&'
+            catch(:unfullfilled_and) do
+              v.collect do |vv| 
+                rr = recurse(vv, dependent_name, &block)
+                throw(:unfullfilled_and) unless rr 
+                rr
+              end
+            end
+          else
+            yield(dependent_name, k, v[0]) # for a non-boolean node, use the first & only value
+          end
+          if s
+            solution = s
+            break
+          end
+        end
+        solution
+      end
+      
+    end
+  end
+end

data/lib/cml/parser.rb

@@ -1,7 +1,14 @@
 module CML
   class Parser
-    attr_reader :doc, :cftags, :tags, :errors
-    BASE_TAGS_XPATH = ".//cml:*[not(ancestor::cml:checkboxes or ancestor::cml:ratings or ancestor::cml:select or ancestor::cml:radios or self::cml:gold or self::cml:instructions)]"
+    
+    include CML::ParserLogic
+    
+    attr_reader :doc, :cftags, :tags, :errors, :cml_tag_map
+    
+    TAG_XPATH = '//cml:*'
+    BASE_TAGS_XPATH = ".#{TAG_XPATH}[not(ancestor::cml:checkboxes or ancestor::cml:ratings or ancestor::cml:select or ancestor::cml:radios or self::cml:gold or self::cml:instructions)]"
+    GROUP_XPATH = "//cml:group"
+    GROUP_DESCENDANTS_XPATH = ".#{GROUP_XPATH}#{TAG_XPATH}"
     
     def initialize(content, opts = {})
       @opts = opts.merge(:parser => self)
@@ -16,8 +23,10 @@ module CML
       #Pull all cml tags that aren't children
       @cftags = @doc.xpath(BASE_TAGS_XPATH, "xmlns:cml"=>"http://crowdflower.com")
       normalize if opts[:normalize]
+      @cml_tag_map = {}
       @tags = @cftags.map do |t|
-        t = Parser.tag_class(t.name).new(t, @opts)
+        cml_tag = Parser.tag_class(t.name).new(t, @opts)
+        @cml_tag_map[t.object_id] = cml_tag
       end.flatten
     end
     
@@ -31,13 +40,31 @@ module CML
     def convert(opts = nil)
       @opts.merge!(opts) if opts
       cloned = @doc.dup
-      cloned.xpath(BASE_TAGS_XPATH, "xmlns:cml"=>"http://crowdflower.com").each_with_index do |t,i|
-        t.namespace = nil
-        t.replace(@tags[i].convert(opts))
+      
+      base_nodes = cloned.xpath(BASE_TAGS_XPATH, "xmlns:cml"=>"http://crowdflower.com")
+      group_children_nodes = cloned.xpath(GROUP_DESCENDANTS_XPATH, "xmlns:cml"=>"http://crowdflower.com")
+      
+      (base_nodes - group_children_nodes).each_with_index do |node, i|
+        node.namespace = nil
+        real_index = base_nodes.index( node )
+        node.replace(self.tags[real_index].convert(opts))
       end
       cloned
     end
     
+    # Do something for each <cml::group> descendant "base" CML::Tag
+    def each_cml_group_descendant
+      return unless block_given?
+      group_nodes = @doc.xpath(".#{GROUP_XPATH}", "xmlns:cml"=>"http://crowdflower.com")
+      group_nodes.each do |group_node|
+        group_descendant_nodes = group_node.xpath(BASE_TAGS_XPATH, "xmlns:cml"=>"http://crowdflower.com")
+        group_descendant_nodes.each_with_index do |node, i|
+          cml_tag = @cml_tag_map[node.object_id]
+          yield group_node, cml_tag, i
+        end
+      end
+    end
+    
     def normalize
       @cftags.each do |t|
         if ["radios", "select"].include?(t.name)
@@ -59,6 +86,16 @@ module CML
       @fields
     end
     
+    def finite_fields
+      return @finite_fields if @finite_fields
+      @finite_fields = {}
+      @tags.each do |t|
+        next unless t.finite_value?
+        @finite_fields[t.name] = t
+      end
+      @finite_fields
+    end
+    
     def golds(rich = false, opts={})
       unless @golds
         @golds = @tags.map do |tag|
@@ -108,6 +145,9 @@ module CML
           @errors << "#{c} a child of #{t.to_s.split("\n")[0]} has a duplicated value, please specify a unique value attribute."
         end
       end
+      if !logic_tree.valid?
+        @errors += logic_tree.errors
+      end
       @errors.length == 0
     end
     
@@ -151,7 +191,7 @@ module CML
              gsub( />/, "&gt;" ).
              gsub( /"/, "&quot;" )
     end
-        
+    
     #This takes the name of the tag and converts it to the appropriate tag class
     def self.tag_class(name)
       CML::TagClasses[name] || CML::Tags::Unknown