tanuki 0.3.1 → 0.4.0

data/lib/tanuki/argument.rb

@@ -5,7 +5,8 @@ require 'tanuki/argument/string'
 
 module Tanuki
 
-  # Tanuki::Argument contains basic classes and methods for controller arguments.
+  # Tanuki::Argument contains basic classes and methods for controller
+  # arguments.
   module Argument
 
     @assoc = {}
@@ -14,18 +15,22 @@ module Tanuki
 
       # Removes argument association for a given type class +klass+.
       def delete(klass)
-        @assoc.delete(klass)
+        @assoc.delete klass
       end
 
-      # Associates a given type class +klass+ with an argument class +arg_class+.
+      # Associates a given type class +klass+ with an argument class
+      # +arg_class+.
       def store(klass, arg_class)
-        warn "Tanuki::Argument::Base is not an ancestor of `#{arg_class}'" unless arg_class.ancestors.include? Argument::Base
+        unless arg_class.ancestors.include? Argument::Base
+          warn "Tanuki::Argument::Base is not an ancestor of `#{arg_class}'"
+        end
         @assoc[klass] = arg_class
       end
 
       alias_method :[], :store
 
-      # Converts a given type object +obj+ to an argument object with optional +args+.
+      # Converts a given type object +obj+ to an argument object with
+      # optional +args+.
       def to_argument(obj, *args)
         if @assoc.include?(klass = obj.class)
           @assoc[klass].new(obj, *args)

data/lib/tanuki/argument/integer_range.rb

@@ -1,10 +1,12 @@
 module Tanuki
   module Argument
 
-    # Tanuki::Argument::IntegerRange is a class for +Integer+ arguments with a certain value range.
+    # Tanuki::Argument::IntegerRange is a class for +Integer+ arguments with
+    # a certain value range.
     class IntegerRange < Integer
 
-      # Initializes the argument with a +default+ value and allowed value +range+.
+      # Initializes the argument with a +default+ value and allowed value
+      # +range+.
       def initialize(range, default=nil)
         super(default ? default : range.first)
         @range = range

data/lib/tanuki/{behavior/object_behavior.rb → base_behavior.rb}

@@ -15,14 +15,31 @@ module Tanuki
     end
 
     # Returns the same context as given. Used internally by templates.
-    def _ctx(ctx)
+    def _ctx(ctx, template_signature)
+      if !ctx.resources.include? template_signature
+        Loader.load_template_files(ctx, template_signature)
+      end
       ctx
     end
 
-    # Allows to return template blocks. E. g. returns +foobar+ template block when +foobar_view+ method is called.
+    # Allows to return template blocks. E. g. returns +foobar+ template block
+    # when +foobar_view+ method is called.
     def method_missing(sym, *args, &block)
-      if matches = sym.to_s.match(/^(.*)_view$/)
-        return Tanuki::Loader.run_template({}, self, matches[1].to_sym, *args, &block)
+      if matches = sym.to_s.match(/^.*(?=_view$)|view$/)
+        return Tanuki::Loader.run_template(
+          {},
+          self,
+          matches[0].to_sym,
+          *args,
+          &block
+        )
+      end
+      super
+    end
+
+    def method(sym)
+      if !respond_to?(sym) && (m = sym.to_s.match(/^.*(?=_view$)|view$/))
+        Tanuki::Loader.load_template({}, self, m[0].to_sym)
       end
       super
     end

data/lib/tanuki/configurator.rb

@@ -1,19 +1,31 @@
 module Tanuki
 
-  # Tanuki::Configurator is a scope for evaluating a Tanuki application configuration block.
+  # Tanuki::Configurator is a scope for evaluating
+  # a Tanuki application configuration block.
   class Configurator
 
     # Configuration root.
     attr_writer :config_root
 
+    # Configurator context.
+    attr_reader :context
+
     # Creates a new configurator in context +ctx+ and +root+ directory.
-    # Configuration root +config_root+ defaults to _config_ directory in +root+.
+    # Configuration root +config_root+ defaults
+    # to _config_ directory in +root+.
     def initialize(ctx, root, config_root=nil)
       @context = ctx
       set :root, root ? root : Dir.pwd
     end
 
