class Mustache

Mustache is the base class from which your Mustache subclasses should inherit (though it can be used on its own).

The typical Mustache workflow is as follows:

Create a Mustache subclass: class Stats < Mustache
Create a template: stats.mustache
Instantiate an instance: view = Stats.new
Render that instance: view.render

You can skip the instantiation by calling ‘Stats.render` directly.

While Mustache 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 Mustache uses to find templates.

Here are the available options:

template_path

The ‘template_path` setting determines the path Mustache 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 Mustache subclass `Stats` will try to load /usr/local/templates/stats.mustache

template_extension

The ‘template_extension` is the extension Mustache uses when looking for template files. By default it is “mustache”

template_file

You can tell Mustache exactly which template to use with this setting. It can be a relative or absolute path.

template

Sometimes you want Mustache to render a string, not a file. In those cases you may set the ‘template` setting. For example:

>> Mustache.render("Hello {{planet}}", :planet => "World!")
=> "Hello World!"

The ‘template` setting is also available on instances.

view = Mustache.new
view.template = "Hi, {{person}}!"
view[:person] = 'Mom'
view.render # => Hi, mom!

view_namespace

To make life easy on those developing Mustache plugins for web frameworks or other libraries, Mustache will attempt to load view classes (i.e. Mustache subclasses) using the ‘view_class` class method. The `view_namespace` tells Mustache under which constant view classes live. By default it is `Object`.

view_path

Similar to ‘template_path`, the `view_path` option tells Mustache where to look for files containing view classes when using the `view_class` method.

Settings which can be configured for all view classes, a single view class, or a single Mustache instance.

Constants

Enumerable
VERSION

Public Class Methods

classify (underscored)

Source

# File lib/mustache.rb, line 290
def self.classify(underscored)
  Mustache::Utils::String.new(underscored).classify
end

template_partial => TemplatePartial template/partial => Template::Partial

compiled? ()

Source

# File lib/mustache.rb, line 283
def self.compiled?
  @template.is_a? Template
end

Has this template already been compiled? Compilation is somewhat expensive so it may be useful to check this before attempting it.

const_from_file (name)

Source

# File lib/mustache.rb, line 271
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

inheritable_config_for (attr_name, default)

Source

# File lib/mustache.rb, line 324
def self.inheritable_config_for(attr_name, default)
  superclass.respond_to?(attr_name) ? superclass.send(attr_name) : default
end

Return the value of the configuration setting on the superclass, or return the default.

@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.

@return Inherited or default configuration setting.

inherited (subclass)

Source

# File lib/mustache/settings.rb, line 25
def self.inherited(subclass)
  subclass.initialize_settings
end

initialize_settings ()

Source

# File lib/mustache/settings.rb, line 14
def self.initialize_settings
  @template = nil
  @template_path = nil
  @template_extension = nil
  @template_name = nil
  @template_file = nil
  @raise_on_context_miss = nil
end

new (options = {})

Source

# File lib/mustache.rb, line 86
def initialize(options = {})
  @options = options
  
  initialize_settings
end

Initialize a new Mustache instance.

@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

partial (name)

Source

# File lib/mustache.rb, line 182
def self.partial(name)
  self.new.partial(name)
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 {{mustaches}}.

Call ‘render` if you need to process it.

path ()

Source

# File lib/mustache/settings.rb, line 59
def self.path
  template_path
end

Alias for ‘template_path`

path= (path)

Source

# File lib/mustache/settings.rb, line 64
def self.path=(path)
  self.template_path = path
end

Alias for ‘template_path`

raise_on_context_miss= (boolean)

Source

# File lib/mustache/settings.rb, line 204
def self.raise_on_context_miss=(boolean)
  @raise_on_context_miss = boolean
end

raise_on_context_miss? ()

Source

# File lib/mustache/settings.rb, line 200
def self.raise_on_context_miss?
  @raise_on_context_miss
end

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, ‘Mustache::ContextMiss` will be raised.

render (*args)

Source

# File lib/mustache.rb, line 96
def self.render(*args)
  new.render(*args)
end

Instantiates an instance of this class and calls ‘render` with the passed args.

@return A rendered String version of a template.

render_file (name, context = {})

Source

# File lib/mustache.rb, line 167
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.

rescued_const_get (name)

Source

# File lib/mustache.rb, line 265
def self.rescued_const_get name
  const_get(name, true) || Mustache
