porthole 0.99.4

data/bin/porthole

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+
+require 'yaml'
+require 'optparse'
+
+require 'porthole'
+require 'porthole/version'
+
+class Porthole
+  class CLI
+    # Return a structure describing the options.
+    def self.parse_options(args)
+      opts = OptionParser.new do |opts|
+        opts.banner = "Usage: porthole [-c] [-t] [-r library] FILE ..."
+
+        opts.separator " "
+
+        opts.separator "Examples:"
+        opts.separator "  $ porthole data.yml template.porthole"
+        opts.separator "  $ cat data.yml | porthole - template.porthole"
+        opts.separator "  $ porthole -c template.porthole"
+
+        opts.separator " "
+
+        opts.separator "  See porthole(1) or " +
+          "http://porthole.github.com/porthole.1.html"
+        opts.separator "  for more details."
+
+        opts.separator " "
+        opts.separator "Options:"
+
+        opts.on("-c", "--compile FILE",
+          "Print the compiled Ruby for a given template.") do |file|
+          puts Porthole::Template.new(File.read(file)).compile
+          exit
+        end
+
+        opts.on("-t", "--tokens FILE",
+          "Print the tokenized form of a given template.") do |file|
+          require 'pp'
+          pp Porthole::Template.new(File.read(file)).tokens
+          exit
+        end
+
+        opts.on('-r', '--require LIB', 'Require a Ruby library before running.') do |lib|
+          require lib
+        end
+
+        opts.separator "Common Options:"
+
+        opts.on("-v", "--version", "Print the version") do |v|
+          puts "Porthole v#{Porthole::Version}"
+          exit
+        end
+
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+      end
+
+      opts.separator ""
+
+      opts.parse!(args)
+    end
+
+    # Does the dirty work of reading files from STDIN and the command
+    # line then processing them. The meat of this script, if you will.
+    def self.process_files(input_stream)
+      doc = input_stream.read
+
+      if doc =~ /^(\s*---(.+)---\s*)/m
+        yaml = $2.strip
+        template = doc.sub($1, '')
+
+        YAML.each_document(yaml) do |data|
+          puts Porthole.render(template, data)
+        end
+      else
+        puts Porthole.render(doc)
+      end
+    end
+  end
+end
+
+# Help is the default.
+ARGV << '-h' if ARGV.empty? && $stdin.tty?
+
+# Process options
+Porthole::CLI.parse_options(ARGV) if $stdin.tty?
+
+# Still here - process ARGF
+Porthole::CLI.process_files(ARGF)
+

data/lib/porthole.rb

