Documentation
¶
Overview ¶
Package htmlentities encodes and decodes HTML entities, providing a subset of the behavior of the npm "html-entities" library. It exists so that Go code ported from a Node codebase can keep calling a familiar encode/decode pair when rendering user-supplied text into HTML or when reading entity-laden text back out again, without pulling in a third-party dependency.
Escaping HTML entities is the front line of defense against cross-site scripting: turning the characters & < > " ' into their named forms prevents user input from being interpreted as markup or from breaking out of an attribute value. The npm html-entities library grew popular precisely because it makes this safe by default while still allowing a stricter mode that also escapes non-ASCII text for transports that are not UTF-8 clean. This port keeps that same two-mode split and matches the library's output for the characters and entities it supports.
Encode supports two modes selected via EncodeOptions.Mode. The default, "specialChars", encodes only the five characters & < > " ' as the named entities & < > " and ', leaving all other runes (including non-ASCII text such as accented letters) untouched. The "nonAscii" mode does everything specialChars does and additionally rewrites every rune with a code point above 127 as a decimal numeric entity (for example é becomes é), which is useful when the output must be pure ASCII. Any unrecognized Mode value falls back to specialChars behavior.
Decode is the inverse and is intentionally more permissive than Encode. It resolves the named entities in a built-in table (the five specials plus a selection of common ones such as ©, , — and several typographic and currency symbols) as well as decimal (é) and hexadecimal (é or é) numeric references. A leading fast path returns the input unchanged when it contains no ampersand. Anything that does not form a recognized entity is left exactly as-is: a bare or trailing ampersand, an unknown name like &unknownentity;, and malformed numerics like &#zz; all pass through untouched, and the scanner only looks a bounded distance ahead for the terminating semicolon so stray ampersands never swallow following text.
Parity with the Node package is partial by design. The named-entity table is a curated subset rather than the full HTML5 entity set, so Decode will leave less common named entities unresolved, and Encode never emits named forms beyond the five specials. Because Encode and Decode agree on those five characters, specialChars-mode output round-trips exactly through Decode, which is the common case for escaping and later unescaping application text. DecodeOptions is accepted for API compatibility but currently has no effect.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Decode ¶
func Decode(s string, opts ...DecodeOptions) string
Decode converts HTML entities in s back to their literal characters. It handles named entities from a built-in table plus decimal and hexadecimal numeric references. Unrecognized entities are left unchanged.
Example ¶
ExampleDecode converts HTML entities back into their literal characters. It resolves named entities from a built-in table as well as decimal (é) and hexadecimal (é) numeric references. Entities it does not recognize, such as an unknown name or a bare ampersand, are left exactly as they appear. This example decodes a mix of the five special named entities back into markup characters. Decoding is the inverse of specialChars-mode Encode for those characters, so escaped text round-trips cleanly.
package main
import (
"fmt"
"github.com/malcolmston/express/htmlentities"
)
func main() {
out := htmlentities.Decode(`<a href="x">Tom & Jerry's`)
fmt.Println(out)
}
Output: <a href="x">Tom & Jerry's
func Encode ¶
func Encode(s string, opts ...EncodeOptions) string
Encode converts special characters in s to HTML entities according to the supplied options. When no options are given, the "specialChars" mode is used.
Example ¶
ExampleEncode shows the default "specialChars" mode, which escapes only the five characters that are significant in HTML: & < > " and '. This is the mode you want when inserting untrusted text into an HTML document, since it neutralizes markup and attribute-breaking characters. Non-special characters, including accented and other non-ASCII runes, are passed through unchanged. The result below is safe to drop into an HTML page. Calling Encode with no options selects this default behavior.
package main
import (
"fmt"
"github.com/malcolmston/express/htmlentities"
)
func main() {
out := htmlentities.Encode(`<a href="x">Tom & Jerry's</a>`)
fmt.Println(out)
}
Output: <a href="x">Tom & Jerry's</a>
Example (NonAscii) ¶
ExampleEncode_nonAscii demonstrates the stricter "nonAscii" mode, selected through EncodeOptions. In addition to escaping the five special characters, this mode rewrites every rune above code point 127 as a decimal numeric entity. That makes the output pure ASCII, which is useful for transports that are not guaranteed to be UTF-8 clean. Here the accented "é" becomes é and the copyright sign becomes ©. The special characters would still be escaped in this mode if the input contained any.
package main
import (
"fmt"
"github.com/malcolmston/express/htmlentities"
)
func main() {
out := htmlentities.Encode("café ©", htmlentities.EncodeOptions{Mode: "nonAscii"})
fmt.Println(out)
}
Output: café ©
Types ¶
type DecodeOptions ¶
type DecodeOptions struct {
// Scope is reserved for future use and currently has no effect.
Scope string
}
DecodeOptions configures Decode. It is currently a placeholder for future options and may be passed as the zero value.
type EncodeOptions ¶
type EncodeOptions struct {
// Mode selects the encoding strategy: "specialChars" or "nonAscii".
Mode string
}
EncodeOptions configures Encode. Mode may be "specialChars" (default) or "nonAscii".
Source Files