porthole 0.99.4

data/lib/porthole/settings.rb

@@ -0,0 +1,226 @@
+# Settings which can be configured for all view classes, a single
+# view class, or a single Porthole instance.
+class Porthole
+
+  #
+  # Template Path
+  #
+
+  # The template path informs your Porthole view where to look for its
+  # corresponding template. By default it's the current directory (".")
+  #
+  # A class named Stat with a template_path of "app/templates" will look
+  # for "app/templates/stat.porthole"
+
+  def self.template_path
+    @template_path ||= inheritable_config_for :template_path, '.'
+  end
+
+  def self.template_path=(path)
+    @template_path = File.expand_path(path)
+    @template = nil
+  end
+
+  def template_path
+    @template_path ||= self.class.template_path
+  end
+
+  def template_path=(path)
+    @template_path = File.expand_path(path)
+    @template = nil
+  end
+
+  # Alias for `template_path`
+  def self.path
+    template_path
+  end
+  alias_method :path, :template_path
+
+  # Alias for `template_path`
+  def self.path=(path)
+    self.template_path = path
+  end
+  alias_method :path=, :template_path=
+
+
+  #
+  # Template Extension
+  #
+
+  # A Porthole template's default extension is 'porthole', but this can be changed.
+
+  def self.template_extension
+    @template_extension ||= inheritable_config_for :template_extension, 'porthole'
+  end
+
+  def self.template_extension=(template_extension)
+    @template_extension = template_extension
+    @template = nil
+  end
+
+  def template_extension
+    @template_extension ||= self.class.template_extension
+  end
+
+  def template_extension=(template_extension)
+    @template_extension = template_extension
+    @template = nil
+  end
+
+
+  #
+  # Template Name
+  #
+
+  # The template name is the Porthole template file without any
+  # extension or other information. Defaults to `class_name`.
+  #
+  # You may want to change this if your class is named Stat but you want
+  # to re-use another template.
+  #
+  #   class Stat
+  #     self.template_name = "graphs" # use graphs.porthole
+  #   end
+
+  def self.template_name
+    @template_name || underscore
+  end
+
+  def self.template_name=(template_name)
+    @template_name = template_name
+    @template = nil
+  end
+
+  def template_name
+    @template_name ||= self.class.template_name
+  end
+
+  def template_name=(template_name)
+    @template_name = template_name
+    @template = nil
+  end
+
+
+  #
+  # Template File
+  #
+
+  # The template file is the absolute path of the file Porthole will
+  # use as its template. By default it's ./class_name.porthole
+
+  def self.template_file
+    @template_file || "#{path}/#{template_name}.#{template_extension}"
+  end
+
+  def self.template_file=(template_file)
+    @template_file = template_file
+    @template = nil
+  end
+
+  # The template file is the absolute path of the file Porthole will
+  # use as its template. By default it's ./class_name.porthole
+  def template_file
+    @template_file || "#{path}/#{template_name}.#{template_extension}"
+  end
+
+  def template_file=(template_file)
+    @template_file = template_file
+    @template = nil
+  end
+
+
+  #
+  # Template
+  #
+
+  # The template is the actual string Porthole uses as its template.
+  # There is a bit of magic here: what we get back is actually a
+  # Porthole::Template object, but you can still safely use `template=`
+  #  with a string.
+
+  def self.template
+    @template ||= templateify(File.read(template_file))
+  end
+
+  def self.template=(template)
+    @template = templateify(template)
+  end
+
+  # The template can be set at the instance level.
+  def template
+    return @template if @template
+
+    # If they sent any instance-level options use that instead of the class's.
+    if @template_path || @template_extension || @template_name || @template_file
+      @template = templateify(File.read(template_file))
+    else
+      @template = self.class.template
+    end
+  end
+
+  def template=(template)
+    @template = templateify(template)
+  end
+
+
+  #
+  # Raise on context miss
+  #
+
+  # Should an exception be raised when we cannot find a corresponding method
+  # or key in the current context? By default this is false to emulate ctemplate's
+  # behavior, but it may be useful to enable when debugging or developing.
+  #
+  # If set to true and there is a context miss, `Porthole::ContextMiss` will
+  # be raised.
+
+  def self.raise_on_context_miss?
+    @raise_on_context_miss
+  end
+
+  def self.raise_on_context_miss=(boolean)
+    @raise_on_context_miss = boolean
+  end
+
+  # Instance level version of `Porthole.raise_on_context_miss?`
+  def raise_on_context_miss?
+    self.class.raise_on_context_miss? || @raise_on_context_miss
+  end
+
+  def raise_on_context_miss=(boolean)
+    @raise_on_context_miss = boolean
+  end
+
+
+  #
+  # View Namespace
+  #
+
+  # The constant under which Porthole will look for views when autoloading.
+  # By default the view namespace is `Object`, but it might be nice to set
+  # it to something like `Hurl::Views` if your app's main namespace is `Hurl`.
+
+  def self.view_namespace
+    @view_namespace ||= inheritable_config_for(:view_namespace, Object)
+  end
+
+  def self.view_namespace=(namespace)
+    @view_namespace = namespace
+  end
+
+
+  #
+  # View Path
+  #
+
+  # Porthole searches the view path for .rb files to require when asked to find a
+  # view class. Defaults to "."
+
+  def self.view_path
+    @view_path ||= inheritable_config_for(:view_path, '.')
+  end
+
+  def self.view_path=(path)
+    @view_path = path
+  end
+end

