1
// Copyright 2014 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15

16
goog.provide('goog.labs.html.AttributeRewriter');
17
goog.provide('goog.labs.html.AttributeValue');
18
goog.provide('goog.labs.html.attributeRewriterPresubmitWorkaround');
19

20

21
/**
22
 * The type of an attribute value.
23
 * <p>
24
 * Many HTML attributes contain structured data like URLs, CSS, or even entire
25
 * HTML documents, so the type is a union of several variants.
26
 *
27
 * @typedef {(string |
28
 *            goog.html.SafeHtml | goog.html.SafeStyle | goog.html.SafeUrl)}
29
 */
30
goog.labs.html.AttributeValue;
31

32

33
/**
34
 * A function that takes an attribute value, and returns a safe value.
35
 * <p>
36
 * Since rewriters can be chained, a rewriter must be able to accept the output
37
 * of another rewriter, instead of just a string though a rewriter that coerces
38
 * its input to a string before checking its safety will fail safe.
39
 * <p>
40
 * The meaning of the result is:
41
 * <table>
42
 *   <tr><td>{@code null}</td>
43
 *       <td>Unsafe.  The attribute should not be output.</tr>
44
 *   <tr><td>a string</td>
45
 *       <td>The plain text (not HTML-entity encoded) of a safe attribute
46
 *           value.</td>
47
 *   <tr><td>a {@link goog.html.SafeHtml}</td>
48
 *       <td>A fragment that is safe to be included as embedded HTML as in
49
 *           {@code <iframe srchtml="...">}</td></tr>
50
 *   <tr><td>a {@link goog.html.SafeUrl}</td>
51
 *       <td>A URL that does not need to be further checked against the URL
52
 *           white-list.</td></tr>
53
 *   <tr><td>a {@link goog.html.SafeStyle}</td>
54
 *       <td>A safe value for a <code>style="..."</code> attribute.</td></tr>
55
 * </table>
56
 * <p>
57
 * Implementations are responsible for making sure that "safe" complies with
58
 * the contract established by the safe string types in {@link goog.html}.
59
 * </p>
60
 *
61
 * @typedef {function(goog.labs.html.AttributeValue) :
62
 *           goog.labs.html.AttributeValue}
63
 */
64
goog.labs.html.AttributeRewriter;
65

66

67
/**
68
 * g4 presubmit complains about requires of this file because its clients
69
 * don't use any symbols from it outside JSCompiler comment annotations.
70
 * genjsdeps.sh doesn't generate the right dependency graph unless this
71
 * file is required.
72
 * Clients can mention this noop.
73
 */
74
goog.labs.html.attributeRewriterPresubmitWorkaround = function() {};
75

76