mustache 0.99.4 → 1.1.3

data/lib/mustache.rb

@@ -1,6 +1,8 @@
+require 'mustache/enumerable'
 require 'mustache/template'
 require 'mustache/context'
 require 'mustache/settings'
+require 'mustache/utils'
 
 # Mustache is the base class from which your Mustache subclasses
 # should inherit (though it can be used on its own).
@@ -40,7 +42,7 @@ require 'mustache/settings'
 #
 # * template_file
 #
-# You can tell Mustache exactly which template to us with this
+# You can tell Mustache exactly which template to use with this
 # setting. It can be a relative or absolute path.
 #
 # * template
@@ -72,48 +74,60 @@ require 'mustache/settings'
 #
 class Mustache
 
+  # Initialize a new Mustache instance.
   #
-  # Public API
-  #
+  # @param [Hash] options An options hash
+  # @option options [String] template_path 
+  # @option options [String] template_extension
+  # @option options [String] template_file
+  # @option options [String] template
+  # @option options [String] view_namespace 
+  # @option options [String] view_path
+  def initialize(options = {})
+    @options = options
+    
+    initialize_settings
+  end
 
   # Instantiates an instance of this class and calls `render` with
   # the passed args.
   #
-  # Returns a rendered String version of a template
+  # @return 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
-  #
+  # @example Render view
   #   @view.render("Hi {{thing}}!", :thing => :world)
   #
+  # @example Set view template and then render
   #   View.template = "Hi {{thing}}!"
   #   @view = View.new
   #   @view.render(:thing => :world)
   #
-  # Returns a rendered String version of a template
+  # @param [String,Hash] data A String template or a Hash context.
+  #                           If a Hash is given, we'll try to figure
+  #                           out the template from the class.
+  # @param [Hash] ctx A Hash context if `data` is a String template.
+  # @return [String] Returns a rendered version of a template.
   def render(data = template, ctx = {})
-    if data.is_a? Hash
+    case data
+    when Hash
       ctx = data
-      tpl = templateify(template)
-    elsif data.is_a? Symbol
+    when Symbol
       self.template_name = data
-      tpl = templateify(template)
+    end
+
+    tpl = case data
+    when Hash
+      templateify(template)
+    when Symbol
+      templateify(template)
     else
-      tpl = templateify(data)
+      templateify(data)
     end
 
     return tpl.render(context) if ctx == {}
@@ -126,15 +140,13 @@ class Mustache
     end
   end
 
-  alias_method :to_html, :render
-  alias_method :to_text, :render
-
   # Context accessors.
   #
-  # view = Mustache.new
-  # view[:name] = "Jon"
-  # view.template = "Hi, {{name}}!"
-  # view.render # => "Hi, Jon!"
+  # @example Context accessors
+  #   view = Mustache.new
+  #   view[:name] = "Jon"
+  #   view.template = "Hi, {{name}}!"
+  #   view.render # => "Hi, Jon!"
   def [](key)
     context[key.to_sym]
   end
@@ -168,136 +180,144 @@ class Mustache
   #
   # Call `render` if you need to process it.
   def self.partial(name)
-    File.read("#{template_path}/#{name}.#{template_extension}")
+    self.new.partial(name)
   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)
+    partialpath = template_path.map{|p| "#{p}/#{name}.#{template_extension}" }.find{|pf| File.readable? pf}
+
+    raise RuntimeError.new("Can't find partial #{name}") if not partialpath and raise_on_context_miss?
+
+    partialpath ? File.read(partialpath) : ""
   end
 
+  # Override this to provide custom escaping.
+  # By default it uses `CGI.escapeHTML`.
+  #
+  # @example Overriding #escape
+  #   class PersonView < Mustache
+  #     def escape(value)
+  #       my_html_escape_method(value.to_s)
+  #     end
+  #   end
+  #
+  # @param [Object] value Value to escape.
+  # @return [String] Escaped content.
+  def escape(value)
+    self.escapeHTML(value.to_s)
+  end
+  
   # Override this to provide custom escaping.
   #
-  # class PersonView < Mustache
-  #   def escapeHTML(str)
-  #     my_html_escape_method(str)
+  # @example Overriding #escapeHTML
+  #   class PersonView < Mustache
+  #     def escapeHTML(str)
+  #       my_html_escape_method(str)
+  #     end
   #   end
-  # end
   #
-  # Returns a String
+  # @deprecated Use {#escape} instead.
+  #
+  #   Note that {#escape} can receive any kind of object.
+  #   If your override logic is expecting a string, you will
+  #   have to call to_s on it yourself.
+  # @param [String] str String to escape.
+  # @return [String] Escaped HTML.
   def escapeHTML(str)
     CGI.escapeHTML(str)
   end
 
