cadenza 0.7.2 → 0.8.0

data/lib/cadenza/context/blocks.rb

@@ -0,0 +1,60 @@
+
+module Cadenza
+   BlockNotDefinedError = Class.new(Cadenza::Error)
+
+   class Context
+      module Blocks
+         
+         # @!attribute [r] blocks
+         # @return [Hash] the block names mapped to their implementing procs
+         def blocks
+            @blocks ||= {}
+         end
+
+         # looks up the block by name
+         # 
+         # @raise [BlockNotDefinedError] if the block can not be found
+         # @param [Symbol] name the name of the block to look up
+         # @return [Proc] the block implementation
+         def lookup_block(name)
+            blocks.fetch(name.to_sym) { raise BlockNotDefinedError.new("undefined block '#{name}'") }
+         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
+
+         # creates an alias of the given block name under a different name 
+         #
+         # @raise [BlockNotDefinedError] if the original block name isn't defined
+         # @param [Symbol] original_name the original name of the block
+         # @param [Symbol] alias_name the new name of the block
+         # @return nil
+         def alias_block(original_name, alias_name)
+            define_block alias_name, &lookup_block(original_name)
+         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)
+            lookup_block(name).call(self, nodes, parameters)
+         end
+      end
+   end
+end

data/lib/cadenza/context/filters.rb

@@ -0,0 +1,60 @@
+
+module Cadenza
+   FilterNotDefinedError = Class.new(Cadenza::Error)
+
+   class Context
+      module Filters
+
+         # @!attribute [r] filters
+         # @return [Hash] the filter names mapped to their implementing procs
+         def filters
+            @filters ||= {}
+         end
+
+         # looks up the filter by name
+         # 
+         # @raise [FilterNotDefinedError] if the filter can not be found
+         # @param [Symbol] name the name of the filter to look up
+         # @return [Proc] the filter implementation
+         def lookup_filter(name)
+            filters.fetch(name.to_sym) { raise FilterNotDefinedError.new("undefined filter '#{name}'") }
+         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
+
+         # creates an alias of the given filter name under a different name 
+         #
+         # @raise [FilterNotDefinedError] if the original filter name isn't defined
+         # @param [Symbol] original_name the original name of the filter
+         # @param [Symbol] alias_name the new name of the filter
+         # @return nil
+         def alias_filter(original_name, alias_name)
+            define_filter alias_name, &lookup_filter(original_name)
+         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 [Object] input the input value which will be filtered
+         # @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, input, params=[])
+            lookup_filter(name).call(input, params)
+         end
+
+
+      end
+   end
+end

data/lib/cadenza/context/functional_variables.rb

@@ -0,0 +1,58 @@
+
+module Cadenza
+   FunctionalVariableNotDefinedError = Class.new(Cadenza::Error)
+
+   class Context
+      module FunctionalVariables
+
+         # @!attribute [r] functional_variables
+         # @return [Hash] the functional variable names mapped to their implementing procs
+         def functional_variables
+            @functional_variables ||= {}
+         end
+
+         # looks up the functional variable by name
+         # 
+         # @raise [FunctionalVariableNotDefinedError] if the functional variable can not be found
+         # @param [Symbol] name the name of the functional variable to look up
+         # @return [Proc] the functional variable implementation
+         def lookup_functional_variable(name)
+            functional_variables.fetch(name.to_sym) { raise FunctionalVariableNotDefinedError.new("undefined functional variable '#{name}'") }
+         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
+         
+         # creates an alias of the given functional variable name under a different name 
+         #
+         # @raise [FunctionalVariableNotDefinedError] if the original functional variable name isn't defined
+         # @param [Symbol] original_name the original name of the functional variable
+         # @param [Symbol] alias_name the new name of the functional variable
+         # @return nil
+         def alias_functional_variable(original_name, alias_name)
+            define_functional_variable alias_name, &lookup_functional_variable(original_name)
+         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=[])
+            lookup_functional_variable(name).call([self] + params)
+         end
+         
+      end
+   end
+end

data/lib/cadenza/context/loaders.rb

@@ -0,0 +1,116 @@
+
+module Cadenza
+   TemplateNotFoundError = Class.new(Cadenza::Error)
+
+   class Context
+      module Loaders
+
+         # @!attribute [rw] whiny_template_loading
+         # @return [Boolean] true if a {TemplateNotFoundError} should still be
+         #                   raised if not calling the bang form of {#load_source}
+         #                   or {#load_template}
+         def whiny_template_loading
+            @whiny_template_loading ||= false
+         end
+
+         def whiny_template_loading=(rhs)
+            @whiny_template_loading = rhs
+         end
+
+         # @!attribute [r] loaders
+         # @return [Array] the list of loaders
+         def loaders
+            @loaders ||= []
+         end
+
+         # constructs a {FilesystemLoader} with the string given as its path and
+         # adds the loader to the end of the loader list.
+         #
+         # @param [String] path to use for loader
+         # @return [Loader] the loader that was created
+         def add_load_path(path)
+           loader = FilesystemLoader.new(path)
+           add_loader(loader)
+           loader
+         end
+
+         # adds the given loader to the end of the loader list.
+         #
+         # @param [Loader] loader the loader to add
+         # @return nil
+         def add_loader(loader)
+            loaders.push loader
+            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
+
+            loaders.each do |loader|
+               source = loader.load_source(template_name)
+               break if source
+            end
+
+            if source.nil? and whiny_template_loading
+               raise TemplateNotFoundError.new(template_name)
+            else
+               return source
+            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
+
+            loaders.each do |loader|
+               template = loader.load_template(template_name)
+               break if template
+            end
+            
+            if template.nil? and whiny_template_loading
+               raise TemplateNotFoundError.new(template_name)
+            else
+               return template
+            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
+
+      end
+   end
+end

