@rhinostone/swig 2.4.3 → 2.5.1

package/lib/swig.js

@@ -14,7 +14,7 @@ var utils = require('./utils'),
  *
  * @type {String}
  */
-exports.version = "2.4.3";
+exports.version = "2.5.1";
 
 /**
  * Swig Options Object. This object can be passed to many of the API-level Swig methods to control various aspects of the engine. All keys are optional.
@@ -336,17 +336,193 @@ exports.Swig = function (opts) {
  * Export methods publicly
  */
 defaultInstance = new exports.Swig();
+/**
+ * Add a custom filter for swig variables.
+ *
+ * @example
+ * function replaceMs(input) { return input.replace(/m/g, 'f'); }
+ * swig.setFilter('replaceMs', replaceMs);
+ * // => {{ "onomatopoeia"|replaceMs }}
+ * // => onofatopeia
+ *
+ * @param {string}    name    Name of filter, used in templates. <strong>Will</strong> overwrite previously defined filters, if using the same name.
+ * @param {function}  method  Function that acts against the input. See <a href="/docs/filters/#custom">Custom Filters</a> for more information.
+ * @return {undefined}
+ */
 exports.setFilter = defaultInstance.setFilter;
+/**
+ * Add a custom tag. To expose your own extensions to compiled template code, see <code data-language="js">swig.setExtension</code>.
+ *
+ * For a more in-depth explanation of writing custom tags, see <a href="../extending/#tags">Custom Tags</a>.
+ *
+ * @example
+ * var tacotag = require('./tacotag');
+ * swig.setTag('tacos', tacotag.parse, tacotag.compile, tacotag.ends, tacotag.blockLevel);
+ * // => {% tacos %}Make this be tacos.{% endtacos %}
+ * // => Tacos tacos tacos tacos.
+ *
+ * @param  {string} name      Tag name.
+ * @param  {function} parse   Method for parsing tokens.
+ * @param  {function} compile Method for compiling renderable output.
+ * @param  {boolean} [ends=false]     Whether or not this tag requires an <i>end</i> tag.
+ * @param  {boolean} [blockLevel=false] If false, this tag will not be compiled outside of <code>block</code> tags when extending a parent template.
+ * @return {undefined}
+ */
 exports.setTag = defaultInstance.setTag;
+/**
+ * Add extensions for custom tags. This allows any custom tag to access a globally available methods via a special globally available object, <var>_ext</var>, in templates.
+ *
+ * @example
+ * swig.setExtension('trans', function (v) { return translate(v); });
+ * function compileTrans(compiler, args, content, parent, options) {
+ *   return '_output += _ext.trans(' + args[0] + ');'
+ * };
+ * swig.setTag('trans', parseTrans, compileTrans, true);
+ *
+ * @param  {string} name   Key name of the extension. Accessed via <code data-language="js">_ext[name]</code>.
+ * @param  {*}      object The method, value, or object that should be available via the given name.
+ * @return {undefined}
+ */
 exports.setExtension = defaultInstance.setExtension;
+/**
+ * Parse a given file into tokens.
+ * @param  {string} pathname  Full path to file to parse.
+ * @param  {SwigOpts} [options={}]   Swig options object.
+ * @return {object} parsed    Template tokens object.
+ * @private
+ */
 exports.parseFile = defaultInstance.parseFile;
+/**
+ * Pre-compile a source string into a cache-able template function.
+ *
+ * @example
+ * swig.precompile('{{ tacos }}');
+ * // => {
+ * //      tpl: function (_swig, _locals, _filters, _utils, _fn) { ... },
+ * //      tokens: {
+ * //        name: undefined,
+ * //        parent: null,
+ * //        tokens: [...],
+ * //        blocks: {}
+ * //      }
+ * //    }
+ *
+ * In order to render a pre-compiled template, you must have access to filters and utils from Swig. <var>efn</var> is simply an empty function that does nothing.
+ *
+ * @param  {string} source  Swig template source string.
+ * @param  {SwigOpts} [options={}] Swig options object.
+ * @return {object}         Renderable function and tokens object.
+ */
 exports.precompile = defaultInstance.precompile;
+/**
+ * Compile string source into a renderable template function.
+ *
+ * @example
+ * var tpl = swig.compile('{{ tacos }}');
+ * // => {
+ * //      [Function: compiled]
+ * //      parent: null,
+ * //      tokens: [{ compile: [Function] }],
+ * //      blocks: {}
+ * //    }
+ * tpl({ tacos: 'Tacos!!!!' });
+ * // => Tacos!!!!
+ *
+ * When compiling a source string, a file path should be specified in the options object in order for <var>extends</var>, <var>include</var>, and <var>import</var> to work properly. Do this by adding <code data-language="js">{ filename: '/absolute/path/to/mytpl.html' }</code> to the options argument.
+ *
+ * @param  {string} source    Swig template source string.
+ * @param  {SwigOpts} [options={}] Swig options object.
+ * @return {function}         Renderable function with keys for parent, blocks, and tokens.
+ */
 exports.compile = defaultInstance.compile;
