From 7e652956f58f7ba3aef009e582f0f36d29fcc665 Mon Sep 17 00:00:00 2001 From: Tyler Kellen Date: Thu, 18 Oct 2012 18:02:45 -0500 Subject: [PATCH] rough in .4 --- .jshintrc | 14 ++ CONTRIBUTING.md | 73 ++++++++++ grunt.js => Gruntfile.js | 37 ++--- README.md | 211 +++++++++++++++++----------- docs/examples.md | 0 docs/jst-examples.md | 16 +++ docs/{options.md => jst-options.md} | 34 ++--- docs/jst-overview.md | 16 +++ docs/overview.md | 1 - package.json | 6 +- tasks/jst.js | 30 ++-- 11 files changed, 292 insertions(+), 146 deletions(-) create mode 100644 .jshintrc create mode 100644 CONTRIBUTING.md rename grunt.js => Gruntfile.js (67%) delete mode 100644 docs/examples.md create mode 100644 docs/jst-examples.md rename docs/{options.md => jst-options.md} (72%) create mode 100644 docs/jst-overview.md delete mode 100644 docs/overview.md diff --git a/.jshintrc b/.jshintrc new file mode 100644 index 0000000..e0cc7bb --- /dev/null +++ b/.jshintrc @@ -0,0 +1,14 @@ +{ + "curly": true, + "eqeqeq": true, + "immed": true, + "latedef": true, + "newcap": true, + "noarg": true, + "sub": true, + "undef": true, + "boss": true, + "eqnull": true, + "node": true, + "es5": true +} \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..43313a7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +[Grunt homepage](http://gruntjs.com/) | [Documentation table of contents](https://github.com/gruntjs/grunt/blob/devel/docs/toc.md) + +# Contributing to grunt + +There are a number of grunt projects. + +* [grunt](https://github.com/gruntjs/grunt) - the main grunt project +* [gruntjs.com](https://github.com/gruntjs/gruntjs.com) - the gruntjs.com website +* [grunt-contrib collection](https://github.com/gruntjs/grunt-contrib) - a collection of all grunt "contrib" plugins + +In addition, each individual grunt-contrib plugin is a separate repository listed on the [gruntjs org homepage](https://github.com/gruntjs). + +## Filing issues +If something isn't working like you think it should, please read the documentation first. If you'd like to chat with someone, [pop into IRC](#discussing-grunt) and ask your question there. + +The best way to ensure an issue gets addressed is to file it in the appropriate issues tracker. + +**If there's an issue with a specific grunt-contrib plugin:** +Please file an issue on that plugin's issues tracker. + +**If you'd like to contribute a new plugin:** +Please file an issue on the [grunt-contrib collection issues tracker](https://github.com/gruntjs/grunt-contrib/issues). We don't accept all plugins, but we'll certainly consider yours. + +**If there's an issue with the [website](http://gruntjs.com/):** +Please file an issue on the [gruntjs.com website issues tracker](https://github.com/gruntjs/gruntjs.com/issues). + +**If there's an issue that isn't specific to any of the above:** +Please file an issue on the [grunt issues tracker](https://github.com/gruntjs/grunt/issues). + +### Simplify the issue +Try to [reduce your code](http://www.webkit.org/quality/reduction.html) to the bare minimum required to reproduce the issue. This makes it much easier (and much faster) to isolate and fix the issue. + +### Explain the issue +If we can't reproduce the issue, we can't fix it. Please list the exact steps required to reproduce the issue. Include versions of your OS, Node.js, grunt, etc. Include relevant logs or sample code. + +## Discussing grunt +Join the [freenode](http://freenode.net/) IRC #grunt channel. We've got a bot and everything. + +_No private messages, please._ + +## Modifying grunt +First, ensure that you have the latest [Node.js](http://nodejs.org/) and [npm](http://npmjs.org/) installed. + +1. Fork and clone the repo. +1. Check out the correct branch. Currently, grunt development happens in the `devel` branch. +1. Run `npm install` to install all grunt dependencies. +1. Run `npm link` to put the dev version of grunt in the system path (this is only needed for developing grunt, not for plugins or the website). +1. Run `grunt` to grunt grunt. + +Assuming that you don't see any red, you're ready to go. Just be sure to run `grunt` after making any changes, to ensure that nothing breaks. + +### Submitting pull requests + +1. Create a new branch, please don't work in your `master` or `devel` branch directly. +1. Add failing tests for the change you want to make. Run `grunt` to see the tests fail. +1. Fix stuff. +1. Run `grunt` to see if the tests pass. Repeat steps 2-4 until done. +1. Update the documentation to reflect any changes. +1. Push to your fork and submit a pull request. + +### Syntax + +* Two space indents. Don't use tabs anywhere. Use `\t` if you need a tab character in a string. +* No trailing whitespace, except in markdown files where a linebreak must be forced. +* Don't go overboard with the whitespace. +* No more than [one assignment](http://benalman.com/news/2012/05/multiple-var-statements-javascript/) per `var` statement. +* Delimit strings with single-quotes `'`, not double-quotes `"`. +* Prefer `if` and `else` to ["clever"](http://programmers.stackexchange.com/a/25281) uses of `? :` conditional or `||`, `&&` logical operators. +* Comments are great. Just put them _before_ the line of code, _not_ at the _end_ of the line. +* **When in doubt, follow the conventions you see used in the source already.** + +### Reverting back to the "official" grunt +If you've used `npm link` to put a dev version of grunt in the system path and, for some reason, need to revert back to the current official grunt release, just reinstall grunt globally with `npm install -g grunt` diff --git a/grunt.js b/Gruntfile.js similarity index 67% rename from grunt.js rename to Gruntfile.js index faad08a..2dce6de 100644 --- a/grunt.js +++ b/Gruntfile.js @@ -6,29 +6,20 @@ * Licensed under the MIT license. */ +'use strict'; + module.exports = function(grunt) { - 'use strict'; // Project configuration. grunt.initConfig({ - lint: { - all: ['grunt.js', 'tasks/*.js', ''] - }, - jshint: { + all: [ + 'Gruntfile.js', + 'tasks/*.js', + '<%= nodeunit.tests %>' + ], options: { - curly: true, - eqeqeq: true, - immed: true, - latedef: true, - newcap: true, - noarg: true, - sub: true, - undef: true, - boss: true, - eqnull: true, - node: true, - es5: true + jshintrc: '.jshintrc' } }, @@ -76,14 +67,16 @@ module.exports = function(grunt) { // Actually load this plugin's task(s). grunt.loadTasks('tasks'); - // The clean plugin helps in testing. - grunt.loadNpmTasks('grunt-contrib-clean'); + // These plugins provide necessary tasks. + grunt.loadNpmTasks('grunt-contrib-jshint'); + grunt.loadNpmTasks('grunt-contrib-nodeunit'); + grunt.loadNpmTasks('grunt-contrib-internal'); // Whenever the "test" task is run, first clean the "tmp" dir, then run this // plugin's task(s), then test the result. - grunt.renameTask('test', 'nodeunit'); - grunt.registerTask('test', 'clean jst nodeunit'); + grunt.registerTask('test', ['nodeunit']); // By default, lint and run all tests. - grunt.registerTask('default', 'lint test'); + grunt.registerTask('default', ['jst', 'test', 'build-contrib']); + }; \ No newline at end of file diff --git a/README.md b/README.md index b4a86d4..7b3e72d 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,126 @@ -# grunt-contrib-jst [![Build Status](https://secure.travis-ci.org/gruntjs/grunt-contrib-jst.png?branch=master)](http://travis-ci.org/gruntjs/grunt-contrib-jst) - -> Compile underscore templates to JST file. - -## Getting Started -Install this grunt plugin next to your project's [grunt.js gruntfile][getting_started] with: `npm install grunt-contrib-jst` - -Then add this line to your project's `grunt.js` gruntfile: - -```javascript -grunt.loadNpmTasks('grunt-contrib-jst'); -``` - -[grunt]: https://github.com/gruntjs/grunt -[getting_started]: https://github.com/gruntjs/grunt/blob/master/docs/getting_started.md - -### Overview - -This task compiles Underscore compatible templates into functions that can be concatenated and minified with existing source files. - -Inside your `grunt.js` file, add a section named `jst`. This section specifies the files to compile and the options passed to [underscore.template](http://underscorejs.org/#template). - -#### Parameters - -##### files ```object``` - -This defines what files this task will process and should contain key:value pairs. - -The key (destination) should be an unique filepath (supports [grunt.template](https://github.com/gruntjs/grunt/blob/master/docs/api_template.md)) and the value (source) should be a filepath or an array of filepaths (supports [minimatch](https://github.com/isaacs/minimatch)). - -Note: Values are precompiled to the namespaced JST array in the order passed. - -##### options ```object``` - -This controls how this task (and its helpers) operate and should contain key:value pairs, see options below. - -#### Options - -##### namespace ```string``` - -The namespace in which the precompiled templates will be asssigned (default is JST). *Use dot notation (e.g. App.Templates) for nested namespaces.* - -Example: -``` javascript -options: { - namespace: 'JST' -} -``` - -##### processName ```function``` - -This option accepts a function which takes one argument (the template filepath) and returns a string which will be used as the key for the precompiled template object. The example below stores all templates on the default JST namespace in capital letters. - -``` javascript -options: { - processName: function(filename) { - return filename.toUpperCase(); - } -} -``` - -##### templateSettings ```object``` - -The settings passed to underscore when compiling templates. - -#### Config Examples - -``` javascript -jst: { - compile: { - options: { - templateSettings: { - interpolate : /\{\{(.+?)\}\}/g - } - }, - files: { - "path/to/compiled/templates.js": ["path/to/source/**/*.html"] - } - } -} -``` - --- - -*Task submitted by [Tim Branyen](http://github.com/tbranyen).* \ No newline at end of file +# grunt-contrib-jst [![Build Status](https://secure.travis-ci.org/gruntjs/grunt-contrib-jst.png?branch=master)](http://travis-ci.org/gruntjs/grunt-contrib-jst) + +> Precompile Underscore templates to JST file. + +_Note that this plugin has not yet been released, and only works with the latest bleeding-edge, in-development version of grunt. See the [When will I be able to use in-development feature 'X'?](https://github.com/gruntjs/grunt/blob/devel/docs/faq.md#when-will-i-be-able-to-use-in-development-feature-x) FAQ entry for more information._ + +## Getting Started +_If you haven't used [grunt][] before, be sure to check out the [Getting Started][] guide._ + +From the same directory as your project's [Gruntfile][Getting Started] and [package.json][], install this plugin with the following command: + +```bash +npm install grunt-contrib-jst --save-dev +``` + +Once that's done, add this line to your project's Gruntfile: + +```js +grunt.loadNpmTasks('grunt-contrib-jst'); +``` + +If the plugin has been installed correctly, running `grunt --help` at the command line should list the newly-installed plugin's task or tasks. In addition, the plugin should be listed in package.json as a `devDependency`, which ensures that it will be installed whenever the `npm install` command is run. + +[grunt]: http://gruntjs.com/ +[Getting Started]: https://github.com/gruntjs/grunt/blob/devel/docs/getting_started.md +[package.json]: https://npmjs.org/doc/json.html + + +## The jst task + +### Overview + +In your project's Gruntfile, add a section named `jst` to the data object passed into `grunt.initConfig()`. + +```js +grunt.initConfig({ + jst: { + options: { + // Task-specific options go here. + }, + your_target: { + // Target-specific file lists and/or options go here. + }, + }, +}) +``` +### Options + +#### files +Type: `Object` + +This defines what files this task will process and should contain key:value pairs. + +The key (destination) should be an unique filepath (supports [grunt.template](https://github.com/gruntjs/grunt/blob/master/docs/api_template.md)) and the value (source) should be a filepath or an array of filepaths (supports [minimatch](https://github.com/isaacs/minimatch)). + +Note: Values are precompiled to the namespaced JST array in the order passed. + +#### options.namespace +Type: `String` +Default: 'JST' + +The namespace in which the precompiled templates will be asssigned. *Use dot notation (e.g. App.Templates) for nested namespaces.* + +#### options.processName +Type: ```function``` +Default: null + +This option accepts a function which takes one argument (the template filepath) and returns a string which will be used as the key for the precompiled template object. The example below stores all templates on the default JST namespace in capital letters. + +```js +options: { + processName: function(filename) { + return filename.toUpperCase(); + } +} +``` + +#### options.templateSettings +Type: ```Object``` +Default: null + +The settings passed to underscore when compiling templates. + +```js +jst: { + compile: { + options: { + templateSettings: { + interpolate : /\{\{(.+?)\}\}/g + } + }, + files: { + "path/to/compiled/templates.js": ["path/to/source/**/*.html"] + } + } +} +``` +### Examples + +```js +jst: { + compile: { + options: { + templateSettings: { + interpolate : /\{\{(.+?)\}\}/g + } + }, + files: { + "path/to/compiled/templates.js": ["path/to/source/**/*.html"] + } + } +} +``` + +## Release History + + * 2012-10-11 - v0.3.1 - Rename grunt-contrib-lib dep to grunt-lib-contrib. + * 2012-08-22 - v0.3.0 - Options no longer accepted from global config key. + * 2012-08-15 - v0.2.3 - Support for nested namespaces. + * 2012-08-11 - v0.2.2 - Added processName functionality & escaping single quotes in filenames. + * 2012-08-09 - v0.2.0 - Refactored from grunt-contrib into individual repo. + +-- +Task submitted by Tim Branyen. + +*Generated on Thu Oct 18 2012 18:02:35.* diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/jst-examples.md b/docs/jst-examples.md new file mode 100644 index 0000000..e801787 --- /dev/null +++ b/docs/jst-examples.md @@ -0,0 +1,16 @@ +# Examples + +```js +jst: { + compile: { + options: { + templateSettings: { + interpolate : /\{\{(.+?)\}\}/g + } + }, + files: { + "path/to/compiled/templates.js": ["path/to/source/**/*.html"] + } + } +} +``` \ No newline at end of file diff --git a/docs/options.md b/docs/jst-options.md similarity index 72% rename from docs/options.md rename to docs/jst-options.md index 6d0e500..31be7f8 100644 --- a/docs/options.md +++ b/docs/jst-options.md @@ -1,4 +1,7 @@ -##### files ```object``` +# Options + +## files +Type: `Object` This defines what files this task will process and should contain key:value pairs. @@ -6,24 +9,15 @@ The key (destination) should be an unique filepath (supports [grunt.template](ht Note: Values are precompiled to the namespaced JST array in the order passed. -##### options ```object``` - -This controls how this task (and its helpers) operate and should contain key:value pairs, see options below. - -#### Options - -##### namespace ```string``` - -The namespace in which the precompiled templates will be asssigned (default is JST). *Use dot notation (e.g. App.Templates) for nested namespaces.* +## options.namespace +Type: `String` +Default: 'JST' -Example: -```js -options: { - namespace: 'JST' -} -``` +The namespace in which the precompiled templates will be asssigned. *Use dot notation (e.g. App.Templates) for nested namespaces.* -##### processName ```function``` +## options.processName +Type: ```function``` +Default: null This option accepts a function which takes one argument (the template filepath) and returns a string which will be used as the key for the precompiled template object. The example below stores all templates on the default JST namespace in capital letters. @@ -35,12 +29,12 @@ options: { } ``` -##### templateSettings ```object``` +## options.templateSettings +Type: ```Object``` +Default: null The settings passed to underscore when compiling templates. -#### Config Examples - ```js jst: { compile: { diff --git a/docs/jst-overview.md b/docs/jst-overview.md new file mode 100644 index 0000000..8cd93e7 --- /dev/null +++ b/docs/jst-overview.md @@ -0,0 +1,16 @@ +# Overview + +In your project's Gruntfile, add a section named `jst` to the data object passed into `grunt.initConfig()`. + +```js +grunt.initConfig({ + jst: { + options: { + // Task-specific options go here. + }, + your_target: { + // Target-specific file lists and/or options go here. + }, + }, +}) +``` \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md deleted file mode 100644 index ab5cdc1..0000000 --- a/docs/overview.md +++ /dev/null @@ -1 +0,0 @@ -This task compiles Underscore compatible templates into functions that can be concatenated and minified with existing source files. \ No newline at end of file diff --git a/package.json b/package.json index 040d7ad..c9ae174 100644 --- a/package.json +++ b/package.json @@ -32,8 +32,10 @@ "grunt-lib-contrib": "~0.3.0" }, "devDependencies": { - "grunt": "~0.3.15", - "grunt-contrib-clean": "~0.3.0" + "grunt-contrib-jshint": "0.1.0", + "grunt-contrib-nodeunit": "0.1.0", + "grunt-contrib-internal": "*", + "grunt": "~0.4.0a" }, "keywords": [ "gruntplugin" diff --git a/tasks/jst.js b/tasks/jst.js index c755604..a613899 100644 --- a/tasks/jst.js +++ b/tasks/jst.js @@ -6,27 +6,27 @@ * Licensed under the MIT license. */ +'use strict'; + module.exports = function(grunt) { - "use strict"; - var _ = require("underscore"); - var helpers = require('grunt-lib-contrib').init(grunt); + var _ = require('underscore'); // filename conversion for templates var defaultProcessName = function(name) { return name; }; - grunt.registerMultiTask("jst", "Compile underscore templates to JST file", function() { + grunt.registerMultiTask('jst', 'Compile underscore templates to JST file', function() { - var helpers = require("grunt-lib-contrib").init(grunt); - var options = helpers.options(this, {namespace: "JST", templateSettings: {}}); + var helpers = require('grunt-lib-contrib').init(grunt); + var options = this.options({ + namespace: 'JST', + templateSettings: {} + }); // assign filename transformation functions var processName = options.processName || defaultProcessName; - grunt.verbose.writeflags(options, "Options"); - - // TODO: ditch this when grunt v0.4 is released - this.files = this.files || helpers.normalizeMultiTaskFiles(this.data, this.target); + grunt.verbose.writeflags(options, 'Options'); var compiled, srcFiles, src, filename; var output = []; @@ -41,21 +41,19 @@ module.exports = function(grunt) { compiled = _.template(src, false, options.templateSettings).source; } catch (e) { grunt.log.error(e); - grunt.fail.warn("JST failed to compile."); + grunt.fail.warn('JST failed to compile.'); } filename = processName(file); - output.push(nsInfo.namespace+"["+JSON.stringify(filename)+"] = "+compiled+";"); + output.push(nsInfo.namespace+'['+JSON.stringify(filename)+'] = '+compiled+';'); }); if(output.length > 0) { output.unshift(nsInfo.declaration); - grunt.file.write(files.dest, output.join("\n\n")); - grunt.log.writeln("File '" + files.dest + "' created."); + grunt.file.write(files.dest, output.join('\n\n')); + grunt.log.writeln('File "' + files.dest + '" created.'); } }); - }); - };