2 * EJS Embedded JavaScript templates
3 * Copyright 2112 Matthew Eernisse (mde@fleegix.org)
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
22 * @file Embedded JavaScript templating engine. {@link http://ejs.co}
23 * @author Matthew Eernisse <mde@fleegix.org>
24 * @author Tiancheng "Timothy" Gu <timothygu99@gmail.com>
26 * @license {@link http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0}
30 * EJS internal functions.
32 * Technically this "module" lies in the same file as {@link module:ejs}, for
33 * the sake of organization all the private functions re grouped into this
36 * @module ejs-internal
41 * Embedded JavaScript templating engine.
47 var fs = require('fs');
48 var path = require('path');
49 var utils = require('./utils');
51 var scopeOptionWarned = false;
52 var _VERSION_STRING = require('../package.json').version;
53 var _DEFAULT_OPEN_DELIMITER = '<';
54 var _DEFAULT_CLOSE_DELIMITER = '>';
55 var _DEFAULT_DELIMITER = '%';
56 var _DEFAULT_LOCALS_NAME = 'locals';
58 var _REGEX_STRING = '(<%%|%%>|<%=|<%-|<%_|<%#|<%|%>|-%>|_%>)';
59 var _OPTS_PASSABLE_WITH_DATA = ['delimiter', 'scope', 'context', 'debug', 'compileDebug',
60 'client', '_with', 'rmWhitespace', 'strict', 'filename', 'async'];
61 // We don't allow 'cache' option to be passed in the data obj for
62 // the normal `render` call, but this is where Express 2 & 3 put it
63 // so we make an exception for `renderFile`
64 var _OPTS_PASSABLE_WITH_DATA_EXPRESS = _OPTS_PASSABLE_WITH_DATA.concat('cache');
68 * EJS template function cache. This can be a LRU object from lru-cache NPM
69 * module. By default, it is {@link module:utils.cache}, a simple in-process
70 * cache that grows continuously.
75 exports.cache = utils.cache;
78 * Custom file loader. Useful for template preprocessing or restricting access
79 * to a certain part of the filesystem.
84 exports.fileLoader = fs.readFileSync;
87 * Name of the object containing the locals.
89 * This variable is overridden by {@link Options}`.localsName` if it is not
96 exports.localsName = _DEFAULT_LOCALS_NAME;
99 * Promise implementation -- defaults to the native implementation if available
100 * This is mostly just for testability
106 exports.promiseImpl = (new Function('return this;'))().Promise;
109 * Get the path to the included file from the parent file path and the
112 * @param {String} name specified path
113 * @param {String} filename parent file path
114 * @param {Boolean} isDir parent file path whether is directory
117 exports.resolveInclude = function(name, filename, isDir) {
118 var dirname = path.dirname;
119 var extname = path.extname;
120 var resolve = path.resolve;
121 var includePath = resolve(isDir ? filename : dirname(filename), name);
122 var ext = extname(name);
124 includePath += '.ejs';
130 * Get the path to the included file by Options
132 * @param {String} path specified path
133 * @param {Options} options compilation options
136 function getIncludePath(path, options) {
139 var views = options.views;
140 var match = /^[A-Za-z]+:\\|^\//.exec(path);
143 if (match && match.length) {
144 includePath = exports.resolveInclude(path.replace(/^\/*/,''), options.root || '/', true);
148 // Look relative to a passed filename first
149 if (options.filename) {
150 filePath = exports.resolveInclude(path, options.filename);
151 if (fs.existsSync(filePath)) {
152 includePath = filePath;
155 // Then look in any views directories
157 if (Array.isArray(views) && views.some(function (v) {
158 filePath = exports.resolveInclude(path, v, true);
159 return fs.existsSync(filePath);
161 includePath = filePath;
165 throw new Error('Could not find the include file "' +
166 options.escapeFunction(path) + '"');
173 * Get the template from a string or a file, either compiled on-the-fly or
174 * read from cache (if enabled), and cache the template if needed.
176 * If `template` is not set, the file specified in `options.filename` will be
179 * If `options.cache` is true, this function reads the file from
180 * `options.filename` so it must be set prior to calling this function.
182 * @memberof module:ejs-internal
183 * @param {Options} options compilation options
184 * @param {String} [template] template source
185 * @return {(TemplateFunction|ClientFunction)}
186 * Depending on the value of `options.client`, either type might be returned.
190 function handleCache(options, template) {
192 var filename = options.filename;
193 var hasTemplate = arguments.length > 1;
197 throw new Error('cache option requires a filename');
199 func = exports.cache.get(filename);
204 template = fileLoader(filename).toString().replace(_BOM, '');
207 else if (!hasTemplate) {
208 // istanbul ignore if: should not happen at all
210 throw new Error('Internal EJS error: no file name or template '
213 template = fileLoader(filename).toString().replace(_BOM, '');
215 func = exports.compile(template, options);
217 exports.cache.set(filename, func);
223 * Try calling handleCache with the given options and data and call the
224 * callback with the result. If an error occurs, call the callback with
225 * the error. Used by renderFile().
227 * @memberof module:ejs-internal
228 * @param {Options} options compilation options
229 * @param {Object} data template data
230 * @param {RenderFileCallback} cb callback
234 function tryHandleCache(options, data, cb) {
237 if (typeof exports.promiseImpl == 'function') {
238 return new exports.promiseImpl(function (resolve, reject) {
240 result = handleCache(options)(data);
249 throw new Error('Please provide a callback function');
254 result = handleCache(options)(data);
265 * fileLoader is independent
267 * @param {String} filePath ejs file path.
268 * @return {String} The contents of the specified file.
272 function fileLoader(filePath){
273 return exports.fileLoader(filePath);
277 * Get the template function.
279 * If `options.cache` is `true`, then the template is cached.
281 * @memberof module:ejs-internal
282 * @param {String} path path for the specified file
283 * @param {Options} options compilation options
284 * @return {(TemplateFunction|ClientFunction)}
285 * Depending on the value of `options.client`, either type might be returned
289 function includeFile(path, options) {
290 var opts = utils.shallowCopy({}, options);
291 opts.filename = getIncludePath(path, opts);
292 return handleCache(opts);
296 * Get the JavaScript source of an included file.
298 * @memberof module:ejs-internal
299 * @param {String} path path for the specified file
300 * @param {Options} options compilation options
305 function includeSource(path, options) {
306 var opts = utils.shallowCopy({}, options);
309 includePath = getIncludePath(path, opts);
310 template = fileLoader(includePath).toString().replace(_BOM, '');
311 opts.filename = includePath;
312 var templ = new Template(template, opts);
313 templ.generateSource();
315 source: templ.source,
316 filename: includePath,
322 * Re-throw the given `err` in context to the `str` of ejs, `filename`, and
325 * @implements RethrowCallback
326 * @memberof module:ejs-internal
327 * @param {Error} err Error object
328 * @param {String} str EJS source
329 * @param {String} filename file name of the EJS file
330 * @param {String} lineno line number of the error
334 function rethrow(err, str, flnm, lineno, esc){
335 var lines = str.split('\n');
336 var start = Math.max(lineno - 3, 0);
337 var end = Math.min(lines.length, lineno + 3);
338 var filename = esc(flnm); // eslint-disable-line
340 var context = lines.slice(start, end).map(function (line, i){
341 var curr = i + start + 1;
342 return (curr == lineno ? ' >> ' : ' ')
348 // Alter exception message
350 err.message = (filename || 'ejs') + ':'
358 function stripSemi(str){
359 return str.replace(/;(\s*$)/, '$1');
363 * Compile the given `str` of ejs into a template function.
365 * @param {String} template EJS template
367 * @param {Options} opts compilation options
369 * @return {(TemplateFunction|ClientFunction)}
370 * Depending on the value of `opts.client`, either type might be returned.
371 * Note that the return type of the function also depends on the value of `opts.async`.
375 exports.compile = function compile(template, opts) {
379 // 'scope' is 'context'
380 // FIXME: Remove this in a future version
381 if (opts && opts.scope) {
382 if (!scopeOptionWarned){
383 console.warn('`scope` option is deprecated and will be removed in EJS 3');
384 scopeOptionWarned = true;
387 opts.context = opts.scope;
391 templ = new Template(template, opts);
392 return templ.compile();
396 * Render the given `template` of ejs.
398 * If you would like to include options but not data, you need to explicitly
399 * call this function with `data` being an empty object or `null`.
401 * @param {String} template EJS template
402 * @param {Object} [data={}] template data
403 * @param {Options} [opts={}] compilation and rendering options
404 * @return {(String|Promise<String>)}
405 * Return value type depends on `opts.async`.
409 exports.render = function (template, d, o) {
413 // No options object -- if there are optiony names
414 // in the data, copy them to options
415 if (arguments.length == 2) {
416 utils.shallowCopyFromList(opts, data, _OPTS_PASSABLE_WITH_DATA);
419 return handleCache(opts, template)(data);
423 * Render an EJS file at the given `path` and callback `cb(err, str)`.
425 * If you would like to include options but not data, you need to explicitly
426 * call this function with `data` being an empty object or `null`.
428 * @param {String} path path to the EJS file
429 * @param {Object} [data={}] template data
430 * @param {Options} [opts={}] compilation and rendering options
431 * @param {RenderFileCallback} cb callback
435 exports.renderFile = function () {
436 var args = Array.prototype.slice.call(arguments);
437 var filename = args.shift();
439 var opts = {filename: filename};
443 // Do we have a callback?
444 if (typeof arguments[arguments.length - 1] == 'function') {
447 // Do we have data/opts?
449 // Should always have data obj
451 // Normal passed opts (data obj + opts obj)
453 // Use shallowCopy so we don't pollute passed in opts obj with new vals
454 utils.shallowCopy(opts, args.pop());
456 // Special casing for Express (settings + opts-in-data)
460 // Pull a few things from known locations
461 if (data.settings.views) {
462 opts.views = data.settings.views;
464 if (data.settings['view cache']) {
467 // Undocumented after Express 2, but still usable, esp. for
468 // items that are unsafe to be passed along with data, like `root`
469 viewOpts = data.settings['view options'];
471 utils.shallowCopy(opts, viewOpts);
474 // Express 2 and lower, values set in app.locals, or people who just
475 // want to pass options in their data. NOTE: These values will override
476 // anything previously set in settings or settings['view options']
477 utils.shallowCopyFromList(opts, data, _OPTS_PASSABLE_WITH_DATA_EXPRESS);
479 opts.filename = filename;
485 return tryHandleCache(opts, data, cb);
489 * Clear intermediate JavaScript cache. Calls {@link Cache#reset}.
497 exports.Template = Template;
499 exports.clearCache = function () {
500 exports.cache.reset();
503 function Template(text, opts) {
506 this.templateText = text;
508 this.truncate = false;
509 this.currentLine = 1;
511 this.dependencies = [];
512 options.client = opts.client || false;
513 options.escapeFunction = opts.escape || opts.escapeFunction || utils.escapeXML;
514 options.compileDebug = opts.compileDebug !== false;
515 options.debug = !!opts.debug;
516 options.filename = opts.filename;
517 options.openDelimiter = opts.openDelimiter || exports.openDelimiter || _DEFAULT_OPEN_DELIMITER;
518 options.closeDelimiter = opts.closeDelimiter || exports.closeDelimiter || _DEFAULT_CLOSE_DELIMITER;
519 options.delimiter = opts.delimiter || exports.delimiter || _DEFAULT_DELIMITER;
520 options.strict = opts.strict || false;
521 options.context = opts.context;
522 options.cache = opts.cache || false;
523 options.rmWhitespace = opts.rmWhitespace;
524 options.root = opts.root;
525 options.outputFunctionName = opts.outputFunctionName;
526 options.localsName = opts.localsName || exports.localsName || _DEFAULT_LOCALS_NAME;
527 options.views = opts.views;
528 options.async = opts.async;
530 if (options.strict) {
531 options._with = false;
534 options._with = typeof opts._with != 'undefined' ? opts._with : true;
539 this.regex = this.createRegex();
550 Template.prototype = {
551 createRegex: function () {
552 var str = _REGEX_STRING;
553 var delim = utils.escapeRegExpChars(this.opts.delimiter);
554 var open = utils.escapeRegExpChars(this.opts.openDelimiter);
555 var close = utils.escapeRegExpChars(this.opts.closeDelimiter);
556 str = str.replace(/%/g, delim)
558 .replace(/>/g, close);
559 return new RegExp(str);
562 compile: function () {
565 var opts = this.opts;
568 var escapeFn = opts.escapeFunction;
572 this.generateSource();
573 prepended += ' var __output = [], __append = __output.push.bind(__output);' + '\n';
574 if (opts.outputFunctionName) {
575 prepended += ' var ' + opts.outputFunctionName + ' = __append;' + '\n';
577 if (opts._with !== false) {
578 prepended += ' with (' + opts.localsName + ' || {}) {' + '\n';
579 appended += ' }' + '\n';
581 appended += ' return __output.join("");' + '\n';
582 this.source = prepended + this.source + appended;
585 if (opts.compileDebug) {
586 src = 'var __line = 1' + '\n'
587 + ' , __lines = ' + JSON.stringify(this.templateText) + '\n'
588 + ' , __filename = ' + (opts.filename ?
589 JSON.stringify(opts.filename) : 'undefined') + ';' + '\n'
592 + '} catch (e) {' + '\n'
593 + ' rethrow(e, __lines, __filename, __line, escapeFn);' + '\n'
601 src = 'escapeFn = escapeFn || ' + escapeFn.toString() + ';' + '\n' + src;
602 if (opts.compileDebug) {
603 src = 'rethrow = rethrow || ' + rethrow.toString() + ';' + '\n' + src;
608 src = '"use strict";\n' + src;
616 // Have to use generated function for this, since in envs without support,
617 // it breaks in parsing
619 ctor = (new Function('return (async function(){}).constructor;'))();
622 if (e instanceof SyntaxError) {
623 throw new Error('This environment does not support async/await');
633 fn = new ctor(opts.localsName + ', escapeFn, include, rethrow', src);
636 // istanbul ignore else
637 if (e instanceof SyntaxError) {
639 e.message += ' in ' + opts.filename;
641 e.message += ' while compiling ejs\n\n';
642 e.message += 'If the above error is not helpful, you may want to try EJS-Lint:\n';
643 e.message += 'https://github.com/RyanZim/EJS-Lint';
646 e.message += 'Or, if you meant to create an async function, pass async: true as an option.';
653 fn.dependencies = this.dependencies;
657 // Return a callable function which will execute the function
658 // created by the source-code, with the passed data as locals
659 // Adds a local `include` function which allows full recursive include
660 var returnedFn = function (data) {
661 var include = function (path, includeData) {
662 var d = utils.shallowCopy({}, data);
664 d = utils.shallowCopy(d, includeData);
666 return includeFile(path, opts)(d);
668 return fn.apply(opts.context, [data || {}, escapeFn, include, rethrow]);
670 returnedFn.dependencies = this.dependencies;
674 generateSource: function () {
675 var opts = this.opts;
677 if (opts.rmWhitespace) {
678 // Have to use two separate replace here as `^` and `$` operators don't
679 // work well with `\r` and empty lines don't work well with the `m` flag.
681 this.templateText.replace(/[\r\n]+/g, '\n').replace(/^\s+|\s+$/gm, '');
684 // Slurp spaces and tabs before <%_ and after _%>
686 this.templateText.replace(/[ \t]*<%_/gm, '<%_').replace(/_%>[ \t]*/gm, '_%>');
689 var matches = this.parseTemplateText();
690 var d = this.opts.delimiter;
691 var o = this.opts.openDelimiter;
692 var c = this.opts.closeDelimiter;
694 if (matches && matches.length) {
695 matches.forEach(function (line, index) {
702 // If this is an opening tag, check for closing tags
703 // FIXME: May end up with some false positives here
704 // Better to store modes as k/v with openDelimiter + delimiter as key
705 // Then this can simply check against the map
706 if ( line.indexOf(o + d) === 0 // If it is a tag
707 && line.indexOf(o + d + d) !== 0) { // and is not escaped
708 closing = matches[index + 2];
709 if (!(closing == d + c || closing == '-' + d + c || closing == '_' + d + c)) {
710 throw new Error('Could not find matching close tag for "' + line + '".');
713 // HACK: backward-compat `include` preprocessor directives
714 if ((include = line.match(/^\s*include\s+(\S+)/))) {
715 opening = matches[index - 1];
716 // Must be in EVAL or RAW mode
717 if (opening && (opening == o + d || opening == o + d + '-' || opening == o + d + '_')) {
718 includeOpts = utils.shallowCopy({}, self.opts);
719 includeObj = includeSource(include[1], includeOpts);
720 if (self.opts.compileDebug) {
722 ' ; (function(){' + '\n'
723 + ' var __line = 1' + '\n'
724 + ' , __lines = ' + JSON.stringify(includeObj.template) + '\n'
725 + ' , __filename = ' + JSON.stringify(includeObj.filename) + ';' + '\n'
728 + ' } catch (e) {' + '\n'
729 + ' rethrow(e, __lines, __filename, __line, escapeFn);' + '\n'
731 + ' ; }).call(this)' + '\n';
733 includeSrc = ' ; (function(){' + '\n' + includeObj.source +
734 ' ; }).call(this)' + '\n';
736 self.source += includeSrc;
737 self.dependencies.push(exports.resolveInclude(include[1],
738 includeOpts.filename));
748 parseTemplateText: function () {
749 var str = this.templateText;
750 var pat = this.regex;
751 var result = pat.exec(str);
756 firstPos = result.index;
758 if (firstPos !== 0) {
759 arr.push(str.substring(0, firstPos));
760 str = str.slice(firstPos);
764 str = str.slice(result[0].length);
765 result = pat.exec(str);
775 _addOutput: function (line) {
777 // Only replace single leading linebreak in the line after
778 // -%> tag -- this is the single, trailing linebreak
779 // after the tag that the truncation mode replaces
780 // Handle Win / Unix / old Mac linebreaks -- do the \r\n
781 // combo first in the regex-or
782 line = line.replace(/^(?:\r\n|\r|\n)/, '');
783 this.truncate = false;
789 // Preserve literal slashes
790 line = line.replace(/\\/g, '\\\\');
792 // Convert linebreaks
793 line = line.replace(/\n/g, '\\n');
794 line = line.replace(/\r/g, '\\r');
796 // Escape double-quotes
797 // - this will be the delimiter during execution
798 line = line.replace(/"/g, '\\"');
799 this.source += ' ; __append("' + line + '")' + '\n';
802 scanLine: function (line) {
804 var d = this.opts.delimiter;
805 var o = this.opts.openDelimiter;
806 var c = this.opts.closeDelimiter;
807 var newLineCount = 0;
809 newLineCount = (line.split('\n').length - 1);
814 this.mode = Template.modes.EVAL;
817 this.mode = Template.modes.ESCAPED;
820 this.mode = Template.modes.RAW;
823 this.mode = Template.modes.COMMENT;
826 this.mode = Template.modes.LITERAL;
827 this.source += ' ; __append("' + line.replace(o + d + d, o + d) + '")' + '\n';
830 this.mode = Template.modes.LITERAL;
831 this.source += ' ; __append("' + line.replace(d + d + c, d + c) + '")' + '\n';
836 if (this.mode == Template.modes.LITERAL) {
837 this._addOutput(line);
841 this.truncate = line.indexOf('-') === 0 || line.indexOf('_') === 0;
844 // In script mode, depends on type of tag
846 // If '//' is found without a line break, add a line break.
848 case Template.modes.EVAL:
849 case Template.modes.ESCAPED:
850 case Template.modes.RAW:
851 if (line.lastIndexOf('//') > line.lastIndexOf('\n')) {
856 // Just executing code
857 case Template.modes.EVAL:
858 this.source += ' ; ' + line + '\n';
860 // Exec, esc, and output
861 case Template.modes.ESCAPED:
862 this.source += ' ; __append(escapeFn(' + stripSemi(line) + '))' + '\n';
865 case Template.modes.RAW:
866 this.source += ' ; __append(' + stripSemi(line) + ')' + '\n';
868 case Template.modes.COMMENT:
871 // Literal <%% mode, append as raw output
872 case Template.modes.LITERAL:
873 this._addOutput(line);
877 // In string mode, just add the output
879 this._addOutput(line);
883 if (self.opts.compileDebug && newLineCount) {
884 this.currentLine += newLineCount;
885 this.source += ' ; __line = ' + this.currentLine + '\n';
891 * Escape characters reserved in XML.
893 * This is simply an export of {@link module:utils.escapeXML}.
895 * If `markup` is `undefined` or `null`, the empty string is returned.
897 * @param {String} markup Input string
898 * @return {String} Escaped string
902 exports.escapeXML = utils.escapeXML;
905 * Express.js support.
907 * This is an alias for {@link module:ejs.renderFile}, in order to support
908 * Express.js out-of-the-box.
913 exports.__express = exports.renderFile;
915 // Add require support
916 /* istanbul ignore else */
917 if (require.extensions) {
918 require.extensions['.ejs'] = function (module, flnm) {
919 var filename = flnm || /* istanbul ignore next */ module.filename;
924 var template = fileLoader(filename).toString();
925 var fn = exports.compile(template, options);
926 module._compile('module.exports = ' + fn.toString() + ';', filename);
938 exports.VERSION = _VERSION_STRING;
941 * Name for detection of EJS.
948 exports.name = _NAME;
950 /* istanbul ignore if */
951 if (typeof window != 'undefined') {
952 window.ejs = exports;