-    # Loads and executes a given configuraion file with symbolic name +config+.
+    # Returns true, if a configuration file
+    # with a symbolic name +config+ exists.
+    def config_file?(config)
+      File.file?(File.join(@config_root, config.to_s) << '.rb')
+    end
+
+    # Loads and executes a given configuraion file
+    # with symbolic name +config+.
     # If +silent+ is +true+, exception is not raised on missing file.
     def load_config(config, silent=false)
       file = File.join(@config_root, config.to_s) << '.rb'
@@ -26,27 +38,27 @@ module Tanuki
 
     # Invokes Tanuki::Argument::store.
     def argument(klass, arg_class)
-      Argument.store(klass, arg_class)
+      Argument.store klass, arg_class
     end
 
     # Sets an +option+ to +value+ in the current context.
     def set(option, value)
-      @context.send("#{option}=".to_sym, value)
+      @context.send "#{option}=".to_sym, value
     end
 
     # Invokes Tanuki::Application::use.
     def use(middleware, *args, &block)
-      Application.use(middleware, *args, &block)
+      Application.use middleware, *args, &block
     end
 
     # Invokes Tanuki::Application::discard.
     def discard(middleware)
-      Application.discard(middleware)
+      Application.discard middleware
     end
 
     # Invokes Tanuki::Application::visitor.
     def visitor(sym, &block)
-      Application.visitor(sym, &block)
+      Application.visitor sym, &block
     end
 
   end # Configurator

data/lib/tanuki/const.rb

@@ -0,0 +1,32 @@
+module Tanuki
+
+  # This module includes constants that are commonly used
+  # during requests in the framework.
+  # All of them are frozen to keep the GC from unwanted stress.
+  module Const
+
+    ARG_KEY_ESCAPE = '\/:-'.freeze
+    ARG_VALUE_ESCAPE = '\/:'.freeze
+    CONTENT_TYPE = 'Content-Type'.freeze
+    EMPTY_ARRAY = [].freeze
+    EMPTY_STRING = ''.freeze
+    ESCAPED_MATCH = '$\0'.freeze
+    ESCAPED_ROUTE_CHARS = /\$([\/\$:-])/.freeze
+    ESCAPED_SLASH = '$/'.freeze
+    ETAG = 'ETag'.freeze
+    FIRST_SUBPATTERN = '\1'.freeze
+    LOCATION = 'Location'.freeze
+    MIME_TEXT_HTML = 'text/html; charset=utf-8'.freeze
+    PATH_INFO = 'PATH_INFO'.freeze
+    QUERY_STRING = 'QUERY_STRING'.freeze
+    SLASH = '/'.freeze
+    TRAILING_SLASH = /^(.+)(?<!\$)\/$/.freeze
+    UNESCAPED_COLON = /(?<!\$):/.freeze
+    UNESCAPED_MINUS = /(?<!\$)-/.freeze
+    UNESCAPED_SLASH = /(?<!\$)\//.freeze
+    UTF_8 = 'UTF-8'.freeze
+    VIEW_METHOD = /^.*_view$/.freeze
+
+  end # Const
+
+end # Tanuki

data/lib/tanuki/context.rb

@@ -1,7 +1,8 @@
 module Tanuki
 
   # Tanuki::Context is used to create unique environments for each request.
-  # Child contexts inherit parent context entries and can override them without modifying the parent context.
+  # Child contexts inherit parent context entries and can override them
+  # without modifying the parent context.
   # Use Tanuki::Context::child to create new contexts.
   class Context
 
@@ -17,13 +18,17 @@ module Tanuki
         child
       end
 
-      # Returns a printable version of Tanuki::Context, represented as a +Hash+.
+      # Returns a printable version of Tanuki::Context,
+      # represented as a +Hash+.
       # Can be used during development for inspection purposes.
       #--
-      # When changing this method, remember to update `#{__LINE__ + 12}' to `defined.inspect` line number.
+      # When changing this method, remember to update `#{__LINE__ + 13}'
+      # to `defined.inspect` line number.
       # This is required to avoid infinite recursion.
       def inspect
