@rhinostone/swig-django 2.7.0

package/lib/index.js

@@ -0,0 +1,345 @@
+/**
+ * @rhinostone/swig-django — Django frontend for the @rhinostone/swig family.
+ *
+ * End-to-end render wiring (Path A): the package exposes a Django
+ * constructor + default instance via `engine.install(self, frontend)` from
+ * @rhinostone/swig-core, so callers can `render(source, locals)` /
+ * `renderFile(path, locals, cb)` directly against Django syntax.
+ *
+ * The async loader surface (`renderFileAsync` / `compileFileAsync` + the
+ * pre-walker) pre-walks the `extends` / `include` dependency graph through an
+ * async loader and runs the existing sync pipeline against a populated memory
+ * map. The public `renderFile(path, locals, cb)` cb-dispatch (active when
+ * `loader.async === true`) is inherited from swig-core's engine.
+ */
+
+var utils = require('@rhinostone/swig-core/lib/utils'),
+  engine = require('@rhinostone/swig-core/lib/engine'),
+  loaders = require('@rhinostone/swig-core/lib/loaders'),
+  dateformatter = require('@rhinostone/swig-core/lib/dateformatter'),
+  parser = require('./parser'),
+  _tags = require('./tags'),
+  _filters = require('./filters'),
+  preWalker = require('./async/pre-walker');
+
+exports.name = 'django';
+
+/**
+ * Expression-level parser — Pratt-style recursive descent that consumes
+ * Django lexer tokens and returns swig-core IRExpr nodes, plus the top-level
+ * `parse(swig, source, opts, tags, filters)` splitter.
+ *
+ * @type {object}
+ */
+exports.parser = parser;
+
+/**
+ * Built-in Django tag registry.
+ *
+ * @type {object}
+ */
+exports.tags = _tags;
+
+/**
+ * Built-in Django filter catalog.
+ *
+ * @type {object}
+ */
+exports.filters = _filters;
+
+/**
+ * Template loaders re-exported from swig-core.
+ *
+ * @type {object}
+ */
+exports.loaders = loaders;
+
+var defaultOptions = {
+    autoescape: true,
+    varControls: ['{{', '}}'],
+    tagControls: ['{%', '%}'],
+    cmtControls: ['{#', '#}'],
+    locals: {},
+    cache: 'memory',
+    loader: loaders.fs()
+  },
+  defaultInstance;
+
+/**
+ * Validate the Django options object.
+ *
+ * @param  {?object} options Django options object.
+ * @return {undefined}      Throws on malformed input.
+ * @private
+ */
+function validateOptions(options) {
+  if (!options) {
+    return;
+  }
+
+  utils.each(['varControls', 'tagControls', 'cmtControls'], function (key) {
+    if (!options.hasOwnProperty(key)) {
+      return;
+    }
+    if (!utils.isArray(options[key]) || options[key].length !== 2) {
+      throw new Error('Option "' + key + '" must be an array containing 2 different control strings.');
+    }
+    if (options[key][0] === options[key][1]) {
+      throw new Error('Option "' + key + '" open and close controls must not be the same.');
+    }
+    utils.each(options[key], function (a, i) {
+      if (a.length < 2) {
+        throw new Error('Option "' + key + '" ' + ((i) ? 'open ' : 'close ') + 'control must be at least 2 characters. Saw "' + a + '" instead.');
+      }
+    });
+  });
+
+  if (options.hasOwnProperty('cache')) {
+    if (options.cache && options.cache !== 'memory') {
+      if (!options.cache.get || !options.cache.set) {
+        throw new Error('Invalid cache option ' + JSON.stringify(options.cache) + ' found. Expected "memory" or { get: function (key) { ... }, set: function (key, value) { ... } }.');
+      }
+    }
+  }
+  if (options.hasOwnProperty('loader')) {
+    if (options.loader) {
+      if (!options.loader.load || !options.loader.resolve) {
+        throw new Error('Invalid loader option ' + JSON.stringify(options.loader) + ' found. Expected { load: function (pathname, cb) { ... }, resolve: function (to, from) { ... } }.');
+      }
+    }
+  }
+}
+
+/**
+ * Set defaults for the base and all new Django environments.
+ *
+ * @param  {object} [options={}] Django options object.
+ * @return {undefined}
+ */
+exports.setDefaults = function (options) {
+  validateOptions(options);
+  defaultInstance.options = utils.extend(defaultInstance.options, options);
+};
+
+/**
+ * Set the default TimeZone offset for date formatting via the date filter.
+ * Mutates the shared dateformatter's tzOffset — affects every frontend
+ * (native swig + swig-django) because both consume the same module instance.
+ *
+ * @param  {number} offset Offset from GMT, in minutes (west of GMT).
+ * @return {undefined}
+ */
+exports.setDefaultTZOffset = function (offset) {
+  dateformatter.tzOffset = offset;
+};
+
+/**
+ * Create a new, separate Django compile/render environment.
+ *
+ * @example
+ * var django = require('@rhinostone/swig-django');
+ * var mydjango = new django.Django({ autoescape: false });
+ * mydjango.render('Hello {{ name }}', { locals: { name: 'world' }});
+ *
+ * @param  {object} [opts={}] Django options object.
+ * @return {object}           New Django environment.
+ */
+exports.Django = function (opts) {
+  var self = this;
+
+  validateOptions(opts);
+  this.options = utils.extend({}, defaultOptions, opts || {});
+  this.cache = {};
+  this.extensions = {};
+
+  engine.install(this, {
+    parser: parser,
+    tags: _tags,
+    filters: _filters,
+    validateOptions: validateOptions,
+    onCompileError: function (err, options) {
+      utils.throwError(err, null, options.filename);
+    }
+  });
+
+  /*!
+   * Build the pre-walker scan options for this instance. Django's verbatim
+   * region tag is `verbatim`, and the only template-loading tags with a
+   * string-literal path argument are `extends` and `include` (Django has no
+   * Python-style `import` / `from`). @private
+   */
+  function buildScanOpts() {
+    return {
+      varControls: self.options.varControls,
+      tagControls: self.options.tagControls,
+      cmtControls: self.options.cmtControls,
+      rawTag: 'verbatim',
+      keywords: ['extends', 'include']
+    };
+  }
+
+  /**
+   * Render a Django template file asynchronously, supporting async loaders.
+   *
+   * Pre-walks `extends` / `include` targets in parallel via the user loader,
+   * populates an in-memory map, then runs the existing sync render pipeline
+   * against the populated map. Dynamic paths (`{% extends parent_var %}`) are
+   * not pre-resolved and will throw at render time as they would on the sync
+   * path.
+   *
+   * @deprecated since 2.7.0 — use {@link Django#renderFile} with a loader that
+   *   sets `loader.async === true`. The async-codegen dispatch handles dynamic
+   *   include paths the pre-walker cannot. This method will be removed in 3.0.
+   *
+   * @example
+   * django.setDefaults({ loader: myAsyncLoader });
+   * django.renderFileAsync('page.html', { name: 'world' }, function (err, output) {
+   *   if (err) { return done(err); }
+   *   res.end(output);
+   * });
+   *
+   * @param  {string}   pathName  Template path; resolved via the active loader.
+   * @param  {object}   [locals]  Locals to render with.
+   * @param  {Function} cb        Node-style callback `(err, output)`.
+   * @return {undefined}
+   */
+  this.renderFileAsync = function (pathName, locals, cb) {
+    if (typeof locals === 'function') {
+      cb = locals;
+      locals = undefined;
+    }
+
+    var loader = self.options.loader;
+    var entry;
+
+    try {
+      entry = loader.resolve(pathName);
+    } catch (e) {
+      cb(e);
+      return;
+    }
+
+    preWalker.walk(entry, loader, buildScanOpts()).then(function (memMap) {
+      var memWrapper = preWalker.makeMemoryWrapper(loader, memMap);
+      var origLoader = self.options.loader;
+      self.options.loader = memWrapper;
+      var output, error;
+      try {
+        output = self.renderFile(entry, locals);
+      } catch (e) {
+        error = e;
+      }
+      self.options.loader = origLoader;
+      if (error) {
+        cb(error);
+        return;
+      }
+      cb(null, output);
+    }, function (err) {
+      cb(err);
+    });
+  };
+
+  /**
+   * Compile a Django template file asynchronously, supporting async loaders.
+   *
+   * Same pre-walk / memory-wrapper / sync-pipeline shape as
+   * {@link Django#renderFileAsync}. Returns the compiled function (via `cb`)
+   * that takes a locals object and yields a rendered string. The returned
+   * function captures the pre-walked memory map and temporarily swaps the
+   * loader on each call, so subsequent runtime `include`s resolve correctly
+   * without re-running the pre-walk.
+   *
+   * @deprecated since 2.7.0 — use {@link Django#compileFile} with
+   *   `options.codegenMode === 'async'` on a loader that sets
+   *   `loader.async === true`. The returned compiled function yields a
+   *   `Promise<{output, exports}>` instead of a string. This method will be
+   *   removed in 3.0.
+   *
+   * @example
+   * django.compileFileAsync('page.html', {}, function (err, fn) {
+   *   if (err) { return done(err); }
+   *   res.end(fn({ name: 'world' }));
+   * });
+   *
+   * @param  {string}   pathName  Template path.
+   * @param  {object}   [options] Compilation options.
+   * @param  {Function} cb        Node-style callback `(err, fn)`.
+   * @return {undefined}
+   */
+  this.compileFileAsync = function (pathName, options, cb) {
+    if (typeof options === 'function') {
+      cb = options;
+      options = {};
+    }
+
+    var loader = self.options.loader;
+    var entry;
+
+    try {
+      entry = loader.resolve(pathName);
+    } catch (e) {
+      cb(e);
+      return;
+    }
+
+    preWalker.walk(entry, loader, buildScanOpts()).then(function (memMap) {
+      var memWrapper = preWalker.makeMemoryWrapper(loader, memMap);
+      var origLoader = self.options.loader;
+      self.options.loader = memWrapper;
+      var compiled, error;
+      try {
+        compiled = self.compileFile(entry, options);
+      } catch (e) {
+        error = e;
+      }
+      self.options.loader = origLoader;
+      if (error) {
+        cb(error);
+        return;
+      }
+      var wrapped = function (locals) {
+        var origInner = self.options.loader;
+        self.options.loader = memWrapper;
+        try {
+          var output = compiled(locals);
+          self.options.loader = origInner;
+          return output;
+        } catch (e) {
+          self.options.loader = origInner;
+          throw e;
+        }
+      };
+      cb(null, wrapped);
+    }, function (err) {
+      cb(err);
+    });
+  };
+};
+
+/*!
+ * Export methods publicly via the default instance.
+ */
+defaultInstance = new exports.Django();
+exports.setFilter = defaultInstance.setFilter;
+exports.setTag = defaultInstance.setTag;
+exports.setExtension = defaultInstance.setExtension;
+exports.parseFile = defaultInstance.parseFile;
+exports.precompile = defaultInstance.precompile;
+exports.compile = defaultInstance.compile;
+exports.compileFile = defaultInstance.compileFile;
+exports.compileFileAsync = defaultInstance.compileFileAsync;
+exports.render = defaultInstance.render;
+exports.renderFile = defaultInstance.renderFile;
+exports.renderFileAsync = defaultInstance.renderFileAsync;
+exports.run = defaultInstance.run;
+exports.invalidateCache = defaultInstance.invalidateCache;
+
+/**
+ * Express 3/4 compatibility alias.
+ *
+ * @example
+ * app.engine('html', require('@rhinostone/swig-django').__express);
+ * app.set('view engine', 'html');
+ */
+exports.__express = defaultInstance.renderFile;

