Previous: (kracht strings), Up: API
Parse a URL-encoded bytevector HTTP BODY into an association list of decoded key/value string pairs.
Only the first ‘=‘ in each ‘&‘-separated segment separates the key from the value, so a value may itself contain ‘=‘ characters. A segment without any ‘=‘ gets an empty-string value, and empty segments are skipped. A body consisting solely of ‘=‘ is treated as empty and returns ’().
Replace the characters of string X that are significant to HTML – the ampersand, less-than, greater-than, double-quote and apostrophe characters – plus every character in the HTML4 entity set (the accented Latin letters, and the common symbols from currency signs to Greek letters and arrows) with their named-entity equivalents.
This covers two contexts: HTML element text, and a *quoted* attribute value. For an unquoted attribute, a JavaScript string, a CSS value or a URL, use ‘html-escape-context’ instead; those contexts have their own ways to end a value early that escaping the five HTML special characters does not address.
X is processed one character at a time, so escaping is deliberately *not* idempotent: ‘&’ becomes ‘&’. Escape raw text exactly once and never escape output that has already been escaped.
Encode string X for the given output CONTEXT, picking the encoder that matches where the value is about to be written:
text HTML element text attribute a quoted HTML attribute value unquoted-attribute an unquoted HTML attribute value js-string the inside of a JavaScript string literal css-value a CSS value or an inline style declaration url a URL component: a path segment, a query parameter name or value, or a fragment
‘url’ delegates to ‘uri-encode’, which percent-encodes every byte outside the RFC 3986 unreserved set. Use it for a component and not for a whole URL, whose ‘://’, ‘?’ and ‘&’ delimiters must survive.
Encode string X for use as a CSS value: an inline ‘style’ declaration or a rule body.
Every character except an ASCII letter or digit becomes a CSS hex escape, six hex digits followed by a space (CSS consumes that one space as the escape’s terminator). The value can therefore not close the declaration, the rule or the enclosing <style> element.
Note that the space that terminates each escape survives in the result, so put it in a *quoted* attribute when it goes into a ‘style’ attribute rather than leaning on the attribute’s own quoting.
Encode string X for the inside of a JavaScript string literal.
Every character except an ASCII letter or digit is written as a ‘\xHH’, ‘\uHHHH’ or surrogate-pair escape. The result can therefore not close the literal, cannot carry a line separator into the code, and cannot end the enclosing <script> element with ‘</script’ – ‘<’ and ‘/’ both become escapes. Use it for the contents of a quoted string; write the quotes yourself.
Because only ASCII letters, digits and backslash escapes survive, the result is also safe to drop straight into an HTML attribute – quoted or not – with no further escaping: no quote, angle bracket, ampersand or whitespace is left to break out with.
Encode string X for an unquoted HTML attribute value.
Every character that is not an ASCII letter, digit, ‘-’, ‘_’ or ‘.’ becomes a numeric character reference, so the value cannot be ended early by whitespace or by a delimiter such as ‘>’ or ‘/’. Quoting the attribute and using ‘html-escape’ is usually the better fix; this is for the cases where you cannot.
Convert HTML entities inside string X back into their original characters.
Every named character reference the HTML standard defines is recognised, as long as it is written with its trailing semicolon – ‘<’, ‘á’, ‘…’, even ‘≂̸’ – together with numeric references such as ‘'’ and ‘'’. Some of those references stand for two code points, so the result can be longer than the text that was decoded.
The string is processed in a single pass; an unknown or malformed entity is copied through unchanged.
Percent-decode the given STR, according to ENCODING, which should be the name of a character encoding.
Note that this function should not generally be applied to a full URI string. For paths, use ‘split-and-decode-uri-path’ instead. For query strings, split the query on ‘&’ and ‘=’ boundaries, and decode the components separately.
Note also that percent-encoded strings encode _bytes_, not characters. There is no guarantee that a given byte sequence is a valid string encoding. Therefore this routine may signal an error if the decoded bytes are not valid for the given encoding. Pass ‘#f’ for ENCODING if you want decoded bytes as a bytevector directly. ‘set-port-encoding!’, for more information on character encodings.
If DECODE-PLUS-TO-SPACE? is true, which is the default, also replace instances of the plus character (+) with a space character. This is needed when parsing application/x-www-form-urlencoded data.
Returns a string of the decoded characters, or a bytevector if ENCODING was ‘#f’.
Percent-encode any character not in the character set, UNESCAPED-CHARS.
The default character set includes alphanumerics from ASCII, as well as the special characters ‘-’, ‘.’, ‘_’, and ‘~’. Any other character will be percent-encoded, by writing out the character to a bytevector within the given ENCODING, then encoding each byte as ‘%HH’, where HH is the uppercase hexadecimal representation of the byte.
Previous: (kracht strings), Up: API