How are you @model.name? Today is a sunny day on the planet Gunsmoke.
\n\n\tI am a @model.t!
');\n\n\tvar out = tpl({ t: 'template' });\n\t//I am a template!
\n\nexpress \n--------------------\n\nCheck out [vash-express-example][] for a full example of hooking up vash as a view engine for express 3. But it's basically as simple as:\n\n\tvar express = require('express');\n\n\tvar app = express();\n\tapp.set('view engine', 'vash');\n\nMore information is also available in the [Layout Helpers][] sections.\n\n[vash-express-example]: https://github.com/kirbysayshi/vash-express-example\n\nBrowser - Vanilla \n-------------------------\n\n\t\n\n\tvar tpl = vash.compile( 'I am a @model.t!
' );\n\tdocument.querySelector('#content').innerHTML = tpl({ t: 'template' });\n\nBut you should probably be precompiling your templates. See [Precompiling Templates][] for more info. Then you can just include the Vash runtime instead of the entire compiler.\n\nBrowser - Browserify et al \n----------------------------------\n\nJust `require` Vash, and compile. If you want something fancier, try [vashify](https://www.npmjs.com/package/vashify)! Then you can directly require any `.vash` file and it will be resolved as compiled template:\n\n\tvar tpl = require('my-awesome-template.vash');\n\tdocument.querySelector('#content').innerHTML = tpl({ t: 'template' });\n\nBrowser - RequireJS \n---------------------------\n\nRequireJS support has been recently dropped. However Vash does support CJS environments, so as long as you configure RequireJS to consume Vash as a CJS project (including `node_modules` resolution), everything should work.\n\nPlayground \n==================\n\nVash now has [a playground][] of sorts at [CodePen.io][]. It uses the current version of `vash.js` from the `build` folder. Fork it to test your own template ideas!\n\n[a playground]: http://codepen.io/kirbysayshi/full/IjrFw\n[CodePen.io]: http://codepen.io\n\nSyntax \n==============\n\nFor the following examples, assume a model is passed into the compiled function. If a model is explicitly defined, it will appear as:\n\n\t// model = { what: 'hello!' }\n\nThe Transition Character: @ \n------------------------------------\n\nVash uses the `@` symbol to transition between code and markup. To escape and print a literal `@`, use a double `@`, like this: `@@`.\n\nExpressions \n-------------------\n\nThe most basic usage of Vash is an implicit expression. Vash is smart enough to know what's valid JS and what's not, and can usually do what you want it to do. An expression is an @ followed by a valid JS identifier. This is then interpolated automatically.\n\ninput:\n\n\t// model = { what: 'hello!' }\n\t@what
\n\noutput:\n\n\thello!
\n\nThe `model` comment is just to show that the object passed into the compiled template contains a key that matches the expression.\n\nTo allow for the fastest render time possible, Vash by default requires the model to be addressed explicitly. This is to avoid using a `with` statment in the compiled template, which is approximately 25 times slower. The above example then becomes:\n\ninput:\n\n\t@model.what
\n\noutput:\n\n\thello!
\n\nAs you can see, the output is exactly the same. The name used to reference the model is configurable via [vash.config.modelName][]. Typical values are `model` and `it`.\n\n\nAdvanced Expressions \n----------------------------\n\nVash typically knows when an expression ends, even when the expression is complex. For example:\n\ninput:\n\n\t@model.what().who[2]('are you sure')('yes, it\\'s ok')( model.complex ? 'FULL POWER' : '' )
\n\nThis will work just fine, assuming you have a model that actually contains that complexity! I hope you don't, and if so, I feel bad.\n\nCallbacks work as well:\n\ninput:\n\n\t// model = ['a', 'b']\n\t@model.forEach(function(item){\n\t\tPlants are @model.description.
\n\noutput:\n\n\tPlants are living.
\n\nAnd empty brackets, because they're not valid JS:\n\ninput:\n\n\t// model = { formName: 'addresses' }\n\t\n\noutput:\n\n\t\n\nEmail addresses, to an extent, are fine as well. Vash makes a trade-off. It uses the following regex to validate an email address:\n\n\t/^([a-zA-Z0-9.%]+@[a-zA-Z0-9.\\-]+\\.(?:ca|co\\.uk|com|edu|net|org))\\b/\n\nEmail addresses can actually contain many more valid characters, and are [really hard to validate][]. Vash can handle a typical email address with ease:\n\ninput:\n\n\tEmail Me\n\noutput:\n\n\tEmail Me\n\nIf you have a complex email address that confuses Vash, then you should use an [explicit expression](#explicit-expressions) instead.\n\n[really hard to validate]: http://www.regular-expressions.info/email.html\n\nExplicit Expressions \n----------------------------\n\nAn explicit expression is simply an expression that, instead of being composed of `@` and a valid JS identifier, is surrounded by parenthesis.\n\ninput:\n\n\t@(model.what)
\n\noutput:\n\n\thello!
\n\nWhy would you ever need this? Perhaps you want to do something like:\n\ninput:\n\n\t// model = { hasIceCream: true }\n\tIce Cream
\n\noutput:\n\n\tIce Cream
\n\nYou could even create an anonymous function.\n\ninput:\n\n\t@(function(type){ return type + ' cream'; }('banana'))\n\noutput:\n\n\tbanana cream\n\nAs you can see, Vash does not require a model to be referenced, or even passed in.\n\nCode Blocks \n-------------------\n\nSometimes, AGAINST ALL ODDS, a template may need some quick computation of values to avoid repeating yourself. Unlike expressions and explicit expressions, a code block does not directly output. To compare to PHP, expressions are like ``, while a code block is like ``.\n\nA code block is simply `@{ }`.\n\ninput:\n\n\t@{ var rideOn = 'shooting star'; }\n\noutput:\n\nThat's right, _nothing_! Here's a better example:\n\ninput:\n\n\t@{\n\t\tvar total = model.price + model.tax;\n\t}\n\n\tYour total is: $@total
\n\noutput:\n\n\tYour total is: $2.70
\n\nAnything is valid within a code block, such as function declarations or even something as complex as defining a prototype. You can also use markup within a code block, and it will behave as expected:\n\ninput:\n\n\t@{This works!
}\n\noutput:\n\n\tThis works!
\n\nA code block just tells Vash, \"expect the next stuff to be code until otherwise\".\n\nKeyword Blocks \n----------------------\n\nVash is aware of keywords, and will open a code block automatically for you.\n\ninput:\n\n\t// model = { type: 'banana' }\n\t@if(model.type){\n\t\tI'm a @model.type!
\n\t} else if(model.name){\n\t\tMy name is @model.name.
\n\t} else {\n\t\tI DON'T KNOW WHO OR WHAT I AM...
\n\t}\n\noutput:\n\n\tI'm a banana!
\n\nThis also works for `while`, `for`, `do`, `try/catch`, `with`, `switch`, `function`, and other keywords.\n\nYou don't even need to worry about whitespace or newlines:\n\ninput:\n\n\t// model = 1\n\t@switch(model){case 1:break;case 2:break;}\n\noutput:\n\n\t\n\nComments \n----------------\n\nVash also supports comments that are not compiled into the template. These are delineated with `@*` and `*@`\n\ninput:\n\n\t@* I am a comment that extends\n\tover multiple lines *@\n\tBANANA!
\n\noutput:\n\n\tBANANA!
\n\nHTML Escaping \n---------------------\n\nBy default, Vash escapes any HTML-like values before outputting them.\n\ninput:\n\n\t// model = { what: '@model.what
\n\noutput:\n\n\t<img />
\n\nIf you are sure that you trust the content and/or need to display HTML-like values, you can escape the HTML escaping via a call to Vash's [helper system][]: `html.raw`.\n\ninput:\n\n\t// model = { what: '@html.raw(model.what)
\n\noutput:\n\n\tMy tpl
', { debug: true });\n\nvash.config.useWith \n---------------------------\n\n\tDefault: false\n\nIf `useWith` is set to `true`, then Vash will wrap a `with` block around the contents of the compiled function.\n\n\t// vash.config.useWith == true\n\t');\n\t\t\thtml.vl = 1, html.vc = 3;\n\t\t\t__vbuffer.push('
');\n\t\t\thtml.vl = 1, html.vc = 7;\n\t\t\t__vbuffer.push('\\n');\n\t\t\t(__vopts && __vopts.onRenderEnd && __vopts.onRenderEnd(null, html));\n\t\t\treturn (__vopts && __vopts.asContext)\n\t\t\t\t? html\n\t\t\t\t: html.toString();\n\t\t} catch( e ){\n\t\t\thtml.reportError( e, html.vl, html.vc, \"!LB!\" );\n\t\t}\n\t}\n\nAnd that same template with `debug` set to `false`:\n\n\tfunction anonymous(model,html,__vopts,vash) {\n\t\tvar __vbuffer = html.buffer;\n\t\thtml.options = __vopts;\n\t\tmodel = model || {};\n\t\t__vbuffer.push('\\n');\n\t\t(__vopts && __vopts.onRenderEnd && __vopts.onRenderEnd(null, html));\n\t\treturn (__vopts && __vopts.asContext)\n\t\t\t? html\n\t\t\t: html.toString();\n\t}\n\nAs you can see, the difference, especially in code size and instruction size is significant. For production apps, templates should be precompiled with `debug` as `false`.\n\nvash.config.debugParser \n-------------------------------\n\n\tDefault: false\n\nVash's parser will output useful debugging infomation if `debugParser` is `true`:\n\n* Tokens and what mode they were processed as\n* A textual representation of the fully parsed AST\n\nvash.config.debugCompiler \n---------------------------------\n\n\tDefault: false\n\nVash's compiler will output useful debugging information if `debugCompiler` is `true`:\n\n* The text content of the template function before it is passed into [vash.link][] for actual evaluation\n* The options passed into the compiler. This is useful for debugging [vash.compileBatch][] and [vash.compileHelper][].\n\nvash.config.simple \n--------------------------\n\n\tDefault: false\n\nIf `true`, the template is compiled in \"fast path\" mode. This disables several advanced features for the sake of speed:\n\n* [onRenderEnd][] callbacks are completely ignored.\n* The [Helper System][] instance normally available within a running template as `html` is no longer an instance of `vash.helpers.constructor`, and thus the entire buffer API and helpers are missing. Instead it is a plain object with the following properties:\n * `buffer`: a plain array\n * `escape`: [vash.helpers.escape][]\n * `raw`: [vash.helpers.raw][]\n* The [asContext][] runtime option is completely ignored.\n* [vash.config.htmlEscape][], [vash.config.useWith][], and [vash.config.debug][] still behave as expected.\n\nWhile standard Vash templates are definitely not slow, using `true` for this option decreases render time by 15% - 25% depending on the size of the template.\n\n[vash-benchgraph](https://github.com/kirbysayshi/vash-benchgraph) can be used to show the speed increase:\n\n\tnode benches.js --tinclude 004.vash,007.vash --vinclude '0.6.2-2482' --chart vashv,ops\n\nvash.config.favorText \n-----------------------------\n\n\tDefault: false\n\nWhen Vash encounters text that directly follows an opening brace of a block, it assumes that unless it encounters an HTML tag, the text is JS code. For example:\n\n\t@it.forEach(function(a){\n\t\tvar b = a; // vash assumes this line is code\n\t})\n\nWhen `favorText` is set to `true`, Vash will instead assume that most things are content (not code) unless it's very explicit.\n\n\t@it.forEach(function(a){\n\t\tvar b = a; // vash.config.favorText assumes this line is content\n\t})\n\nThis option is __EXPERIMENTAL__, and should be treated as such. It allows Vash to be used in a context like [Markdown](http://daringfireball.net/projects/markdown/syntax), where HTML tags, which typically help Vash tell the difference between code and content, are rare.\n\nTemplate Options \n========================\n\nThese options concern rendering a template, after it has already been compiled. For options related to compiling templates, see [Configuration][].\n\nThe compiled templates themselves have three signatures.\n\n\ttpl(model) -> string\n\nThe most basic form accepts a single argument, `model`, that can be any value: Number, Boolean, Object, Array, undefined, null, etc. It returns the rendered template as a string.\n\n\ttpl(model, function(){}) -> string\n\nThe second form accepts a function callback as its second parameter, which is called [onRenderEnd][] (see below).\n\n\ttpl(model, options) -> string\n\nThe third form allows for options in addition to [onRenderEnd][]. There are two options that can affect a template while rendering:\n\nasContext \n-----------------\n\n\ttpl(model, { asContext: true }) -> vash.helpers.constructor\n\nThis option tells the template that instead of returning a string, it should return the \"render context\", otherwise known as an instance of `vash.helpers.constructor` ([Helper System][]).\n\nonRenderEnd \n-------------------\n\n\ttpl(model, { onRenderEnd: function(){} }) -> string\n\nThis option is effectively a callback for once primary execution of the rendering template has finished. The arguments passed to the callback are: `( err, html )`, where `err` is always `null` (for now), and `html` is the render context (instance of `vash.helpers.constructor`). This callback is not required, and is only called if defined (and has no default definition). The [Layout Helpers][] use this to know when all includes, prepends, appends, blocks, and extend calls have finished.\n\n[onRenderEnd][] can also be defined as a property of the model:\n\n\tvar model = { hey: 'what', onRenderEnd: function(err, ctx){ ... } }\n\nHelper System \n===============\n\nVash's primary point of expandability lies in its Helper API. When a template is rendering, there is a free variable avaiable. This variable is, by default, named `html`. This name can be changed with the [vash.config.helpersName][] option. `html` is an instance of the prototype that is attached to `vash.helpers`. It's a bit confusing, but this is how it kind of works:\n\n\tvar Helpers = function(){}\n\tvash.helpers = Helpers.prototype;\n\tvash.helpers.constructor = Helpers;\n\nWhat this means is that any function that is attached to `vash.helpers` is available within a rendering template via `html`. For example:\n\n\t// defined in a JS file or script tag somewhere\n\tvash.helpers.echo = function(arg){ return arg; }\n\ninput:\n\n\t@html.echo('hello!')
\n\noutput:\n\n\thello!
\n\nHere is a simple helper that converts text like \"This is a holdup!\" to \"this-is-a-holdup\":\n\n\tvash.helpers.mdHref = function(text){\n\t\treturn text\n\t\t\t.toLowerCase()\n\t\t\t.replace(/[^a-zA-Z0-9-_]+/g, '-')\n\t\t\t.replace(/^-+|\\n|-+$/g, '');\n\t}\n\nNotice how it's just JavaScript. Within a template, it could be accessed via `html.mdHref(\"This is a holdup!\")`.\n\nBuilt-in Helpers \n========================\n\nvash.helpers.raw \n------------------------\n\nAvailable as `html.raw` within an executing template. By default, all content that passes from a model to a template is HTML encoded. In the event that the text is trusted (or is already encoded), wrap the text in this function. For an example, see [HTML Escaping][];\n\nvash.helpers.escape \n---------------------------\n\nAvailable as `html.escape` within an executing template, this is the method Vash uses to HTML encode model values. It can also be used manually.\n\nvash.helpers.tplcache \n-----------------------------\n\nThe `tplcache` is just that, a place to put a global index of templates. This is used primarily for the more \"view engine\" aspects that Vash provides, as well as a default location for [precompiled templates][--target-namespace] using [vash(1)][].\n\nLayout Helpers \n======================\n\nVash provides a relatively simple but powerful view engine whose API is borrowed directly from [Jade][]. Below is the API, but an example can be found at [vash-express-example][].\n\nCallbacks are used to maintain compatibility with typical JS syntax.\n\nWhen running in [nodejs][] and using [express][], Vash will automatically resolve and load templates using the same conventions as express itself, specifically [app.engine][]. When in the browser, Vash uses the same rules, but looks in [vash.helpers.tplcache][] instead.\n\n[nodejs]: http://nodejs.org\n[express]: http://expressjs.com\n[app.engine]: http://expressjs.com/api.html#app.engine\n[Jade]: http://jade-lang.com\n[vash-express-example]: https://github.com/kirbysayshi/vash-express-example/tree/master/views\n[layout.vash]: https://github.com/kirbysayshi/vash-express-example/blob/master/views/layout.vash\n[Layout.vash]: https://github.com/kirbysayshi/vash-express-example/blob/master/views/layout.vash\n\n\n\nvash.helpers.extend \n---------------------------\n\n\tvash.helpers.extend(parent_path, cb)\n\nThis is Vash's main form of inheritance for view templates. `parent_path` is the location or name of the template to be extended.\n\nA template can define various locations in itself that can be [overridden](#vash-helpers-block) or [added to](#vash-helpers-append). In addition, a template that calls `extend` can even be extended itself!\n\nIn the following example, this template extends another named [layout.vash][]. [Layout.vash][] defines an empty [block](#vash-helpers-block) named 'content', which is overrided in this example.\n\n\t@html.extend('layout', function(model){\n\t\t@html.block('content', function(model){\n\t\t\tHello, I'm default content. It's nice to meet you.
\n\t})\n\n_Tech note: due to the way JS scoping works, the `model` parameter of the `cb` function must be explicitely defined as above if it is referenced in the content. This may change in a future version of Vash._\n\n\nvash.helpers.append \n---------------------------\n\n\tvash.helpers.append(name, cb)\n\n[vash.helpers.append][] is a way to control the content of a block from within an extending template. In this way, it allows templates to invert control over content \"above\" them.\n\nAn example is a navigation area. Perhaps there is a default navigation list that templates can add to:\n\n\t// layout.vash\n\t' );\n\n\t\tif( helpers.config.highlighter ){\n\t\t\tthis.buffer.push( helpers.config.highlighter(lang, cbOutLines.join('')).value );\n\t\t} else {\n\t\t\tthis.buffer.push( cbOutLines );\n\t\t}\n\n\t\tthis.buffer.push( 'Hello
\n\nCompiles to a function:\n\n\tfunction anonymous(model,html,__vopts,vash) {\n\t\tvar __vbuffer = html.buffer;\n\t\thtml.options = __vopts;\n\t\tmodel = model || {};\n\t\t__vbuffer.push('\\n');\n\t\t(__vopts && __vopts.onRenderEnd && __vopts.onRenderEnd(null, html));\n\t\treturn (__vopts && __vopts.asContext)\n\t\t\t? html\n\t\t\t: html.toString();\n\t}\n\nIf `toClientString` is called on that function, the following is returned:\n\n\tvash.link( function anonymous(model,html,__vopts,vash) {\n\t\tvar __vbuffer = html.buffer;\n\t\thtml.options = __vopts;\n\t\tmodel = model || {};\n\t\t__vbuffer.push('\\n');\n\t\t(__vopts && __vopts.onRenderEnd && __vopts.onRenderEnd(null, html));\n\t\treturn (__vopts && __vopts.asContext)\n\t\t\t? html\n\t\t\t: html.toString();\n\t}, {\"simple\":false,\"modelName\":\"model\",\"helpersName\":\"html\"} )\n\nThis string could then be sent to the client (probably prefixed with something like `TPLCACHE[\"name-of-template\"] = `). [vash(1)][] helps to automate this easily.\n\nNote: this assumes that `vash` is available globally. A future version of Vash will hopefully remove this assumption.\n\nVash Runtime (Browser) \n====================\n\nThe Vash runtime is a set of functions that every executing template expects to be available. The runtime is automatically packaged with full Vash builds. However, if only precompiled templates are sent to the browser, then only the runtime must be sent. The runtime includes all helpers and a few standard functions, such as [HTML Escaping][].\n\nThere are two runtime builds:\n\n* [vash-runtime.js][]: This is the basic runtime. It contains everything a standard Vash template needs to execute.\n* [vash-runtime-all.js][]: This also includes the [Layout Helpers][]. It is roughly twice as large as `vash-runtime.js`. Unless you're using the Vash view system in the browser, this is probably not necessary.\n\nIf you're in a Browserify-like environemnt, you should be able to:\n\n```js\nvar vashruntime = require('vash/runtime');\n```\n\n..and have access to the [Runtime API][].\n\n[vash-runtime.js]: https://github.com/kirbysayshi/vash/blob/master/build/vash-runtime.js\n[vash-runtime-all.js]: https://github.com/kirbysayshi/vash/blob/master/build/vash-runtime-all.js\n\nCompile-time API \n=============\n\nvash.compile \n-----------------------------------------------\n\n\tvash.compile(str_template, opt_options) -> Function\n\nAt its core, Vash has a `compile` function that accepts a string and options, and returns a function, otherwise known as a compiled template. That function, when called with a parameter (otherwise known as a _model_), will use that parameter to fill in the template. A model can be any value, including `undefined`, objects, arrays, strings, and booleans.\n\nvash.compileHelper \n-----------------------------------------------------\n\n\tvash.compileHelper(str_template, opt_options) -> Object\n\nSee [Compiled Helpers][] for more detail.\n\nvash.compileBatch \n----------------------------------------------------\n\n\tvash.compileBatch(str_template, opt_options) -> Object\n\nThis function can take a single string containing many named templates, and output an object containing the compiled versions of those templates. A \"named template\" is of the form (similar to a `sourceURL`):\n\n\t//@batch = div\n\t