data/lib/porthole/sinatra.rb

@@ -0,0 +1,205 @@
+require 'sinatra/base'
+require 'porthole'
+
+class Porthole
+  # Support for Porthole in your Sinatra app.
+  #
+  #   require 'porthole/sinatra'
+  #
+  #   class Hurl < Sinatra::Base
+  #     register Porthole::Sinatra
+  #
+  #     set :porthole, {
+  #       # Should be the path to your .porthole template files.
+  #       :templates => "path/to/porthole/templates",
+  #
+  #       # Should be the path to your .rb Porthole view files.
+  #       :views => "path/to/porthole/views",
+  #
+  #       # This tells Porthole where to look for the Views module,
+  #       # under which your View classes should live. By default it's
+  #       # the class of your app - in this case `Hurl`. That is, for an :index
+  #       # view Porthole will expect Hurl::Views::Index by default.
+  #       # If our Sinatra::Base subclass was instead Hurl::App,
+  #       # we'd want to do `set :namespace, Hurl::App`
+  #       :namespace => Hurl
+  #     }
+  #
+  #     get '/stats' do
+  #       porthole :stats
+  #     end
+  #   end
+  #
+  # As noted above, Porthole will look for `Hurl::Views::Index` when
+  # `porthole :index` is called.
+  #
+  # If no `Views::Stats` class exists Porthole will render the template
+  # file directly.
+  #
+  # You can indeed use layouts with this library. Where you'd normally
+  # <%= yield %> you instead {{{yield}}} - the body of the subview is
+  # set to the `yield` variable and made available to you.
+  #
+  # If you don't want the Sinatra extension to look up your view class,
+  # maybe because you've already loaded it or you're pulling it in from
+  # a gem, you can hand the `porthole` helper a Porthole subclass directly:
+  #
+  #   # Assuming `class Omnigollum::Login < Porthole`
+  #   get '/login' do
+  #     @title = "Log In"
+  #     require 'lib/omnigollum/views/login'
+  #     porthole Omnigollum::Login
+  #   end
+  #
+  module Sinatra
+    module Helpers
+      # Call this in your Sinatra routes.
+      def porthole(template, options={}, locals={})
+        # Locals can be passed as options under the :locals key.
+        locals.update(options.delete(:locals) || {})
+
+        # Grab any user-defined settings.
+        if settings.respond_to?(:porthole)
+          options = settings.send(:porthole).merge(options)
+        end
+
+        # If they aren't explicitly disabling layouts, try to find
+        # one.
+        if options[:layout] != false
+          # Let the user pass in a layout name.
+          layout_name = options[:layout]
+
+          # If all they said was `true` (or nothing), default to :layout.
+          layout_name = :layout if layout_name == true || !layout_name
+
+          # If they passed a layout name use that.
+          layout = porthole_class(layout_name, options)
+
+          # If it's just an anonymous subclass then don't bother, otherwise
+          # give us a layout instance.
+          if layout.name && layout.name.empty?
+            layout = nil
+          else
+            layout = layout.new
+          end
+        end
+
+        # If instead of a symbol they gave us a Porthole class,
+        # use that for rendering.
+        klass = template if template.is_a?(Class) && template < Porthole
+
+        # Find and cache the view class we want if we don't have
+        # one yet. This ensures the compiled template is cached,
+        # too - no looking up and compiling templates on each page
+        # load.
+        if klass.nil?
+          klass = porthole_class(template, options)
+        end
+
+        # Does the view subclass the layout? If so we'll use the
+        # view to render the layout so you can override layout
+        # methods in your view - tricky.
+        view_subclasses_layout = klass < layout.class if layout
+
+        # Create a new instance for playing with.
+        instance = klass.new
+
+        # Copy instance variables set in Sinatra to the view
+        instance_variables.each do |name|
+          instance.instance_variable_set(name, instance_variable_get(name))
+        end
+
+        # Render with locals.
+        rendered = instance.render(instance.template, locals)
+
+        # Now render the layout with the view we just rendered, if we
+        # need to.
+        if layout && view_subclasses_layout
+          rendered = instance.render(layout.template, :yield => rendered)
+        elsif layout
+          rendered = layout.render(layout.template, :yield => rendered)
+        end
+
+        # That's it.
+        rendered
+      end
+
+      # Returns a View class for a given template name.
+      def porthole_class(template, options = {})
+        @template_cache.fetch(:porthole, template) do
+          compile_porthole(template, options)
+        end
+      end
+
+      # Given a view name and settings, finds and prepares an
+      # appropriate view class for this view.
+      def compile_porthole(view, options = {})
+        options[:templates] ||= settings.views if settings.respond_to?(:views)
+        options[:namespace] ||= self.class
+
+        unless options[:namespace].to_s.include? 'Views'
+          options[:namespace] = options[:namespace].const_get(:Views)
+        end
+
+        factory = Class.new(Porthole) do
+          self.view_namespace = options[:namespace]
+          self.view_path      = options[:views]
+        end
+
+        # If we were handed :"positions.atom" or some such as the
+        # template name, we need to remember the extension.
+        if view.to_s.include?('.')
+          view, ext = view.to_s.split('.')
+        end
+
+        # Try to find the view class for a given view, e.g.
+        # :view => Hurl::Views::Index.
+        klass = factory.view_class(view)
+        klass.view_namespace = options[:namespace]
+        klass.view_path      = options[:views]
+
+        # If there is no view class, issue a warning and use the one
+        # we just generated to cache the compiled template.
+        if klass == Porthole
+          warn "No view class found for #{view} in #{factory.view_path}"
+          klass = factory
+
+          # If this is a generic view class make sure we set the
+          # template name as it was given. That is, an anonymous
+          # subclass of Porthole won't know how to find the
+          # "index.porthole" template unless we tell it to.
+          klass.template_name = view.to_s
+        elsif ext
+          # We got an ext (like "atom"), so look for an "Atom" class
+          # under the current View's namespace.
+          #
+          # So if our template was "positions.atom", try to find
+          # Positions::Atom.
+          if klass.const_defined?(ext_class = ext.capitalize)
+            # Found Positions::Atom - set it
+            klass = klass.const_get(ext_class)
+          else
+            # Didn't find Positions::Atom - create it by creating an
+            # anonymous subclass of Positions and setting that to
+            # Positions::Atom.
+            new_class = Class.new(klass)
+            new_class.template_name = "#{view}.#{ext}"
+            klass.const_set(ext_class, new_class)
+            klass = new_class
+          end
+        end
+
+        # Set the template path and return our class.
+        klass.template_path = options[:templates] if options[:templates]
+        klass
+      end
+    end
+
+    # Called when you `register Porthole::Sinatra` in your Sinatra app.
+    def self.registered(app)
+      app.helpers Porthole::Sinatra::Helpers
+    end
+  end
+end
+
+Sinatra.register Porthole::Sinatra

