Crate html_escape

Expand description

§HTML Escape

This library is for encoding/escaping special characters in HTML and decoding/unescaping HTML entities as well.

§Usage

§Encoding

This crate provides some encode_* functions to encode HTML text in different situations.

Escaping is context-sensitive. Use encode_text for text, quoted attribute encoders for quoted attributes, encode_unquoted_attribute for unquoted attributes, and script or style encoders for raw-text elements. encode_safe is not a context-independent sanitizer.

For example, to put a text between a start tag <foo> and an end tag </foo>, use the encode_text function to escape every &, <, and > in the text.

assert_eq!("a &gt; b &amp;&amp; a &lt; c", html_escape::encode_text("a > b && a < c"));

The script and style *_quoted_text functions take raw string content and do not add outer quotes. They escape every backslash, including those in existing escape sequences, and also C0 control characters and every <. Script variants also escape U+2028 and U+2029. Style variants replace NUL with U+FFFD, so an input containing NUL cannot round-trip without a change. Use these functions for single-quoted or double-quoted string content inside <script> or <style>.

Since 0.3.0, the *_quoted_text encoders escape every input backslash. Pass the original text and remove manual string escaping at the call site; for example, pass C:\temp\file instead of C:\\temp\\file. Their decoders also decode escaped backslashes and hex escapes. They still recognize legacy tag and comment escapes, but some decoding results differ from 0.2.

let text = r"C:\temp\file";
assert_eq!(r"C:\\temp\\file", html_escape::encode_script_single_quoted_text(text));
assert_eq!(text, html_escape::decode_script_single_quoted_text(r"C:\\temp\\file"));
assert_eq!("\n", html_escape::decode_script_single_quoted_text(r"\x0A"));
assert_eq!(r"\x0A", html_escape::decode_script_single_quoted_text(r"\\x0A"));

encode_script and encode_style scan the whole element text without parsing JavaScript or CSS. They insert backslashes before tag and comment sequences, so check that the result is valid in the target language. They keep existing escapes, so encoding and decoding may not return the original text. For example, <\/script> stays the same during script encoding, but script decoding changes it to </script>. encode_script is not a JSON encoder; its \! escape for <!-- is not valid JSON. To put JSON inside <script type="application/json">, serialize the data as JSON first, then replace each literal < with \u003C in the JSON text.

