diff --git a/.gitignore b/.gitignore index bd08399..9000776 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ .DS_Store .rvmrc +node_modules runner.js jquery.mustache.js qooxdoo.mustache.js diff --git a/.jshintrc b/.jshintrc new file mode 100644 index 0000000..28dff71 --- /dev/null +++ b/.jshintrc @@ -0,0 +1,5 @@ +{ + "eqnull": true, + "evil": true +} + diff --git a/.travis.yml b/.travis.yml index b52599e..3d839b0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,4 @@ -rvm: - - 1.9.2 -before_script: - - sudo apt-get -y install xulrunner-2.0 - - gem install rspec +language: node_js +node_js: + - 0.6 + diff --git a/CHANGES b/CHANGES new file mode 100644 index 0000000..436f791 --- /dev/null +++ b/CHANGES @@ -0,0 +1,27 @@ += HEAD / 22 Sep 2012 + + * Cache partials by template, not by name. Fixes #257. + * Added Mustache.compileTokens to compile the output of Mustache.parse. Fixes + #258. + += 0.7.0 / 10 Sep 2012 + + * Rename Renderer => Writer. + * Allow partials to be loaded dynamically using a callback (thanks @TiddoLangerak + for the suggestion). + * Fixed a bug with higher-order sections that prevented them from being + passed the raw text of the section from the original template. + * More concise token format. Tokens also include start/end indices in the + original template. + * High-level API is consistent with the Writer API. + * Allow partials to be passed to the pre-compiled function (thanks @fallenice). + * Don't use eval (thanks @cweider). + += 0.6.0 / 31 Aug 2012 + + * Use JavaScript's definition of falsy when determining whether to render an + inverted section or not. Issue #186. + * Use Mustache.escape to escape values inside {{}}. This function may be + reassigned to alter the default escaping behavior. Issue #244. + * Fixed a bug that clashed with QUnit (thanks @kannix). + * Added volo support (thanks @guybedford). diff --git a/LICENSE b/LICENSE index 395e263..6626848 100644 --- a/LICENSE +++ b/LICENSE @@ -3,21 +3,8 @@ The MIT License Copyright (c) 2009 Chris Wanstrath (Ruby) Copyright (c) 2010 Jan Lehnardt (JavaScript) -Permission is hereby granted, free of charge, to any person obtaining -a copy of this software and associated documentation files (the -"Software"), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Software, and to -permit persons to whom the Software is furnished to do so, subject to -the following conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index a04f667..75c45b1 100644 --- a/README.md +++ b/README.md @@ -2,31 +2,23 @@ > What could be more logical awesome than no logic at all? -[mustache.js](http://github.com/janl/mustache.js) is an implementation of the -[Mustache](http://mustache.github.com/) template system in JavaScript. +[mustache.js](http://github.com/janl/mustache.js) is an implementation of the [mustache](http://mustache.github.com/) template system in JavaScript. -[Mustache](http://mustache.github.com/) is a logic-less template syntax. It can -be used for HTML, config files, source code - anything. It works by expanding -tags in a template using values provided in a hash or object. +[Mustache](http://mustache.github.com/) is a logic-less template syntax. It can be used for HTML, config files, source code - anything. It works by expanding tags in a template using values provided in a hash or object. -We call it "logic-less" because there are no if statements, else clauses, or for -loops. Instead there are only tags. Some tags are replaced with a value, some -nothing, and others a series of values. +We call it "logic-less" because there are no if statements, else clauses, or for loops. Instead there are only tags. Some tags are replaced with a value, some nothing, and others a series of values. -For a language-agnostic overview of Mustache's template syntax, see the -`mustache(5)` [manpage](http://mustache.github.com/mustache.5.html). +For a language-agnostic overview of mustache's template syntax, see the `mustache(5)` [manpage](http://mustache.github.com/mustache.5.html). ## Where to use mustache.js? -You can use mustache.js to render templates in many various scenarios where you -can use JavaScript. For example, you can render templates in a browser, -server-side using [node](http://nodejs.org/), in [CouchDB](http://couchdb.apache.org/) -views, or in almost any other environment where you can use JavaScript. +You can use mustache.js to render mustache templates anywhere you can use JavaScript. This includes web browsers, server-side environments such as [node](http://nodejs.org/), and [CouchDB](http://couchdb.apache.org/) views. + +mustache.js ships with support for both the [CommonJS](http://www.commonjs.org/) module API and the [Asynchronous Module Definition](https://github.com/amdjs/amdjs-api/wiki/AMD) API, or AMD. ## Who uses mustache.js? -An updated list of mustache.js users is kept [on the Github wiki](http://wiki.github.com/janl/mustache.js/beard-competition). -Add yourself or your company if you use mustache.js! +An updated list of mustache.js users is kept [on the Github wiki](http://wiki.github.com/janl/mustache.js/beard-competition). Add yourself or your company if you use mustache.js! ## Usage @@ -41,36 +33,26 @@ Below is quick example how to use mustache.js: var output = Mustache.render("{{title}} spends {{calc}}", view); -In this example, the `Mustache.render` function takes two parameters: 1) the -[mustache](http://mustache.github.com/) template and 2) a `view` object that -contains the data and code needed to render the template. - -### CommonJS - -mustache.js is usable without any modification in both browsers and [CommonJS](http://www.commonjs.org/) -environments like [node.js](http://nodejs.org/). To use it as a CommonJS module, -simply require the file, like this: - - var Mustache = require("mustache"); +In this example, the `Mustache.render` function takes two parameters: 1) the [mustache](http://mustache.github.com/) template and 2) a `view` object that contains the data and code needed to render the template. ## Templates -A [mustache](http://mustache.github.com/) template is a string that contains -any number of mustache tags. Tags are indicated by the double mustaches that -surround them. `{{person}}` is a tag, as is `{{#person}}`. In both examples we -refer to `person` as the tag's key. +A [mustache](http://mustache.github.com/) template is a string that contains any number of mustache tags. Tags are indicated by the double mustaches that surround them. `{{person}}` is a tag, as is `{{#person}}`. In both examples we refer to `person` as the tag's key. There are several types of tags available in mustache.js. ### Variables -The most basic tag type is a simple variable. A `{{name}}` tag renders the value -of the `name` key in the current context. If there is no such key, nothing is -rendered. +The most basic tag type is a simple variable. A `{{name}}` tag renders the value of the `name` key in the current context. If there is no such key, nothing is rendered. + +All variables are HTML-escaped by default. If you want to render unescaped HTML, use the triple mustache: `{{{name}}}`. You can also use `&` to unescape a variable. + +View: -All variables are HTML-escaped by default. If you want to render unescaped HTML, -use the triple mustache: `{{{name}}}`. You can also use `&` to unescape a -variable. + { + "name": "Chris", + "company": "GitHub" + } Template: @@ -80,13 +62,6 @@ Template: * {{{company}}} * {{&company}} -View: - - { - "name": "Chris", - "company": "GitHub" - } - Output: * Chris @@ -95,13 +70,7 @@ Output: * GitHub * GitHub -JavaScript's dot notation may be used to access keys that are properties of -objects in a view. - -Template: - - * {{name.first}} {{name.last}} - * {{age}} +JavaScript's dot notation may be used to access keys that are properties of objects in a view. View: @@ -113,6 +82,11 @@ View: "age": "RIP" } +Template: + + * {{name.first}} {{name.last}} + * {{age}} + Output: * Michael Jackson @@ -120,19 +94,21 @@ Output: ### Sections -Sections render blocks of text one or more times, depending on the value of the -key in the current context. +Sections render blocks of text one or more times, depending on the value of the key in the current context. -A section begins with a pound and ends with a slash. That is, `{{#person}}` -begins a `person` section, while `{{/person}}` ends it. The text between the two -tags is referred to as that section's "block". +A section begins with a pound and ends with a slash. That is, `{{#person}}` begins a `person` section, while `{{/person}}` ends it. The text between the two tags is referred to as that section's "block". The behavior of the section is determined by the value of the key. #### False Values or Empty Lists -If the `person` key exists and has a value of `null`, `undefined`, or `false`, -or is an empty list, the block will not be rendered. +If the `person` key does not exist, or exists and has a value of `null`, `undefined`, or `false`, or is an empty list, the block will not be rendered. + +View: + + { + "person": false + } Template: @@ -141,30 +117,15 @@ Template: Never shown! {{/person}} -View: - - { - "person": true - } - Output: Shown. #### Non-Empty Lists -If the `person` key exists and is not `null`, `undefined`, or `false`, and is -not an empty list the block will be rendered one or more times. - -When the value is a list, the block is rendered once for each item in the list. -The context of the block is set to the current item in the list for each -iteration. In this way we can loop over collections. - -Template: +If the `person` key exists and is not `null`, `undefined`, or `false`, and is not an empty list the block will be rendered one or more times. - {{#stooges}} - {{name}} - {{/stooges}} +When the value is a list, the block is rendered once for each item in the list. The context of the block is set to the current item in the list for each iteration. In this way we can loop over collections. View: @@ -176,20 +137,19 @@ View: ] } +Template: + + {{#stooges}} + {{name}} + {{/stooges}} + Output: Moe Larry Curly -When looping over an array of strings, a `.` can be used to refer to the current -item in the list. - -Template: - - {{#musketeers}} - * {{.}} - {{/musketeers}} +When looping over an array of strings, a `.` can be used to refer to the current item in the list. View: @@ -197,6 +157,12 @@ View: "musketeers": ["Athos", "Aramis", "Porthos", "D'Artagnan"] } +Template: + + {{#musketeers}} + * {{.}} + {{/musketeers}} + Output: * Athos @@ -204,14 +170,7 @@ Output: * Porthos * D'Artagnan -If the value of a section variable is a function, it will be called in the -context of the current item in the list on each iteration. - -Template: - - {{#beatles}} - * {{name}} - {{/beatles}} +If the value of a section variable is a function, it will be called in the context of the current item in the list on each iteration. View: @@ -227,6 +186,12 @@ View: } } +Template: + + {{#beatles}} + * {{name}} + {{/beatles}} + Output: * John Lennon @@ -236,14 +201,7 @@ Output: #### Functions -If the value of a section key is a function, it is called with the section's -literal block of text, un-rendered, as its first argument. The second argument -is a special rendering function that uses the current view as its view argument. -It is called in the context of the current view object. - -Template: - - {{#bold}}Hi {{name}}.{{/bold}} +If the value of a section key is a function, it is called with the section's literal block of text, un-rendered, as its first argument. The second argument is a special rendering function that uses the current view as its view argument. It is called in the context of the current view object. View: @@ -256,20 +214,17 @@ View: } } +Template: + + {{#bold}}Hi {{name}}.{{/bold}} + Output: Hi Tater. ### Inverted Sections -An inverted section opens with `{{^section}}` instead of `{{#section}}`. The -block of an inverted section is rendered only if the value of that section's tag -is `null`, `undefined`, `false`, or an empty list. - -Template: - - {{#repos}}{{name}}{{/repos}} - {{^repos}}No repos :({{/repos}} +An inverted section opens with `{{^section}}` instead of `{{#section}}`. The block of an inverted section is rendered only if the value of that section's tag is `null`, `undefined`, `false`, or an empty list. View: @@ -277,6 +232,11 @@ View: "repos": [] } +Template: + + {{#repos}}{{name}}{{/repos}} + {{^repos}}No repos :({{/repos}} + Output: No repos :( @@ -297,8 +257,7 @@ Comments may contain newlines. Partials begin with a greater than sign, like {{> box}}. -Partials are rendered at runtime (as opposed to compile time), so recursive -partials are possible. Just avoid infinite loops. +Partials are rendered at runtime (as opposed to compile time), so recursive partials are possible. Just avoid infinite loops. They also inherit the calling context. Whereas in ERB you may have this: @@ -308,9 +267,7 @@ Mustache requires only this: {{> next_more}} -Why? Because the `next_more.mustache` file will inherit the `size` and `start` -variables from the calling context. In this way you may want to think of -partials as includes, or template expansion, even though it's not literally true. +Why? Because the `next_more.mustache` file will inherit the `size` and `start` variables from the calling context. In this way you may want to think of partials as includes, or template expansion, even though it's not literally true. For example, this template and partial: @@ -330,14 +287,11 @@ Can be thought of as a single, expanded template: {{name}} {{/names}} -In mustache.js an object of partials may be passed as the third argument to -`Mustache.render`. The object should be keyed by the name of the partial, and -its value should be the partial text. +In mustache.js an object of partials may be passed as the third argument to `Mustache.render`. The object should be keyed by the name of the partial, and its value should be the partial text. ### Set Delimiter -Set Delimiter tags start with an equals sign and change the tag delimiters from -`{{` and `}}` to custom strings. +Set Delimiter tags start with an equals sign and change the tag delimiters from `{{` and `}}` to custom strings. Consider the following contrived example: @@ -347,55 +301,57 @@ Consider the following contrived example: <%={{ }}=%> * {{ 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. +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. -According to [ctemplates](http://google-ctemplate.googlecode.com/svn/trunk/doc/howto.html), -this "is useful for languages like TeX, where double-braces may occur in the -text and are awkward to use for markup." +According to [ctemplates](http://google-ctemplate.googlecode.com/svn/trunk/doc/howto.html), this "is useful for languages like TeX, where double-braces may occur in the text and are awkward to use for markup." Custom delimiters may not contain whitespace or the equals sign. -## Streaming - -To stream template results out of mustache.js, you can pass an optional callback -to the call to `Mustache.render`: - - Mustache.render(template, view, partials, function (chunk) { - print(chunk); - }); - -When the template is finished rendering, the callback will be called with `null` -after which it won't be called anymore for that rendering. - ## Plugins for JavaScript Libraries -By default mustache.js may be used in a browser or any [CommonJS](http://www.commonjs.org/) -environment, including [node](http://nodejs.org/). Additionally, mustache.js may -be built specifically for several different client libraries and platforms, -including the following: +mustache.js may be built specifically for several different client libraries, including the following: - [jQuery](http://jquery.com/) - [MooTools](http://mootools.net/) - [Dojo](http://www.dojotoolkit.org/) - [YUI](http://developer.yahoo.com/yui/) - - [RequireJS](http://requirejs.org/) - [qooxdoo](http://qooxdoo.org/) -These may be built using [Rake](http://rake.rubyforge.org/) and one of the -following commands: +These may be built using [Rake](http://rake.rubyforge.org/) and one of the following commands: $ rake jquery $ rake mootools $ rake dojo $ rake yui - $ rake requirejs $ rake qooxdoo +## Testing + +The mustache.js test suite uses the [vows](http://vowsjs.org/) testing framework. In order to run the tests you'll need to install [node](http://nodejs.org/). Once that's done you can install vows using [npm](http://npmjs.org/). + + $ npm install -g vows + +Then run the tests. + + $ vows --spec + +The test suite consists of both unit and integration tests. If a template isn't rendering correctly for you, you can make a test for it by doing the following: + + 1. Create a template file named `mytest.mustache` in the `test/_files` + directory. Replace `mytest` with the name of your test. + 2. Create a corresponding view file named `mytest.js` in the same directory. + This file should contain a JavaScript object literal enclosed in + parentheses. See any of the other view files for an example. + 3. Create a file with the expected output in `mytest.txt` in the same + directory. + +Then, you can run the test with: + + $ TEST=mytest vows test/render_test.js + ## Thanks -Mustache.js wouldn't kick ass if it weren't for these fine souls: +mustache.js wouldn't kick ass if it weren't for these fine souls: * Chris Wanstrath / defunkt * Alexander Lang / langalex diff --git a/Rakefile b/Rakefile index 61700ee..bc32175 100644 --- a/Rakefile +++ b/Rakefile @@ -1,15 +1,33 @@ require 'rake' require 'rake/clean' -task :default => :spec - -desc "Run all specs" -task :spec do - require 'rspec/core/rake_task' - RSpec::Core::RakeTask.new(:spec) do |t| - #t.spec_opts = ['--options', "\"#{File.dirname(__FILE__)}/spec/spec.opts\""] - t.pattern = 'spec/*_spec.rb' - end +task :default => :test + +ROOT = File.expand_path('..', __FILE__) +MUSTACHE_JS = File.read(File.join(ROOT, 'mustache.js')) + +def mustache_version + match = MUSTACHE_JS.match(/exports\.version = "([^"]+)";/) + match[1] +end + +def minified_file + ENV['FILE'] || 'mustache.min.js' +end + +desc "Run all tests, requires vows (see http://vowsjs.org)" +task :test do + sh "vows --spec" +end + +desc "Minify to #{minified_file}, requires UglifyJS (see http://marijnhaverbeke.nl/uglifyjs)" +task :minify do + sh "uglifyjs mustache.js > #{minified_file}" +end + +desc "Run JSHint, requires jshint (see http://www.jshint.com)" +task :lint do + sh "jshint mustache.js" end # Creates a task that uses the various template wrappers to make a wrapped @@ -47,13 +65,4 @@ templated_build "jQuery" templated_build "MooTools" templated_build "Dojo", :location => "dojox/string" templated_build "YUI3", :location => "yui3/mustache" -templated_build "RequireJS" templated_build "qooxdoo" - -task :minify do - # npm install uglify-js - mmjs = "mustache.min.js" - `echo "/*! Version: 0.5.1-dev */" > #{mmjs}` - `uglifyjs mustache.js >> #{mmjs}` - puts "Created #{mmjs}" -end diff --git a/TESTING.md b/TESTING.md deleted file mode 100644 index 47d15e4..0000000 --- a/TESTING.md +++ /dev/null @@ -1,62 +0,0 @@ -## Running the mustache.js test suite - -The mustache.js test suite uses the [RSpec](http://rspec.info/) testing -framework. In order to run the tests you'll need to install [Ruby](http://ruby-lang.org/) -as well as the `rake`, `rspec` (>=2), and `json` [RubyGems](http://rubygems.org/). - -### How to install Ruby and the required gems from source - -Make sure you have the required tools to compile it: - - $ apt-get install build-essential libssl-dev libreadline5-dev zlib1g-dev - -Download and extract the Ruby source, and install it: - - $ wget ftp://ftp.ruby-lang.org/pub/ruby/stable-snapshot.tar.gz - $ tar xvzf stable-snapshot.tar.gz - $ cd ruby - $ ./configure && make && make install - -Download and extract RubyGems, and install it: - - $ wget http://production.cf.rubygems.org/rubygems/rubygems-1.8.12.tgz - $ tar xzvf rubygems-1.8.12.tgz - $ cd rubygems-1.8.12 - $ ruby setup.rb - -If you want to update RubyGems: - - $ gem update --system - -Install the required gems: - - $ gem install rake rspec json - -That's it! - -### How to run the tests - -The mustache.js test suite currently uses 4 different JavaScript runtime engines -to maximize portability across platforms and browsers. They are: - - * node - * SpiderMonkey (Mozilla, Firefox) - * JavaScriptCore (WebKit, Safari) - * Rhino (Mozilla, Java) - -When the test suite runs it will automatically determine which platforms are -available on your machine and run on all of them. The suite must run on at least -one platform in order to succeed. - -Once you have at least one JavaScript platform installed, you can run the test -suite with the following command: - - $ rake - -### How to create a test - -All test files live in the spec/_files directory. To create a new test: - - * Create a template file called `somename.mustache` - * Create a JavaScript file containing the view called `somename.js` - * Create a text file with the expected result called `somename.txt` diff --git a/mustache.js b/mustache.js index 641cebd..7165a8a 100644 --- a/mustache.js +++ b/mustache.js @@ -2,535 +2,621 @@ * mustache.js - Logic-less {{mustache}} templates with JavaScript * http://github.com/janl/mustache.js */ -var Mustache = (typeof module !== "undefined" && module.exports) || {}; -(function (exports) { - - exports.name = "mustache.js"; - exports.version = "0.5.0-dev"; - exports.tags = ["{{", "}}"]; - exports.parse = parse; - exports.compile = compile; - exports.render = render; - exports.clearCache = clearCache; - - // This is here for backwards compatibility with 0.4.x. - exports.to_html = function (template, view, partials, send) { - var result = render(template, view, partials); - - if (typeof send === "function") { - send(result); - } else { - return result; - } - }; +/*global define: false*/ - var _toString = Object.prototype.toString; - var _isArray = Array.isArray; - var _forEach = Array.prototype.forEach; - var _trim = String.prototype.trim; +var Mustache; - var isArray; - if (_isArray) { - isArray = _isArray; +(function (exports) { + if (typeof module !== "undefined" && module.exports) { + module.exports = exports; // CommonJS + } else if (typeof define === "function") { + define(exports); // AMD } else { - isArray = function (obj) { - return _toString.call(obj) === "[object Array]"; - }; + Mustache = exports; //