closure-builder
Version:
Simple Closure, Soy and JavaScript Build system
1,397 lines (1,257 loc) • 95.1 kB
JavaScript
/*
* Copyright 2008 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @fileoverview
* Utility functions and classes for Soy gencode
*
* <p>
* This file contains utilities that should only be called by Soy-generated
* JS code. Please do not use these functions directly from
* your hand-written code. Their names all start with '$$', or exist within the
* soydata.VERY_UNSAFE namespace.
*
* <p>TODO(lukes): ensure that the above pattern is actually followed
* consistently.
*
*/
goog.provide('soy');
goog.provide('soy.asserts');
goog.provide('soy.esc');
goog.provide('soydata');
goog.provide('soydata.SanitizedHtml');
goog.provide('soydata.VERY_UNSAFE');
goog.require('goog.array');
goog.require('goog.asserts');
goog.require('goog.debug');
goog.require('goog.format');
goog.require('goog.html.SafeHtml');
goog.require('goog.html.SafeScript');
goog.require('goog.html.SafeStyle');
goog.require('goog.html.SafeStyleSheet');
goog.require('goog.html.SafeUrl');
goog.require('goog.html.TrustedResourceUrl');
goog.require('goog.html.uncheckedconversions');
goog.require('goog.i18n.BidiFormatter');
goog.require('goog.i18n.bidi');
goog.require('goog.object');
goog.require('goog.soy.data.SanitizedContent');
goog.require('goog.soy.data.SanitizedContentKind');
goog.require('goog.soy.data.SanitizedCss');
goog.require('goog.soy.data.SanitizedHtml');
goog.require('goog.soy.data.SanitizedHtmlAttribute');
goog.require('goog.soy.data.SanitizedJs');
goog.require('goog.soy.data.SanitizedTrustedResourceUri');
goog.require('goog.soy.data.SanitizedUri');
goog.require('goog.soy.data.UnsanitizedText');
goog.require('goog.string');
goog.require('goog.string.Const');
goog.require('soy.checks');
/**
* A structural interface for injected data.
*
* <p>Generated code contributes optional properties.
*
* @record
*/
soy.IjData = function() {};
// -----------------------------------------------------------------------------
// soydata: Defines typed strings, e.g. an HTML string `"a<b>c"` is
// semantically distinct from the plain text string `"a<b>c"` and smart
// templates can take that distinction into account.
/**
* Properties added to all idom HTML / Attributes functions. The TypeScript type
* inherits this and adds a call signature (which is not really possible here).
* @typedef {{
* toString: function(),
* contentKind: !goog.soy.data.SanitizedContentKind
* }}
*/
soydata.IdomFunctionMembers;
/** @typedef {!soydata.IdomFunctionMembers|!Function} */
soydata.IdomFunction;
/**
* Checks whether a given value is of a given content kind.
*
* @param {?} value The value to be examined.
* @param {!goog.soy.data.SanitizedContentKind} contentKind The desired content
* kind.
* @return {boolean} Whether the given value is of the given kind.
* @private
*/
soydata.isContentKind_ = function(value, contentKind) {
// TODO(user): This function should really include the assert on
// value.constructor that is currently sprinkled at most of the call sites.
// Unfortunately, that would require a (debug-mode-only) switch statement.
// TODO(user): Perhaps we should get rid of the contentKind property
// altogether and only at the constructor.
return value != null && value.contentKind === contentKind;
};
/**
* Returns a given value's contentDir property, constrained to a
* goog.i18n.bidi.Dir value or null. Returns null if the value is null,
* undefined, a primitive or does not have a contentDir property, or the
* property's value is not 1 (for LTR), -1 (for RTL), or 0 (for neutral).
*
* @param {?} value The value whose contentDir property, if any, is to
* be returned.
* @return {?goog.i18n.bidi.Dir} The contentDir property.
*/
soydata.getContentDir = function(value) {
if (value != null) {
switch (value.contentDir) {
case goog.i18n.bidi.Dir.LTR:
return goog.i18n.bidi.Dir.LTR;
case goog.i18n.bidi.Dir.RTL:
return goog.i18n.bidi.Dir.RTL;
case goog.i18n.bidi.Dir.NEUTRAL:
return goog.i18n.bidi.Dir.NEUTRAL;
}
}
return null;
};
/**
* This class is only a holder for `soydata.SanitizedHtml.from`. Do not
* instantiate or extend it. Use `goog.soy.data.SanitizedHtml` instead.
*
* @constructor
* @extends {goog.soy.data.SanitizedHtml}
* @abstract
*/
soydata.SanitizedHtml = function() {
soydata.SanitizedHtml.base(this, 'constructor'); // Throws an exception.
};
goog.inherits(soydata.SanitizedHtml, goog.soy.data.SanitizedHtml);
/**
* Returns a SanitizedHtml object for a particular value. The content direction
* is preserved.
*
* This HTML-escapes the value unless it is already SanitizedHtml or SafeHtml.
*
* @param {?} value The value to convert. If it is already a SanitizedHtml
* object, it is left alone.
* @return {!goog.soy.data.SanitizedHtml} A SanitizedHtml object derived from
* the stringified value. It is escaped unless the input is SanitizedHtml or
* SafeHtml.
*/
soydata.SanitizedHtml.from = function(value) {
// The check is soydata.isContentKind_() inlined for performance.
if (soy.checks.isHtml(value)) {
return /** @type {!goog.soy.data.SanitizedHtml} */ (value);
}
if (value instanceof goog.html.SafeHtml) {
return soydata.VERY_UNSAFE.ordainSanitizedHtml(
goog.html.SafeHtml.unwrap(value), value.getDirection());
}
return soydata.VERY_UNSAFE.ordainSanitizedHtml(
soy.esc.$$escapeHtmlHelper(String(value)), soydata.getContentDir(value));
};
/**
* Empty string, used as a type in Soy templates.
* @enum {string}
* @private
*/
soydata.$$EMPTY_STRING_ = {
VALUE: ''
};
/**
* Creates a factory for SanitizedContent types.
*
* This is a hack so that the soydata.VERY_UNSAFE.ordainSanitized* can
* instantiate Sanitized* classes, without making the Sanitized* constructors
* publicly usable. Requiring all construction to use the VERY_UNSAFE names
* helps callers and their reviewers easily tell that creating SanitizedContent
* is not always safe and calls for careful review.
*
* @param {function(new: T)} ctor A constructor.
* @return {function(*, ?goog.i18n.bidi.Dir=): T} A factory that takes
* content and an optional content direction and returns a new instance. If
* the content direction is undefined, ctor.prototype.contentDir is used.
* @template T
* @private
*/
soydata.$$makeSanitizedContentFactory_ = function(ctor) {
/**
* @param {string} content
* @constructor
* @extends {goog.soy.data.SanitizedContent}
*/
function InstantiableCtor(content) {
/** @override */
this.content = content;
}
InstantiableCtor.prototype = ctor.prototype;
/**
* Creates a ctor-type SanitizedContent instance.
*
* @param {?} content The content to put in the instance.
* @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction. If
* undefined, ctor.prototype.contentDir is used.
* @return {!goog.soy.data.SanitizedContent} The new instance. It is actually
* of type T above (ctor's type, a descendant of SanitizedContent), but
* there is no way to express that here.
*/
function sanitizedContentFactory(content, opt_contentDir) {
var result = new InstantiableCtor(String(content));
if (opt_contentDir !== undefined) {
result.contentDir = opt_contentDir;
}
return result;
}
return sanitizedContentFactory;
};
/**
* Creates a factory for SanitizedContent types that should always have their
* default directionality.
*
* This is a hack so that the soydata.VERY_UNSAFE.ordainSanitized* can
* instantiate Sanitized* classes, without making the Sanitized* constructors
* publicly usable. Requiring all construction to use the VERY_UNSAFE names
* helps callers and their reviewers easily tell that creating SanitizedContent
* is not always safe and calls for careful review.
*
* @param {function(new: T, string)} ctor A constructor.
* @return {function(*): T} A factory that takes content and returns a new
* instance (with default directionality, i.e. ctor.prototype.contentDir).
* @template T
* @private
*/
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_ = function(ctor) {
/**
* @param {string} content
* @constructor
* @extends {goog.soy.data.SanitizedContent}
*/
function InstantiableCtor(content) {
/** @override */
this.content = content;
}
InstantiableCtor.prototype = ctor.prototype;
/**
* Creates a ctor-type SanitizedContent instance.
*
* @param {?} content The content to put in the instance.
* @return {!goog.soy.data.SanitizedContent} The new instance. It is actually
* of type T above (ctor's type, a descendant of SanitizedContent), but
* there is no way to express that here.
*/
function sanitizedContentFactory(content) {
var result = new InstantiableCtor(String(content));
return result;
}
return sanitizedContentFactory;
};
// -----------------------------------------------------------------------------
// Sanitized content ordainers. Please use these with extreme caution (with the
// exception of markUnsanitizedText). A good recommendation is to limit usage
// of these to just a handful of files in your source tree where usages can be
// carefully audited.
/**
* Protects a string from being used in an noAutoescaped context.
*
* This is useful for content where there is significant risk of accidental
* unescaped usage in a Soy template. A great case is for user-controlled
* data that has historically been a source of vulernabilities.
*
* @param {?} content Text to protect.
* @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
* unknown and thus to be estimated when necessary. Default: null.
* @return {!goog.soy.data.UnsanitizedText} A wrapper that is rejected by the
* Soy noAutoescape print directive.
*/
soydata.markUnsanitizedText = function(content, opt_contentDir) {
return new goog.soy.data.UnsanitizedText(content, opt_contentDir);
};
/**
* Takes a leap of faith that the provided content is "safe" HTML.
*
* @param {?} content A string of HTML that can safely be embedded in
* a PCDATA context in your app. If you would be surprised to find that an
* HTML sanitizer produced `s` (e.g. it runs code or fetches bad URLs)
* and you wouldn't write a template that produces `s` on security or
* privacy grounds, then don't pass `s` here.
* @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
* unknown and thus to be estimated when necessary. Default: null.
* @return {!goog.soy.data.SanitizedHtml} Sanitized content wrapper that
* indicates to Soy not to escape when printed as HTML.
*/
soydata.VERY_UNSAFE.ordainSanitizedHtml =
soydata.$$makeSanitizedContentFactory_(goog.soy.data.SanitizedHtml);
/**
* Takes a leap of faith that the provided content is "safe" (non-attacker-
* controlled, XSS-free) Javascript.
*
* @param {?} content Javascript source that when evaluated does not
* execute any attacker-controlled scripts.
* @return {!goog.soy.data.SanitizedJs} Sanitized content wrapper that indicates
* to Soy not to escape when printed as Javascript source.
*/
soydata.VERY_UNSAFE.ordainSanitizedJs =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
goog.soy.data.SanitizedJs);
/**
* Takes a leap of faith that the provided content is "safe" to use as a URI
* in a Soy template.
*
* This creates a Soy SanitizedContent object which indicates to Soy there is
* no need to escape it when printed as a URI (e.g. in an href or src
* attribute), such as if it's already been encoded or if it's a Javascript:
* URI.
*
* @param {?} content A chunk of URI that the caller knows is safe to
* emit in a template.
* @return {!goog.soy.data.SanitizedUri} Sanitized content wrapper that
* indicates to Soy not to escape or filter when printed in URI context.
*/
soydata.VERY_UNSAFE.ordainSanitizedUri =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
goog.soy.data.SanitizedUri);
/**
* Takes a leap of faith that the provided content is "safe" to use as a
* TrustedResourceUri in a Soy template.
*
* This creates a Soy SanitizedContent object which indicates to Soy there is
* no need to filter it when printed as a TrustedResourceUri.
*
* @param {?} content A chunk of TrustedResourceUri such as that the caller
* knows is safe to emit in a template.
* @return {!goog.soy.data.SanitizedTrustedResourceUri} Sanitized content
* wrapper that indicates to Soy not to escape or filter when printed in
* TrustedResourceUri context.
*/
soydata.VERY_UNSAFE.ordainSanitizedTrustedResourceUri =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
goog.soy.data.SanitizedTrustedResourceUri);
/**
* Takes a leap of faith that the provided content is "safe" to use as an
* HTML attribute.
*
* @param {?} content An attribute name and value, such as
* `dir="ltr"`.
* @return {!goog.soy.data.SanitizedHtmlAttribute} Sanitized content wrapper
* that indicates to Soy not to escape when printed as an HTML attribute.
*/
soydata.VERY_UNSAFE.ordainSanitizedHtmlAttribute =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
goog.soy.data.SanitizedHtmlAttribute);
/**
* Takes a leap of faith that the provided content is "safe" to use as CSS
* in a style block.
*
* @param {?} content CSS, such as `color:#c3d9ff`.
* @return {!goog.soy.data.SanitizedCss} Sanitized CSS wrapper that indicates to
* Soy there is no need to escape or filter when printed in CSS context.
*/
soydata.VERY_UNSAFE.ordainSanitizedCss =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
goog.soy.data.SanitizedCss);
// -----------------------------------------------------------------------------
// Soy-generated utilities in the soy namespace. Contains implementations for
// common soyfunctions (e.g. keys()) and escaping/print directives.
/**
* Whether the locale is right-to-left.
*
* @type {boolean}
*/
soy.$$IS_LOCALE_RTL = goog.i18n.bidi.IS_RTL;
/**
* Builds an augmented map. The returned map will contain mappings from both
* the base map and the additional map. If the same key appears in both, then
* the value from the additional map will be visible, while the value from the
* base map will be hidden. The base map will be used, but not modified.
*
* @param {!Object} baseMap The original map to augment.
* @param {!Object} additionalMap A map containing the additional mappings.
* @return {!Object} An augmented map containing both the original and
* additional mappings.
*/
soy.$$augmentMap = function(baseMap, additionalMap) {
return soy.$$assignDefaults(soy.$$assignDefaults({}, additionalMap), baseMap);
};
/**
* Copies extra properties into an object if they do not already exist. The
* destination object is mutated in the process.
*
* @param {?} obj The destination object to update.
* @param {?} defaults An object with default properties to apply.
* @return {?} The destination object for convenience.
*/
soy.$$assignDefaults = function(obj, defaults) {
for (var key in defaults) {
if (!(key in obj)) {
obj[key] = defaults[key];
}
}
return obj;
};
/**
* Gets the keys in a map as an array. There are no guarantees on the order.
* @param {!Object} map The map to get the keys of.
* @return {!Array<string>} The array of keys in the given map.
*/
soy.$$getMapKeys = function(map) {
var mapKeys = [];
for (var key in map) {
mapKeys.push(key);
}
return mapKeys;
};
/**
* Returns the argument if it is not null.
*
* @param {T} val The value to check
* @return {T} val if is isn't null
* @template T
*/
soy.$$checkNotNull = function(val) {
if (val == null) {
throw Error('unexpected null value');
}
return val;
};
/**
* Parses the given string into a base 10 integer. Returns null if parse is
* unsuccessful.
* @param {?string|!goog.soy.data.UnsanitizedText} str The string to parse
* @return {?number} The string parsed as a base 10 integer, or null if
* unsuccessful
*/
soy.$$parseInt = function(str) {
var parsed = parseInt(String(str), 10);
return isNaN(parsed) ? null : parsed;
};
/**
* When equals comparison cannot be expressed using JS runtime semantics for ==,
* bail out to a runtime function. In practice, this only means comparisons
* of boolean and number are valid for equals, and everything else needs this
* function. Even "strings" have to go through this since in some cases they
* are just strings and in some cases they are UnsanitizedText. In addition,
* some sanitized content may be functions or objects that need to be coerced
* to a string.
* @param {?} obj1
* @param {?} obj2
* @return {boolean}
*/
soy.$$equals = function(obj1, obj2) {
/** @type {?} */
var valueOne;
/** @type {?} */
var valueTwo;
/**
* Convert text to string since that's what it really is. Or just keep it the
* same
* @param {?} obj
* @return {?}
*/
function unsanitizedTextOrObject(obj) {
if (obj instanceof goog.soy.data.UnsanitizedText) {
return obj.toString();
} else {
return obj;
}
}
valueOne = unsanitizedTextOrObject(obj1);
valueTwo = unsanitizedTextOrObject(obj2);
// Incremental DOM functions have to be coerced to a string. At runtime
// they are tagged with a type for ATTR or HTML. They both need to be
// the same to be considered structurally equal. Beware, as this is a
// very expensive function.
if (goog.isFunction(valueOne) && goog.isFunction(valueTwo)) {
if ((/** @type {?} */ (valueOne)).contentKind !==
(/** @type {?} */ (valueTwo)).contentKind) {
return false;
} else {
return valueOne.toString() === valueTwo.toString();
}
}
// Likewise for sanitized content.
if (valueOne instanceof goog.soy.data.SanitizedContent &&
valueTwo instanceof goog.soy.data.SanitizedContent) {
if (valueOne.contentKind != valueTwo.contentKind) {
return false;
} else {
return valueOne.toString() == valueTwo.toString();
}
}
// Rely on javascript semantics for comparing two objects.
return valueOne == valueTwo;
};
/**
* Parses the given string into a float. Returns null if parse is unsuccessful.
* @param {?string|!goog.soy.data.UnsanitizedText} str The string to parse
* @return {?number} The string parsed as a float, or null if unsuccessful.
*/
soy.$$parseFloat = function(str) {
var parsed = parseFloat(str);
return isNaN(parsed) ? null : parsed;
};
/**
* Returns a random integer.
* @return {number} a random integer between 0 and num
*/
soy.$$randomInt = function(/** number */ num) {
return Math.floor(Math.random() * num);
};
/**
* Rounds the given value to the closest decimal point left (negative numbers)
* or right (positive numbers) of the decimal point
*
* TODO(b/112835292): This is probably not something that anyone should use,
* instead they should use an i18n friendly number formatting routine.
*
* @return {number} the rounded value
*/
soy.$$round = function(/** number */ num, /** number */ numDigitsAfterPt) {
const shift = Math.pow(10, numDigitsAfterPt);
return Math.round(num * shift) / shift;
};
/** @return {boolean} returns whether the needle was found in the haystack */
soy.$$strContains = function(/** string */ haystack, /** string */ needle) {
return haystack.indexOf(needle) != -1;
};
/**
* Coerce the given value into a bool.
*
* For objects of type `SanitizedContent`, the contents are used to determine
* the boolean value; this is because the outer `SanitizedContent` object
* instance is always truthy (unless it's null).
*
* @param {*} arg The argument to coerce.
* @return {boolean}
*/
soy.$$coerceToBoolean = function(arg) {
if (arg instanceof goog.soy.data.SanitizedContent) {
return !!arg.getContent();
}
return !!arg;
};
/**
* Gets a consistent unique id for the given delegate template name. Two calls
* to this function will return the same id if and only if the input names are
* the same.
*
* <p> Important: This function must always be called with a string constant.
*
* <p> If Closure Compiler is not being used, then this is just this identity
* function. If Closure Compiler is being used, then each call to this function
* will be replaced with a short string constant, which will be consistent per
* input name.
*
* @param {string} delTemplateName The delegate template name for which to get a
* consistent unique id.
* @return {string} A unique id that is consistent per input name.
*
* @idGenerator {consistent}
*/
soy.$$getDelTemplateId = function(delTemplateName) {
return delTemplateName;
};
/**
* Map from registered delegate template key to the priority of the
* implementation.
* @const {!Object<number>}
* @private
*/
soy.$$DELEGATE_REGISTRY_PRIORITIES_ = {};
/**
* Map from registered delegate template key to the implementation function.
* @const {!Object<!Function>}
* @private
*/
soy.$$DELEGATE_REGISTRY_FUNCTIONS_ = {};
/**
* Registers a delegate implementation. If the same delegate template key (id
* and variant) has been registered previously, then priority values are
* compared and only the higher priority implementation is stored (if
* priorities are equal, an error is thrown).
*
* @param {string} delTemplateId The delegate template id.
* @param {string} delTemplateVariant The delegate template variant (can be
* empty string).
* @param {number} delPriority The implementation's priority value.
* @param {!Function} delFn The implementation function.
*/
soy.$$registerDelegateFn = function(
delTemplateId, delTemplateVariant, delPriority, delFn) {
var mapKey = 'key_' + delTemplateId + ':' + delTemplateVariant;
var currPriority = soy.$$DELEGATE_REGISTRY_PRIORITIES_[mapKey];
if (currPriority === undefined || delPriority > currPriority) {
// Registering new or higher-priority function: replace registry entry.
soy.$$DELEGATE_REGISTRY_PRIORITIES_[mapKey] = delPriority;
soy.$$DELEGATE_REGISTRY_FUNCTIONS_[mapKey] = delFn;
} else if (delPriority == currPriority) {
// Registering same-priority function: error.
throw Error(
'Encountered two active delegates with the same priority ("' +
delTemplateId + ':' + delTemplateVariant + '").');
} else {
// Registering lower-priority function: do nothing.
}
};
/**
* Retrieves the (highest-priority) implementation that has been registered for
* a given delegate template key (id and variant). If no implementation has
* been registered for the key, then the fallback is the same id with empty
* variant. If the fallback is also not registered, and allowsEmptyDefault is
* true, then returns an implementation that is equivalent to an empty template
* (i.e. rendered output would be empty string).
*
* @param {string|!goog.soy.data.UnsanitizedText} delTemplateId The
* delegate template id.
* @param {string|!goog.soy.data.UnsanitizedText} delTemplateVariant
* The delegate template variant (can be empty string).
* @param {boolean} allowsEmptyDefault Whether to default to the empty template
* function if there's no active implementation.
* @return {!Function} The retrieved implementation function.
*/
soy.$$getDelegateFn = function(
delTemplateId, delTemplateVariant, allowsEmptyDefault) {
var delFn = soy.$$DELEGATE_REGISTRY_FUNCTIONS_[
'key_' + delTemplateId + ':' + delTemplateVariant];
if (! delFn && delTemplateVariant != '') {
// Fallback to empty variant.
delFn = soy.$$DELEGATE_REGISTRY_FUNCTIONS_['key_' + delTemplateId + ':'];
}
if (delFn) {
return delFn;
} else if (allowsEmptyDefault) {
return soy.$$EMPTY_TEMPLATE_FN_;
} else {
throw Error(
'Found no active impl for delegate call to "' + delTemplateId +
(delTemplateVariant ? ':' + delTemplateVariant : '') +
'" (and delcall does not set allowemptydefault="true").');
}
};
/**
* Private helper soy.$$getDelegateFn(). This is the empty template function
* that is returned whenever there's no delegate implementation found.
*
* Note: This is also used for idom.
*
* @return {string}
* @private
*/
soy.$$EMPTY_TEMPLATE_FN_ = function() {
return '';
};
// -----------------------------------------------------------------------------
// Internal sanitized content wrappers.
/**
* Creates a SanitizedContent factory for SanitizedContent types for internal
* Soy let and param blocks.
*
* This is a hack within Soy so that SanitizedContent objects created via let
* and param blocks will truth-test as false if they are empty string.
* Tricking the Javascript runtime to treat empty SanitizedContent as falsey is
* not possible, and changing the Soy compiler to wrap every boolean statement
* for just this purpose is impractical. Instead, we just avoid wrapping empty
* string as SanitizedContent, since it's a no-op for empty strings anyways.
*
* @param {function(new: T)} ctor A constructor.
* @return {function(*, ?goog.i18n.bidi.Dir=): (T|!soydata.$$EMPTY_STRING_)}
* A factory that takes content and an optional content direction and
* returns a new instance, or an empty string. If the content direction is
* undefined, ctor.prototype.contentDir is used.
* @template T
* @private
*/
soydata.$$makeSanitizedContentFactoryForInternalBlocks_ = function(ctor) {
/**
* @param {string} content
* @constructor
* @extends {goog.soy.data.SanitizedContent}
*/
function InstantiableCtor(content) {
/** @override */
this.content = content;
}
InstantiableCtor.prototype = ctor.prototype;
/**
* Creates a ctor-type SanitizedContent instance.
*
* @param {?} content The content to put in the instance.
* @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction. If
* undefined, ctor.prototype.contentDir is used.
* @return {!goog.soy.data.SanitizedContent|!soydata.$$EMPTY_STRING_} The new
* instance, or an empty string. A new instance is actually of type T
* above (ctor's type, a descendant of SanitizedContent), but there's no
* way to express that here.
*/
function sanitizedContentFactory(content, opt_contentDir) {
var contentString = String(content);
if (!contentString) {
return soydata.$$EMPTY_STRING_.VALUE;
}
var result = new InstantiableCtor(contentString);
if (opt_contentDir !== undefined) {
result.contentDir = opt_contentDir;
}
return result;
}
return sanitizedContentFactory;
};
/**
* Creates a SanitizedContent factory for SanitizedContent types that should
* always have their default directionality for internal Soy let and param
* blocks.
*
* This is a hack within Soy so that SanitizedContent objects created via let
* and param blocks will truth-test as false if they are empty string.
* Tricking the Javascript runtime to treat empty SanitizedContent as falsey is
* not possible, and changing the Soy compiler to wrap every boolean statement
* for just this purpose is impractical. Instead, we just avoid wrapping empty
* string as SanitizedContent, since it's a no-op for empty strings anyways.
*
* @param {function(new: T)} ctor A constructor.
* @return {function(*): (T|!soydata.$$EMPTY_STRING_)} A
* factory that takes content and returns a
* new instance (with default directionality, i.e.
* ctor.prototype.contentDir), or an empty string.
* @template T
* @private
*/
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_ =
function(ctor) {
/**
* @param {string} content
* @constructor
* @extends {goog.soy.data.SanitizedContent}
*/
function InstantiableCtor(content) {
/** @override */
this.content = content;
}
InstantiableCtor.prototype = ctor.prototype;
/**
* Creates a ctor-type SanitizedContent instance.
*
* @param {?} content The content to put in the instance.
* @return {!goog.soy.data.SanitizedContent|!soydata.$$EMPTY_STRING_} The new
* instance, or an empty string. A new instance is actually of type T
* above (ctor's type, a descendant of SanitizedContent), but there's no
* way to express that here.
*/
function sanitizedContentFactory(content) {
var contentString = String(content);
if (!contentString) {
return soydata.$$EMPTY_STRING_.VALUE;
}
var result = new InstantiableCtor(contentString);
return result;
}
return sanitizedContentFactory;
};
/**
* Creates kind="text" block contents (internal use only).
*
* @param {?} content Text.
* @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
* unknown and thus to be estimated when necessary. Default: null.
* @return {!goog.soy.data.UnsanitizedText|!soydata.$$EMPTY_STRING_} Wrapped
* result.
*/
soydata.$$markUnsanitizedTextForInternalBlocks = function(
content, opt_contentDir) {
var contentString = String(content);
if (!contentString) {
return soydata.$$EMPTY_STRING_.VALUE;
}
return new goog.soy.data.UnsanitizedText(contentString, opt_contentDir);
};
/**
* Creates kind="html" block contents (internal use only).
*
* @param {?} content Text.
* @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
* unknown and thus to be estimated when necessary. Default: null.
* @return {!goog.soy.data.SanitizedHtml|!soydata.$$EMPTY_STRING_} Wrapped
* result.
*/
soydata.VERY_UNSAFE.$$ordainSanitizedHtmlForInternalBlocks =
soydata.$$makeSanitizedContentFactoryForInternalBlocks_(
goog.soy.data.SanitizedHtml);
/**
* Creates kind="js" block contents (internal use only).
*
* @param {?} content Text.
* @return {!goog.soy.data.SanitizedJs|!soydata.$$EMPTY_STRING_} Wrapped result.
*/
soydata.VERY_UNSAFE.$$ordainSanitizedJsForInternalBlocks =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
goog.soy.data.SanitizedJs);
/**
* Creates kind="trustedResourceUri" block contents (internal use only).
*
* @param {?} content Text.
* @return {!goog.soy.data.SanitizedTrustedResourceUri|!soydata.$$EMPTY_STRING_}
* Wrapped result.
*/
soydata.VERY_UNSAFE.$$ordainSanitizedTrustedResourceUriForInternalBlocks =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
goog.soy.data.SanitizedTrustedResourceUri);
/**
* Creates kind="uri" block contents (internal use only).
*
* @param {?} content Text.
* @return {!goog.soy.data.SanitizedUri|!soydata.$$EMPTY_STRING_} Wrapped
* result.
*/
soydata.VERY_UNSAFE.$$ordainSanitizedUriForInternalBlocks =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
goog.soy.data.SanitizedUri);
/**
* Creates kind="attributes" block contents (internal use only).
*
* @param {?} content Text.
* @return {!goog.soy.data.SanitizedHtmlAttribute|!soydata.$$EMPTY_STRING_}
* Wrapped result.
*/
soydata.VERY_UNSAFE.$$ordainSanitizedAttributesForInternalBlocks =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
goog.soy.data.SanitizedHtmlAttribute);
/**
* Creates kind="css" block contents (internal use only).
*
* @param {?} content Text.
* @return {!goog.soy.data.SanitizedCss|!soydata.$$EMPTY_STRING_} Wrapped
* result.
*/
soydata.VERY_UNSAFE.$$ordainSanitizedCssForInternalBlocks =
soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
goog.soy.data.SanitizedCss);
// -----------------------------------------------------------------------------
// Escape/filter/normalize.
/**
* Returns a SanitizedHtml object for a particular value. The content direction
* is preserved.
*
* This HTML-escapes the value unless it is already SanitizedHtml. Escapes
* double quote '"' in addition to '&', '<', and '>' so that a string can be
* included in an HTML tag attribute value within double quotes.
*
* @param {?} value The value to convert. If it is already a SanitizedHtml
* object, it is left alone.
* @return {!goog.soy.data.SanitizedHtml} An escaped version of value.
*/
soy.$$escapeHtml = function(value) {
return soydata.SanitizedHtml.from(value);
};
/**
* Strips unsafe tags to convert a string of untrusted HTML into HTML that
* is safe to embed. The content direction is preserved.
*
* @param {?} value The string-like value to be escaped. May not be a string,
* but the value will be coerced to a string.
* @param {?Array<string>=} opt_safeTags Additional tag names to whitelist.
* @return {!goog.soy.data.SanitizedHtml} A sanitized and normalized version of
* value.
*/
soy.$$cleanHtml = function(value, opt_safeTags) {
if (soy.checks.isHtml(value)) {
return /** @type {!goog.soy.data.SanitizedHtml} */ (value);
}
var tagWhitelist;
if (opt_safeTags) {
tagWhitelist = goog.object.createSet(opt_safeTags);
goog.object.extend(tagWhitelist, soy.esc.$$SAFE_TAG_WHITELIST_);
} else {
tagWhitelist = soy.esc.$$SAFE_TAG_WHITELIST_;
}
return soydata.VERY_UNSAFE.ordainSanitizedHtml(
soy.$$stripHtmlTags(value, tagWhitelist), soydata.getContentDir(value));
};
// LINT.IfChange(htmlToText)
/**
* Converts HTML to plain text by removing tags, normalizing spaces and
* converting entities.
*
* The last two parameters are idom functions.
* @param {(string|?goog.soy.data.SanitizedHtml|?goog.soy.data.UnsanitizedText|
* !soydata.IdomFunction|!Function|null|undefined)}
* value
* @return {string}
*/
soy.$$htmlToText = function(value) {
if (value == null) {
return '';
}
if (soydata.isContentKind_(value, goog.soy.data.SanitizedContentKind.TEXT)) {
return value.toString();
}
if (!soydata.isContentKind_(value, goog.soy.data.SanitizedContentKind.HTML)) {
return goog.asserts.assertString(value);
}
var html = value.toString();
var text = '';
var start = 0;
// Tag name to stop removing contents, e.g. '/script'.
var removingUntil = '';
// Tag name to stop preserving whitespace, e.g. '/pre'.
var wsPreservingUntil = '';
var tagRe =
/<(?:!--.*?--|(?:!|(\/?[a-z][\w:-]*))(?:[^>'"]|"[^"]*"|'[^']*')*)>|$/gi;
for (var match; match = tagRe.exec(html);) {
var tag = match[1];
var offset = match.index;
if (!removingUntil) {
var chunk = html.substring(start, offset);
chunk = goog.string.unescapeEntities(chunk);
if (!wsPreservingUntil) {
// We are not inside <pre>, normalize spaces.
chunk = chunk.replace(/\s+/g, ' ');
if (!/\S$/.test(text)) {
// Strip leading space unless after non-whitespace.
chunk = chunk.replace(/^ /, '');
}
}
text += chunk;
if (/^(script|style|textarea|title)$/i.test(tag)) {
removingUntil = '/' + tag.toLowerCase();
} else if (/^br$/i.test(tag)) {
// <br> adds newline even after newline.
text += '\n';
} else if (soy.BLOCK_TAGS_RE_.test(tag)) {
if (/[^\n]$/.test(text)) {
// Block tags don't add more consecutive newlines.
text += '\n';
}
if (/^pre$/i.test(tag)) {
wsPreservingUntil = '/' + tag.toLowerCase();
} else if (tag.toLowerCase() == wsPreservingUntil) {
wsPreservingUntil = '';
}
} else if (/^(td|th)$/i.test(tag)) {
// We add \t even after newline to support more leading <td>.
text += '\t';
}
} else if (removingUntil == tag.toLowerCase()) {
removingUntil = '';
}
if (!match[0]) {
break;
}
start = offset + match[0].length;
}
return text;
};
/** @private @const */
soy.BLOCK_TAGS_RE_ =
/^\/?(address|blockquote|dd|div|dl|dt|h[1-6]|hr|li|ol|p|pre|table|tr|ul)$/i;
// LINT.ThenChange(
// ../../../third_party/java_src/soy/java/com/google/template/soy/basicfunctions/HtmlToText.java,
// ../../../third_party/java_src/soy/python/runtime/sanitize.py:htmlToText)
/**
* Escapes HTML, except preserves entities.
*
* Used mainly internally for escaping message strings in attribute and rcdata
* context, where we explicitly want to preserve any existing entities.
*
* @param {?} value Value to normalize.
* @return {string} A value safe to insert in HTML without any quotes or angle
* brackets.
*/
soy.$$normalizeHtml = function(value) {
return soy.esc.$$normalizeHtmlHelper(value);
};
/**
* Escapes HTML special characters in a string so that it can be embedded in
* RCDATA.
* <p>
* Escapes HTML special characters so that the value will not prematurely end
* the body of a tag like `<textarea>` or `<title>`. RCDATA tags
* cannot contain other HTML entities, so it is not strictly necessary to escape
* HTML special characters except when part of that text looks like an HTML
* entity or like a close tag : `</textarea>`.
* <p>
* Will normalize known safe HTML to make sure that sanitized HTML (which could
* contain an innocuous `</textarea>` don't prematurely end an RCDATA
* element.
*
* @param {?} value The string-like value to be escaped. May not be a string,
* but the value will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeHtmlRcdata = function(value) {
if (soy.checks.isHtml(value)) {
return soy.esc.$$normalizeHtmlHelper(value.getContent());
}
return soy.esc.$$escapeHtmlHelper(value);
};
/**
* Matches any/only HTML5 void elements' start tags.
* See http://www.w3.org/TR/html-markup/syntax.html#syntax-elements
* @const {!RegExp}
* @private
*/
soy.$$HTML5_VOID_ELEMENTS_ = new RegExp(
'^<(?:area|base|br|col|command|embed|hr|img|input' +
'|keygen|link|meta|param|source|track|wbr)\\b');
/**
* Removes HTML tags from a string of known safe HTML.
* If opt_tagWhitelist is not specified or is empty, then
* the result can be used as an attribute value.
*
* @param {?} value The HTML to be escaped. May not be a string, but the
* value will be coerced to a string.
* @param {?Object<string, boolean>=} opt_tagWhitelist Has an own property whose
* name is a lower-case tag name and whose value is `1` for
* each element that is allowed in the output.
* @return {string} A representation of value without disallowed tags,
* HTML comments, or other non-text content.
*/
soy.$$stripHtmlTags = function(value, opt_tagWhitelist) {
if (!opt_tagWhitelist) {
// If we have no white-list, then use a fast track which elides all tags.
return String(value).replace(soy.esc.$$HTML_TAG_REGEX_, '')
// This is just paranoia since callers should normalize the result
// anyway, but if they didn't, it would be necessary to ensure that
// after the first replace non-tag uses of < do not recombine into
// tags as in "<<foo>script>alert(1337)</<foo>script>".
.replace(soy.esc.$$LT_REGEX_, '<');
}
// Escapes '[' so that we can use [123] below to mark places where tags
// have been removed.
var html = String(value).replace(/\[/g, '[');
// Consider all uses of '<' and replace whitelisted tags with markers like
// [1] which are indices into a list of approved tag names.
// Replace all other uses of < and > with entities.
var tags = [];
var attrs = [];
html = html.replace(
soy.esc.$$HTML_TAG_REGEX_,
function(tok, tagName) {
if (tagName) {
tagName = tagName.toLowerCase();
if (opt_tagWhitelist.hasOwnProperty(tagName) &&
opt_tagWhitelist[tagName]) {
var isClose = tok.charAt(1) == '/';
var index = tags.length;
var start = '</';
var attributes = '';
if (!isClose) {
start = '<';
var match;
while ((match = soy.esc.$$HTML_ATTRIBUTE_REGEX_.exec(tok))) {
if (match[1] && match[1].toLowerCase() == 'dir') {
var dir = match[2];
if (dir) {
if (dir.charAt(0) == '\'' || dir.charAt(0) == '"') {
dir = dir.substr(1, dir.length - 2);
}
dir = dir.toLowerCase();
if (dir == 'ltr' || dir == 'rtl' || dir == 'auto') {
attributes = ' dir="' + dir + '"';
}
}
break;
}
}
soy.esc.$$HTML_ATTRIBUTE_REGEX_.lastIndex = 0;
}
tags[index] = start + tagName + '>';
attrs[index] = attributes;
return '[' + index + ']';
}
}
return '';
});
// Escape HTML special characters. Now there are no '<' in html that could
// start a tag.
html = soy.esc.$$normalizeHtmlHelper(html);
var finalCloseTags = soy.$$balanceTags_(tags);
// Now html contains no tags or less-than characters that could become
// part of a tag via a replacement operation and tags only contains
// approved tags.
// Reinsert the white-listed tags.
html = html.replace(/\[(\d+)\]/g, function(_, index) {
if (attrs[index] && tags[index]) {
return tags[index].substr(0, tags[index].length - 1) + attrs[index] + '>';
}
return tags[index];
});
// Close any still open tags.
// This prevents unclosed formatting elements like <ol> and <table> from
// breaking the layout of containing HTML.
return html + finalCloseTags;
};
/**
* Make sure that tag boundaries are not broken by Safe CSS when embedded in a
* `<style>` element.
* @param {string} css
* @return {string}
* @private
*/
soy.$$embedCssIntoHtml_ = function(css) {
// Port of a method of the same name in
// com.google.template.soy.shared.restricted.Sanitizers
return css.replace(/<\//g, '<\\/').replace(/\]\]>/g, ']]\\>');
};
/**
* Throw out any close tags that don't correspond to start tags.
* If `<table>` is used for formatting, embedded HTML shouldn't be able
* to use a mismatched `</table>` to break page layout.
*
* @param {!Array<string>} tags Array of open/close tags (e.g. '<p>', '</p>')
* that will be modified in place to be either an open tag, one or more close
* tags concatenated, or the empty string.
* @return {string} zero or more closed tags that close all elements that are
* opened in tags but not closed.
* @private
*/
soy.$$balanceTags_ = function(tags) {
var open = [];
for (var i = 0, n = tags.length; i < n; ++i) {
var tag = tags[i];
if (tag.charAt(1) == '/') {
var openTagIndex = goog.array.lastIndexOf(open, tag);
if (openTagIndex < 0) {
tags[i] = ''; // Drop close tag with no corresponding open tag.
} else {
tags[i] = open.slice(openTagIndex).reverse().join('');
open.length = openTagIndex;
}
} else if (tag == '<li>' &&
goog.array.lastIndexOf(open, '</ol>') < 0 &&
goog.array.lastIndexOf(open, '</ul>') < 0) {
// Drop <li> if it isn't nested in a parent <ol> or <ul>.
tags[i] = '';
} else if (!soy.$$HTML5_VOID_ELEMENTS_.test(tag)) {
open.push('</' + tag.substring(1));
}
}
return open.reverse().join('');
};
/**
* Escapes HTML special characters in an HTML attribute value.
*
* @param {?} value The HTML to be escaped. May not be a string, but the
* value will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeHtmlAttribute = function(value) {
// NOTE: We don't accept ATTRIBUTES here because ATTRIBUTES is actually not
// the attribute value context, but instead k/v pairs.
if (soy.checks.isHtml(value)) {
// NOTE: After removing tags, we also escape quotes ("normalize") so that
// the HTML can be embedded in attribute context.
return soy.esc.$$normalizeHtmlHelper(
soy.$$stripHtmlTags(value.getContent()));
}
return soy.esc.$$escapeHtmlHelper(value);
};
/**
* Escapes HTML special characters in an HTML attribute value containing HTML
* code, such as <iframe srcdoc>.
*
* @param {?} value The HTML to be escaped. May not be a string, but the
* value will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeHtmlHtmlAttribute = function(value) {
return String(soy.$$escapeHtml(value));
};
/**
* Escapes HTML special characters in a string including space and other
* characters that can end an unquoted HTML attribute value.
*
* @param {?} value The HTML to be escaped. May not be a string, but the
* value will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeHtmlAttributeNospace = function(value) {
if (soy.checks.isHtml(value)) {
return soy.esc.$$normalizeHtmlNospaceHelper(
soy.$$stripHtmlTags(value.getContent()));
}
return soy.esc.$$escapeHtmlNospaceHelper(value);
};
/**
* Filters out strings that cannot be a substring of a valid HTML attribute.
*
* Note the input is expected to be key=value pairs.
*
* @param {?} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} A valid HTML attribute name part or name/value pair.
* `"zSoyz"` if the input is invalid.
*/
soy.$$filterHtmlAttributes = function(value) {
// NOTE: Explicitly no support for SanitizedContentKind.HTML, since that is
// meaningless in this context, which is generally *between* html attributes.
if (soy.checks.isAttribute(value)) {
// Add a space at the end to ensure this won't get merged into following
// attributes, unless the interpretation is unambiguous (ending with quotes
// or a space).
return value.getContent().replace(/([^"'\s])$/, '$1 ');
}
// TODO: Dynamically inserting attributes that aren't marked as trusted is
// probably unnecessary. Any filtering done here will either be inadequate
// for security or not flexible enough. Having clients use kind="attributes"
// in parameters seems like a wiser idea.
return soy.esc.$$filterHtmlAttributesHelper(value);
};
/**
* Allows only decimal and floating-point numbers.
* @param {?} value
* @return {number} The number.
*/
soy.$$filterNumber = function(value) {
return /^\d*\.?\d+$/.test(value) ? value : 'zSoyz';
};
/**
* Filters out strings that cannot be a substring of a valid HTML element name.
*
* @param {?} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} A valid HTML element name part.
* `"zSoyz"` if the input is invalid.
*/
soy.$$filterHtmlElementName = function(value) {
// NOTE: We don't accept any SanitizedContent here. HTML indicates valid
// PCDATA, not tag names. A sloppy developer shouldn't be able to cause an
// exploit:
// ... {let userInput}script src=http://evil.com/evil.js{/let} ...
// ... {param tagName kind="html"}{$userInput}{/param} ...
// ... <{$tagName}>Hello World</{$tagName}>
return soy.esc.$$filterHtmlElementNameHelper(value);
};
/**
* Escapes characters in the value to make it valid content for a JS string
* literal.
*
* @param {?} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeJsString = function(value) {
return soy.esc.$$escapeJsStringHelper(value);
};
/**
* Encodes a value as a JavaScript literal.
*
* @param {?} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} A JavaScript code representation of the input.
*/
soy.$$escapeJsValue = function(value) {
// We surround values with spaces so that they can't be interpolated into
// identifiers by accident.
// We could use parentheses but those might be interpreted as a function call.
if (value == null) { // Intentionally matches undefined.
// Java returns null from maps where there is no corresponding key while
// JS returns undefined.
// We always output null for compatibility with Java which does not have a
//