let json = r#"{"text":"<!--</script>"}"#;
let escaped_json = json.replace('<', r"\u003C");
let html = format!(r#"<script type="application/json">{}</script>"#, escaped_json);
assert_eq!(r#"<script type="application/json">{"text":"\u003C!--\u003C/script>"}</script>"#, html);

The functions suffixed with _to_writer, _to_vec or _to_string are useful to generate HTML. The _to_string and _to_vec functions append to the output and return only the slice written by the current call. The _to_writer functions accept writers including &mut dyn std::io::Write. Pass the whole element source in one call to encode_script or encode_style, including their output variants; separate calls do not share tag-matching state. Quoted string encoders can be appended in chunks because they escape every <. For an empty attribute value, use a quoted attribute; the unquoted attribute encoder does not add quotes.

let mut html = String::from("<input value=");
assert_eq!("Hello&#x20;world&#x21;", html_escape::encode_unquoted_attribute_to_string("Hello world!", &mut html));
html.push_str(" placeholder=\"");
assert_eq!("The default value is &quot;Hello world!&quot;.", html_escape::encode_double_quoted_attribute_to_string("The default value is \"Hello world!\".", &mut html));
html.push_str("\"/><script>alert('");
assert_eq!(r"\x3Cscript>\'s end tag is \x3C/script>", html_escape::encode_script_single_quoted_text_to_string("<script>'s end tag is </script>", &mut html));
html.push_str("');</script>");

assert_eq!(r#"<input value=Hello&#x20;world&#x21; placeholder="The default value is &quot;Hello world!&quot;."/><script>alert('\x3Cscript>\'s end tag is \x3C/script>');</script>"#, html);

§Decoding

Decoding accepts exact named and numeric character references ending with ;. It does not apply legacy semicolonless references or C1 control replacements used by browser tokenizers.

assert_eq!("Hello world!", html_escape::decode_html_entities("Hello&#x20;world&#x21;"));

assert_eq!("alert('<script></script>');", html_escape::decode_script(r"alert('<script><\/script>');"));

§No Std

Disable the default features to compile this crate without std.

[dependencies.html-escape]
version = "*"
default-features = false

§Benchmark

cargo bench

Statics§

NAMED_ENTITIES: The table of HTML named entities ordered by the names.

Functions§

decode_html_entities: Decode HTML entities in a given string.
decode_html_entities_to_string: Decode HTML entities in a given string to a mutable String reference and return the decoded string slice.
decode_html_entities_to_vec: Decode HTML entities in a given string to a mutable Vec<u8> reference and return the decoded data slice.
decode_html_entities_to_writerstd: Decode HTML entities in a given string to a writer.
decode_script: Decode text from the <script> element.
decode_script_double_quoted_text: Decode content of a double-quoted JavaScript string from <script>.
decode_script_double_quoted_text_to_string: Decode content of a double-quoted JavaScript string to a mutable String and return the new string slice.
decode_script_double_quoted_text_to_vec: Decode content of a double-quoted JavaScript string to a mutable Vec<u8> and return the new data slice.
decode_script_double_quoted_text_to_writerstd: Decode content of a double-quoted JavaScript string to a writer.
decode_script_quoted_text: Decode content of a single-quoted or double-quoted JavaScript string from <script>.
decode_script_quoted_text_to_string: Decode content of a single-quoted or double-quoted JavaScript string to a mutable String and return the new string slice.
decode_script_quoted_text_to_vec: Decode content of a single-quoted or double-quoted JavaScript string to a mutable Vec<u8> and return the new data slice.
decode_script_quoted_text_to_writerstd: Decode content of a single-quoted or double-quoted JavaScript string to a writer.
decode_script_single_quoted_text: Decode content of a single-quoted JavaScript string from <script>.
decode_script_single_quoted_text_to_string: Decode content of a single-quoted JavaScript string to a mutable String and return the new string slice.
decode_script_single_quoted_text_to_vec: Decode content of a single-quoted JavaScript string to a mutable Vec<u8> and return the new data slice.
decode_script_single_quoted_text_to_writerstd: Decode content of a single-quoted JavaScript string to a writer.
decode_script_to_string: Write text from the <script> element to a mutable String reference and return the decoded string slice.
decode_script_to_vec: Write text from the <script> element to a mutable Vec<u8> reference and return the decoded data slice.
decode_script_to_writerstd: Write text from the <script> element to a writer.
decode_style: Decode text from the <style> element.
decode_style_double_quoted_text: Decode content of a double-quoted CSS string from <style>.
decode_style_double_quoted_text_to_string: Decode content of a double-quoted CSS string to a mutable String and return the new string slice.
decode_style_double_quoted_text_to_vec: Decode content of a double-quoted CSS string to a mutable Vec<u8> and return the new data slice.
decode_style_double_quoted_text_to_writerstd: Decode content of a double-quoted CSS string to a writer.
decode_style_quoted_text: Decode content of a single-quoted or double-quoted CSS string from <style>.
decode_style_quoted_text_to_string: Decode content of a single-quoted or double-quoted CSS string to a mutable String and return the new string slice.
decode_style_quoted_text_to_vec: Decode content of a single-quoted or double-quoted CSS string to a mutable Vec<u8> and return the new data slice.
decode_style_quoted_text_to_writerstd: Decode content of a single-quoted or double-quoted CSS string to a writer.
decode_style_single_quoted_text: Decode content of a single-quoted CSS string from <style>.
decode_style_single_quoted_text_to_string: Decode content of a single-quoted CSS string to a mutable String and return the new string slice.
decode_style_single_quoted_text_to_vec: Decode content of a single-quoted CSS string to a mutable Vec<u8> and return the new data slice.
decode_style_single_quoted_text_to_writerstd: Decode content of a single-quoted CSS string to a writer.
decode_style_to_string: Write text from the <style> element to a mutable String reference and return the decoded string slice.
decode_style_to_vec: Write text from the <style> element to a mutable Vec<u8> reference and return the decoded data slice.
decode_style_to_writerstd: Write text from the <style> element to a writer.
encode_double_quoted_attribute: Encode text used in a double-quoted attribute.
encode_double_quoted_attribute_to_string: Write text used in a double-quoted attribute to a mutable String reference and return the encoded string slice.
encode_double_quoted_attribute_to_vec: Write text used in a double-quoted attribute to a mutable Vec<u8> reference and return the encoded data slice.
encode_double_quoted_attribute_to_writerstd: Write text used in a double-quoted attribute to a writer.
encode_quoted_attribute: Encode text used in a quoted attribute.
encode_quoted_attribute_to_string: Write text used in a quoted attribute to a mutable String reference and return the encoded string slice.
encode_quoted_attribute_to_vec: Write text used in a quoted attribute to a mutable Vec<u8> reference and return the encoded data slice.
encode_quoted_attribute_to_writerstd: Write text used in a quoted attribute to a writer.
encode_safe: Encode &, <, >, ", ', and / as HTML entities.
encode_safe_to_string: Encode &, <, >, ", ', and / as HTML entities, write the result to a mutable String reference, and return the encoded string slice.
encode_safe_to_vec: Encode &, <, >, ", ', and / as HTML entities, write the result to a mutable Vec<u8> reference, and return the encoded data slice.
encode_safe_to_writerstd: Encode &, <, >, ", ', and / as HTML entities and write the result to a writer.
encode_script: Encode text used in the <script> element.
encode_script_double_quoted_text: Encode raw text for a double-quoted JavaScript string inside <script>.
encode_script_double_quoted_text_to_string: Encode content of a double-quoted JavaScript string to a mutable String and return the new string slice.
encode_script_double_quoted_text_to_vec: Encode content of a double-quoted JavaScript string to a mutable Vec<u8> and return the new data slice.
encode_script_double_quoted_text_to_writerstd: Encode content of a double-quoted JavaScript string to a writer.
encode_script_quoted_text: Encode raw text for a single-quoted or double-quoted JavaScript string inside <script>.
encode_script_quoted_text_to_string: Encode content of a single-quoted or double-quoted JavaScript string to a mutable String and return the new string slice.
encode_script_quoted_text_to_vec: Encode content of a single-quoted or double-quoted JavaScript string to a mutable Vec<u8> and return the new data slice.
encode_script_quoted_text_to_writerstd: Encode content of a single-quoted or double-quoted JavaScript string to a writer.
encode_script_single_quoted_text: Encode raw text for a single-quoted JavaScript string inside <script>.
encode_script_single_quoted_text_to_string: Encode content of a single-quoted JavaScript string to a mutable String and return the new string slice.
encode_script_single_quoted_text_to_vec: Encode content of a single-quoted JavaScript string to a mutable Vec<u8> and return the new data slice.
encode_script_single_quoted_text_to_writerstd: Encode content of a single-quoted JavaScript string to a writer.
encode_script_to_string: Write text used in the <script> element to a mutable String reference and return the encoded string slice.
encode_script_to_vec: Write text used in the <script> element to a mutable Vec<u8> reference and return the encoded data slice.
encode_script_to_writerstd: Write text used in the <script> element to a writer.
encode_single_quoted_attribute: Encode text used in a single-quoted attribute.
encode_single_quoted_attribute_to_string: Write text used in a single-quoted attribute to a mutable String reference and return the encoded string slice.
encode_single_quoted_attribute_to_vec: Write text used in a single-quoted attribute to a mutable Vec<u8> reference and return the encoded data slice.
encode_single_quoted_attribute_to_writerstd: Write text used in a single-quoted attribute to a writer.
encode_style: Encode text used in the <style> element.
encode_style_double_quoted_text: Encode raw text for a double-quoted CSS string inside <style>.
encode_style_double_quoted_text_to_string: Encode content of a double-quoted CSS string to a mutable String and return the new string slice.
encode_style_double_quoted_text_to_vec: Encode content of a double-quoted CSS string to a mutable Vec<u8> and return the new data slice.
encode_style_double_quoted_text_to_writerstd: Encode content of a double-quoted CSS string to a writer.
encode_style_quoted_text: Encode raw text for a single-quoted or double-quoted CSS string inside <style>.
encode_style_quoted_text_to_string: Encode content of a single-quoted or double-quoted CSS string to a mutable String and return the new string slice.
encode_style_quoted_text_to_vec: Encode content of a single-quoted or double-quoted CSS string to a mutable Vec<u8> and return the new data slice.
encode_style_quoted_text_to_writerstd: Encode content of a single-quoted or double-quoted CSS string to a writer.
encode_style_single_quoted_text: Encode raw text for a single-quoted CSS string inside <style>.
encode_style_single_quoted_text_to_string: Encode content of a single-quoted CSS string to a mutable String and return the new string slice.
encode_style_single_quoted_text_to_vec: Encode content of a single-quoted CSS string to a mutable Vec<u8> and return the new data slice.
encode_style_single_quoted_text_to_writerstd: Encode content of a single-quoted CSS string to a writer.
encode_style_to_string: Write text used in the <style> element to a mutable String reference and return the encoded string slice.
encode_style_to_vec: Write text used in the <style> element to a mutable Vec<u8> reference and return the encoded data slice.
encode_style_to_writerstd: Write text used in the <style> element to a writer.
encode_text: Encode text used as regular HTML text.
encode_text_minimal: Encode text used as regular HTML text.
encode_text_minimal_to_string: Write text used as regular HTML text to a mutable String reference and return the encoded string slice.
encode_text_minimal_to_vec: Write text used as regular HTML text to a mutable Vec<u8> reference and return the encoded data slice.
encode_text_minimal_to_writerstd: Write text used as regular HTML text to a writer.
encode_text_to_string: Write text used as regular HTML text to a mutable String reference and return the encoded string slice.
encode_text_to_vec: Write text used as regular HTML text to a mutable Vec<u8> reference and return the encoded data slice.
encode_text_to_writerstd: Write text used as regular HTML text to a writer.
encode_unquoted_attribute: Encode text used in an unquoted attribute. Except for alphanumeric characters, escape all characters which are less than 128.
encode_unquoted_attribute_to_string: Write text used in an unquoted attribute to a mutable String reference and return the encoded string slice. Except for alphanumeric characters, escape all characters which are less than 128.
encode_unquoted_attribute_to_vec: Write text used in an unquoted attribute to a mutable Vec<u8> reference and return the encoded data slice. Except for alphanumeric characters, escape all characters which are less than 128.
encode_unquoted_attribute_to_writerstd: Write text used in an unquoted attribute to a writer. Except for alphanumeric characters, escape all characters which are less than 128.