@@ -0,0 +1,304 @@
+require 'porthole/template'
+require 'porthole/context'
+require 'porthole/settings'
+
+# Porthole is the base class from which your Porthole subclasses
+# should inherit (though it can be used on its own).
+#
+# The typical Porthole workflow is as follows:
+#
+# * Create a Porthole subclass: class Stats < Porthole
+# * Create a template: stats.porthole
+# * Instantiate an instance: view = Stats.new
+# * Render that instance: view.render
+#
+# You can skip the instantiation by calling `Stats.render` directly.
+#
+# While Porthole will do its best to load and render a template for
+# you, this process is completely customizable using a few options.
+#
+# All settings can be overriden at the class level.
+#
+# For example, going with the above example, we can use
+# `Stats.template_path = "/usr/local/templates"` to specify the path
+# Porthole uses to find templates.
+#
+# Here are the available options:
+#
+# * template_path
+#
+# The `template_path` setting determines the path Porthole uses when
+# looking for a template. By default it is "."
+# Setting it to /usr/local/templates, for example, means (given all
+# other settings are default) a Porthole subclass `Stats` will try to
+# load /usr/local/templates/stats.porthole
+#
+# * template_extension
+#
+# The `template_extension` is the extension Porthole uses when looking
+# for template files. By default it is "porthole"
+#
+# * template_file
+#
+# You can tell Porthole exactly which template to use with this
+# setting. It can be a relative or absolute path.
+#
+# * template
+#
+# Sometimes you want Porthole to render a string, not a file. In those
+# cases you may set the `template` setting. For example:
+#
+#   >> Porthole.render("Hello {{planet}}", :planet => "World!")
+#   => "Hello World!"
+#
+# The `template` setting is also available on instances.
+#
+#   view = Porthole.new
+#   view.template = "Hi, {{person}}!"
+#   view[:person] = 'Mom'
+#   view.render # => Hi, mom!
+#
+# * view_namespace
+#
+# To make life easy on those developing Porthole plugins for web frameworks or
+# other libraries, Porthole will attempt to load view classes (i.e. Porthole
+# subclasses) using the `view_class` class method. The `view_namespace` tells
+# Porthole under which constant view classes live. By default it is `Object`.
+#
+# * view_path
+#
+# Similar to `template_path`, the `view_path` option tells Porthole where to look
+# for files containing view classes when using the `view_class` method.
+#
+class Porthole
+
+  #
+  # Public API
+  #
+
+  # Instantiates an instance of this class and calls `render` with
+  # the passed args.
+  #
+  # Returns a rendered String version of a template
+  def self.render(*args)
+    new.render(*args)
+  end
+
+  class << self
+    alias_method :to_html, :render
+    alias_method :to_text, :render
+  end
+
+  # Parses our fancy pants template file and returns normal file with
+  # all special {{tags}} and {{#sections}}replaced{{/sections}}.
+  #
+  # data - A String template or a Hash context. If a Hash is given,
+  #        we'll try to figure out the template from the class.
+  #  ctx - A Hash context if `data` is a String template.
+  #
+  # Examples
+  #
+  #   @view.render("Hi {{thing}}!", :thing => :world)
+  #
+  #   View.template = "Hi {{thing}}!"
+  #   @view = View.new
+  #   @view.render(:thing => :world)
+  #
+  # Returns a rendered String version of a template
+  def render(data = template, ctx = {})
+    if data.is_a? Hash
+      ctx = data
+      tpl = templateify(template)
+    elsif data.is_a? Symbol
+      self.template_name = data
+      tpl = templateify(template)
+    else
+      tpl = templateify(data)
+    end
+
+    return tpl.render(context) if ctx == {}
+
+    begin
+      context.push(ctx)
+      tpl.render(context)
+    ensure
+      context.pop
+    end
+  end
+
+  alias_method :to_html, :render
+  alias_method :to_text, :render
+
+  # Context accessors.
+  #
+  # view = Porthole.new
+  # view[:name] = "Jon"
+  # view.template = "Hi, {{name}}!"
+  # view.render # => "Hi, Jon!"
+  def [](key)
+    context[key.to_sym]
+  end
+
+  def []=(key, value)
+    context[key.to_sym] = value
+  end
+
+  # A helper method which gives access to the context at a given time.
+  # Kind of a hack for now, but useful when you're in an iterating section
+  # and want access to the hash currently being iterated over.
+  def context
+    @context ||= Context.new(self)
+  end
+
+  # Given a file name and an optional context, attempts to load and
+  # render the file as a template.
+  def self.render_file(name, context = {})
+    render(partial(name), context)
+  end
+
+  # Given a file name and an optional context, attempts to load and
+  # render the file as a template.
+  def render_file(name, context = {})
+    self.class.render_file(name, context)
+  end
+
+  # Given a name, attempts to read a file and return the contents as a
+  # string. The file is not rendered, so it might contain
+  # {{portholes}}.
+  #
+  # Call `render` if you need to process it.
+  def self.partial(name)
+    File.read("#{template_path}/#{name}.#{template_extension}")
+  end
+
+  # Override this in your subclass if you want to do fun things like
+  # reading templates from a database. It will be rendered by the
+  # context, so all you need to do is return a string.
+  def partial(name)
+    self.class.partial(name)
+  end
+
+  # Override this to provide custom escaping.
+  #
+  # class PersonView < Porthole
+  #   def escapeHTML(str)
+  #     my_html_escape_method(str)
+  #   end
+  # end
+  #
+  # Returns a String
+  def escapeHTML(str)
+    CGI.escapeHTML(str)
+  end
+
+
+  #
+  # Private API
+  #
+
+  # When given a symbol or string representing a class, will try to produce an
+  # appropriate view class.
+  # e.g.
+  #   Porthole.view_namespace = Hurl::Views
+  #   Porthole.view_class(:Partial) # => Hurl::Views::Partial
+  def self.view_class(name)
+    if name != classify(name.to_s)
+      name = classify(name.to_s)
+    end
+
+    # Emptiness begets emptiness.
+    if name.to_s == ''
+      return Porthole
+    end
+
+    file_name = underscore(name)
+    name = "#{view_namespace}::#{name}"
+
+    if const = const_get!(name)
+      const
+    elsif File.exists?(file = "#{view_path}/#{file_name}.rb")
+      require "#{file}".chomp('.rb')
+      const_get!(name) || Porthole
+    else
+      Porthole
+    end
+  end
+
+  # Supercharged version of Module#const_get.
+  #
+  # Always searches under Object and can find constants by their full name,
+  #   e.g. Porthole::Views::Index
+  #
+  # name - The full constant name to find.
+  #
+  # Returns the constant if found
+  # Returns nil if nothing is found
+  def self.const_get!(name)
+    name.split('::').inject(Object) do |klass, cname|
+      klass.const_get(cname)
+    end
+  rescue NameError
+    nil
+  end
+
+  # Has this template already been compiled? Compilation is somewhat
+  # expensive so it may be useful to check this before attempting it.
+  def self.compiled?
+    @template.is_a? Template
+  end
+
+  # Has this instance or its class already compiled a template?
+  def compiled?
+    (@template && @template.is_a?(Template)) || self.class.compiled?
+  end
+
+  # template_partial => TemplatePartial
+  # template/partial => Template::Partial
+  def self.classify(underscored)
+    underscored.split('/').map do |namespace|
+      namespace.split(/[-_]/).map do |part|
+        part[0] = part[0].chr.upcase; part
+      end.join
+    end.join('::')
+  end
+
+  #   TemplatePartial => template_partial
+  # Template::Partial => template/partial
+  # Takes a string but defaults to using the current class' name.
+  def self.underscore(classified = name)
+    classified = name if classified.to_s.empty?
+    classified = superclass.name if classified.to_s.empty?
+
+    string = classified.dup.split("#{view_namespace}::").last
+
+    string.split('::').map do |part|
+      part[0] = part[0].chr.downcase
+      part.gsub(/[A-Z]/) { |s| "_#{s.downcase}"}
+    end.join('/')
+  end
+
+  # Turns a string into a Porthole::Template. If passed a Template,
+  # returns it.
+  def self.templateify(obj)
+    if obj.is_a?(Template)
+      obj
+    else
+      Template.new(obj.to_s)
+    end
+  end
+
+  def templateify(obj)
+    self.class.templateify(obj)
+  end
+
+  # Return the value of the configuration setting on the superclass, or return
+  # the default.
+  #
+  # attr_name - Symbol name of the attribute.  It should match the instance variable.
+  # default   - Default value to use if the superclass does not respond.
+  #
+  # Returns the inherited or default configuration setting.
+  def self.inheritable_config_for(attr_name, default)
+    superclass.respond_to?(attr_name) ? superclass.send(attr_name) : default
+  end
+end

