rocketio 0.0.0 → 0.0.1

data/lib/rocketio/controller/middleware.rb

@@ -0,0 +1,32 @@
+module RocketIO
+  class Controller
+
+    # storing Rack middleware to be called when a request handled by controller
+    #
+    # @note middleware is inheritable
+    #
+    # @example add a middleware to be used in current controller
+    #   and any controllers that inherits from it
+    #
+    #   class Users < RocketIO::Controller
+    #     use Rack::CommonLogger
+    #   end
+    #
+    # @param w [Class, Proc] a valid Rack middleware that responds to `call`
+    # @param *a [Array] any args to be passed at middleware initialization
+    # @param &b [Proc] a block to be yielded at middleware initialization
+    #
+    def self.use w = nil, *a, &b
+      (@__middleware__ ||= []).push(proc {|app| w.new(app, *a, &b)})
+      define_middleware_methods
+    end
+
+    def self.define_middleware_methods source = self
+      middleware = ((source.instance_variable_get(:@__middleware__) || []) + allocate.middleware).uniq.freeze
+      return if middleware.empty?
+      define_method(:middleware) {middleware}
+    end
+
+    def middleware; RocketIO::EMPTY_ARRAY end
+  end
+end

data/lib/rocketio/controller/render.rb

@@ -0,0 +1,148 @@
+module RocketIO
+  class Controller
+
+    # if called without arguments render a template with lowercased name of current request method, e.g. get for GET, post for POST etc.
+    # at first it will look between defined templates.
+    # then it will search a file.
+    # it will try each extension the effective engine has registered, e.g. .erb, .rhtml for ERB.
+    # it will search in the folder the controller was defined in(NOT in path_to_templates, which is used for defined templates only).
+    # so put each controller in a separate folder to avoid templates clash.
+    #
+    # if no file found a TemplateError will be raised.
+    # if a block given it will use the the string returned by the block as template
+    # and wont search for defined nor file templates.
+    #
+    # by default ERB engine will be used (@see engine).
+    #
+    # for layout it will take one given through options or one defined at class level.
+    # if none given, it will render without layout.
+    # to use a layout path_to_layouts should be defined at class level.
+    #
+    # by default it will use current instance as scope.
+    # to render in a isolated scope, set it via :scope option
+    #
+    # to pass some local variables use :locals option
+    #
+    # @example render ./get.erb without layout
+    #   class Pages < RocketIO::Controller
+    #
+    #     def get
+    #       render
+    #     end
+    #   end
+    #
+    # @example render ./get.erb with :master layout
+    #   class Pages < RocketIO::Controller
+    #     layout :master
+    #
+    #     def get
+    #       render
+    #     end
+    #   end
+    #
+    # @example render ./get.erb with explicit :master layout
+    #   class Pages < RocketIO::Controller
+    #
+    #     def get
+    #       render(layout: :master)
+    #     end
+    #   end
+    #
+    # @example render within isolated scope
+    #   class Pages < RocketIO::Controller
+    #
+    #     def get
+    #       render(scope: Object.new)
+    #     end
+    #   end
+    #
+    # @example render with custom locals
+    #   class Pages < RocketIO::Controller
+    #
+    #     def get
+    #       render(locals: {x: 'y'})
+    #     end
+    #   end
+    #
+    def render template = nil, opts = {}
+      opts, template = template, nil if template.is_a?(::Hash)
+      engine, engine_opts = resolve_engine(opts)
+      template = block_given? ? yield : resolve_template(template, engine)
+      scope    = opts.fetch(:scope, self)
+      locals   = opts.fetch(:locals, RocketIO::EMPTY_HASH).freeze
+      layout   = opts.fetch(:layout, self.layout)
+      template = compile_template(template, engine, engine_opts).render(scope, locals)
+      layout   ? render_layout(layout, opts) {template} : template
+    end
+
+    # render a template that yields the given block.
+    # that's it, a layout is a template that yields given string.
+    # if no layout name given, it will use the one set at class level.
+    # if no layout set at class level and no layout given, it will raise a RuntimeError.
+    # it will firstly search for given layout between defined ones.
+    # if none found, it will search a file in `path_to_layouts` folder.
+    # it will try each extension registered with effective engine.
+    # if no file found it will raise a TemplateError.
+    #
+    # block is required and should return the string to be yielded.
+    #
+    def render_layout template = nil, opts = {}, &block
+      opts, template = template, nil if template.is_a?(::Hash)
+      template ||= self.layout
+      template || raise(RocketIO::LayoutError, 'No default layout set and no explicit layout given')
+      engine, engine_opts = resolve_engine(opts)
+      template = resolve_layout(template, engine)
+      scope    = opts.fetch(:scope, self)
+      locals   = opts.fetch(:locals, RocketIO::EMPTY_HASH).freeze
+      compile_template(template, engine, engine_opts)
+        .render(scope, locals, &(block || RocketIO::EMPTY_STRING_PROC))
+    end
+
+    private
+    def resolve_template template, engine
+      template ||= requested_method
+      return __send__(templates[template]) if templates[template]
+      read_template(find_template(dirname, template, engine))
+    end
+
+    def resolve_layout layout, engine
+      return __send__(layouts[layout]) if layouts[layout]
+      read_template(find_template(dirname, layout, engine))
+    end
+
+    def resolve_engine opts = nil
+      return engine_const(engine_class(opts[:engine])) if opts && opts[:engine]
+      [engine_const(engine[0]), engine[1]]
+    end
+
+    def read_template file
+      RocketIO::READ_TEMPLATES[[file, ::File.mtime(file).to_i]] ||= ::File.read(file)
+    end
+
+    def find_template path, template, engine
+      RocketIO::FOUND_TEMPLATES[[path, template, engine]] ||= begin
+        extensions = ::Tilt.default_mapping.extensions_for(engine)
+        file = nil
+        extensions.each do |ext|
+          try = RocketIO::TEMPLATE_PATH_FORMAT % [path, template, ext]
+          next unless File.exists?(try)
+          file = try
+          break
+        end
+        file || raise(RocketIO::TemplateError, '"%s" template not found in "%s".
+          Tried extensions: %s' % [template, path, extensions.join(', ')])
+      end
+    end
+
+    def compile_template template, engine, engine_opts = nil
+      RocketIO::COMPILED_TEMPLATES[[template.hash, engine, engine_opts]] ||= begin
+        engine.new(0, *engine_opts) { template }
+      end
+    end
+  end
+end
+
+require 'rocketio/controller/render/engine'
+require 'rocketio/controller/render/layout'
+require 'rocketio/controller/render/layouts'
+require 'rocketio/controller/render/templates'

data/lib/rocketio/controller/render/engine.rb

@@ -0,0 +1,76 @@
+module RocketIO
+  class Controller
+
+    # if no engine set, templates will be rendered using ERB engine.
+    # any engine supported by [Tilt](github.com/rtomayko/tilt) can be used.
+    # to set engine use symbolized constant name, e.g. :Slim, :Haml
+    # engine name is Case Sensitive and there should be a Tilt::{ENGINE}Template class defined
+    # e.g. `engine :Slim` will look for Tilt::SlimTemplate
+    # and  `engine RDiscount` will look for Tilt::RDiscountTemplate
+    #
+    # @note if a block given it will be executed at instance level
+    #   and result used for engine. To have any options passed at engine initialization
+    #   the block should return an array having engine as first element
+    #   and options as consequent elements.
+    #
+    # @note if given block returns no engine, inherited engine will be used
+    #
+    # @example use static engine
+    #   engine :Slim
+    #
+    # @example use static engine with options
+    #   engine :Slim, pretty_print: true
+    #
+    # @example use dynamically set engine
+    #   engine do
+    #     some_condition ? :SomeEngine : AnotherEngine
+    #   end
+    #
+    # @example use dynamically set engine with options
+    #   engine do
+    #     some_condition ? [:SomeEngine, :opt1, :opt2] : AnotherEngine
+    #   end
+    #
+    # @example Search will use ERB when requested by a bot and Slim otherwise
+    #
+    #   class BaseController < RocketIO
+    #     engine :Slim
+    #   end
+    #
+    #   class Search < BaseController
+    #     engine do
+    #       if request.user_agent =~ /i'm a bot/
+    #         # requested by a bot, using ERB
+    #         :ERB
+    #       end
+    #       # requested by a user, returning no engine for inherited engine to be used
+    #     end
+    #   end
+    #
+    # @param engine  engine name.
+    # @param *engine_options  any arguments to be passed at engine initialization
+    # @param block  to be executed at instance level
+    #
+    def self.engine engine = nil, *engine_options, &block
+      @__engine__ = block || [RocketIO.engine_class(engine), engine_options.freeze].freeze
+      define_engine_methods
+    end
+
+    def self.define_engine_methods source = self
+      return unless engine = source.instance_variable_get(:@__engine__)
+      if Proc === engine
+        selfengine = allocate.engine
+        define_method(:__rocketio_engine__, &engine)
+        define_method(:engine) {
+          engine, *engine_options = __rocketio_engine__
+          return selfengine unless engine
+          [RocketIO.engine_class(engine), engine_options.freeze].freeze
+        }
+      else
+        define_method(:engine) {engine}
+      end
+    end
+
+    def engine; RocketIO::DEFAULT_ENGINE end
+  end
+end

data/lib/rocketio/controller/render/layout.rb

@@ -0,0 +1,27 @@
+module RocketIO
+  class Controller
+
+    # by default templates will be rendered without layout.
+    # to make them render inside a layout use `layout :layout_name` at class level.
+    # to use a layout it should be defined at first (@see define_layout)
+    #
+    # @note to disable layout set it to false: `layout false`
+    #
+    # @param layout  name of a defined layout
+    #
+    def self.layout layout
+      @__layout__ = layout
+      define_layout_methods
+    end
+
+    def self.define_layout_methods source = self
+      return unless source.instance_variables.include?(:@__layout__)
+      layout = source.instance_variable_get(:@__layout__)
+      define_method(:layout) {layout}
+    end
+
+    # by default no layout used, so this method returns nil.
+    # controllers that uses a layout will override this method.
+    def layout; end
+  end
+end

data/lib/rocketio/controller/render/layouts.rb

@@ -0,0 +1,85 @@
+module RocketIO
+  class Controller
+
+    # if only name given it will search for a file with same name in controller's dirname.
+    #
+    # if file name differs from layout name pass it as :file option.
+    # file path should be relative to controller's dirname.
+    # also a block accepted for :file option. the block will be executed at controllers's instance level
+    # and should return path to layout file.
+    # file name should NOT include extension.
+    #
+    # if a block given NO file will be searched and returned value will be used as layout.
+    #
+    # @note files will be searched relative to controller's dirname,
+    #   that's it, the folder controller was defined in and operates from.
+    #
+    # @note when searching for file multiple extensions will be tried,
+    #   that's it, all extensions controller's engine actually supports.
+    #
+    # @note controllers that inherits named layouts will always search for files in own dirname.
+    #   controllers that inherits :file layouts will search files in the original controller's dirname.
+    #
+    # @example define :master layout.
+    #   ./master.erb file will be used
+    #
+    #   define_layout :master
+    #
+    # @example define :master layout.
+    #   ../layouts/master.erb file will be used
+    #
+    #   define_layout :master, file: '../layouts/master'
+    #
+    # @example define :master layout.
+    #   ./admin file to be used when user logged in and ./user otherwise
+    #
+    #   define_layout :master, file: -> {user? ? 'admin' : 'user'}
+    #
+    # @example define :master layout using a block that returns the layout string.
+    #   no file will be used.
+    #
+    #   define_layout(:master) do
+    #     layout = Layouts.find_by(id: params[:layout_id]) || halt(400, 'Template not found')
+    #     layout.source
+    #   end
+    #
+    # @param name
+    # @param file
+    # @param block
+    #
+    def self.define_layout name, file: nil, &block
+      file && block && raise(::ArgumentError, 'both file and block given, please use either one')
+      (@__layouts__ ||= {})[name.to_sym] = {block: block, root: dirname, file: file, name: name}.freeze
+      define_layouts_methods
+    end
+
+    def self.define_layouts_methods source = self
+      return unless source.instance_variables.include?(:@__layouts__)
+      layouts = source.instance_variable_get(:@__layouts__).each_with_object(allocate.layouts.dup) do |(name,setup),o|
+        o[name] = :"__#{name}_layout__"
+        if setup[:block]
+          # block given, do not search for file, use returned value instead
+          define_method(o[name], &setup[:block])
+        elsif setup[:file]
+          # file given, search the file in original controller dirname
+          meth_name = :"__#{name}_layout_file__"
+          meth_proc = setup[:file].is_a?(::Proc) ? setup[:file] : -> {setup[:file]}
+          define_method(meth_name, &meth_proc)
+          define_method o[name] do
+            engine, * = resolve_engine
+            read_template(find_template(setup[:root], __send__(meth_name), engine))
+          end
+        else
+          # only name given, search for a file with same name in controller's dirname
+          define_method o[name] do
+            engine, * = resolve_engine
+            read_template(find_template(self.dirname, setup[:name], engine))
+          end
+        end
+      end.freeze
+      define_method(:layouts) {layouts}
+    end
+
+    def layouts; RocketIO::EMPTY_HASH end
+  end
+end

data/lib/rocketio/controller/render/templates.rb

@@ -0,0 +1,83 @@
+module RocketIO
+  class Controller
+
+    # if only name given it will search for a file with same name in controller's dirname
+    #
+    # if file name differs from template name pass it as :file option.
+    # file path should be relative to controller's dirname.
+    # also a block accepted for :file option. the block will be executed at controllers's instance level
+    # and should return path to template file.
+    # file name should NOT include extension.
+    #
+    # if a block given NO file will be searched and returned value will be used as template.
+    #
+    # @note files will be searched relative to controller's dirname,
+    #   that's it, the folder controller was defined in and operates from.
+    #
+    # @note when searching for file multiple extensions will be tried,
+    #   that's it, all extensions controller's engine actually supports.
+    #
+    # @note controllers that inherits named templates will always search for files in own dirname.
+    #   controllers that inherits :file templates will search files in the original controller's dirname.
+    #
+    # @example define :items template.
+    #   ./items.erb file will be used
+    #   define_template :items
+    #
+    # @example define :items template.
+    #   ../shared_templates/items.erb file will be used
+    #   define_template :items, file: '../shared_templates/items'
+    #
+    # @example define :items template.
+    #   ./admin-items.erb file to be used when user logged in and ./items.erb otherwise
+    #
+    #   define_template :items, file: -> {user? ? 'admin-items' : 'items'}
+    #
+    # @example define :items template using a block that returns the template string.
+    #   no file will be used.
+    #
+    #   define_template(:items) do
+    #     template = Templates.find_by(id: params[:template_id]) || halt(400, 'Template not found')
+    #     template.source
+    #   end
+    #
+    # @param name
+    # @param file
+    # @param block
+    #
+    def self.define_template name, file: nil, &block
+      file && block && raise(ArgumentError, 'both file and block given, please use either one')
+      (@__templates__ ||= {})[name.to_sym] = {block: block, root: dirname, file: file, name: name}.freeze
+      define_templates_methods
+    end
+
+    def self.define_templates_methods source = self
+      return unless source.instance_variables.include?(:@__templates__)
+      templates = source.instance_variable_get(:@__templates__).each_with_object(allocate.templates.dup) do |(name,setup),o|
+        o[name] = :"__#{name}_template__"
+        if setup[:block]
+          # block given, do not search for file, use returned value instead
+          define_method(o[name], &setup[:block])
+        elsif setup[:file]
+          # file given, search the file in original controller dirname
+          meth_name = :"__#{name}_template_file__"
+          meth_proc = setup[:file].is_a?(Proc) ? setup[:file] : -> {setup[:file]}
+          define_method(meth_name, &meth_proc)
+          define_method o[name] do
+            engine, * = resolve_engine
+            read_template(find_template(setup[:root], __send__(meth_name), engine))
+          end
+        else
+          # only name given, search for a file with same name in controller's dirname
+          define_method o[name] do
+            engine, * = resolve_engine
+            read_template(find_template(self.dirname, setup[:name], engine))
+          end
+        end
+      end.freeze
+      define_method(:templates) {templates}
+    end
+
+    def templates; RocketIO::EMPTY_HASH end
+  end
+end