Skip to content
A very useful build step; read any number of files, process them as JavaScript templates, and save output to another destination.
JavaScript CSS Shell
Latest commit 7b9b169 Jan 14, 2014 @drkibitz Merge pull request #4 from bitdeli-chef/master
Add a Bitdeli Badge to README
Failed to load latest commit information.
lib removed unused event Feb 16, 2013
test Redo event namespaces, put them into one, removed unused, dead code a… Feb 13, 2013
.gitignore
.npmignore don't want to add jsdoc3 to my path, and got tired of doing this. Feb 13, 2013
LICENSE initial commit May 20, 2012
README.md Add a Bitdeli badge to README Jan 14, 2014
bin.js
gh-pages.sh no more symlink for docs Feb 16, 2013
package.json upped version Feb 16, 2013

README.md

Samson

The elevator pitch:

A very useful build step; read any number of files, process them as JavaScript templates, and save output to another destination.

The more descriptive version:

Process an input directory to an output directory recursively:

samson -i path/to/directory -o path/to/other/directory -R

Samson's functionality can be summarized in 3 steps:

  1. Read any number of files that are of any size
  2. Process the content of files read as doT.js templates
    • Each template's delimiters are defined as comment blocks specific to the processed file's language
    • Although files are processed in chunks, the internal validation queues data until it may be processed correctly
    • If a file's mimeType is not a processable type, then the data is simply piped through without processing
  3. Write the processed or piped data to a new location on the file system

Include samson in your own module:

var samson = require('samson');
samson.run(['source/dir/**/*'], {
    copyUnknown : true,
    outputDir   : 'build/dir',
    recursive   : true
});

doT

Sounds pretty simple right?

The unique part of Samson is in step #2. doT.js is both the fastest, and most open-ended JavaScript template engine I've found to date, and is the engine I believe to be best suited for the task I'm trying to achieve with Samson. If you are familiar with doT, skip to the next section, otherwise now would be a good time to visit http://olado.github.com/doT/

Install

With npm this module prefers global installation:

npm i samson -g

Usage

Settings

One thing doT allows, is defining custom delimiters before compiling a string into a template, and with that I have defined different settings for the most common comment block delimiters.

A quick look at these settings:

  • html
    • tag start <!--{
    • tag end }-->
  • js, css, php
    • tag start /*{
    • tag end }*/
  • txt (the most common and default format)
    • tag start #{
    • tag end }#

A more detailed view of these settings can be found here http://drkibitz.github.com/node-samson/docs/0.3.2/Template.settingsByType.html

Example

Take a look at the following example in my-file.js, that is not processed with Samson:

/* start */
/*{?argv.target !== 'release'}*/
var DEBUG = true;
/*{?}*/
/* end */

Process with Samson as samson my-file.js outputs:

/* start */

var DEBUG = true;

/* end */

Process with Samson as samson my-file.js --target release outputs:

/* start */


/* end */

Template Namespaces and Variables

Notice the argv member accessible in the doT template. This object contains all of the script arguments parsed by the module optimist, and passed directly into the doT template.

Just as within doT, the def object is special. Once a member property is set, it may not be changed. There is one def object defined for each file, and one file's template may not access another file's def.

Additionally but not limited to, enumerables set within def are passed directly to the template's runtime function as arguments. What this means is /*{#def.FILE}*/, may also be accessed as /*{=FILE}*/

For a more detailed view of the defailt members of def, please visit http://drkibitz.github.com/node-samson/docs/0.3.2/ResourceProcessor.def.html

More Usage Examples

Be sure to to look at:

samson
samson -h
samson --help

Process a single file and output to console:

samson path/to/file

Process a single file and output to file system:

samson path/to/file -o path/to/directory

Process multiple files and output to file system:

samson path/to/file1 path/to/file2 path/to/file3 -o path/to/directory

Process single directory recursively and output to file system:

samson path/to/directory -o path/to/directory -R

Process files and directories recursively and output to file system:

samson path/to/dir1 path/to/file path/to/dir2 -o path/to/directory -R

Process matched files recursively and output to file system:

samson -i path/to/* -o path/to/other/directory -R

Bitdeli Badge

Something went wrong with that request. Please try again.