rescue NameError
  nil
end

template ()

Source

# File lib/mustache/settings.rb, line 164
def self.template
  @template ||= templateify(File.read(template_file))
end

The template is the actual string Mustache uses as its template. There is a bit of magic here: what we get back is actually a Mustache::Template object, but you can still safely use ‘template=`

with a string.

template= (template)

Source

# File lib/mustache/settings.rb, line 168
def self.template=(template)
  @template = templateify(template)
end

template_extension ()

Source

# File lib/mustache/settings.rb, line 75
def self.template_extension
  @template_extension ||= inheritable_config_for :template_extension, 'mustache'
end

A Mustache template’s default extension is ‘mustache’, but this can be changed.

template_extension= (template_extension)

Source

# File lib/mustache/settings.rb, line 79
def self.template_extension=(template_extension)
  @template_extension = template_extension
  @template = nil
end

template_file ()

Source

# File lib/mustache/settings.rb, line 134
def self.template_file
  @template_file || "#{path}/#{template_name}.#{template_extension}"
end

The template file is the absolute path of the file Mustache will use as its template. By default it’s ./class_name.mustache

template_file= (template_file)

Source

# File lib/mustache/settings.rb, line 138
def self.template_file=(template_file)
  @template_file = template_file
  @template = nil
end

template_name ()

Source

# File lib/mustache/settings.rb, line 108
def self.template_name
  @template_name || underscore
end

The template name is the Mustache 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.mustache
end

template_name= (template_name)

Source

# File lib/mustache/settings.rb, line 112
def self.template_name=(template_name)
  @template_name = template_name
  @template = nil
end

template_path ()

Source

# File lib/mustache/settings.rb, line 39
def self.template_path
  @template_path ||= inheritable_config_for :template_path, '.'
end

The template path informs your Mustache 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.mustache”

template_path= (path)

Source

# File lib/mustache/settings.rb, line 43
def self.template_path=(path)
  @template_path = File.expand_path(path)
  @template = nil
end

templateify (obj, options = {})

Source

# File lib/mustache.rb, line 305
def self.templateify(obj, options = {})
  obj.is_a?(Template) ? obj : Template.new(obj, options)
end

@param [Template,String] obj Turns ‘obj` into a template @param [Hash] options Options for template creation

underscore (classified = name)

Source

# File lib/mustache.rb, line 297
def self.underscore(classified = name)
  classified = superclass.name if classified.to_s.empty?

  Mustache::Utils::String.new(classified).underscore(view_namespace)
end

TemplatePartial => template_partial Template::Partial => template/partial Takes a string but defaults to using the current class’ name.

view_class (name)

Source

# File lib/mustache.rb, line 251
def self.view_class(name)
  name = classify(name.to_s)

  # Emptiness begets emptiness.
  return Mustache if name.to_s.empty?

  name = "#{view_namespace}::#{name}"
  const = rescued_const_get(name)

  return const if const

  const_from_file(name)
end

When given a symbol or string representing a class, will try to produce an appropriate view class.

@example

Mustache.view_namespace = Hurl::Views
Mustache.view_class(:Partial) # => Hurl::Views::Partial

view_namespace ()

Source

# File lib/mustache/settings.rb, line 226
def self.view_namespace
  @view_namespace ||= inheritable_config_for(:view_namespace, Object)
end