+/**
+ * Compile a source file into a renderable template function.
+ *
+ * @example
+ * var tpl = swig.compileFile('./mytpl.html');
+ * // => {
+ * //      [Function: compiled]
+ * //      parent: null,
+ * //      tokens: [{ compile: [Function] }],
+ * //      blocks: {}
+ * //    }
+ * tpl({ tacos: 'Tacos!!!!' });
+ * // => Tacos!!!!
+ *
+ * @example
+ * swig.compileFile('/myfile.txt', { varControls: ['<%=', '=%>'], tagControls: ['<%', '%>']});
+ * // => will compile 'myfile.txt' using the var and tag controls as specified.
+ *
+ * @param  {string} pathname  File location.
+ * @param  {SwigOpts} [options={}] Swig options object.
+ * @param  {Function} [cb] Asynchronous callback function. If not provided, <var>compileFile</var> will run synchronously.
+ * @return {function}         Renderable function with keys for parent, blocks, and tokens.
+ */
 exports.compileFile = defaultInstance.compileFile;
 exports.compileFileAsync = defaultInstance.compileFileAsync;
+/**
+ * Compile and render a template string for final output.
+ *
+ * When rendering a source string, a file path should be specified in the options object in order for <var>extends</var>, <var>include</var>, and <var>import</var> to work properly. Do this by adding <code data-language="js">{ filename: '/absolute/path/to/mytpl.html' }</code> to the options argument.
+ *
+ * @example
+ * swig.render('{{ tacos }}', { locals: { tacos: 'Tacos!!!!' }});
+ * // => Tacos!!!!
+ *
+ * @param  {string} source    Swig template source string.
+ * @param  {SwigOpts} [options={}] Swig options object.
+ * @return {string}           Rendered output.
+ */
 exports.render = defaultInstance.render;
+/**
+ * Compile and render a template file for final output. This is most useful for libraries like Express.js.
+ *
+ * When the active loader sets <code>loader.async === true</code> and a callback is provided, this method routes to the async-codegen dispatch path (added in v2.2.0) which supports dynamic <var>include</var> paths the sync path cannot. Otherwise it runs synchronously.
+ *
+ * @example
+ * swig.renderFile('./template.html', {}, function (err, output) {
+ *   if (err) {
+ *     throw err;
+ *   }
+ *   console.log(output);
+ * });
+ *
+ * @example
+ * swig.renderFile('./template.html', {});
+ * // => output
+ *
+ * @param  {string}   pathName    File location.
+ * @param  {object}   [locals={}] Template variable context.
+ * @param  {Function} [cb] Asynchronous callback function. If not provided, <var>renderFile</var> will run synchronously.
+ * @return {string}             Rendered output.
+ */
 exports.renderFile = defaultInstance.renderFile;
 exports.renderFileAsync = defaultInstance.renderFileAsync;
+/**
+ * Run a pre-compiled template function. This is most useful in the browser when you've pre-compiled your templates with the Swig command-line tool.
+ *
+ * @example
+ * $ swig compile ./mytpl.html --wrap-start="var mytpl = " > mytpl.js
+ * @example
+ * <script src="mytpl.js"></script>
+ * <script>
+ *   swig.run(mytpl, {});
+ *   // => "rendered template..."
+ * </script>
+ *
+ * @param  {function} tpl       Pre-compiled Swig template function. Use the Swig CLI to compile your templates.
+ * @param  {object} [locals={}] Template variable context.
+ * @param  {string} [filepath]  Filename used for caching the template.
+ * @return {string}             Rendered output.
+ */
 exports.run = defaultInstance.run;
+/**
+ * Clears the in-memory template cache.
+ *
+ * @example
+ * swig.invalidateCache();
+ *
+ * @return {undefined}
+ */
 exports.invalidateCache = defaultInstance.invalidateCache;
 exports.loaders = loaders;

package/lib/tags/extends.js

@@ -10,14 +10,14 @@
  *
  * @param {string} parentFile  Relative path to the file that this template extends.
  */
