Class: Mustache

Inherits:
Object
  • Object
show all
Defined in:
lib/mustache.rb,
lib/mustache/utils.rb,
lib/mustache/parser.rb,
lib/mustache/context.rb,
lib/mustache/version.rb,
lib/mustache/settings.rb,
lib/mustache/template.rb,
lib/mustache/generator.rb,
lib/mustache/enumerable.rb,
lib/mustache/context_miss.rb

Overview

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

Defined Under Namespace

Modules: Utils Classes: Context, ContextMiss, Generator, Parser, Template

Constant Summary collapse

VERSION = 
'1.1.1'
Enumerable = 
Module.new

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Mustache

Initialize a new Mustache instance.

Parameters:

  • options (Hash) (defaults to: {}) —

    An options hash

Options Hash (options):

  • template_path (String)
  • template_extension (String)
  • template_file (String)
  • template (String)
  • view_namespace (String)
  • view_path (String) 


86
87
88
89
90
 
# File 'lib/mustache.rb', line 86

def initialize(options = {})
  @options = options
  
  initialize_settings
end

Class Method Details

.inherited(subclass) ⇒ Object 



25
26
27
 
# File 'lib/mustache/settings.rb', line 25

def self.inherited(subclass)
  subclass.initialize_settings
end

.initialize_settings ⇒ Object 



14
15
16
17
18
19
20
21
 
# 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

.partial(name) ⇒ Object

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.



182
183
184
 
# File 'lib/mustache.rb', line 182

def self.partial(name)
  self.new.partial(name)
end

.path ⇒ Object

Alias for ‘template_path`



59
60
61
 
# File 'lib/mustache/settings.rb', line 59

def self.path
  template_path
end

.path=(path) ⇒ Object

Alias for ‘template_path`



64
65
66
 
# File 'lib/mustache/settings.rb', line 64

def self.path=(path)
  self.template_path = path
end

.raise_on_context_miss=(boolean) ⇒ Object 



204
205
206
 
# File 'lib/mustache/settings.rb', line 204

def self.raise_on_context_miss=(boolean)
  @raise_on_context_miss = boolean
end

.raise_on_context_miss? ⇒ Boolean

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.

Returns:

  • (Boolean) 


200
201
202
 
# File 'lib/mustache/settings.rb', line 200

def self.raise_on_context_miss?
  @raise_on_context_miss
end

.render(*args) ⇒ Object

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

Returns:

  • A rendered String version of a template.



96
97
98
 
# File 'lib/mustache.rb', line 96

def self.render(*args)
  new.render(*args)
end

.render_file(name, context = {}) ⇒ Object

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



167
168
169
 
# File 'lib/mustache.rb', line 167

def self.render_file(name, context = {})
  render(partial(name), context)
end

.template ⇒ Object

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.



164
165
166
 
# File 'lib/mustache/settings.rb', line 164

def self.template
  @template ||= templateify(File.read(template_file))
end

.template=(template) ⇒ Object 



168
169
170
 
# File 'lib/mustache/settings.rb', line 168

def self.template=(template)
  @template = templateify(template)
end

.template_extension ⇒ Object

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



75
76
77
 
# File 'lib/mustache/settings.rb', line 75

def self.template_extension
  @template_extension ||= inheritable_config_for :template_extension, 'mustache'
end

.template_extension=(template_extension) ⇒ Object 



79
80
81
82
 
# File 'lib/mustache/settings.rb', line 79

def self.template_extension=(template_extension)
  @template_extension = template_extension
  @template = nil
end

.template_file ⇒ Object

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



134
135
136
 
# File 'lib/mustache/settings.rb', line 134

def self.template_file
  @template_file || "#{path}/#{template_name}.#{template_extension}"
end

.template_file=(template_file) ⇒ Object 



138
139
140
141
 
# File 'lib/mustache/settings.rb', line 138

def self.template_file=(template_file)
  @template_file = template_file
  @template = nil
end

.template_name ⇒ Object

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



108
109
110
 
# File 'lib/mustache/settings.rb', line 108

def self.template_name
  @template_name || underscore
end

.template_name=(template_name) ⇒ Object 



112
113
114
115
 
# File 'lib/mustache/settings.rb', line 112

def self.template_name=(template_name)
  @template_name = template_name
  @template = nil
end

.template_path ⇒ Object

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”



39
40
41
 
# File 'lib/mustache/settings.rb', line 39

def self.template_path
  @template_path ||= inheritable_config_for :template_path, '.'
end

.template_path=(path) ⇒ Object 



43
44
45
46
 
# File 'lib/mustache/settings.rb', line 43

def self.template_path=(path)
  @template_path = File.expand_path(path)
  @template = nil
end

.view_namespace ⇒ Object

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



226
227
228
 
# File 'lib/mustache/settings.rb', line 226

def self.view_namespace
  @view_namespace ||= inheritable_config_for(:view_namespace, Object)
end

.view_namespace=(namespace) ⇒ Object 



230
231
232
 
# File 'lib/mustache/settings.rb', line 230

def self.view_namespace=(namespace)
  @view_namespace = namespace
end

.view_path ⇒ Object

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



242
243
244
 
# File 'lib/mustache/settings.rb', line 242