The constant under which Mustache 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`.

view_namespace= (namespace)

Source

# File lib/mustache/settings.rb, line 230
def self.view_namespace=(namespace)
  @view_namespace = namespace
end

view_path ()

Source

# File lib/mustache/settings.rb, line 242
def self.view_path
  @view_path ||= inheritable_config_for(:view_path, '.')
end

Mustache searches the view path for .rb files to require when asked to find a view class. Defaults to “.”

view_path= (path)

Source

# File lib/mustache/settings.rb, line 246
def self.view_path=(path)
  @view_path = path
end

Public Instance Methods

[] (key)

Source

# File lib/mustache.rb, line 150
def [](key)
  context[key.to_sym]
end

Context accessors.

@example Context accessors

view = Mustache.new
view[:name] = "Jon"
view.template = "Hi, {{name}}!"
view.render # => "Hi, Jon!"

[]= (key, value)

Source

# File lib/mustache.rb, line 154
def []=(key, value)
  context[key.to_sym] = value
end

compiled? ()

Source

# File lib/mustache.rb, line 237
def compiled?
  (@template && @template.is_a?(Template)) || self.class.compiled?
end

Has this instance or its class already compiled a template?

context ()

Source

# File lib/mustache.rb, line 161
def context
  @context ||= Context.new(self)
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.

escape (value)

Source

# File lib/mustache.rb, line 212
def escape(value)
  self.escapeHTML(value.to_s)
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.

escapeHTML (str)

Source

# File lib/mustache.rb, line 232
def escapeHTML(str)
  CGI.escapeHTML(str)
end

Override this to provide custom escaping.

@example Overriding escapeHTML

class PersonView < Mustache
  def escapeHTML(str)
    my_html_escape_method(str)
  end
end

@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.

initialize_settings ()

Source

# File lib/mustache/settings.rb, line 5
def initialize_settings
  @template = nil
  @template_path = nil
  @template_extension = nil
  @template_name = nil
  @template_file = nil
  @raise_on_context_miss = nil
end

partial (name)

Source

# File lib/mustache.rb, line 189
def partial(name)
  path = "#{template_path}/#{name}.#{template_extension}"

  begin
    File.read(path)
  rescue
    raise if raise_on_context_miss?
    ""
  end
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.

path ()

Alias for: template_path

raise_on_context_miss= (boolean)

Source

# File lib/mustache/settings.rb, line 213
def raise_on_context_miss=(boolean)
  @raise_on_context_miss = boolean
end

raise_on_context_miss? ()

Source

# File lib/mustache/settings.rb, line 209
def raise_on_context_miss?
  self.class.raise_on_context_miss? || @raise_on_context_miss
end

Instance level version of ‘Mustache.raise_on_context_miss?`

render (data = template, ctx = {})

Source

# File lib/mustache.rb, line 116
def render(data = template, ctx = {})
  case data
  when Hash
    ctx = data
  when Symbol
    self.template_name = data
  end

  tpl = case data
  when Hash
    templateify(template)
  when Symbol
    templateify(template)
  else
    templateify(data)
  end

  return tpl.render(context) if ctx == {}

  begin
    context.push(ctx)
    tpl.render(context)
  ensure
    context.pop
  end
end

Parses our fancy pants template file and returns normal file with all special {{tags}} and {{#sections}}replaced{{/sections}}.

@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)

@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.

render_file (name, context = {})

Source

# File lib/mustache.rb, line 173
def render_file(name, context = {})
  self.class.render_file(name, context)
end

Given a file name and an optional context, attempts to load and render the file as a template.

template ()

Source

# File lib/mustache/settings.rb, line 173
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

The template can be set at the instance level.

template= (template)

Source

# File lib/mustache/settings.rb, line 184
def template=(template)
  @template = templateify(template)
end

template_extension ()

Source

# File lib/mustache/settings.rb, line 84
def template_extension
  @template_extension ||= self.class.template_extension
end

template_extension= (template_extension)

Source

# File lib/mustache/settings.rb, line 88
def template_extension=(template_extension)
  @template_extension = template_extension
  @template = nil
end

template_file ()

Source

# File lib/mustache/settings.rb, line 145
def template_file
  @template_file || "#{path}/#{template_name}.#{template_extension}"
end

The template file is the absolute path of the file Mustache will use as its template. By default it’s ./class_name.mustache

template_file= (template_file)

Source

# File lib/mustache/settings.rb, line 149
def template_file=(template_file)
  @template_file = template_file
  @template = nil
end

template_name ()

Source

# File lib/mustache/settings.rb, line 117
def template_name
  @template_name ||= self.class.template_name
end

template_name= (template_name)

Source

# File lib/mustache/settings.rb, line 121
def template_name=(template_name)
  @template_name = template_name
  @template = nil
end

template_path ()

Source

# File lib/mustache/settings.rb, line 48
def template_path
  @template_path ||= self.class.template_path
end

Also aliased as: path

template_path= (path)

Source

# File lib/mustache/settings.rb, line 53
def template_path=(path)
  @template_path = File.expand_path(path)
  @template = nil
end

Private Instance Methods

templateify (obj)

Source

# File lib/mustache.rb, line 309
def templateify(obj)
  opts = {:partial_resolver => self.method(:partial)}
  opts.merge!(@options) if @options.is_a?(Hash)
  self.class.templateify(obj, opts)
end