cadenza 0.7.0.rc1 → 0.7.0

data/lib/cadenza.rb

@@ -1,5 +1,7 @@
+require 'cadenza/error'
 require 'cadenza/token'
 require 'cadenza/lexer'
+require 'cadenza/racc_parser'
 require 'cadenza/parser'
 require 'cadenza/context'
 require 'cadenza/base_renderer'
@@ -15,6 +17,13 @@ Dir[File.join File.dirname(__FILE__), 'cadenza', 'nodes', '*.rb'].each {|f| requ
 module Cadenza
    BaseContext = Context.new
 
+   # this utility method sets up the standard Cadenza lexer/parser/renderer 
+   # stack and renders the given template text with the given variable scope
+   # using the {BaseContext}.  the result of rendering is returned as a string.
+   #
+   # @param [String] template_text the content of the template to parse/render
+   # @param [Hash] scope any variables to define as a new scope for {BaseContext}
+   #               in this template.
    def self.render(template_text, scope=nil)
       template = Parser.new.parse(template_text)
 
@@ -29,6 +38,12 @@ module Cadenza
       output.string
    end
 
+   # similar to {#render} except the given template name will be loaded using
+   # {BaseContext}s predefined list of loaders.
+   #
+   # @param [String] template_name the name of the template to load then parse and render
+   # @param [Hash] scope any variables to define as a new scope for {BaseContext}
+   #               in this template.
    def self.render_template(template_name, scope=nil)
       context = BaseContext.clone
 

data/lib/cadenza/base_renderer.rb

@@ -1,12 +1,35 @@
 module Cadenza
+   # BaseRenderer is a class you can use to more easily and cleanly implement 
+   # your own rendering class.  To use this then subclass {BaseRenderer} and 
+   # implement the appropriate render_xyz methods (see {#render} for details).
    class BaseRenderer
-      attr_reader :output, :document
+      # @return [IO] the io object that is being written to
+      attr_reader :output
 
+      # @deprecated temporary hack, will be removed later
+      # @return [DocumentNode] the node which is at the root of the AST
+      attr_reader :document
+
+      # creates a new renderer and assigns the given output io object to it
+      # @param [IO] output_io the IO object which will be written to
       def initialize(output_io)
          @output = output_io
       end
       
+      # renders the given document node to the output stream given in the 
+      # constructor.  this method will call the render_xyz method for the node
+      # given, where xyz is the demodulized underscored version of the node's 
+      # class name.  for example: given a Cadenza::DocumentNode this method will
+      # call render_document_node
+      #
+      # @param [Node] node the node to render
+      # @param [Context] context the context to render with
+      # @param [Hash] blocks a mapping of the block names to the matching 
+      #               {BlockNode}.  The blocks given should be rendered instead
+      #               of blocks of the same name in the given document.
       def render(node, context, blocks={})
+         #TODO: memoizing this is a terrible smell, add a "parent" hierarchy so
+         # we can always find the root node from any node in the AST
          @document ||= node
 
          node_type = node.class.name.split("::").last
@@ -16,6 +39,8 @@ module Cadenza
          send("render_#{node_name}", node, context, blocks)
       end
 
+   private
+
       # very stripped down form of ActiveSupport's underscore method
       def underscore(word)
          word.gsub!(/([a-z\d])([A-Z])/,'\1_\2').downcase!

data/lib/cadenza/context.rb

@@ -1,21 +1,49 @@
 
 module Cadenza
-   class TemplateNotFoundError < StandardError
+   class TemplateNotFoundError < Cadenza::Error
    end
 
-   class FilterNotDefinedError < StandardError
+   class FilterNotDefinedError < Cadenza::Error
    end
 
-   class FunctionalVariableNotDefinedError < StandardError
+   class FunctionalVariableNotDefinedError < Cadenza::Error
    end
 
-   class BlockNotDefinedError < StandardError
+   class BlockNotDefinedError < Cadenza::Error
    end
 
+   # The {Context} class is an essential class in Cadenza that contains all the
+   # data necessary to render a template to it's output.  The context holds all
+   # defined variable names (see {#stack}), {#filters}, {#functional_variables},
+   # generic {#blocks}, {#loaders} and configuration data as well as all the 
+   # methods you should need to define and evaluate those.
    class Context
-      attr_accessor :stack, :filters, :functional_variables, :blocks, :loaders
+      # @return [Array] the variable stack
+      attr_accessor :stack
+
+      # @return [Hash] the filter names mapped to their implementing procs
+      attr_accessor :filters
+
+      # @return [Hash] the functional variable names mapped to their implementing procs
+      attr_accessor :functional_variables
+
+      # @return [Hash] the block names mapped to their implementing procs
+      attr_accessor :blocks
+
+      # @return [Array] the list of loaders
+      attr_accessor :loaders
+
+      # @return [Boolean] true if a {TemplateNotFoundError} should still be
+      #                   raised if not calling the bang form of {#load_source}
+      #                   or {#load_template}
       attr_accessor :whiny_template_loading
 
+      # creates a new context object with an empty stack, filter list, functional
+      # variable list, block list, loaders list and default configuration options.
+      #
+      # When created you can push an optional scope onto as the initial stack
+      #
+      # @param [Hash] initial_scope the initial scope for the context
       def initialize(initial_scope={})
          @stack = []
          @filters = {}
@@ -29,6 +57,8 @@ module Cadenza
 
       # creates a new instance of the context with the stack, loaders, filters,
       # functional variables and blocks shallow copied.
+      #
+      # @return [Context] the cloned context
       def clone
          copy = super
          copy.stack = stack.dup
@@ -40,6 +70,12 @@ module Cadenza
          copy
       end
 
+      # retrieves the value of the given identifier by inspecting the variable
+      # stack from top to bottom.  Identifiers with dots in them are separated
+      # on that dot character and looked up as a path.  If no value could be 
+      # found then nil is returned.
+      #
+      # @return [Object] the object matching the identifier or nil if not found
       def lookup(identifier)
          @stack.reverse_each do |scope|
             value = lookup_identifier(scope, identifier)
@@ -50,64 +86,143 @@ module Cadenza
          nil
       end
 
+      # assigns the given value to the given identifier at the highest current
+      # scope of the stack.
+      #
+      # @param [String] identifier the name of the variable to store
+      # @param [Object] value the value to assign to the given name
       def assign(identifier, value)
          @stack.last[identifier.to_sym] = value
       end
 
-      # TODO: symbolizing strings is slow so consider symbolizing here to improve
-      # the speed of the lookup method (its more important than push)
-      # TODO: since you can assign with the #assign method then make the scope
-      # variable optional (assigns an empty hash)
+      # creates a new scope on the variable stack and assigns the given hash
+      # to it.
+      #
+      # @param [Hash] scope the mapping of names to values for the new scope
+      # @return nil
       def push(scope)
+         # TODO: symbolizing strings is slow so consider symbolizing here to improve
+         # the speed of the lookup method (its more important than push)
+
+         # TODO: since you can assign with the #assign method then make the scope
+         # variable optional (assigns an empty hash)
          @stack.push(scope)
+
+         nil
       end
 
+      # removes the highest scope from the variable stack
+      # @return [Hash] the removed scope
       def pop
          @stack.pop
       end
 
+      # defines a filter proc with the given name
+      #
+      # @param [Symbol] name the name for the template to use for this filter
+      # @yield [String, *args] the block will receive the input string and a 
+      #                        variable number of arguments passed to the filter.
+      # @return nil
       def define_filter(name, &block)
          @filters[name.to_sym] = block
+         nil
       end
 
+      # calls the defined filter proc with the given parameters and returns the
+      # result.  
+      #
+      # @raise [FilterNotDefinedError] if the named filter doesn't exist
+      # @param [Symbol] name the name of the filter to evaluate
+      # @param [Array] params a list of parameters to pass to the filter 
+      #                block when calling it.
+      # @return [String] the result of evaluating the filter
       def evaluate_filter(name, params=[])
          filter = @filters[name.to_sym]
          raise FilterNotDefinedError.new("undefined filter '#{name}'") if filter.nil?
          filter.call(*params)
       end
 
+      # defines a functional variable proc with the given name
+      #
+      # @param [Symbol] name the name for the template to use for this variable
+      # @yield [Context, *args] the block will receive the context object and a
+      #                         variable number of arguments passed to the variable.
+      # @return nil
       def define_functional_variable(name, &block)
          @functional_variables[name.to_sym] = block
+         nil
       end
 
+      # calls the defined functional variable proc with the given parameters and
+      # returns the result.
+      #
+      # @raise [FunctionalVariableNotDefinedError] if the named variable doesn't exist
+      # @param [Symbol] name the name of the functional variable to evaluate
+      # @param [Array] params a list of parameters to pass to the variable
+      #                block when calling it
+      # @return [Object] the result of  evaluating the functional variable
       def evaluate_functional_variable(name, params=[])
          var = @functional_variables[name.to_sym]
          raise FunctionalVariableNotDefinedError.new("undefined functional variable '#{name}'") if var.nil?
          var.call([self] + params)
       end
 
+      # defines a generic block proc with the given name
+      #
+      # @param [Symbol] name the name for the template to use for this block
+      # @yield [Context, Array, *args] the block will receive the context object,
+      #                                a list of Node objects (it's children), and
+      #                                a variable number of aarguments passed to
+      #                                the block.
+      # @return nil
       def define_block(name, &block)
          @blocks[name.to_sym] = block
+         nil
       end
 
+      # calls the defined generic block proc with the given name and children
+      # nodes.
+      #
+      # @raise [BlockNotDefinedError] if the named block does not exist
+      # @param [Symbol] name the name of the block to evaluate
+      # @param [Array] nodes the child nodes of the block
+      # @param [Array, []] params a list of parameters to pass to the block
+      #                    when calling it.
+      # @return [String] the result of evaluating the block
       def evaluate_block(name, nodes, parameters)
          block = @blocks[name.to_sym]
          raise BlockNotDefinedError.new("undefined block '#{name}") if block.nil?
          block.call(self, nodes, parameters)
       end
 
+      # adds the given loader to the end of the loader list.  If the argument 
+      # passed is a string then a {FilesystemLoader} will be constructed with
+      # the string given as a path for it.
+      #
+      # @param [Loader,String] loader the loader to add
+      # @return nil
       def add_loader(loader)
          if loader.is_a?(String)
             @loaders.push FilesystemLoader.new(loader)
          else
             @loaders.push loader
          end
+         nil
       end
 
+      # removes all loaders from the context
+      # @return nil
       def clear_loaders
          @loaders.reject! { true }
+         nil
       end
 
+      # loads and returns the given template but does not parse it
+      #
+      # @raise [TemplateNotFoundError] if {#whiny_template_loading} is enabled and
+      #                                the template could not be loaded.
+      # @param [String] template_name the name of the template to load
+      # @return [String] the template text or nil if the template could not be loaded
       def load_source(template_name)
          source = nil
 
@@ -123,10 +238,22 @@ module Cadenza
          end
       end
 
+      # loads and returns the given template but does not parse it
+      #
+      # @raise [TemplateNotFoundError] if the template could not be loaded
+      # @param [String] template_name the name of the template to load
+      # @return [String] the template text
       def load_source!(template_name)
          load_source(template_name) || raise(TemplateNotFoundError.new(template_name))
       end
 
+      # loads, parses and returns the given template
+      #
+      # @raise [TemplateNotFoundError] if {#whiny_template_loading} is enabled and
+      #                                the template could not be loaded.
+      # @param [String] template_name the name of the template to load
+      # @return [DocumentNode] the root of the parsed document or nil if the 
+      #                          template could not be loaded.
       def load_template(template_name)
          template = nil
 
@@ -142,6 +269,11 @@ module Cadenza
          end
       end
 
+      # loads, parses and returns the given template
+      #
+      # @raise [TemplateNotFoundError] if the template could not be loaded
+      # @param [String] template_name the name of the template ot load
+      # @return [DocumentNode] the root of the parsed document
       def load_template!(template_name)
          load_template(template_name) || raise(TemplateNotFoundError.new(template_name))
       end

data/lib/cadenza/error.rb

@@ -0,0 +1,13 @@
+module Cadenza
+   # The {Error} class is the base class of all types of errors Cadenza will
+   # raise, this should make exception handling much simpler for you.
+   #
+   # Example:
+   #    begin
+   #       Cadenza.parse("some {{ invalid template")
+   #    rescue Cadenza::Error => e
+   #       puts "oh noes!"
+   #    end
+   class Error < StandardError
+   end
+end

data/lib/cadenza/filesystem_loader.rb

@@ -1,12 +1,35 @@
 
 module Cadenza
+   # The {FilesystemLoader} is a very simple loader object which takes a given
+   # "root" directory and loads templates using the filesystem.  Relative file
+   # paths from this directory should be used for template names.
+   #
+   # This implemenation makes no attempt to be secure so upwards relative file
+   # paths could be used to load sensitive files into the output template.
+   # 
+   # ```django
+   #   {# assuming you add /home/someuser as a loaded path #}
+   #   {{ load '../../etc/passwd' }}
+   # ```
+   #
+   # If you allow loading to be used for insecure user content then consider
+   # using a more secure loader class such as {ZipLoader} or writing a simple
+   # loader for your database connection.
    class FilesystemLoader
+      # @return [String] the path on the filesystem to load relative to
       attr_accessor :path
 
+      # creates a new {FilesystemLoader} with the given filesystem directory
+      # to load templates relative to.
+      # @param [String] path see {#path}
       def initialize(path)
          @path = path
       end
 
+      # loads and returns the given template's content or nil if the file was
+      # not a file object (such as a directory).
+      # @param [String] template the name of the template to load
+      # @return [String] the content of the template
       def load_source(template)
          filename = File.join(path, template)
 
@@ -15,6 +38,10 @@ module Cadenza
          File.read filename
       end
 
+      # loads and parses the given template name using {Parser}.  If the template
+      # could not be loaded then nil is returned.
+      # @param [String] template the name of the template to load
+      # @return [DocumentNode] the root node of the parsed AST
       def load_template(template)
          source = load_source(template)
 

data/lib/cadenza/lexer.rb

@@ -1,13 +1,22 @@
 require 'strscan'
 
 module Cadenza
-
+  # The {Lexer} class accepts in input {IO} object which it will parse simple
+  # {Token}s from for use in a {Parser} class.
   class Lexer
+    #TODO: look at using the CodeRay scanner instead, it supports reading from
+    # an IO object (unlike StringScanner which must have a string in memory)
+    # http://coderay.rubychan.de/doc/classes/CodeRay/Scanners/Scanner.html
+
+    # constructs a new parser and sets it to the position (0, 0)
     def initialize
       @line = 0
       @column = 0
     end
 
+    # assigns a new string to retrieve tokens and resets the line and column
+    # counters to (1, 1)
+    # @param [String] source the string from which to parse tokens
     def source=(source)
       @scanner = ::StringScanner.new(source || "")
 
@@ -17,10 +26,47 @@ module Cadenza
       @context = :body
     end
 
+    # gives the current line and column counter as a two element array
+    # @return [Array] the line and column
     def position
       [@line, @column]
     end
 
+    # Gets the next token and returns it.  Tokens are two element arrays where
+    # the first element is one of the following symbols and the second is an
+    # instance of {Cadenza::Token} containing the value of the token.
+    #
+    # valid tokens:
+    # - :VAR_OPEN - for opening an inject tag ex. "{{"
+    # - :VAR_CLOSE - for closing an inject tag ex. "}}"
+    # - :STMT_OPEN - for opening a control tag ex. "{%"
+    # - :STMT_CLOSE - for closing a control tag ex. "%}"
+    # - :TEXT_BLOCK - for a block of raw text
+    # - :OP_EQ - for an equivalence symbol ex. "=="
+    # - :OP_NEQ - for a nonequivalence symbol ex. "!="
+    # - :OP_GEQ - for a greater than or equal to symbol ex. ">="
+    # - :OP_LEQ - for a less than or equal to symbol ex. "<="
+    # - :REAL - for a number with a decimal value ex. "123.45"
+    # - :INTEGER - for a number without a decimal value ex. "12345"
+    # - :STRING - for a string literal, either from single quotes or double quotes ex. "'foo'"
+    # - :IDENTIFIER - for a variable name ex. "foo"
+    # - :IF - for the 'if' keyword
+    # - :UNLESS - for the 'unless' keyword
+    # - :ELSE - for the 'else' keyword
+    # - :ENDIF - for the 'endif' keyword
+    # - :ENDUNLESS - for the 'endunless' keyword
+    # - :FOR - for the 'for' keyword
+    # - :IN - for the 'in' keyword
+    # - :ENDFOR - for the 'endfor' keyword
+    # - :BLOCK - for the 'block' keyword
+    # - :ENDBLOCK - for the 'endblock' keyword
+    # - :EXTENDS - for the 'extends' keyword
+    # - :END - for the 'end' keyword
+    # - :AND - for the 'and' keyword
+    # - :OR - for the 'or' keyword
+    # - :NOT - for the 'not' keyword
+    #
+    # if no tokens are left the return value will be [false, false]
     def next_token
       if @scanner.eos?
         [false, false]
@@ -29,6 +75,11 @@ module Cadenza
       end
     end
 
+    # returns an array of all remaining tokens left to be parsed.  See {#next_token}
+    # for details regarding the definition of a token.  The array will always end in
+    # [false, false].
+    #
+    # @return [Array] a list of all remaining tokens
     def remaining_tokens
       result = []