+  # Has this instance or its class already compiled a template?
+  def compiled?
+    (@template && @template.is_a?(Template)) || self.class.compiled?
+  end
+
+
+  private
 
-  #
-  # Private API
-  #
 
   # When given a symbol or string representing a class, will try to produce an
   # appropriate view class.
-  # e.g.
+  #
+  # @example
   #   Mustache.view_namespace = Hurl::Views
   #   Mustache.view_class(:Partial) # => Hurl::Views::Partial
   def self.view_class(name)
-    if name != classify(name.to_s)
-      name = classify(name.to_s)
-    end
+    name = classify(name.to_s)
 
     # Emptiness begets emptiness.
-    if name.to_s == ''
-      return Mustache
-    end
+    return Mustache if name.to_s.empty?
 
-    file_name = underscore(name)
     name = "#{view_namespace}::#{name}"
+    const = rescued_const_get(name)
 
-    if const = const_get!(name)
-      const
-    elsif File.exists?(file = "#{view_path}/#{file_name}.rb")
-      require "#{file}".chomp('.rb')
-      const_get!(name) || Mustache
-    else
-      Mustache
-    end
+    return const if const
+
+    const_from_file(name)
   end
 
-  # Supercharged version of Module#const_get.
-  #
-  # Always searches under Object and can find constants by their full name,
-  #   e.g. Mustache::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, name|
-      klass.const_get(name)
-    end
+  def self.rescued_const_get name
+    const_get(name, true) || Mustache
   rescue NameError
     nil
   end
 
+  def self.const_from_file name
+    file_name = underscore(name)
+    file_path = "#{view_path}/#{file_name}.rb"
+
+    return Mustache unless File.exist?(file_path)
+
+    require file_path.chomp('.rb')
+    rescued_const_get(name)
+  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('::')
+    Mustache::Utils::String.new(underscored).classify
   end
 
-  #   TemplatePartial => template_partial
+  # 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('/')
+    Mustache::Utils::String.new(classified).underscore(view_namespace)
   end
 
-  # Turns a string into a Mustache::Template. If passed a Template,
-  # returns it.
-  def self.templateify(obj)
-    if obj.is_a?(Template)
-      obj
-    else
-      Template.new(obj.to_s)
-    end
+  # @param [Template,String] obj      Turns `obj` into a template
+  # @param [Hash]            options  Options for template creation
+  def self.templateify(obj, options = {})
+    obj.is_a?(Template) ? obj : Template.new(obj, options)
   end
 
   def templateify(obj)
-    self.class.templateify(obj)
+    opts = {:partial_resolver => self.method(:partial)}
+    opts.merge!(@options) if @options.is_a?(Hash)
+    self.class.templateify(obj, opts)
   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.
+  # @param [Symbol] attr_name Name of the attribute. It should match
+  #                           the instance variable.
+  # @param [Object] default Default value to use if the superclass does
+  #                         not respond.
   #
-  # Returns the inherited or default configuration setting.
+  # @return Inherited or default configuration setting.
   def self.inheritable_config_for(attr_name, default)
     superclass.respond_to?(attr_name) ? superclass.send(attr_name) : default
   end

data/man/mustache.1

@@ -1,10 +1,10 @@
-.\" generated with Ronn/v0.5
-.\" http://github.com/rtomayko/ronn/
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "MUSTACHE" "1" "May 2010" "DEFUNKT" "Mustache Manual"
+.TH "MUSTACHE" "1" "November 2016" "DEFUNKT" "Mustache Manual"
 .
 .SH "NAME"
-\fBmustache\fR \-\- Mustache processor
+\fBmustache\fR \- Mustache processor
 .
 .SH "SYNOPSIS"
 .
@@ -17,17 +17,13 @@ mustache \-\-tokens <FILE>
 .fi
 .
 .SH "DESCRIPTION"
-Mustache is a logic\-less templating system for HTML, config files,
-anything.
+Mustache is a logic\-less templating system for HTML, config files, anything\.
 .
 .P
-The \fBmustache\fR command processes a Mustache template preceded by YAML
-frontmatter from standard input and prints one or more documents to
-standard output.
+The \fBmustache\fR command processes a Mustache template preceded by YAML frontmatter from standard input and prints one or more documents to standard output\.
 .
 .P
-YAML frontmatter beings with \fB\-\-\-\fR on a single line, followed by YAML,
-ending with another \fB\-\-\-\fR on a single line, e.g.
+YAML frontmatter begins with \fB\-\-\-\fR on a single line, followed by YAML, ending with another \fB\-\-\-\fR on a single line, e\.g\.
 .
 .IP "" 4
 .