package/lib/lexer.js

@@ -0,0 +1,302 @@
+var utils = require('@rhinostone/swig-core/lib/utils');
+var TYPES = require('./tokentypes');
+
+/**
+ * A Django lexer token.
+ *
+ * @typedef {object} LexerToken
+ * @property {string} match  The string that was matched (post-replace).
+ * @property {number} type   Django token type enum value.
+ * @property {number} length Length of the input chunk consumed.
+ */
+
+/*!
+ * Django lexer rule table — the swig-shared token subset plus the Django
+ * literals.
+ *
+ * Departures from the Jinja2 sibling lexer:
+ *
+ *   - Filters are a single `|name` token (FILTEREMPTY). Django filters take
+ *     at most one positional argument introduced by a colon (`|date:"Y"`),
+ *     which the parser grabs as an optional `COLON + arg` in parsePostfix —
+ *     there is no `|name(...)` paren-call filter form, so the Jinja2 FILTER
+ *     rule is dropped.
+ *   - BOOL matches `True` / `False` (Python casing) and normalizes to the
+ *     JS `true` / `false` the parser expects.
+ *   - `None` lexes to a dedicated NONE token (Django's null literal).
+ *   - `is` / `is not` are kept (Django identity comparisons), but lower to
+ *     `===` / `!==` in the parser, not to Jinja2 test calls.
+ *   - No `~` concat, `**` power, or `//` floor-division — Django has none of
+ *     them, so those Jinja2-only rules are absent.
+ *   - Whitespace-control (`{{-` / `-%}`) is not Django syntax and is not
+ *     stripped in the parser's splitter.
+ *
+ * Rule ordering constraints worth the call-out:
+ *
+ *   - FILTEREMPTY / FUNCTION above VAR — `|name` and `name(` must be
+ *     consumed as filter / function tokens before VAR's `^[a-zA-Z_$]\w*`
+ *     pattern gobbles the bare identifier.
+ *   - LOGIC (`and` / `or`), NOT (`not`), BOOL (`True` / `False`), NONE
+ *     (`None`), and the `is` / `is not` keywords above VAR — same reason:
+ *     bake the keyword sequence into its own token rather than emit an
+ *     identifier. The `\b` word boundary keeps identifiers like `Truthy`,
+ *     `Nonexistent`, or `island` from matching.
+ *
+ * Rules are tried in order; first match wins. Patterns are anchored at
+ * start-of-string because the consumer slices `str` before each dispatch.
+ */
+var rules = [
+  {
+    type: TYPES.WHITESPACE,
+    regex: [
+      /^\s+/
+    ]
+  },
+  {
+    type: TYPES.STRING,
+    regex: [
+      /^""/,
+      /^".*?[^\\]"/,
+      /^''/,
+      /^'.*?[^\\]'/
+    ]
+  },
+  {
+    type: TYPES.FILTEREMPTY,
+    regex: [
+      /^\|\s*(\w+)/
+    ],
+    idx: 1
+  },
+  {
+    type: TYPES.FUNCTIONEMPTY,
+    regex: [
+      /^\s*(\w+)\(\)/
+    ],
+    idx: 1
+  },
+  {
+    type: TYPES.FUNCTION,
+    regex: [
+      /^\s*(\w+)\(/
+    ],
+    idx: 1
+  },
+  {
+    type: TYPES.PARENOPEN,
+    regex: [
+      /^\(/
+    ]
+  },
+  {
+    type: TYPES.PARENCLOSE,
+    regex: [
+      /^\)/
+    ]
+  },
+  {
+    type: TYPES.COMMA,
+    regex: [
+      /^,/
+    ]
+  },
+  {
+    type: TYPES.LOGIC,
+    regex: [
+      /^(&&|\|\|)\s*/,
+      /^(and|or)\s+/
+    ],
+    idx: 1,
+    replace: {
+      'and': '&&',
+      'or': '||'
+    }
+  },
+  {
+    type: TYPES.COMPARATOR,
+    regex: [
+      /^(===|==|\!==|\!=|<=|<|>=|>|in\s)\s*/
+    ],
+    idx: 1
+  },
+  {
+    type: TYPES.ASSIGNMENT,
+    regex: [
+      /^(=|\+=|-=|\*=|\/=)/
+    ]
+  },
+  {
+    type: TYPES.NOT,
+    regex: [
+      /^\!\s*/,
+      /^not\s+/
+    ],
+    replace: {
+      'not': '!'
+    }
+  },
+  {
+    // `\b` (not `\s+|$`) so `True` / `False` are consumed correctly when
+    // immediately followed by a non-word char — e.g. `(x == True)` — which
+    // the inherited (lenient) parenthesis grammar allows. `True\b` still
+    // rejects identifiers like `Truthy` (no word boundary before `t`).
+    type: TYPES.BOOL,
+    regex: [
+      /^(True|False)\b/
+    ],
+    idx: 1,
+    replace: {
+      'True': 'true',
+      'False': 'false'
+    }
+  },
+  {
+    // Django null literal. Above VAR so `None` isn't gobbled as an
+    // identifier; `\b` keeps `Nonexistent` from matching.
+    type: TYPES.NONE,
+    regex: [
+      /^None\b/
+    ]
+  },
+  {
+    // ISNOT above IS above VAR — the `is` keyword would otherwise be gobbled
+    // by VAR's `^[a-zA-Z_$]\w*` pattern. ISNOT above IS because `is not`
+    // must be consumed as a single token, not IS + NOT. The `\b` word
+    // boundary keeps identifiers like `island` from matching.
+    type: TYPES.ISNOT,
+    regex: [
+      /^is\s+not\b/
+    ]
+  },
+  {
+    type: TYPES.IS,
+    regex: [
+      /^is\b/
+    ]
+  },
+  {
+    // The dotted-path interior segment uses `\w+` (not `\w*`) so a future
+    // operator whose first char is `.` cannot be absorbed as a zero-width
+    // interior segment. Matches the Jinja2 / Twig sibling lexers.
+    type: TYPES.VAR,
+    regex: [
+      /^[a-zA-Z_$]\w*((\.\$?\w+)+)?/,
+      /^[a-zA-Z_$]\w*/
+    ]
+  },
+  {
+    type: TYPES.BRACKETOPEN,
+    regex: [
+      /^\[/
+    ]
+  },
+  {
+    type: TYPES.BRACKETCLOSE,
+    regex: [
+      /^\]/
+    ]
+  },
+  {
+    type: TYPES.CURLYOPEN,
+    regex: [
+      /^\{/
+    ]
+  },
+  {
+    type: TYPES.COLON,
+    regex: [
+      /^\:/
+    ]
+  },
+  {
+    type: TYPES.CURLYCLOSE,
+    regex: [
+      /^\}/
+    ]
+  },
+  {
+    type: TYPES.DOTKEY,
+    regex: [
+      /^\.(\w+)/
+    ],
+    idx: 1
+  },
+  {
+    type: TYPES.NUMBER,
+    regex: [
+      /^\d+(\.\d+)?/
+    ]
+  },
+  {
+    type: TYPES.OPERATOR,
+    regex: [
+      /^(\+|\-|\/|\*|%)/
+    ]
+  }
+];
+
+exports.types = TYPES;
+
+/**
+ * Match the next token at the start of `str`.
+ *
+ * Throws via utils.throwError when no rule matches. The throw is opaque (no
+ * line / file info); the Django frontend's onCompileError callback attaches
+ * filename + line per the swig-core / frontend seam rule.
+ *
+ * @param  {string}     str Input slice starting at the unconsumed offset.
+ * @return {LexerToken}     Matched token.
+ * @throws {Error}          When no rule matches.
+ * @private
+ */
+function reader(str) {
+  var matched;
+
+  utils.some(rules, function (rule) {
+    return utils.some(rule.regex, function (regex) {
+      var match = str.match(regex),
+        normalized;
+
+      if (!match) {
+        return;
+      }
+
+      normalized = match[rule.idx || 0].replace(/\s*$/, '');
+      normalized = (rule.hasOwnProperty('replace') && rule.replace.hasOwnProperty(normalized)) ? rule.replace[normalized] : normalized;
+
+      matched = {
+        match: normalized,
+        type: rule.type,
+        length: match[0].length
+      };
+      return true;
+    });
+  });
+
+  if (!matched) {
+    utils.throwError('Unexpected token "' + str.charAt(0) + '" in Django expression');
+  }
+
+  return matched;
+}
+
+/**
+ * Tokenize a Django expression string.
+ *
+ * @param  {string}            str Expression source (the contents of
+ *                                 `{{ … }}` or `{% … %}` minus the control
+ *                                 delimiters and tag name).
+ * @return {Array.<LexerToken>}    Sequence of matched tokens.
+ * @throws {Error}                 On the first unrecognised character.
+ */
+exports.read = function (str) {
+  var offset = 0,
+    tokens = [],
+    match;
+  while (offset < str.length) {
+    match = reader(str.substring(offset));
+    offset += match.length;
+    tokens.push(match);
+  }
+  return tokens;
+};