-        return to_s if caller.any? {|entry_point| entry_point =~ /\A#{__FILE__}:#{__LINE__ + 12}/}
+        return to_s if caller.any? do |entry_point|
+          entry_point =~ /\A#{__FILE__}:#{__LINE__ + 13}/
+        end
         defined = {}
         ancestors.each do |ancestor|
           ancestor.instance_variable_get(:@_defined).each_key do |key|
@@ -38,11 +43,17 @@ module Tanuki
         defined.inspect
       end
 
-      # Allowes arbitary values to be assigned to context with a +key=+ method.
+      # Allowes arbitary values to be assigned to context
+      # with a +key=+ method.
       # A reader in context object class is created for each assigned value.
       def method_missing(sym, arg=nil)
-        match = sym.to_s.match(/\A(?!(?:child|inspect|method_missing)=\Z)([^=]+)(=)?\Z/)
-        raise "`#{sym}' method cannot be called for Context and its descendants" unless match
+        match = sym.to_s.match(%r{
+          \A(?!(?:child|inspect|method_missing)=\Z)([^=]+)(=)?\Z
+        }x)
+        unless match
+          raise "`#{sym}' method cannot be called for Context " \
+                "and its descendants"
+        end
         defined = @_defined
         class << self; self; end.instance_eval do
           method_sym = match[1].to_sym

data/lib/tanuki/controller.rb

@@ -0,0 +1,517 @@
+module Tanuki
+
+  # Tanuki::Controller provides basic methods for
+  # a subclassable framework controller.
+  class Controller
+
+    include Tanuki::BaseBehavior
+    include Enumerable
+
+    internal_attr_reader :model, :logical_parent, :link, :ctx
+    internal_attr_accessor :logical_child, :visual_child
+
+    # Creates new controller with context +ctx+, +logical_parent+ controller,
+    # +route_part+ definitions and a +model+.
+    def initialize(ctx, logical_parent, route_part, model=nil)
+      @_configured = false
+      @_ctx = ctx
+      @_model = model
+      @_args = {}
+      if @_logical_parent = logical_parent
+
+        # Register controller arguments, as declared with #has_arg.
+        @_route = route_part[:route]
+        self.class.arg_defs.each_pair do |arg_name, arg_def|
+          arg_val = arg_def[:arg].to_value(route_part[:args][arg_def[:index]])
+          route_part[:args][arg_def[:index]] = @_args[arg_name] = arg_val
+        end
+
+        @_link = self.class.grow_link(@_logical_parent, {
+          :route => @_route,
+          :args  => @_args
+        }, self.class.arg_defs)
+        initialize_route(*route_part[:args])
+      else
+        @_link = '/'
+        @_route = nil
+        initialize_route
+      end
+    end
+
+    # Invoked with route +args+ when current route is initialized.
+    def initialize_route(*args)
+    end
+
+    # Returns controller context. Used internally by templates.
+    def _ctx(ctx, template_signature)
+      if !ctx.resources.include? template_signature
+        Loader.load_template_files(ctx, template_signature)
+      end
+      @_ctx
+    end
+
+    # Initializes and retrieves child controller on +route+.
+    # Searches static, dynamic, and ghost routes (in that order).
+    def [](route, *args)
+      byname = (args.length == 1 and args[0].is_a? Hash)
+      ensure_configured!
+      key = [route, args.dup]
+      if cached = @_cache[key]
+
+        # Return form cache
+        return cached
+
+      elsif child_def = @_child_defs[route]
+
+        # Search actions
+        if child_def[:type] == :action &&
+           action = child_def[ctx.request.request_method]
+        then
+          throw :action, action
+        else
+
+        # Search static routes
+          klass = child_def[:class]
+          args = klass.extract_args(args[0]) if byname
+          child = klass.new(process_child_context(@_ctx, route), self, {
+            :route => route,
+            :args  => args
+          }, child_def[:model])
+        end
+
+      else
+
+        # Search dynamic routes
+        found = false
+        s = route.to_s
+        @_child_collection_defs.each do |collection_def|
+          collection_def[:parse].match(s) do |route_match|
+            child_def = collection_def[:fetcher].fetch(
+              route_match,
+              collection_def[:format]
+            )
+            if child_def
+              klass = child_def[:class]
+              args = klass.extract_args(args[0]) if byname
+              embedded_args = klass.extract_args(route_match)
+              args.each_index {|i| embedded_args[i] = args[i] if args[i] }
+              child_context = process_child_context(@_ctx, child_def[:route])
+              child = klass.new(child_context, self, {
+                :route => child_def[:route],
+                :args  => embedded_args
+              }, child_def[:model])
+              found = true
+              break child
+            end # if
+          end # match
+        end # each
+
+        # If still not found, search ghost routes
+        child = missing_route(route, *args) unless found
+
+      end
+      # Thread safe (possible overwrite, but within consistent state)
+      @_cache[key] = child
+    end
+
+    # Returns +true+, if controller is active.
+    def active?
+      @_active
+    end
+
+    # Retrieves child controller class on +route+.
+    # Searches static, dynamic, and ghost routes (in that order).
+    def child_class(route)
+      ensure_configured!
+      args = []
+      key = [route, args]
+      if cached = @_cache[key]
+
+        # Return from cache
+        return cached.class
+
+      elsif child_def = @_child_defs[route]
+
+        # Return from static routes
+        return child_def[:class]
+
+      else
+
+        # Search dynamic routes
+        s = route.to_s
+        @_child_collection_defs.each do |collection_def|
+          collection_def[:parse].match(s) do |route_match|
+            child_def = collection_def[:fetcher].fetch(
+              route_match,
+              collection_def[:format]
+            )
+            return child_def[:class] if child_def
+          end
+        end
+
+        # If still not found, search ghost routes
+        return (@_cache[key] = missing_route(route, *args)).class
+
+      end
+    end
+
+    # Invoked when controller needs to be configured.
+    def configure
+    end
+
+    # Returns +true+, if controller is current.
+    def current?
+      @_current
+    end
+
+    # If set, controller navigates to a given child route by default.
+    # Returned object should be either +nil+ (don't navigate),
+    # or a +Hash+ with keys:
+    # * +:route+ is the +Symbol+ for the route
+    # * +:args+ contain route arguments +Hash+
+    # * +:redirect+ makes a 302 redirect to this route, if true (optional)
+    def default_route
+      nil
+    end
+
+    # Calls +block+ once for each visible child controller
+    # on static or dynamic routes, passing it as a parameter.
+    def each(&block)
+      return Enumerator.new(self) unless block_given?
+      ensure_configured!
+      @_child_defs.each_pair do |route, child|
+        if route.is_a? Regexp
+          cd = @_child_collection_defs[child]
+          cd[:fetcher].fetch_all(cd[:format]) do |child_def|
+            key = [child_def[:route], []]
+            unless child = @_cache[key]
+              child_context = process_child_context(@_ctx, route)
+              child = child_def[:class].new(child_context, self, {
+                :route => child_def[:route],
+                :args  => {}
+              }, child_def[:model])
+              @_cache[key] = child
+            end
+            block.call child
+          end
+        else
+          yield self[route] unless child[:hidden]
+        end
+      end
+      self
+    end
+
+    # Invoked when controller configuration needs to be ensured.
+    def ensure_configured!
+      unless @_configured
+        @_child_defs = {}
+        @_child_collection_defs = []
+        @_cache={}
+        @_length = 0
+        configure
+        @_configured = true
+      end
+      nil
+    end
+
+    # Returns the link to the current controller, switching
+    # the active controller on the respective path level to +self+.
+    def forward_link
+      uri_parts = @_ctx.request.path_info.split(Const::UNESCAPED_SLASH)
+      link_parts = link.split(Const::UNESCAPED_SLASH)
+      link_parts.each_index {|i| uri_parts[i] = link_parts[i] }
+      query_string = @_ctx.request.query_string
+      query_string = query_string.empty? ? '' : "?#{query_string}"
+      uri_parts.join(Const::SLASH) << query_string
+    end
+
+    # Returns the number of visible child controllers
+    # on static and dynamic routes.
+    def length
+      if @_child_collection_defs.length > 0
+        if @_length_is_valid
+          @_length
+        else
+          @_child_collection_defs.each {|cd| @_length += cd[:fetcher].length }
+          @_length_is_valid = true
+        end
+      else
+        @_length
+      end
+    end
+
+    # Invoked when child controller context needs to be processed
+    # before initializing.
+    def process_child_context(ctx, route)
+      ctx
+    end
+
+    alias_method :size, :length
+
+    # Returns controller string representation. Defaults to route name.
+    def to_s
+      @_route.to_s
+    end
+
+    # Invoked when visual parent needs to be determined.
+    # Defaults to logical parent.
+    def visual_parent
+      @_logical_parent
+    end
+
+    # Returns the topmost visual container that should be rendered.
+    def visual_top
+      @_ctx.visual_top
+    end
+
+    # Returns Rack request object
+    def request
+      @_ctx.request
+    end
+
+    # Returns Rack response object
+    def response
+      @_ctx.response
+    end
+
+    # Returns Rack params hash
+    def params
+      request.params
+    end
+
+    # Sets HTTP response code.
+    def status(value)
+      @_ctx.response.status = value
+    end
+
+    # Redirects to the specified URL.
+    def redirect(url)
+      @_ctx.response.redirect(url)
+      halt
+    end
+
+    # Includes JavaScript in page footer
+    def javascript(file)
+      if file.is_a? Symbol
+        _, file = *Loader.resource_owner(self.class, file, '.js')
+      end
+      external = file =~ /^https?:/
+      ctx.javascripts[file] = external
+    end
+
+    # Immediately stops request and returns response.
+    def halt
+      throw :halt
+    end
+
+    # Returns default result for HTTP GET to controller's address.
+    def get
+      visual_top.method(:page_view)
+    end
+
+    # Returns default result for HTTP POST to controller's address.
+    def post
+      status 404
+      nil
+    end
+
+    # Returns default result for HTTP PUT to controller's address.
+    def put
+      status 404
+      nil
+    end
+
+    # Returns default result for HTTP DELETE to controller's address.
+    def delete
+      status 404
+      nil
+    end
+
+    def has_action(method, route, &block)
+      (@_child_defs[route.to_sym] ||= {:type => :action})[method] = block
+    end
+
+    private
+
+    # Defines a child of class +klass+ on +route+ with +model+,
+    # optionally +hidden+.
+    def has_child(klass, route, model=nil, hidden=false)
+      @_child_defs[route.to_sym] = {
+        :class  => klass,
+        :model  => model,
+        :hidden => hidden
+      }
+      @_length += 1 unless hidden
+      self
+    end
+
+    # Defines a child collection of type +parse_regexp+,
+    # formatted back by +format+ block.
+    def has_child_collection(child_def_fetcher, parse_regexp, &format)
+      @_child_defs[parse_regexp] = @_child_collection_defs.size
+      @_child_collection_defs << {
+        :parse   => parse_regexp,
+        :format  => format,
+        :fetcher => child_def_fetcher
+      }
+      @_length_is_valid = false
+    end
+
+    # Invoked for +route+ with +args+ when a route is missing.
+    # This hook can be used to make ghost routes.
+    def missing_route(route, *args)
+      @_ctx.missing_page.new(@_ctx, self, {:route => route, :args => []})
+    end
+
+    @_arg_defs = {}
+
+    class << self
+
+      # Returns own or superclass argument definitions.
+      def arg_defs
+        @_arg_defs ||= superclass.arg_defs.dup
+      end
+
+      # Dispathes route chain in context +ctx+ on +request_path+,
+      # starting with controller +klass+.
+      def dispatch(ctx, klass, request_path)
+        route_parts = parse_path(request_path)
+
+        # Prepare for getting an Action result
+        action_result = nil
+
+
+        # Set logical children for active controllers
+        curr = root_ctrl = klass.new(ctx, nil, nil, true)
+        nxt = nil
+        route_parts.each do |route_part|
+          curr.instance_variable_set :@_active, true
+          action_result = catch :action do
+            nxt = curr[route_part[:route], *route_part[:args]]
+            nil
+          end
+          break if action_result
+          curr.logical_child = nxt
+          curr = nxt
+        end
+
+
+        # Set links for active controllers and default routes (only for GET)
+        if ctx.request.get? && !action_result
+          while route_part = curr.default_route
+
+            # Do a redirect, if some controller in the chain asks for it
+            if route_part[:redirect]
+              klass = curr.child_class(route_part)
+              curr.redirect grow_link(curr, route_part, klass.arg_defs)
+            end
+
+            # Add default route as logical child
+            curr.instance_variable_set :@_active, true
+            action_result = catch :action do
+              nxt = curr[route_part[:route], *route_part[:args]]
+              nil
+            end
+            break if action_result
+            curr.logical_child = nxt
+            curr = nxt
+
+          end
+        end
+
+        # Find out dispatch result type from current controller
+        curr.instance_variable_set :@_active, true
+        curr.instance_variable_set :@_current, true
+        type = (curr.is_a? ctx.missing_page) ? :missing_page : :page
+
+        # Set visual children for active controllers
+        last = curr
+        prev = curr
+        while curr = prev.visual_parent
+          curr.visual_child = prev
+          prev = curr
+        end
+
+        # Set visual top
+        ctx.visual_top = prev
+
+        return action_result.call if action_result
+        last.send :"#{ctx.request.request_method.downcase}"
+      end
+
+      # Escapes characters +chrs+ and encodes a given string +s+
+      # for use in links.
+      def escape(s, chrs)
+        if s
+          Rack::Utils.escape(s.to_s.gsub(/[\$#{chrs}]/, Const::ESCAPED_MATCH))
+        else
+          nil
+        end
+      end
+
+      # Extracts arguments, initializing default values beforehand.
+      # Searches +md+ hash for default value overrides.
+      def extract_args(md)
+        res = []
+        arg_defs.each_pair do |name, arg|
+          res[arg[:index]] = md[name]
+        end
+        res
+      end
+
+      # Builds link from controller +ctrl+ to a given route.
+      def grow_link(ctrl, route_part, arg_defs)
+        args = route_part[:args].map {|k, v|
+          if arg_defs[k][:arg].default == v
+            ''
+          else
+            key = escape(k, Const::ARG_KEY_ESCAPE)
+            value = escape(v, Const::ARG_VALUE_ESCAPE)
+            ":#{key}-#{value}"
+          end
+        }.join
+        own_link = escape(route_part[:route], Const::ARG_VALUE_ESCAPE) << args
+        "#{ctrl.link == Const::SLASH ? '' : ctrl.link}/#{own_link}"
+      end
+
+      # Defines an argument with a +name+,
+      # derived from type +obj+ with additional +args+.
+      def has_arg(name, obj, *args)
+        # TODO Ensure thread safety
+        arg_defs[name] = {
+          :arg   => Argument.to_argument(obj, *args),
+          :index => @_arg_defs.size
+        }
+      end
+
+      private
+
+      # Parses +path+ to return route name and arguments.
+      def parse_path(path)
+        path[1..-1].split(Const::UNESCAPED_SLASH).map do |s|
+          arr = s.gsub(
+            Const::ESCAPED_SLASH,
+            Const::SLASH
+          ).split(Const::UNESCAPED_COLON)
+          route_part = {:route => unescape(arr[0]).to_sym}
+          args = {}
+          arr[1..-1].each do |argval|
+            varr = argval.split(Const::UNESCAPED_MINUS)
+            args[unescape(varr[0])] = unescape(varr[1..-1].join)
+            # TODO Predict argument
+          end
+          route_part[:args] = extract_args(args)
+          route_part
+        end # map
+      end
+
+      # Unescapes a given link part for internal use.
+      def unescape(s)
+        s ? s.gsub(Const::ESCAPED_ROUTE_CHARS, Const::FIRST_SUBPATTERN) : nil
+      end
+
+    end # class << self
+
+  end # Controller
+
+end # Tanuki