cadenza 0.7.0.rc1 → 0.7.0

data/lib/cadenza/nodes/block_node.rb

@@ -1,17 +1,31 @@
 module Cadenza
-  
+   # The {BlockNode} is a general container with a given name meant to implement
+   # Cadenza's template inheritance feature.  Blocks defined in a template will
+   # override the definition of blocks defined in the parent template.
    class BlockNode
-      attr_accessor :name, :children
+      # @return [String] the name of the node
+      attr_accessor :name
 
-      def initialize(name, children)
+      # @return [Array] the child nodes belonging to this block
+      attr_accessor :children
+
+      # creates a new block node with the given name and child nodes
+      # @param [String] name the name for this block node
+      # @param [Array] children the child nodes belonging to this block node
+      def initialize(name, children=[])
          @name = name
          @children = children
       end
 
+      # @return [Array] a list of any implied global variable names defined by
+      #                 this block's children.
       def implied_globals
          @children.map(&:implied_globals).flatten.uniq
       end
 
+      # @param [BlockNode] rhs
+      # @return [Boolean] true if the given {BlockNode} is equivalent to the this
+      #                   node by value.
       def ==(rhs)
          @name == rhs.name and
          @children == rhs.children

data/lib/cadenza/nodes/boolean_inverse_node.rb

@@ -1,16 +1,27 @@
 module Cadenza
+   # The {BooleanInverseNode} takes an expression and evaluates the logical inverse
+   # of that expression so any expression that evaluates to true will return false
+   # and vice versa.
    class BooleanInverseNode
+      # @return [OperationNode] an evaluatable expression node
       attr_accessor :expression
 
+      # creates a new {BooleanInverseNode} with the given expression
+      # @param [OperationNode] the node this one will invert
       def initialize(expression)
          @expression = expression
       end
 
+      # @param [BooleanInverseNode] rhs
+      # @return [Boolean] if the given {BooleanInverseNode} is equivalent by value
       def ==(rhs)
          @expression == rhs.expression
       end
 
+      # @param [Context] context
+      # @return the value of this node evaluated with the data in the given {Context}
       def eval(context)
+         #TODO: rename me to .evaluate
          !@expression.eval(context)
       end
    end

data/lib/cadenza/nodes/constant_node.rb

@@ -1,19 +1,29 @@
 module Cadenza
+   # The {ConstantNode} holds a value which is not affected by any context given
+   # to it, such as numbers or strings.
    class ConstantNode
+      # @return [Object] the value of this node
       attr_accessor :value
 
+      # constructs a new {ConstantNode} with the given value.
+      # @param [Object] value the value of this constant node
       def initialize(value)
          @value = value
       end
     
+      # @return [Array] any global variable applied to this node (none)
       def implied_globals
          []
       end
 
+      # @param [Context] context
+      # @return [Object] the value of this node evaluated in the given context
       def eval(context)
          @value
       end
           
+      # @param [ConstantNode] rhs
+      # @return [Boolean] if this node and the given one are equivalent by value
       def ==(rhs)
          @value == rhs.value
       end

data/lib/cadenza/nodes/document_node.rb

@@ -1,24 +1,46 @@
 module Cadenza
+  # The {DocumentNode} is intended to be the root node of any parsed AST in
+  # Cadenza. In addition to holding the primary children it also holds data 
+  # that affects the entire document, such as block definitions and the name of
+  # any extended template.
   class DocumentNode
+    # @return [String] the name of the template this document will inherit from
     attr_accessor :extends
+
+    # @return [Array] any child nodes belonging to this one
     attr_accessor :children
+
+    # @return [Hash] a mapping of any blocks defined in this document where the
+    #                key is the name of the block and the value is the {BlockNode}
+    #                itself
     attr_accessor :blocks
     
+    # creates a new {DocumentNode} with the optional children nodes attached to
+    # it.
+    # @param [Array] children any child nodes to initially assign to this node.
     def initialize(children=[])
       @children = children
       @blocks = {}
     end
 
