@rhinostone/swig 2.5.0 → 2.5.2

package/lib/swig.js

@@ -14,7 +14,7 @@ var utils = require('./utils'),
  *
  * @type {String}
  */
-exports.version = "2.5.0";
+exports.version = "2.5.2";
 
 /**
  * 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

@@ -1,3 +1,5 @@
+var _t = require('@rhinostone/swig-core/lib/tokentypes');
+
 /**
  * Makes the current template extend a parent template. This tag must be the first item in your template.
  *
@@ -24,4 +26,27 @@ exports.parse = function () {
   return true;
 };
 
+/*!
+ * Lower a dynamic parent-path to IR so `{% extends layout_var %}`
+ * resolves at render time on the async codegen path. A lone
+ * string-literal path (`{% extends "x.html" %}`) returns undefined, so
+ * the engine keeps its existing tokens.parent string + ir.literal path
+ * unchanged; only a dynamic path is lowered. Mirrors include.js. The
+ * resulting IRExpr is read back as token.irExpr.file by the parser
+ * splitter and stashed on the sibling tokens.parentExpr slot.
+ */
+exports.lowerExpr = function (parser, tokens) {
+  var i, tk, pathTokens = [];
+  for (i = 0; i < tokens.length; i += 1) {
+    tk = tokens[i];
+    if (tk.type === _t.WHITESPACE) { continue; }
+    pathTokens.push(tk);
+  }
+  if (!pathTokens.length) { return undefined; }
+  if (pathTokens.length === 1 && pathTokens[0].type === _t.STRING) {
+    return undefined;
+  }
+  return { file: parser.parseExpr(tokens) };
+};
+
 exports.ends = false;

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.5.0",
+  "version": "2.5.2",
   "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.5.0"
+    "@rhinostone/swig-core": "2.5.2"
   },
   "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"
-  }
-}