-// Phase 2 (#T15): extends is a parse-time declaration, not an emit-time
-// construct. The engine's getParents / remapBlocks resolves the parent
-// chain before the backend walks the token tree, so by compile-time
-// there is nothing to emit. No IRExtends node exists — the Template IR
-// already carries `.parent` / `.blocks` metadata for flavors that want
-// to reason about inheritance before lowering. The compile function
-// returns undefined and the backend skips it via the `result === undefined`
-// check at the top of the emit loop. This stays this way post-Phase 2.
+// extends is a parse-time declaration, not an emit-time construct. The
+// engine's getParents / remapBlocks resolves the parent chain before the
+// backend walks the token tree, so by compile-time there is nothing to
+// emit. No IRExtends node exists — the Template IR already carries
+// `.parent` / `.blocks` metadata for flavors that want to reason about
+// inheritance before lowering. The compile function returns undefined and
+// the backend skips it via the `result === undefined` check at the top of
+// the emit loop.
 exports.compile = function () {};
 
 exports.parse = function () {

package/lib/tags/filter.js

@@ -52,7 +52,7 @@ exports.lowerExpr = function (parser, tokens) {
   // PARENCLOSE that balances the FUNCTION's paren. Bail (return
   // undefined) on any nested FILTER / FILTEREMPTY — filter pipes inside
   // the argument expression are not part of the expression grammar
-  // (Output-site concern; Session 14+ work).
+  // (Output-site concern; deferred).
   var depth = 1,
     start = i + 1,
     slices = [],

package/lib/tags/if.js

@@ -43,12 +43,11 @@ var ir = require('@rhinostone/swig-core/lib/ir'),
  * @param {...mixed} conditional Conditional statement that returns a truthy or falsy value.
  */
 exports.compile = function (compiler, args, content, parents, options, blockName, token) {
-  // Phase 2 Session 14b Commit 11: filter-in-test fallback lifts into
-  // `IRLegacyJS` rather than a raw string. `if.lowerExpr` bails to
-  // `undefined` when the test contains FILTER/FILTEREMPTY because
-  // per-operand filter precedence (`a === b|upper` binds the filter to
-  // `b` only) can't be captured in flat IR — same widening recipe as
-  // `IROutput.expr` (Session 14b Commit 9). Backend dispatches
+  // Filter-in-test fallback lifts into `IRLegacyJS` rather than a raw
+  // string. `if.lowerExpr` bails to `undefined` when the test contains
+  // FILTER/FILTEREMPTY because per-operand filter precedence
+  // (`a === b|upper` binds the filter to `b` only) can't be captured in
+  // flat IR — same widening recipe as `IROutput.expr`. Backend dispatches
   // `LegacyJS` before `emitExpr`. String fallback still valid for
   // userland `setTag` compile functions that build branches manually.
   var branches = [],

package/lib/tags/import.js

@@ -28,7 +28,7 @@ var _dangerousProps = require('@rhinostone/swig-core/lib/security').dangerousPro
  * @param {literal}     varname   Local-accessible object name to assign the macros to.
  */
 exports.compile = function (compiler, args, content, parents, options) {
-  // Phase 2 (#T22): async-codegen branch. Parse stashed `[{path}, alias]`
+  // Async-codegen branch. Parse stashed `[{path}, alias]`
   // (no macro pre-render in async mode); emit IRImportDeferred so the
   // backend's `_swig.getTemplate` + `.exports` bind happens at runtime.
   if (options && options.codegenMode === 'async') {
@@ -154,11 +154,11 @@ exports.parse = function (str, line, parser, types, stack, opts, swig) {
         return;
       }
       macroName = token.args[0];
-      // Phase 2 (#T15): macro.compile now returns an IRMacro node
-      // rather than a JS source string. Render it through the shared
-      // backend so import.js still gets the JS source it performs
-      // regex-surgery on for namespace-prefixing. The +'\n' trailing
-      // newline matches the pre-Phase-2 compile output exactly.
+      // macro.compile returns an IRMacro node rather than a JS source
+      // string. Render it through the shared backend so import.js still
+      // gets the JS source it performs regex-surgery on for
+      // namespace-prefixing. The +'\n' trailing newline matches the
+      // legacy compile output exactly.
       out += backend.compile([token.compile(compiler, token.args, token.content, [], compileOpts)], [], compileOpts) + '\n';
       self.out.push({compiled: out, name: macroName});
     });

package/lib/tags/parent.js

@@ -35,10 +35,10 @@ exports.compile = function (compiler, args, content, parents, options, blockName
     // Silly JSLint "Strange Loop" requires return to be in a conditional
     if (breaker && parentFile !== parent.name) {
       block = parent.blocks[blockName];
-      // Phase 2: the block tag now returns `IRBlock { body: [...] }`.
-      // Splice the matched parent block's body into an IRParent node;
-      // the backend emits body verbatim plus a trailing newline for
-      // byte-identity with the pre-Phase-2 JS-string emission shape.
+      // The block tag returns `IRBlock { body: [...] }`. Splice the
+      // matched parent block's body into an IRParent node; the backend
+      // emits body verbatim plus a trailing newline for byte-identity
+      // with the legacy JS-string emission shape.
       var blockNode = block.compile(compiler, [blockName], block.content, parents.slice(i + 1), options);
       return ir.parent((blockNode && blockNode.body) ? blockNode.body.concat([ir.legacyJS('\n')]) : [ir.legacyJS('\n')]);
     }

package/lib/tags/set.js

@@ -36,9 +36,9 @@ var ir = require('@rhinostone/swig-core/lib/ir'),
 
 // Pure-dot LHS shape: `_ctx.foo` or `_ctx.foo.bar.baz`. Bracket-touched
 // targets (`_ctx.foo["bar"]`, `_ctx.foo[bar]`, mixed dot+bracket) fail
-// this match and stay on the transitional string fallback per Session
-// 14b Commit 10's narrow scope — the bracket-lvalue contract is a
-// cross-flavor design call and is deferred to a dedicated session.
+// this match and stay on the transitional string fallback. The
+// bracket-lvalue contract is a cross-flavor design call and is deferred
+// to a dedicated session.
 var _pureDotTarget = /^_ctx\.([a-zA-Z_$][\w$]*)((?:\.[a-zA-Z_$][\w$]*)*)$/;
 
 exports.compile = function (compiler, args, content, parents, options, blockName, token) {
@@ -70,8 +70,8 @@ exports.lowerExpr = function (parser, tokens) {
   // assignment operator; lowerExpr only concerns itself with the RHS.
   // Locate the first ASSIGNMENT, slice the tail, and hand it to parseExpr.
   // Fall back (return undefined) if the tail contains FILTER / FILTEREMPTY
-  // (filter pipes are not part of the expression grammar yet — Session
-  // 14+ Output-site work) or a nested ASSIGNMENT (parseExpr does not
+  // (filter pipes are not yet part of the expression grammar — pending
+  // output-site lowering) or a nested ASSIGNMENT (parseExpr does not
   // lower assignments, and bracket-write-as-assignment on the RHS would
   // misparse silently).
   var assignIdx = -1, i;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinostone/swig",
-  "version": "2.4.3",
+  "version": "2.5.1",
   "description": "A simple, powerful, and extendable templating engine for node.js and browsers, similar to Django, Jinja2, and Twig.",
   "keywords": [
     "template",
@@ -21,21 +21,17 @@
     "Rhinostone <contact@gina.io>"
   ],
   "dependencies": {
-    "@rhinostone/swig-core": "2.4.3"
+    "@rhinostone/swig-core": "2.5.1"
   },
   "devDependencies": {
-    "blanket": "~1.1",
     "esbuild": "^0.28.0",
-    "eslint": "^8.57.1",
+    "eslint": "^9",
     "expect.js": "~0.2",
-    "express": "~3",
-    "lodash": "~1.3.1",
-    "mocha": "1.12.0",
-    "mocha-phantomjs": "~3.1",
+    "express": "^4",
+    "globals": "^16",
+    "lodash": "^4",
     "path-browserify": "^1.0.1",
-    "phantomjs": "~1.9.1",
-    "terser": "^5.46.1",
-    "travis-cov": "~0.2"
+    "terser": "^5.46.1"
   },
   "license": "MIT",
   "main": "index",
@@ -50,15 +46,7 @@
   },
   "scripts": {
     "prepublish": "npm prune && make build",
-    "test": "make lint && make test reporter=spec && make test-browser && make coverage cov-reporter=travis-cov",
-    "travis-cov": {
-      "threshold": 95
-    }
-  },
-  "config": {
-    "blanket": {
-      "pattern": "swig/lib"
-    }
+    "test": "make lint && make test reporter=spec && make coverage"
   },
   "publishConfig": {
     "access": "public"

package/.eslintrc.json

@@ -1,24 +0,0 @@
-{
-  "env": {
-    "node": true,
-    "mocha": true,
-    "es2017": true
-  },
-  "parserOptions": {
-    "ecmaVersion": 2017
-  },
-  "globals": {
-    "Promise": "readonly"
-  },
-  "rules": {
-    "max-len": ["error", { "code": 600 }],
-    "semi": ["error", "always"],
-    "no-eval": "off",
-    "no-new-func": "off",
-    "strict": "off",
-    "eqeqeq": "off",
-    "no-trailing-spaces": "error",
-    "no-undef": "error",
-    "no-redeclare": "error"
-  }
-}