mustache 0.5.0 → 0.6.0

data/README.md

@@ -7,6 +7,9 @@ framework-agnostic way to render logic-free views.
 As ctemplates says, "It emphasizes separating logic from presentation:
 it is impossible to embed application logic in this template language."
 
+For a list of implementations (other than Ruby) and tips, see
+<http://defunkt.github.com/mustache/>.
+
 
 Overview
 --------
@@ -94,139 +97,22 @@ Simple.
 Tag Types
 ---------
 
-Tags are indicated by the double mustaches. `{{name}}` is a tag. Let's
-talk about the different types of tags.
-
-### Variables
-
-The most basic tag is the variable. A `{{name}}` tag in a basic
-template will try to call the `name` method on your view. If there is
-no `name` method, an exception will be raised.
-
-All variables are HTML escaped by default. If you want to return
-unescaped HTML, use the triple mustache: `{{{name}}}`.
-
-By default a variable "miss" returns an empty string. You can
-configure this by setting `Mustache.raise_on_context_miss` to true.
-
-### Boolean Sections
-
-A section begins with a pound and ends with a slash. That is,
-`{{#person}}` begins a "person" section while `{{/person}}` ends it.
-
-If the `person` method exists and calling it returns false, the HTML
-between the pound and slash will not be displayed.
-
-If the `person` method exists and calling it returns true, the HTML
-between the pound and slash will be rendered and displayed.
-
-### Enumerable Sections
-
-Enumerable sections are syntactically identical to boolean sections in
-that they begin with a pound and end with a slash. The difference,
-however, is in the view: if the method called returns an enumerable,
-the section is repeated as the enumerable is iterated over.
-
-Each item in the enumerable is expected to be a hash which will then
-become the context of the corresponding iteration. In this way we can
-construct loops.
-
-For example, imagine this template:
-
-    {{#repo}}
-      <b>{{name}}</b>
-    {{/repo}}
-
-And this view code:
-
-    def repo
-      Repository.all.map { |r| { :name => r.to_s } }
-    end
-
-When rendered, our view will contain a list of all repository names in
-the database.
-
-As a convenience, if a section returns a hash (as opposed to an array
-or a boolean) it will be treated as a single item array.
-
-With the above template, we could use this Ruby code for a single
-iteration:
-
-    def repo
-      { :name => Repository.first.to_s }
-    end
-
-This would be treated by Mustache as functionally equivalent to the
-following:
-
-    def repo
-      [ { :name => Repository.first.to_s } ]
-    end
-
-
-### Comments
-
-Comments begin with a bang and are ignored. The following template:
+For a language-agnostic overview of Mustache's template syntax, see
+the `mustache(5)` manpage or
+<http://defunkt.github.com/mustache/mustache.5.html>.
 
-    <h1>Today{{! ignore me }}.</h1>
 
-Will render as follows:
-
-    <h1>Today.</h1>
-
-### Partials
-
-Partials begin with a greater than sign, like `{{> box}}`.
-
-It is useful to think of partials as a "template expansion" - that is,
-the actual partial tag will be replaced with the content of the
-partial. Therefor partials share the current context.
-
-For example, this template and partial:
-
-    base.mustache
-    Names:
-    {{# names }}
-      {{> user }}
-    {{/ names }}
-
-    user.mustache:
-    <strong>{{ name }}</strong>
-
-Can be thought of as a single, expanded template:
-
-    Names:
-    {{# names }}
-      <strong>{{ name }}</strong>
-    {{/ names }}
-
-Have partial-specific code you want to share between view classes?
-Consider using a module and including it.
-
-
-### Set Delimiter
-
-Set Delimiter tags start with an equal sign and change the tag
-delimiters from {{ and }} to custom strings.
-
-Consider the following contrived example:
-
-    * {{ default_tags }}
-    {{=<% %>=}}
-    * <% erb_style_tags %>
-    <%={{ }}=%>
-    * {{ default_tags_again }}
-
-Here we have a list with three items. The first item uses the default
-tag style, the second uses erb style as defined by the Set Delimiter
-tag, and the third returns to the default style after yet another Set
-Delimiter declaration.
+Escaping
+--------
 
-According to [ctemplates][3], this "is useful for languages like TeX, where
-double-braces may occur in the text and are awkward to use for
-markup."
+Mustache does escape all values when using the standard double
+Mustache syntax. Characters which will be escaped: `& \ " < >`. To
+disable escaping, simply use tripple mustaches like
+`{{{unescaped_variable}}}`.
 
-Custom delimiters may not contain whitespace or the equals sign.
+Example: Using `{{variable}}` inside a template for `5 > 2` will
+result in `5 &gt; 2`, where as the usage of `{{{variable}}}` will
+result in `5 > 2`.
 
 
 Dict-Style Views
@@ -417,69 +303,37 @@ Vim
 Thanks to [Juvenn Woo](http://github.com/juvenn) for mustache.vim. It
 is included under the contrib/ directory.
 
+See <http://gist.github.com/323622> for installation instructions.
 
 Emacs
 -----
 
-tpl-mode.el is included under the contrib/ directory for any Emacs users.
-Based on Google's tpl-mode for ctemplates, it adds support for Mustache's
-more lenient tag values and includes a few commands for your editing pleasure.
+mustache-mode.el is included under the contrib/ directory for any
+Emacs users. Based on Google's tpl-mode for ctemplates, it adds
+support for Mustache's more lenient tag values and includes a few
+commands for your editing pleasure.
+
+See <http://gist.github.com/323619> for installation instructions.
 
 
 TextMate
 --------
 
-Check out Tekkub's
-[Mustache.tmbundle](http://github.com/tekkub/Mustache.tmbundle).
+[Mustache.tmbundle](http://github.com/defunkt/Mustache.tmbundle)
 
+See <http://gist.github.com/323624> for installation instructions.
 
 Command Line
 ------------
 
-Mustache includes a `mustache` script for rendering templates on the
-command line. This can be useful when designing HTML that will
-eventually be included in a website: instead of having to format the
-HTML as Mustache later, you can do it now!
-
-The script expects a Mustache template on STDIN with YAML
-frontmatter. An example looks like this:
-
-    $ cat complete.mustache
-    ---
-    names: [ {name: chris}, {name: mark}, {name: scott} ]
-    ---
-    {{#names}}
-      Hi {{name}}!
-    {{/names}}
-
-    $ cat complete.mustache | mustache
-    Hi chris!
-    Hi mark!
-    Hi scott!
-
-It's probably more useful to keep the YAML and HTML in separate files,
-though. Luckily `cat` works great for this, too:
-
-    $ cat data.yml
-    ---
-    names: [ {name: chris}, {name: mark}, {name: scott} ]
-    ---
-
-    $ cat template.mustache
-    {{#names}}
-      Hi {{name}}!
-    {{/names}}
-
-    $ cat data.yml template.mustache | mustache
-    Hi chris!
-    Hi mark!
-    Hi scott!
-
+See `mustache(1)` man page or
+<http://defunkt.github.com/mustache/mustache.1.html>
+for command line docs.
 
 Installation
 ------------
 
-### [Gemcutter](http://gemcutter.org/)
+### [RubyGems](http://rubygems.org/)
 
     $ gem install mustache
 
@@ -487,7 +341,6 @@ Installation
 
     $ rip install git://github.com/defunkt/mustache.git
 
-
 Acknowledgements
 ----------------
 
@@ -499,13 +352,11 @@ Meta
 ----
 
 * Code: `git clone git://github.com/defunkt/mustache.git`
-* Home: <http://github.com/defunkt/mustache>
-* Docs: <http://defunkt.github.com/mustache>
+* Home: <http://defunkt.github.com/mustache>
 * Bugs: <http://github.com/defunkt/mustache/issues>
 * List: <http://groups.google.com/group/mustache-rb>
 * Test: <http://runcoderun.com/defunkt/mustache>
-* Gems: <http://gemcutter.org/gems/mustache>
-* Boss: Chris Wanstrath :: <http://github.com/defunkt>
+* Gems: <http://rubygems.org/gems/mustache>
 
 [1]: http://code.google.com/p/google-ctemplate/
 [2]: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html

data/Rakefile

@@ -1,66 +1,107 @@
 require 'rake/testtask'
 require 'rake/rdoctask'
 
+def command?(command)
+  system("type #{command} > /dev/null")
+end
+
+#
+# Tests
+#
+
 task :default => :test
 
-Rake::TestTask.new do |t|
-  t.libs << 'lib'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
+if command? :turn
+  desc "Run tests"
+  task :test do
+    exec "turn"
+  end
+else
+  Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.pattern = 'test/**/*_test.rb'
+    t.verbose = false
+  end
 end
 
-desc "Build a gem"
-task :gem => [ :gemspec, :build ]
+#
+# Ron
+#
 
-desc "Launch Kicker (like autotest)"
-task :kicker do
-  puts "Kicking... (ctrl+c to cancel)"
-  exec "kicker -e rake test lib examples"
+if command? :ron
+  desc "Show the manual"
+  task :man => "man:build" do
+    exec "man man/mustache.1"
+  end
+
+  desc "Build the manual"
+  task "man:build" do
+    sh "ron -br5 --organization=DEFUNKT --manual='Mustache Manual' man/*.ron"
+  end
 end
 
-begin
-  require 'jeweler'
-  $LOAD_PATH.unshift 'lib'
-  require 'mustache/version'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "mustache"
-    gemspec.summary = "Mustache is a framework-agnostic way to render logic-free views."
-    gemspec.description = "Mustache is a framework-agnostic way to render logic-free views."
-    gemspec.email = "chris@ozmm.org"
-    gemspec.homepage = "http://github.com/defunkt/mustache"
-    gemspec.authors = ["Chris Wanstrath"]
-    gemspec.version = Mustache::Version
+if command? :kicker
+  desc "Launch Kicker (like autotest)"
+  task :kicker do
+    puts "Kicking... (ctrl+c to cancel)"
+    exec "kicker -e rake test lib examples"
   end
-rescue LoadError
-  puts "Jeweler not available."
-  puts "Install it with: gem install jeweler"
 end
 
+#
+# Gems
+#
+
 begin
-  require 'sdoc_helpers'
+  require 'mg'
+  MG.new("mustache.gemspec")
+
+  desc "Build a gem."
+  task :gem => :package
+
+  # Ensure tests pass before pushing a gem.
+  task :gemcutter => :test
+
+  desc "Push a new version to Gemcutter and publish docs."
+  task :publish => :gemcutter do
+    system "git tag v#{Mustache::Version}"
+    system "git push origin v#{Mustache::Version}"
+    system "git push origin master"
+    system "gem push pkg/mustache-#{Mustache::Version}.gem"
+    system "git clean -fd"
+    exec "rake pages"
+  end
 rescue LoadError
-  puts "sdoc support not enabled. Please gem install sdoc-helpers."
+  warn "mg not available."
+  warn "Install it with: gem i mg"
 end
 
-desc "Push a new version to Gemcutter"
-task :publish => [ :test, :gemspec, :build ] do
-  system "git tag v#{Mustache::Version}"
-  system "git push origin v#{Mustache::Version}"
-  system "git push origin master"
-  system "gem push pkg/mustache-#{Mustache::Version}.gem"
-  system "git clean -fd"
-  exec "rake pages"
-end
+#
+# Documentation
+#
 
-desc "Install the edge gem"
-task :install_edge => [ :dev_version, :gemspec, :build ] do
-  exec "gem install pkg/mustache-#{Mustache::Version}.gem"
-end
+# begin
+#   require 'sdoc_helpers'
+# rescue LoadError
+#   warn "sdoc support not enabled. Please gem install sdoc-helpers."
+# end
+
+desc "Publish to GitHub Pages"
+task :pages => [ "build:man" ] do
+  Dir['man/*.html'].each do |f|
+    cp f, File.basename(f).sub('.html', '.newhtml')
+  end
+
+  `git commit -am 'generated manual'`
+  `git checkout gh-pages`
+
+  Dir['*.newhtml'].each do |f|
+    mv f, f.sub('.newhtml', '.html')
+  end
 
-# Sets the current Mustache version to the current dev version
-task :dev_version do
-  $LOAD_PATH.unshift 'lib/mustache'
-  require 'mustache/version'
-  version = Mustache::Version + '.' + Time.now.to_i.to_s
-  Mustache.const_set(:Version, version)
+  `git add .`
+  `git commit -m updated`
+  `git push origin gh-pages`
+  `git checkout master`
+  puts :done
 end

data/bin/mustache

@@ -3,11 +3,15 @@
 require 'mustache'
 require 'yaml'
 
-if STDIN.stat.size > 0
-  doc = STDIN.read
+if !$stdin.tty?
+  doc = $stdin.read
   if doc =~ /^(\s*---(.*)---\s*)/m
-    data = YAML.load($2.strip)
-    puts Mustache.render(doc.sub($1, ''), data)
+    yaml = $2.strip
+    template = doc.sub($1, '')
+
+    YAML.each_document(yaml) do |data|
+      puts Mustache.render(template, data)
+    end
   else
     puts doc
   end
@@ -15,20 +19,7 @@ else
   puts <<-usage
 Usage: cat data.yml template.mustache | mustache
 
-Expects a single Mustache template on STDIN complete with YAML
-frontmatter.
-
-Runs template.mustache through Mustache, using the data in data.yml to
-replace sections and variables. Useful when developing templates
-before hooking them into your website or whatnot.
-
-The data.yml file should start with --- on a single line and end with
---- on a single line, e.g.
-
-    ---
-    names: [ {name: chris}, {name: mark}, {name: scott} ]
-    ---
-
-The converted document will be printed on STDOUT.
+See mustache(1) or http://defunkt.github.com/mustache/mustache.1.html
+for an overview.
 usage
 end

data/lib/mustache/context.rb

@@ -4,30 +4,73 @@ class Mustache
   # set to true.
   #
   # For example, if your View class does not respond to `music` but
-  # your template contains a `{{template}}` tag this exception will be raised.
+  # your template contains a `{{music}}` tag this exception will be raised.
   #
   # By default it is not raised. See Mustache.raise_on_context_miss.
   class ContextMiss < RuntimeError;  end
 
   # A Context represents the context which a Mustache template is
   # executed within. All Mustache tags reference keys in the Context.
-  class Context < Hash
+  class Context
+    # Expect to be passed an instance of `Mustache`.
     def initialize(mustache)
       @mustache = mustache
-      super()
+      @stack = [@mustache]
     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)
-      if has_key?(name)
-        super
-      elsif has_key?(name.to_s)
-        super(name.to_s)
-      elsif @mustache.respond_to?(name)
-        @mustache.send(name)
-      elsif @mustache.raise_on_context_miss?
-        raise ContextMiss.new("Can't find #{name} in #{@mustache.inspect}")
+      fetch(name, nil)
+    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|
+        hash = frame.respond_to?(:has_key?)
+
+        if hash && frame.has_key?(name)
+          return frame[name]
+        elsif hash && frame.has_key?(name.to_s)
+          return frame[name.to_s]
+        elsif !hash && frame.respond_to?(name)
+          return frame.__send__(name)
+        end
+      end
+
+      if default == :__raise || @mustache.raise_on_context_miss?
+        raise ContextMiss.new("Can't find #{name} in #{@stack.inspect}")
       else
-        nil
+        default
       end
     end
   end

data/lib/mustache/sinatra.rb

@@ -92,7 +92,7 @@ class Mustache
 
     def self.registered(app)
       app.helpers Mustache::Sinatra::Helpers
-      app.set :mustaches, ::Sinatra::Base.views
+      app.set :mustaches, app.views
       app.set :namespace, app
     end
   end

data/lib/mustache/template.rb

@@ -76,20 +76,8 @@ class Mustache
         ctxtmp = "ctx#{tmpid}"
         res << ev(<<-compiled)
         if v = ctx[#{name}]
-          v = [v] if v.is_a?(Hash) # shortcut when passed a single hash
-          if v.respond_to?(:each)
-            #{ctxtmp} = ctx.dup
-            begin
-              r = v.map { |h| ctx.update(h); #{code} }.join
-            rescue TypeError => e
-              raise TypeError,
-                "All elements in {{#{name.to_s[1..-1]}}} are not hashes!"
-            end
-            ctx.replace(#{ctxtmp})
-            r
-          else
-            #{code}
-          end
+          v = [v] unless v.is_a?(Array) # shortcut when passed non-array
+          v.map { |h| ctx.push(h); c = #{code}; ctx.pop; c }.join
         end
         compiled
         # $' = The string to the right of the last successful match
@@ -106,7 +94,7 @@ class Mustache
     # 4. Partial tags - {{> partial_name }}
     def compile_tags(src)
       res = ""
-      while src =~ /#{otag}(#|=|!|<|>|\{)?(.+?)\1?#{ctag}+/
+      while src =~ /#{otag}(#|=|!|<|>|\{)?(.+?)\1?#{ctag}+/m
         res << str($`)
         case $1
         when '#'

data/lib/mustache/version.rb

@@ -1,3 +1,3 @@
 class Mustache
-  Version = '0.5.0'
+  Version = '0.6.0'
 end