Version 1.10.0-dev.1.3
svn merge -c 45153 https://dart.googlecode.com/svn/branches/bleeding_edge trunk
git-svn-id: http://dart.googlecode.com/svn/trunk@45175 260f80e4-7a28-3924-810f-c04153c831b5
diff --git a/sdk/lib/convert/html_escape.dart b/sdk/lib/convert/html_escape.dart
index f4be4c6..2c54b91 100644
--- a/sdk/lib/convert/html_escape.dart
+++ b/sdk/lib/convert/html_escape.dart
@@ -4,7 +4,26 @@
part of dart.convert;
-// TODO(floitsch) - Document - Issue 13097
+/**
+ * A `String` converter that converts characters to HTML entities.
+ *
+ * This is intended to sanitice text before inserting the text into an HTML
+ * document. Characters that are meaningful in HTML are converted to
+ * HTML entities (like `&` for `&`).
+ *
+ * The general converter escapes all characters that are meaningful in HTML
+ * attributes or normal element context. Elements with special content types
+ * (like CSS or JavaScript) may need a more specialized escaping that
+ * understands that content type.
+ *
+ * If the context where the text will be inserted is known in more detail,
+ * it's possible to omit escaping some characters (like quotes when not
+ * inside an attribute value).
+ *
+ * The escaped text should only be used inside quoted HTML attributes values
+ * or as text content of a normal element. Using the escaped text inside a
+ * tag, but not inside a quoted attribute value, is still dangerous.
+ */
const HtmlEscape HTML_ESCAPE = const HtmlEscape();
/**
@@ -28,6 +47,13 @@
final bool escapeQuot;
/** Whether to escape "'" (apostrophe). */
final bool escapeApos;
+ /**
+ * Whether to escape "/" (forward slash, solidus).
+ *
+ * Escaping a slash is recommended to avoid cross-site scripting attacks by
+ * [the Open Web Application Security Project](https://www.owasp.org/index.php/XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet#RULE_.231_-_HTML_Escape_Before_Inserting_Untrusted_Data_into_HTML_Element_Content)
+ */
+ final bool escapeSlash;
/**
* Default escaping mode which escape all characters.
@@ -40,7 +66,7 @@
* which require escapes matching their particular content syntax.
*/
static const HtmlEscapeMode UNKNOWN =
- const HtmlEscapeMode._('unknown', true, true, true);
+ const HtmlEscapeMode._('unknown', true, true, true, true);
/**
* Escaping mode for text going into double-quoted HTML attribute values.
@@ -51,7 +77,7 @@
* Escapes only double quotes (`"`) but not single quotes (`'`).
*/
static const HtmlEscapeMode ATTRIBUTE =
- const HtmlEscapeMode._('attribute', false, true, false);
+ const HtmlEscapeMode._('attribute', false, true, false, false);
/**
* Escaping mode for text going into single-quoted HTML attribute values.
@@ -62,7 +88,7 @@
* Escapes only single quotes (`'`) but not double quotes (`"`).
*/
static const HtmlEscapeMode SQ_ATTRIBUTE =
- const HtmlEscapeMode._('attribute', false, false, true);
+ const HtmlEscapeMode._('attribute', false, false, true, false);
/**
* Escaping mode for text going into HTML element content.
@@ -74,22 +100,26 @@
* Escapes `<` and `>` characters.
*/
static const HtmlEscapeMode ELEMENT =
- const HtmlEscapeMode._('element', true, false, false);
+ const HtmlEscapeMode._('element', true, false, false, false);
- const HtmlEscapeMode._(
- this._name, this.escapeLtGt, this.escapeQuot, this.escapeApos);
+ const HtmlEscapeMode._(this._name,
+ this.escapeLtGt,
+ this.escapeQuot,
+ this.escapeApos,
+ this.escapeSlash);
/**
* Create a custom escaping mode.
*
* All modes escape `&`.
* The mode can further be set to escape `<` and `>` ([escapeLtGt]),
- * `"` ([escapeQuot]) and/or `'` ([escapeApos]).
+ * `"` ([escapeQuot]), `'` ([escapeApos]), and/or `/` ([escapeSlash]).
*/
const HtmlEscapeMode({String name: "custom",
this.escapeLtGt: false,
this.escapeQuot: false,
- this.escapeApos: false}) : _name = name;
+ this.escapeApos: false,
+ this.escapeSlash: false}) : _name = name;
String toString() => _name;
}
@@ -108,6 +138,8 @@
* * `'` (apostrophe) when inside a single-quoted attribute value.
* Apostrophe is escaped as `'` instead of `'` since
* not all browsers understand `'`.
+ * * `/` (slash) is recommended to be escaped because it may be used
+ * to terminate an element in some HTML dialects.
*
* Escaping `>` (greater than) isn't necessary, but the result is often
* found to be easier to read if greater-than is also escaped whenever
@@ -150,6 +182,7 @@
case "'": if (mode.escapeApos) replacement = '''; break;
case '<': if (mode.escapeLtGt) replacement = '<'; break;
case '>': if (mode.escapeLtGt) replacement = '>'; break;
+ case '/': if (mode.escapeSlash) replacement = '.'; break;
}
if (replacement != null) {
if (result == null) result = new StringBuffer();
diff --git a/tests/lib/convert/html_escape_test.dart b/tests/lib/convert/html_escape_test.dart
index 787ae34..a4596dc 100644
--- a/tests/lib/convert/html_escape_test.dart
+++ b/tests/lib/convert/html_escape_test.dart
@@ -10,8 +10,8 @@
const _TEST_INPUT = """<A </test> of \xA0 "double" & 'single' values>""";
-const _OUTPUT_UNKNOWN = '<A </test> of \xA0 "double" & '
- ''single' values>';
+const _OUTPUT_UNKNOWN = '<A <.test> of \xA0 "double" '
+ '& 'single' values>';
const _OUTPUT_ATTRIBUTE =
"<A </test> of \xA0 "double" & 'single' values>";
@@ -48,8 +48,7 @@
void _testTransform(HtmlEscape escape, String input, String expected) {
var controller = new StreamController(sync: true);
- var stream = controller.stream
- .transform(escape);
+ var stream = controller.stream.transform(escape);
var done = false;
int count = 0;
diff --git a/tools/VERSION b/tools/VERSION
index 82d7fec..287630a 100644
--- a/tools/VERSION
+++ b/tools/VERSION
@@ -28,4 +28,4 @@
MINOR 10
PATCH 0
PRERELEASE 1
-PRERELEASE_PATCH 2
+PRERELEASE_PATCH 3