+    # @param [DocumentNode] rhs
+    # @return [Boolean] if the given {DocumentNode} is equivalent by value to this one.
     def ==(rhs)
       @children == rhs.children and
       @extends == rhs.extends and
       @blocks == rhs.blocks
     end
 
+    # adds the given {BlockNode} to this document replacing any existing definition
+    # of the same name.
+    # @param [BlockNode] block
     def add_block(block)
       @blocks[block.name] = block
     end
 
+    # returns a list of any global variable names implied by examining the children
+    # of this node.
+    # @return [Array]
     def implied_globals
       @children.map(&:implied_globals).flatten.uniq
     end

data/lib/cadenza/nodes/filter_node.rb

@@ -1,22 +1,41 @@
 
 module Cadenza
+   # The {FilterNode} is a node which contains the definition for a variable 
+   # filter along with any parameters it is defined with.
    class FilterNode
-      attr_accessor :identifier, :parameters
+      # @return [String] the name of the filter
+      attr_accessor :identifier
 
+      # @return [Array] a list of parameter nodes given to the filter
+      attr_accessor :parameters
+
+      # constructs a new {FilterNode} with the given identifier and parameters
+      # @param [String] identifier the name of the filter
+      # @param [Array] parameters the parameters given to the filter
       def initialize(identifier, parameters=[])
          @identifier = identifier
          @parameters = parameters
       end
 
+      # @param [FilterNode] rhs
+      # @return [Boolean] true if the given filter node is equivalent by value to
+      #                   this node.
       def ==(rhs)
          @identifier == rhs.identifier and
          @parameters == rhs.parameters
       end
 
+      # @return [Array] a list of implied global variable names for this node
       def implied_globals
          @parameters.map(&:implied_globals).flatten.uniq
       end
 
+      # evaluates the filter with the given context and input value and returns
+      # the output of the evaluation.
+      # 
+      # @param [Context] context the context to evaluate with
+      # @param [String] value the input value to filter
+      # @return the input value when passed through this evaluated filter
       def evaluate(context, value)
          params = [value] + @parameters.map {|x| x.eval(context) }
          context.evaluate_filter(@identifier, params)

data/lib/cadenza/nodes/for_node.rb

@@ -1,37 +1,53 @@
 module Cadenza
-  class ForNode
-   attr_accessor :iterator, :iterable, :children
-    
-   MAGIC_LOCALS = %w(forloop.counter forloop.counter0 forloop.first forloop.last)
-
-   def initialize(iterator, iterable, children)
-      @iterator = iterator
-      @iterable = iterable
-      @children = children
-   end
+   # The {ForNode} describe a loop in the template code.  The loop should iterate
+   # over all the elements of the iterable and render its children each time.
+   class ForNode
+      # @return [VariableNode] the iterator object for the loop
+      attr_accessor :iterator
+
+      # @return [VariableNode] the iterable object for the loop
+      attr_accessor :iterable
+
+      # @return [Array] the list of children associated with this loop
+      attr_accessor :children
+
+      MAGIC_LOCALS = %w(forloop.counter forloop.counter0 forloop.first forloop.last)
+
+      # constructs a new {ForNode} with the given iterator, iterable and child
+      # nodes.
+      def initialize(iterator, iterable, children)
+         @iterator = iterator
+         @iterable = iterable
+         @children = children
+      end
+
+      # @return [Array] of all global variable names defined by this node and
+      #                 it's child nodes.
+      def implied_globals
+         iterable_globals = @iterable.implied_globals
+         iterator_globals = @iterator.implied_globals
 
-   def implied_globals
-      iterable_globals = @iterable.implied_globals
-      iterator_globals = @iterator.implied_globals
+         iterator_regex = Regexp.new("^#{@iterator.identifier}[\.](.+)$")
 
-      iterator_regex = Regexp.new("^#{@iterator.identifier}[\.](.+)$")
+         all_children_globals = @children.map(&:implied_globals).flatten
 
-      all_children_globals = @children.map(&:implied_globals).flatten
+         children_globals = all_children_globals.reject {|x| x =~ iterator_regex }
 