data/lib/cadenza/context/stack.rb

@@ -0,0 +1,85 @@
+
+module Cadenza
+   class Context
+      module Stack
+
+         # @!attribute [r] stack
+         # @return [Array] the variable stack
+         def stack
+            @stack ||= []
+         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)
+            sym_identifier = identifier.to_sym
+
+            # if a functional variable is defined matching the identifier name then return that
+            return functional_variables[sym_identifier] if functional_variables.has_key?(sym_identifier)
+
+            stack.reverse_each do |scope|
+               value = lookup_identifier(scope, identifier)
+
+               return value unless value.nil?
+            end
+            
+            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
+
+         # 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
+
+      private
+         def lookup_identifier(scope, identifier)
+            if identifier.index('.')
+               lookup_path(scope, identifier.split("."))
+            else
+               self.class.lookup_on_object(identifier, scope)
+            end
+         end
+
+         def lookup_path(scope, path)
+            loop do
+               component = path.shift
+
+               scope = self.class.lookup_on_object(component, scope)
+
+               return scope if path.empty?
+            end
+         end
+
+      end
+   end
+end

data/lib/cadenza/context_object.rb

@@ -1,10 +1,100 @@
 
 module Cadenza
+   # ContextObject is a bare bones class which should become the superclass
+   # of any object you wish to push onto the {Context::Stack#stack} of the 
+   # context you render your template with.
+   # 
+   # Normal ruby objects (with the exception of Hash and Array) will not allow
+   # any value to be looked up upon it when pushed onto the {Context::Stack#stack} 
+   # unless they are subclasses of {ContextObject}.  See {Context.lookup_on_object} 
+   # for specific details on how this is done.
    class ContextObject < Object # intentionally declared, since we cannot 
                                 # subclass BasicObject in 1.8.7
 
-      # this class is intentionally left blank as a placeholder, see 
-      # context_object_spec.rb under spec/ for details.
+   private
+      # Callback method which is called before the given method name is called
+      # by {#invoke_context_method}
+      #
+      # This method can be overridden by subclasses for whatever purpose they
+      # wish, ex. statistics gathering
+      # 
+      # @note this method is a *private* method, but has been documented for
+      #       your understanding.
+      # @!visibility public
+      # @param [String|Symbol] method the name of the method that was called
+      def before_method(method)
+         # no implementation, used by subclasses
+      end
+
+      # Callback method which is called after the given method name is called
+      # by {#invoke_context_method}
+      #
+      # This method can be overridden by subclasses for whatever purpose they
+      # wish, ex. statistics gathering
+      # 
+      # @note this method is a *private* method, but has been documented for
+      #       your understanding.
+      # @!visibility public
+      # @param [String|Symbol] method the name of the method that was called
+      def after_method(method)
+         # no implementation, used by subclasses
+      end
+
+      # Method called by {#invoke_context_method} when the given method could
+      # not be found in the class's public method list.
+      #
+      # The return value of this method is returned by {#invoke_context_method}
+      # 
+      # @note this method is a *private* method, but has been documented for
+      #       your understanding.
+      # @!visibility public
+      # @param [String|Symbol] method the name of the method that was called
+      def missing_context_method(method)
+         # no implementation, used by subclasses
+      end
+
+      # Looks up and calls the given method on this object and returns it's 
+      # value.
+      #
+      # Only methods in the public visibility scope (see {#context_methods}) can
+      # be called by this method.
+      #
+      # If the method can not be found on this object then {#missing_context_method}
+      # will be called instead.  You can use this to provide a "method_missing"
+      # for your context object.
+      #
+      # Around the call to the method on this object the {#before_method} and
+      # {#after_method} methods will be called with the name of the method.  You
+      # may wish to use this to perform live benchmarking or other statistics
+      # gathering.
+      #
+      # @note this method is a *private* method, but has been documented for
+      #       your understanding.
+      # @!visibility public
+      # @param [Symbol|String] method the name of the method to call
+      # @return [Object] the value returned from the method call
+      def invoke_context_method(method)
+         send(:before_method, method)
+         
+         if context_methods.include?(method.to_s)
+            result = send(method)
+         else
+            result = send(:missing_context_method, method)
+         end
+
+         send(:after_method, method)
+
+         result
+      end
+
+      # @note this method is a *private* method, but has been documented for
+      #       your understanding.
+      # @!visibility public
+      # @return [Array] a list of methods which are in the public visibility 
+      #         scope for this class
+      def context_methods
+         (self.class.public_instance_methods - ContextObject.public_instance_methods).map(&:to_s)
+      end
       
    end
 end