def self.view_path
  @view_path ||= inheritable_config_for(:view_path, '.')
end

.view_path=(path) ⇒ Object 



246
247
248
 
# File 'lib/mustache/settings.rb', line 246

def self.view_path=(path)
  @view_path = path
end

Instance Method Details

#[](key) ⇒ Object

Context accessors.

Examples:

Context accessors

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


150
151
152
 
# File 'lib/mustache.rb', line 150

def [](key)
  context[key.to_sym]
end

#[]=(key, value) ⇒ Object 



154
155
156
 
# File 'lib/mustache.rb', line 154

def []=(key, value)
  context[key.to_sym] = value
end

#compiled? ⇒ Boolean

Has this instance or its class already compiled a template?

Returns:

  • (Boolean) 


237
238
239
 
# File 'lib/mustache.rb', line 237

def compiled?
  (@template && @template.is_a?(Template)) || self.class.compiled?
end

#context ⇒ Object

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.



161
162
163
 
# File 'lib/mustache.rb', line 161

def context
  @context ||= Context.new(self)
end

#escape(value) ⇒ String

Override this to provide custom escaping. By default it uses ‘CGI.escapeHTML`.

Examples:

Overriding #escape

class PersonView < Mustache
  def escape(value)
    my_html_escape_method(value.to_s)
  end
end

Parameters:

  • value (Object) —

    Value to escape.

Returns:

  • (String) —

    Escaped content.



212
213
214
 
# File 'lib/mustache.rb', line 212

def escape(value)
  self.escapeHTML(value.to_s)
end

#escapeHTML(str) ⇒ 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.

Override this to provide custom escaping.

Examples:

Overriding #escapeHTML

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

Parameters:

  • str (String) —

    String to escape.

Returns:

  • (String) —

    Escaped HTML.



232
233
234
 
# File 'lib/mustache.rb', line 232

def escapeHTML(str)
  CGI.escapeHTML(str)
end

#initialize_settings ⇒ Object 



5
6
7
8
9
10
11
12
 
# 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) ⇒ Object

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.



189
190
191
192
193
194
195
196
197
198
 
# 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

#raise_on_context_miss=(boolean) ⇒ Object 



213
214
215
 
# File 'lib/mustache/settings.rb', line 213

def raise_on_context_miss=(boolean)
  @raise_on_context_miss = boolean
end

#raise_on_context_miss? ⇒ Boolean

Instance level version of ‘Mustache.raise_on_context_miss?`

Returns:

  • (Boolean) 


209
210
211
 
# File 'lib/mustache/settings.rb', line 209

def raise_on_context_miss?
  self.class.raise_on_context_miss? || @raise_on_context_miss
end

#render(data = template, ctx = {}) ⇒ String

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

Examples:

Render view

@view.render("Hi {{thing}}!", :thing => :world)

Set view template and then render

View.template = "Hi {{thing}}!"
@view = View.new
@view.render(:thing => :world)

Parameters:

  • data (String, Hash) (defaults to: template) —

    A String template or a Hash context. If a Hash is given, we’ll try to figure out the template from the class.

  • ctx (Hash) (defaults to: {}) —

    A Hash context if ‘data` is a String template.

Returns:

  • (String) —

    Returns a rendered version of a template.



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# 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

#render_file(name, context = {}) ⇒ Object

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



173
174
175
 
# File 'lib/mustache.rb', line 173

def render_file(name, context = {})
  self.class.render_file(name, context)
end

#template ⇒ Object

The template can be set at the instance level.



173
174
175
176
177
178
179
180
181
182
 
# 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

#template=(template) ⇒ Object 



184
185
186
 
# File 'lib/mustache/settings.rb', line 184

def template=(template)
  @template = templateify(template)
end

#template_extension ⇒ Object 



84
85
86
 
# File 'lib/mustache/settings.rb', line 84

def template_extension
  @template_extension ||= self.class.template_extension
end

#template_extension=(template_extension) ⇒ Object 



88
89
90
91
 
# File 'lib/mustache/settings.rb', line 88

def template_extension=(template_extension)
  @template_extension = template_extension
  @template = nil
end

#template_file ⇒ Object

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



145
146
147
 
# File 'lib/mustache/settings.rb', line 145

def template_file
  @template_file || "#{path}/#{template_name}.#{template_extension}"
end

#template_file=(template_file) ⇒ Object 



149
150
151
152
 
# File 'lib/mustache/settings.rb', line 149

def template_file=(template_file)
  @template_file = template_file
  @template = nil
end

#template_name ⇒ Object 



117
118
119
 
# File 'lib/mustache/settings.rb', line 117

def template_name
  @template_name ||= self.class.template_name
end

#template_name=(template_name) ⇒ Object 



121
122
123
124
 
# File 'lib/mustache/settings.rb', line 121

def template_name=(template_name)
  @template_name = template_name
  @template = nil
end

#template_path ⇒ Object Also known as: path 



48
49
50
 
# File 'lib/mustache/settings.rb', line 48

def template_path
  @template_path ||= self.class.template_path
end

#template_path=(path) ⇒ Object 



53
54
55
56
 
# File 'lib/mustache/settings.rb', line 53

def template_path=(path)
  @template_path = File.expand_path(path)
  @template = nil
end