-      children_globals = all_children_globals.reject {|x| x =~ iterator_regex }
+         iterator_children_globals = all_children_globals.select {|x| x =~ iterator_regex }.map do |identifier|
+            "#{iterable.identifier}.#{iterator_regex.match(identifier)[1]}"
+         end
 
-      iterator_children_globals = all_children_globals.select {|x| x =~ iterator_regex }.map do |identifier|
-         "#{iterable.identifier}.#{iterator_regex.match(identifier)[1]}"
+         (iterable_globals | children_globals | iterator_children_globals) - MAGIC_LOCALS - iterator_globals
       end
 
-      (iterable_globals | children_globals | iterator_children_globals) - MAGIC_LOCALS - iterator_globals
-   end
+      # @param [ForNode] rhs
+      # @return [Boolean] true if the given {ForNode} is equivalent by value to
+      #                   this node.
+      def ==(rhs)
+         @iterator == rhs.iterator and
+         @iterable == rhs.iterable and
+         @children == rhs.children
+      end
 
-   def ==(rhs)
-      @iterator == rhs.iterator and
-      @iterable == rhs.iterable and
-      @children == rhs.children
    end
-    
-  end
 end

data/lib/cadenza/nodes/generic_block_node.rb

@@ -1,17 +1,38 @@
  module Cadenza
+   # The {GenericBlockNode} allows the end user of Cadenza to provide custom 
+   # block rendering logic via a proc defined on {Context}.
    class GenericBlockNode
-      attr_accessor :identifier, :children, :parameters
+      # @return [String] the name of the block as defined in {Context}
+      attr_accessor :identifier
 
+      # @return [Array] a list of Node objects which are this block's child nodes
+      attr_accessor :children
+
+      # @return [Array] a list of Node objects which hold the value of parameters
+      #                 passed to this block.
+      attr_accessor :parameters
+
+      # Creates a new generic block with the given name, children and parameters.
+      # @param [String] identifier the name of the node as defined in {Context}
+      # @param [Array] children the child nodes belonging to this block
+      # @param [Array] parameters the nodes holding the value of parameters
+      #                passed to this block.
       def initialize(identifier, children, parameters=[])
          @identifier = identifier
          @children = children
          @parameters = parameters
       end    
 
+      # @return [Array] a list of variable names implied to be globals in the node
+      # @note not yet implemented
       def implied_globals
+         #TODO: implement me please, kthxbai
          []
       end
     
+      # @param [GenericBlockNode] rhs
+      # @return [Boolean] true if the given node is equivalent by value to the
+      #                   current node.
       def ==(rhs)
          @identifier == rhs.identifier and
          @children == rhs.children and

data/lib/cadenza/nodes/if_node.rb

@@ -1,42 +1,68 @@
 module Cadenza
-  class IfNode
-   attr_accessor :expression, :true_children, :false_children
+   # The {IfNode} is a structure for rendering one of it's two given blocks 
+   # based on the evaluation of an expression in the current {Context}.
+   class IfNode
+      # @return [OperationNode|BooleanInverseNode] the evaluatable expression 
+      #         used to determine which set of nodes to render.
+      attr_accessor :expression
 
-   def initialize(expression, true_children=[], false_children=[])
-      @expression = expression
-      @true_children = true_children
-      @false_children = false_children
-   end
+      # @return [Array] A list of nodes which will be rendered if the {#expression}
+      #                 evaluates to true in the given {Context}.
+      attr_accessor :true_children
 
-   def implied_globals
-      (@expression.implied_globals + true_children.map(&:implied_globals).flatten + false_children.map(&:implied_globals).flatten).uniq
-   end
+      # @return [Array] A list of nodes which will be rendered if the {#expression}
+      #                 evaluates to false in the given {Context}.
+      attr_accessor :false_children
+
+      # creates a new {IfNode} with the given evaluatable expression and pair of
+      # blocks.
+      # @param [OperationNode|BooleanInverseNode] expression the expression to evaluate
+      # @param [Array] true_children a list of Node objects which will be rendered
+      #        if the {#expression} evaluates to true in the given {Context}.
+      # @param [Array] false_children a list of Node objects which will be
+      #        rendered if the {#expression} evaluates to false in the given {Context}.
+      def initialize(expression, true_children=[], false_children=[])
+         @expression = expression
+         @true_children = true_children
+         @false_children = false_children
+      end
 
