mustache 0.5.1 → 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:
-
-    <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 }}
+For a language-agnostic overview of Mustache's template syntax, see
+the `mustache(5)` manpage or
+<http://defunkt.github.com/mustache/mustache.5.html>.
 
-    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,87 +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}}
-
-    $ mustache < complete.mustache
-    Hi chris!
-    Hi mark!
-    Hi scott!
-
-You can include multiple documents in your YAML frontmatter if you
-like. Then the template is evaluated once for each of them.
-
-    $ cat multiple.mustache
-    ---
-    name: chris
-    ---
-    name: mark
-    ---
-    name: scott
-    ---
-    Hi {{name}!
-    
-    $ mustache < multiple.mustache
-    Hi chris!
-    Hi mark!
-    Hi scott!
-
-It's probably more useful to keep the YAML and HTML in separate files,
-though. `cat` makes this easy:
-
-    $ 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
 
@@ -505,7 +341,6 @@ Installation
 
     $ rip install git://github.com/defunkt/mustache.git
 
-
 Acknowledgements
 ----------------
 
@@ -517,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,12 +3,12 @@
 require 'mustache'
 require 'yaml'
 
-if STDIN.stat.size > 0
-  doc = STDIN.read
+if !$stdin.tty?
+  doc = $stdin.read
   if doc =~ /^(\s*---(.*)---\s*)/m
     yaml = $2.strip
     template = doc.sub($1, '')
-    
+
     YAML.each_document(yaml) do |data|
       puts Mustache.render(template, data)
     end
@@ -19,31 +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.
-
-You can include multiple documents in your YAML frontmatter if you
-like. Then the template is evaluated once for each of them.
-
-    ---
-    name: chris
-    ---
-    name: mark
-    ---
-    name: scott
-    ---
+See mustache(1) or http://defunkt.github.com/mustache/mustache.1.html
+for an overview.
 usage
 end