data/lib/porthole/template.rb

@@ -0,0 +1,58 @@
+require 'cgi'
+
+require 'porthole/parser'
+require 'porthole/generator'
+
+class Porthole
+  # A Template represents a Porthole template. It compiles and caches
+  # a raw string template into something usable.
+  #
+  # The idea is this: when handed a Porthole template, convert it into
+  # a Ruby string by transforming Porthole tags into interpolated
+  # Ruby.
+  #
+  # You shouldn't use this class directly, instead:
+  #
+  # >> Porthole.render(template, hash)
+  class Template
+    attr_reader :source
+
+    # Expects a Porthole template as a string along with a template
+    # path, which it uses to find partials.
+    def initialize(source)
+      @source = source
+    end
+
+    # Renders the `@source` Porthole template using the given
+    # `context`, which should be a simple hash keyed with symbols.
+    #
+    # The first time a template is rendered, this method is overriden
+    # and from then on it is "compiled". Subsequent calls will skip
+    # the compilation step and run the Ruby version of the template
+    # directly.
+    def render(context)
+      # Compile our Porthole template into a Ruby string
+      compiled = "def render(ctx) #{compile} end"
+
+      # Here we rewrite ourself with the interpolated Ruby version of
+      # our Porthole template so subsequent calls are very fast and
+      # can skip the compilation stage.
+      instance_eval(compiled, __FILE__, __LINE__ - 1)
+
+      # Call the newly rewritten version of #render
+      render(context)
+    end
+
+    # Does the dirty work of transforming a Porthole template into an
+    # interpolation-friendly Ruby string.
+    def compile(src = @source)
+      Generator.new.compile(tokens(src))
+    end
+    alias_method :to_s, :compile
+
+    # Returns an array of tokens for a given template.
+    def tokens(src = @source)
+      Parser.new.compile(src)
+    end
+  end
+end