-   def evaluate_expression_for_children(context)
-      value = @expression.eval(context)
+      # @return [Array] a list of variable names implied to be global for this node.
+      def implied_globals
+         (@expression.implied_globals + true_children.map(&:implied_globals).flatten + false_children.map(&:implied_globals).flatten).uniq
+      end
+
+      # @param [Context] context
+      # @return [Array] evalutes the expression in the given context and returns
+      #         a list of nodes which should be rendered based on the result of
+      #         that evaluation.
+      def evaluate_expression_for_children(context)
+         value = @expression.eval(context)
 
-      if value == true
-         return @true_children
+         if value == true
+            return @true_children
 
-      elsif value == false
-         return @false_children
+         elsif value == false
+            return @false_children
 
-      elsif value.is_a?(String)
-         return value.length == 0 || value =~ /\s+/ ? @false_children : @true_children
+         elsif value.is_a?(String)
+            return value.length == 0 || value =~ /\s+/ ? @false_children : @true_children
 
-      elsif value.is_a?(Float) or value.is_a?(Fixnum)
-         return value == 0 ? @false_children : @true_children
+         elsif value.is_a?(Float) or value.is_a?(Fixnum)
+            return value == 0 ? @false_children : @true_children
 
-      else
-         return !!value ? @true_children : @false_children
-         
+         else
+            return !!value ? @true_children : @false_children
+            
+         end
       end
-   end
 
-   def ==(rhs)
-      @expression == rhs.expression and
-      @true_children == rhs.true_children and
-      @false_children == rhs.false_children
+      # @param [IfNode] rhs
+      # @return [Boolean] true if the given node is equivalent by value to this node.
+      def ==(rhs)
+         @expression == rhs.expression and
+         @true_children == rhs.true_children and
+         @false_children == rhs.false_children
+      end
    end
-  end
 end

data/lib/cadenza/nodes/inject_node.rb

@@ -1,23 +1,46 @@
 module Cadenza
+  # The {InjectNode} is intended to write the given variable into the rendered
+  # output by evaluating it in the given {Context} and passing it through an
+  # optional series of {FilterNode}s.
   class InjectNode
-    attr_accessor :value, :filters, :parameters
+    # @return [VariableNode|OperationNode|BooleanInverseNode|ConstantNode] the value being evaluated
+    attr_accessor :value
+
+    # @return [Array] a list of {FilterNode} to evaluate the value with, once the
+    #                 value has itself been evaluated.
+    attr_accessor :filters
+
+    # @return [Array] a list of Node objects passed to the {#value} for use in a
+    #         functional variable.  See {Context#define_functional_variable}.
+    attr_accessor :parameters
     
+    # creates a new {InjectNode} with the given value, filters and parameters
+    # @param [VariableNode|OperationNode|BooleanInverseNode|ConstantNode] value see {#value}
+    # @param [Array] filters see {#filters}
+    # @param [Array] parameters see {#parameters}
     def initialize(value, filters=[], parameters=[])
       @value = value
       @filters = filters
       @parameters = parameters
     end
 
+    # @param [InjectNode] rhs
+    # @return [Boolean] true if the given InjectNode is equivalent by value to this node.
     def ==(rhs)
       self.value == rhs.value and
       self.filters == rhs.filters and
       self.parameters == rhs.parameters
     end
 
+    # @return [Array] a list of variable names implied to be global by this node
     def implied_globals
       (@value.implied_globals + @filters.map(&:implied_globals).flatten).uniq
     end
 
+    # @param [Context] context
+    # @return [String] returns the evaluated {#value} of this node in the given 
+    #         {Context} with any applicable {#parameters} after passed through 
+    #         the given {#filters}.
     def evaluate(context)
       value = @value.eval(context)