Update reference docs with most recent version of brodocs (#4600)

* Update 1.7 apidocs with new brodocs * Update 1.7 resource reference docs with new brodocs * Update 1.7 kubectl reference docs with new brodocs
2017-08-04 14:30:56 -07:00
parent 4b004cf717
commit 217c86642f
387 changed files with 10024 additions and 8309 deletions
@@ -19,7 +19,7 @@
 'use strict';

 /**
- * @file Embedded JavaScript templating engine.
+ * @file Embedded JavaScript templating engine. {@link http://ejs.co}
 * @author Matthew Eernisse <mde@fleegix.org>
 * @author Tiancheng "Timothy" Gu <timothygu99@gmail.com>
 * @project EJS
@@ -56,6 +56,10 @@ var _NAME = 'ejs';
 var _REGEX_STRING = '(<%%|%%>|<%=|<%-|<%_|<%#|<%|%>|-%>|_%>)';
 var _OPTS = ['delimiter', 'scope', 'context', 'debug', 'compileDebug',
  'client', '_with', 'rmWhitespace', 'strict', 'filename'];
+// We don't allow 'cache' option to be passed in the data obj
+// for the normal `render` call, but this is where Express puts it
+// so we make an exception for `renderFile`
+var _OPTS_EXPRESS = _OPTS.concat('cache');
 var _BOM = /^\uFEFF/;

 /**
@@ -68,6 +72,15 @@ var _BOM = /^\uFEFF/;

 exports.cache = utils.cache;

+/**
+ * Custom file loader. Useful for template preprocessing or restricting access
+ * to a certain part of the filesystem.
+ *
+ * @type {fileLoader}
+ */
+
+exports.fileLoader = fs.readFileSync;
+
 /**
 * Name of the object containing the locals.
 *
@@ -108,16 +121,36 @@ exports.resolveInclude = function(name, filename, isDir) {
 * @param  {Options} options compilation options
 * @return {String}
 */
-function getIncludePath(path, options){
+function getIncludePath(path, options) {
  var includePath;
+  var filePath;
+  var views = options.views;
+
+  // Abs path
  if (path.charAt(0) == '/') {
    includePath = exports.resolveInclude(path.replace(/^\/*/,''), options.root || '/', true);
  }
+  // Relative paths
  else {
-    if (!options.filename) {
-      throw new Error('`include` use relative path requires the \'filename\' option.');
+    // Look relative to a passed filename first
+    if (options.filename) {
+      filePath = exports.resolveInclude(path, options.filename);
+      if (fs.existsSync(filePath)) {
+        includePath = filePath;
+      }
+    }
+    // Then look in any views directories
+    if (!includePath) {
+      if (Array.isArray(views) && views.some(function (v) {
+        filePath = exports.resolveInclude(path, v, true);
+        return fs.existsSync(filePath);
+      })) {
+        includePath = filePath;
+      }
+    }
+    if (!includePath) {
+      throw new Error('Could not find include include file.');
    }
-    includePath = exports.resolveInclude(path, options.filename);
  }
  return includePath;
 }
@@ -154,7 +187,7 @@ function handleCache(options, template) {
      return func;
    }
    if (!hasTemplate) {
-      template = fs.readFileSync(filename).toString().replace(_BOM, '');
+      template = fileLoader(filename).toString().replace(_BOM, '');
    }
  }
  else if (!hasTemplate) {
@@ -163,7 +196,7 @@ function handleCache(options, template) {
      throw new Error('Internal EJS error: no file name or template '
                    + 'provided');
    }
-    template = fs.readFileSync(filename).toString().replace(_BOM, '');
+    template = fileLoader(filename).toString().replace(_BOM, '');
  }
  func = exports.compile(template, options);
  if (options.cache) {
@@ -172,6 +205,41 @@ function handleCache(options, template) {
  return func;
 }

+/**
+ * Try calling handleCache with the given options and data and call the
+ * callback with the result. If an error occurs, call the callback with
+ * the error. Used by renderFile().
+ *
+ * @memberof module:ejs-internal
+ * @param {Options} options    compilation options
+ * @param {Object} data        template data
+ * @param {RenderFileCallback} cb callback
+ * @static
+ */
+
+function tryHandleCache(options, data, cb) {
+  var result;
+  try {
+    result = handleCache(options)(data);
+  }
+  catch (err) {
+    return cb(err);
+  }
+  return cb(null, result);
+}
+
+/**
+ * fileLoader is independent
+ *
+ * @param {String} filePath ejs file path.
+ * @return {String} The contents of the specified file.
+ * @static
+ */
+
+function fileLoader(filePath){
+  return exports.fileLoader(filePath);
+}
+
 /**
 * Get the template function.
 *
@@ -205,8 +273,8 @@ function includeSource(path, options) {
  var opts = utils.shallowCopy({}, options);
  var includePath;
  var template;
-  includePath = getIncludePath(path,opts);
-  template = fs.readFileSync(includePath).toString().replace(_BOM, '');
+  includePath = getIncludePath(path, opts);
+  template = fileLoader(includePath).toString().replace(_BOM, '');
  opts.filename = includePath;
  var templ = new Template(template, opts);
  templ.generateSource();
@@ -230,11 +298,11 @@ function includeSource(path, options) {
 * @static
 */

-function rethrow(err, str, flnm, lineno){
+function rethrow(err, str, flnm, lineno, esc){
  var lines = str.split('\n');
  var start = Math.max(lineno - 3, 0);
  var end = Math.min(lines.length, lineno + 3);
-  var filename = utils.escapeXML(flnm);
+  var filename = esc(flnm); // eslint-disable-line
  // Error context
  var context = lines.slice(start, end).map(function (line, i){
    var curr = i + start + 1;
@@ -254,7 +322,7 @@ function rethrow(err, str, flnm, lineno){
  throw err;
 }

-function stripSemi(str) {
+function stripSemi(str){
  return str.replace(/;(\s*$)/, '$1');
 }

@@ -330,43 +398,43 @@ exports.render = function (template, d, o) {
 */

 exports.renderFile = function () {
-  var args = Array.prototype.slice.call(arguments);
-  var filename = args.shift();
-  var cb = args.pop();
-  var data = args.shift() || {};
-  var opts = args.pop() || {};
-  var optsKeys =_OPTS.slice();
-  var result;
+  var filename = arguments[0];
+  var cb = arguments[arguments.length - 1];
+  var opts = {filename: filename};
+  var data;

-  // Don't pollute passed in opts obj with new vals
-  opts = utils.shallowCopy({}, opts);
+  if (arguments.length > 2) {
+    data = arguments[1];

-  // We don't allow 'cache' option to be passed in the data obj
-  // for the normal `render` call, but this is where Expres puts it
-  // so we make an exception for `renderFile`
-  optsKeys.push('cache');
-
-  // No options object -- if there are optiony names
-  // in the data, copy them to options
-  if (arguments.length == 3) {
-    // Express 4
-    if (data.settings && data.settings['view options']) {
-      utils.shallowCopyFromList(opts, data.settings['view options'], optsKeys);
+    // No options object -- if there are optiony names
+    // in the data, copy them to options
+    if (arguments.length === 3) {
+      // Express 4
+      if (data.settings) {
+        if (data.settings['view options']) {
+          utils.shallowCopyFromList(opts, data.settings['view options'], _OPTS_EXPRESS);
+        }
+        if (data.settings.views) {
+          opts.views = data.settings.views;
+        }
+      }
+      // Express 3 and lower
+      else {
+        utils.shallowCopyFromList(opts, data, _OPTS_EXPRESS);
+      }
    }
-    // Express 3 and lower
    else {
-      utils.shallowCopyFromList(opts, data, optsKeys);
+      // Use shallowCopy so we don't pollute passed in opts obj with new vals
+      utils.shallowCopy(opts, arguments[2]);
    }
-  }
-  opts.filename = filename;

-  try {
-    result = handleCache(opts)(data);
+    opts.filename = filename;
  }
-  catch(err) {
-    return cb(err);
+  else {
+    data = {};
  }
-  return cb(null, result);
+
+  return tryHandleCache(opts, data, cb);
 };

 /**
@@ -399,6 +467,7 @@ function Template(text, opts) {
  options.rmWhitespace = opts.rmWhitespace;
  options.root = opts.root;
  options.localsName = opts.localsName || exports.localsName || _DEFAULT_LOCALS_NAME;
+  options.views = opts.views;

  if (options.strict) {
    options._with = false;
@@ -434,7 +503,7 @@ Template.prototype = {
    var opts = this.opts;
    var prepended = '';
    var appended = '';
-    var escape = opts.escapeFunction;
+    var escapeFn = opts.escapeFunction;

    if (!this.source) {
      this.generateSource();
@@ -455,19 +524,15 @@ Template.prototype = {
          + 'try {' + '\n'
          + this.source
          + '} catch (e) {' + '\n'
-          + '  rethrow(e, __lines, __filename, __line);' + '\n'
+          + '  rethrow(e, __lines, __filename, __line, escapeFn);' + '\n'
          + '}' + '\n';
    }
    else {
      src = this.source;
    }

-    if (opts.debug) {
-      console.log(src);
-    }
-
    if (opts.client) {
-      src = 'escape = escape || ' + escape.toString() + ';' + '\n' + src;
+      src = 'escapeFn = escapeFn || ' + escapeFn.toString() + ';' + '\n' + src;
      if (opts.compileDebug) {
        src = 'rethrow = rethrow || ' + rethrow.toString() + ';' + '\n' + src;
      }
@@ -476,9 +541,12 @@ Template.prototype = {
    if (opts.strict) {
      src = '"use strict";\n' + src;
    }
+    if (opts.debug) {
+      console.log(src);
+    }

    try {
-      fn = new Function(opts.localsName + ', escape, include, rethrow', src);
+      fn = new Function(opts.localsName + ', escapeFn, include, rethrow', src);
    }
    catch(e) {
      // istanbul ignore else
@@ -509,7 +577,7 @@ Template.prototype = {
        }
        return includeFile(path, opts)(d);
      };
-      return fn.apply(opts.context, [data || {}, escape, include, rethrow]);
+      return fn.apply(opts.context, [data || {}, escapeFn, include, rethrow]);
    };
    returnedFn.dependencies = this.dependencies;
    return returnedFn;
@@ -568,7 +636,7 @@ Template.prototype = {
                  + '      try {' + '\n'
                  + includeObj.source
                  + '      } catch (e) {' + '\n'
-                  + '        rethrow(e, __lines, __filename, __line);' + '\n'
+                  + '        rethrow(e, __lines, __filename, __line, escapeFn);' + '\n'
                  + '      }' + '\n'
                  + '    ; }).call(this)' + '\n';
            }else{
@@ -614,43 +682,43 @@ Template.prototype = {
    return arr;
  },

+  _addOutput: function (line) {
+    if (this.truncate) {
+      // Only replace single leading linebreak in the line after
+      // -%> tag -- this is the single, trailing linebreak
+      // after the tag that the truncation mode replaces
+      // Handle Win / Unix / old Mac linebreaks -- do the \r\n
+      // combo first in the regex-or
+      line = line.replace(/^(?:\r\n|\r|\n)/, '');
+      this.truncate = false;
+    }
+    else if (this.opts.rmWhitespace) {
+      // rmWhitespace has already removed trailing spaces, just need
+      // to remove linebreaks
+      line = line.replace(/^\n/, '');
+    }
+    if (!line) {
+      return line;
+    }
+
+    // Preserve literal slashes
+    line = line.replace(/\\/g, '\\\\');
+
+    // Convert linebreaks
+    line = line.replace(/\n/g, '\\n');
+    line = line.replace(/\r/g, '\\r');
+
+    // Escape double-quotes
+    // - this will be the delimiter during execution
+    line = line.replace(/"/g, '\\"');
+    this.source += '    ; __append("' + line + '")' + '\n';
+  },
+
  scanLine: function (line) {
    var self = this;
    var d = this.opts.delimiter;
    var newLineCount = 0;

-    function _addOutput() {
-      if (self.truncate) {
-        // Only replace single leading linebreak in the line after
-        // -%> tag -- this is the single, trailing linebreak
-        // after the tag that the truncation mode replaces
-        // Handle Win / Unix / old Mac linebreaks -- do the \r\n
-        // combo first in the regex-or
-        line = line.replace(/^(?:\r\n|\r|\n)/, '');
-        self.truncate = false;
-      }
-      else if (self.opts.rmWhitespace) {
-        // rmWhitespace has already removed trailing spaces, just need
-        // to remove linebreaks
-        line = line.replace(/^\n/, '');
-      }
-      if (!line) {
-        return;
-      }
-
-      // Preserve literal slashes
-      line = line.replace(/\\/g, '\\\\');
-
-      // Convert linebreaks
-      line = line.replace(/\n/g, '\\n');
-      line = line.replace(/\r/g, '\\r');
-
-      // Escape double-quotes
-      // - this will be the delimiter during execution
-      line = line.replace(/"/g, '\\"');
-      self.source += '    ; __append("' + line + '")' + '\n';
-    }
-
    newLineCount = (line.split('\n').length - 1);

    switch (line) {
@@ -679,7 +747,7 @@ Template.prototype = {
    case '-' + d + '>':
    case '_' + d + '>':
      if (this.mode == Template.modes.LITERAL) {
-        _addOutput();
+        this._addOutput(line);
      }

      this.mode = null;
@@ -704,7 +772,7 @@ Template.prototype = {
          break;
            // Exec, esc, and output
        case Template.modes.ESCAPED:
-          this.source += '    ; __append(escape(' + stripSemi(line) + '))' + '\n';
+          this.source += '    ; __append(escapeFn(' + stripSemi(line) + '))' + '\n';
          break;
            // Exec and output
        case Template.modes.RAW:
@@ -715,13 +783,13 @@ Template.prototype = {
          break;
            // Literal <%% mode, append as raw output
        case Template.modes.LITERAL:
-          _addOutput();
+          this._addOutput(line);
          break;
        }
      }
        // In string mode, just add the output
      else {
-        _addOutput();
+        this._addOutput(line);
      }
    }

@@ -766,7 +834,7 @@ if (require.extensions) {
      filename: filename,
      client: true
    };
-    var template = fs.readFileSync(filename).toString();
+    var template = fileLoader(filename).toString();
    var fn = exports.compile(template, options);
    module._compile('module.exports = ' + fn.toString() + ';', filename);
  };
@@ -133,11 +133,12 @@ exports.shallowCopy = function (to, from) {
 * @private
 */
 exports.shallowCopyFromList = function (to, from, list) {
-  list.forEach(function (p) {
+  for (var i = 0; i < list.length; i++) {
+    var p = list[i];
    if (typeof from[p] != 'undefined') {
      to[p] = from[p];
    }
-  });
+  }
  return to;
 };