@@ -42,12 +38,10 @@ names: [ {name: chris}, {name: mark}, {name: scott} ]
 .IP "" 0
 .
 .P
-If you are unfamiliar with YAML, it is a superset of JSON. Valid JSON
-should work fine.
+If you are unfamiliar with YAML, it is a superset of JSON\. Valid JSON should work fine\.
 .
 .P
-After the frontmatter should come any valid Mustache template. See
-mustache(5) for an overview of Mustache templates.
+After the frontmatter should come any valid Mustache template\. See mustache(5) for an overview of Mustache templates\.
 .
 .P
 For example:
@@ -65,23 +59,23 @@ For example:
 .IP "" 0
 .
 .P
-Now let's combine them.
+Now let\'s combine them\.
 .
 .IP "" 4
 .
 .nf
 
-$ cat data.yml
+$ cat data\.yml
 \-\-\-
 names: [ {name: chris}, {name: mark}, {name: scott} ]
 \-\-\-
 
-$ cat template.mustache
+$ cat template\.mustache
 {{#names}}
   Hi {{name}}!
 {{/names}}
 
-$ cat data.yml template.mustache | mustache
+$ mustache data\.yml template\.mustache
 Hi chris!
 Hi mark!
 Hi scott!
@@ -91,8 +85,7 @@ Hi scott!
 .IP "" 0
 .
 .P
-If you provide multiple YAML documents (as delimited by \fB\-\-\-\fR), your
-template will be rendered multiple times. Like a mail merge.
+If you provide multiple YAML documents (as delimited by \fB\-\-\-\fR), your template will be rendered multiple times\. Like a mail merge\.
 .
 .P
 For example:
@@ -101,7 +94,7 @@ For example:
 .
 .nf
 
-$ cat data.yml
+$ cat data\.yml
 \-\-\-
 name: chris
 \-\-\-
@@ -110,10 +103,10 @@ name: mark
 name: scott
 \-\-\-
 
-$ cat template.mustache
+$ cat template\.mustache
 Hi {{name}}!
 
-$ cat data.yml template.mustache | mustache
+$ mustache data\.yml template\.mustache
 Hi chris!
 Hi mark!
 Hi scott!
@@ -123,23 +116,15 @@ Hi scott!
 .IP "" 0
 .
 .SH "OPTIONS"
-By default \fBmustache\fR will try to render a Mustache template using the
-YAML frontmatter you provide. It can do a few other things, however.
+By default \fBmustache\fR will try to render a Mustache template using the YAML frontmatter you provide\. It can do a few other things, however\.
 .
 .TP
 \fB\-c\fR, \fB\-\-compile\fR
-Print the compiled Ruby version of a given template. This is the
-code that is actually used when rendering a template into a
-string. Useful for debugging but only if you are familiar with
-Mustache's internals.
+Print the compiled Ruby version of a given template\. This is the code that is actually used when rendering a template into a string\. Useful for debugging but only if you are familiar with Mustache\'s internals\.
 .
 .TP
 \fB\-t\fR, \fB\-\-tokens\fR
-Print the tokenized form of a given Mustache template. This can be
-used to understand how Mustache parses a template. The tokens are
-handed to a generator which compiles them into a Ruby
-string. Syntax errors and confused tags, therefor, can probably be
-identified by examining the tokens produced.
+Print the tokenized form of a given Mustache template\. This can be used to understand how Mustache parses a template\. The tokens are handed to a generator which compiles them into a Ruby string\. Syntax errors and confused tags, therefore, can probably be identified by examining the tokens produced\.
 .
 .SH "INSTALLATION"
 If you have RubyGems installed:
@@ -158,10 +143,10 @@ gem install mustache
 .
 .nf
 
-$ mustache data.yml template.mustache
-$ cat data.yml | mustache \- template.mustache
-$ mustache \-c template.mustache
-$ cat <<data | ruby mustache \- template.mustache
+$ mustache data\.yml template\.mustache
+$ cat data\.yml | mustache \- template\.mustache
+$ mustache \-c template\.mustache
+$ cat <<data | ruby mustache \- template\.mustache
 \-\-\-
 name: Bob
 age: 30
@@ -177,4 +162,4 @@ Mustache is Copyright (C) 2009 Chris Wanstrath
 Original CTemplate by Google
 .
 .SH "SEE ALSO"
-mustache(5), mustache(7), gem(1), \fIhttp://mustache.github.com/\fR
+mustache(5), gem(1), \fIhttp://mustache\.github\.io/\fR