UNPKG

4.96 kBTypeScriptView Raw
1// Type definitions for he v1.1.1
2// Project: https://github.com/mathiasbynens/he
3// Definitions by: Simon Edwards <https://github.com/sedwards2009>
4// Robin Tregaskis <https://github.com/lokidokicoki>
5// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
6
7// he - "HTML Entities" - A high quality pair of HTML encode and decode functions.
8
9export as namespace he;
10
11export var version: string;
12
13export interface EncodeOptions {
14 /**
15 * The default value for the useNamedReferences option is false. This
16 * means that encode() will not use any named character references
17 * (e.g. &copy;) in the output — hexadecimal escapes (e.g. &#xA9;) will
18 * be used instead. Set it to true to enable the use of named references.
19 */
20 useNamedReferences?: boolean | undefined;
21
22 /**
23 * The default value for the decimal option is false. If the option is
24 * enabled, encode will generally use decimal escapes (e.g. &#169;)
25 * rather than hexadecimal escapes (e.g. &#xA9;). Beside of this
26 * replacement, the basic behavior remains the same when combined with
27 * other options. For example: if both options useNamedReferences and
28 * decimal are enabled, named references (e.g. &copy;) are used over
29 * decimal escapes. HTML entities without a named reference are encoded
30 * using decimal escapes.
31 */
32 decimal?: boolean | undefined;
33
34 /**
35 * The default value for the encodeEverything option is false. This means
36 * that encode() will not use any character references for printable ASCII
37 * symbols that don’t need escaping. Set it to true to encode every symbol
38 * in the input string. When set to true, this option takes precedence over
39 * allowUnsafeSymbols (i.e. setting the latter to true in such a case has
40 * no effect).
41 */
42 encodeEverything?: boolean | undefined;
43
44 /**
45 * The default value for the strict option is false. This means that
46 * encode() will encode any HTML text content you feed it, even if it
47 * contains any symbols that cause parse errors. To throw an error when such
48 * invalid HTML is encountered, set the strict option to true. This option
49 * makes it possible to use he as part of HTML parsers and HTML validators.
50 */
51 strict?: boolean | undefined;
52
53 /**
54 * The default value for the allowUnsafeSymbols option is false. This means
55 * that characters that are unsafe for use in HTML content (&, <, >, ", ',
56 * and `) will be encoded. When set to true, only non-ASCII characters will
57 * be encoded. If the encodeEverything option is set to true, this option
58 * will be ignored.
59 */
60 allowUnsafeSymbols?: boolean | undefined;
61}
62
63export interface Encode {
64 /**
65 * Encode a string of text
66 *
67 * This function takes a string of text and encodes (by default) any symbols
68 * that aren’t printable ASCII symbols and &, <, >, ", ', and `, replacing
69 * them with character references.
70 *
71 * As long as the input string contains allowed code points only, the return
72 * value of this function is always valid HTML. Any (invalid) code points
73 * that cannot be represented using a character reference in the input are
74 * not encoded.
75 */
76 (text: string, options?: EncodeOptions): string;
77
78 options: EncodeOptions;
79}
80export var encode: Encode;
81
82export interface DecodeOptions {
83 /**
84 * The default value for the isAttributeValue option is false. This means
85 * that decode() will decode the string as if it were used in a text
86 * context in an HTML document. HTML has different rules for parsing
87 * character references in attribute values — set this option to true to
88 * treat the input string as if it were used as an attribute value.
89 */
90 isAttributeValue?: boolean | undefined;
91
92 /**
93 * The default value for the strict option is false. This means that
94 * decode() will decode any HTML text content you feed it, even if it
95 * contains any entities that cause parse errors. To throw an error when
96 * such invalid HTML is encountered, set the strict option to true. This
97 * option makes it possible to use he as part of HTML parsers and HTML
98 * validators.
99 */
100 strict?: boolean | undefined;
101}
102
103export interface Decode {
104 /**
105 * Decode a string of HTML text
106 *
107 * This function takes a string of HTML and decodes any named and numerical
108 * character references in it using the algorithm described in section
109 * 12.2.4.69 of the HTML spec.
110 */
111 (html: string, options?: DecodeOptions): string;
112
113 options: DecodeOptions;
114}
115export var decode: Decode;
116
117/**
118 * Escape XML entities
119 *
120 * This function takes a string of text and escapes it for use in text
121 * contexts in XML or HTML documents. Only the following characters are
122 * escaped: &, <, >, ", ', and `.
123 */
124export function escape(text: string): string;
125
126export var unescape: Decode;