data/lib/porthole/context.rb

@@ -0,0 +1,142 @@
+class Porthole
+  # A ContextMiss is raised whenever a tag's target can not be found
+  # in the current context if `Porthole#raise_on_context_miss?` is
+  # set to true.
+  #
+  # For example, if your View class does not respond to `music` but
+  # your template contains a `{{music}}` tag this exception will be raised.
+  #
+  # By default it is not raised. See Porthole.raise_on_context_miss.
+  class ContextMiss < RuntimeError;  end
+
+  # A Context represents the context which a Porthole template is
+  # executed within. All Porthole tags reference keys in the Context.
+  class Context
+    # Expect to be passed an instance of `Porthole`.
+    def initialize(porthole)
+      @stack = [porthole]
+    end
+
+    # A {{>partial}} tag translates into a call to the context's
+    # `partial` method, which would be this sucker right here.
+    #
+    # If the Porthole view handling the rendering (e.g. the view
+    # representing your profile page or some other template) responds
+    # to `partial`, we call it and render the result.
+    def partial(name, indentation = '')
+      # Look for the first Porthole in the stack.
+      porthole = porthole_in_stack
+
+      # Indent the partial template by the given indentation.
+      part = porthole.partial(name).to_s.gsub(/^/, indentation)
+
+      # Call the Porthole's `partial` method and render the result.
+      result = porthole.render(part, self)
+    end
+
+    # Find the first Porthole in the stack. If we're being rendered
+    # inside a Porthole object as a context, we'll use that one.
+    def porthole_in_stack
+      @stack.detect { |frame| frame.is_a?(Porthole) }
+    end
+
+    # Allows customization of how Porthole escapes things.
+    #
+    # Returns a String.
+    def escapeHTML(str)
+      porthole_in_stack.escapeHTML(str)
+    end
+
+    # Adds a new object to the context's internal stack.
+    #
+    # Returns the Context.
+    def push(new)
+      @stack.unshift(new)
+      self
+    end
+    alias_method :update, :push
+
+    # Removes the most recently added object from the context's
+    # internal stack.
+    #
+    # Returns the Context.
+    def pop
+      @stack.shift
+      self
+    end
+
+    # Can be used to add a value to the context in a hash-like way.
+    #
+    # context[:name] = "Chris"
+    def []=(name, value)
+      push(name => value)
+    end
+
+    # Alias for `fetch`.
+    def [](name)
+      fetch(name, nil)
+    end
+
+    # Do we know about a particular key? In other words, will calling
+    # `context[key]` give us a result that was set. Basically.
+    def has_key?(key)
+      !!fetch(key)
+    rescue ContextMiss
+      false
+    end
+
+    # Similar to Hash#fetch, finds a value by `name` in the context's
+    # stack. You may specify the default return value by passing a
+    # second parameter.
+    #
+    # If no second parameter is passed (or raise_on_context_miss is
+    # set to true), will raise a ContextMiss exception on miss.
+    def fetch(name, default = :__raise)
+      @stack.each do |frame|
+        # Prevent infinite recursion.
+        next if frame == self
+
+        value = find(frame, name, :__missing)
+        if value != :__missing
+          return value
+        end
+      end
+
+      if default == :__raise || porthole_in_stack.raise_on_context_miss?
+        raise ContextMiss.new("Can't find #{name} in #{@stack.inspect}")
+      else
+        default
+      end
+    end
+
+    # Finds a key in an object, using whatever method is most
+    # appropriate. If the object is a hash, does a simple hash lookup.
+    # If it's an object that responds to the key as a method call,
+    # invokes that method. You get the idea.
+    #
+    #     obj - The object to perform the lookup on.
+    #     key - The key whose value you want.
+    # default - An optional default value, to return if the
+    #           key is not found.
+    #
+    # Returns the value of key in obj if it is found and default otherwise.
+    def find(obj, key, default = nil)
+      hash = obj.respond_to?(:has_key?)
+
+      if hash && obj.has_key?(key)
+        obj[key]
+      elsif hash && obj.has_key?(key.to_s)
+        obj[key.to_s]
+      elsif !hash && obj.respond_to?(key)
+        meth = obj.method(key) rescue proc { obj.send(key) }
+        if meth.arity == 1
+          meth.to_proc
+        else
+          meth[]
+        end
+      else
+        default
+      end
+    end
+  end
+end