Text encoding

Package: ENCODING_PACKAGE. Registered by createEngine(); for a slimmer engine, register it explicitly (see choosing packages).

Sometimes a piece of text has to travel somewhere that will not accept it as it is: a field that only tolerates letters and digits, a web address that gives & and = their own meaning, a place where you need to see the raw byte values. Encoding rewrites the text into a safe, plain form for that journey; decoding reads it back. This page does both, in the same note as the rest of your working, so you can encode a value on one line and check it decodes on the next.

as encodes and from decodes. Three encodings are covered, each a round trip:

"hello" as base64 // aGVsbG8=
"aGVsbG8=" from base64 // hello
"a b&c=1" as url // a%20b%26c%3D1
"a%20b%26c%3D1" from url // a b&c=1
"Hi" as hex bytes // 48 69
"48 69" from hex bytes // Hi

• base64 packs text into a compact run of letters, digits and a little punctuation, the form data fields and tokens usually expect.
• url escapes the characters that have a special job in a web address, so a space becomes %20, an ampersand %26, an equals %3D.
• hex bytes shows each byte of the text as a two-digit hex number, useful when you want to read the bytes themselves.

base64 also has a function spelling, for when that reads more naturally:

base64("Hello, World!") // SGVsbG8sIFdvcmxkIQ==

Reading a token apart

Two forms read an existing token rather than make one. jwt decodes a JSON Web Token: a JWT is three base64url parts joined by dots (header.payload.signature), and this returns the payload, the claims the token carries, as JSON.

jwt("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c") // {"sub":"1234567890","name":"John Doe","iat":1516239022}

The signature is never checked, and that is deliberate. Reading a token is not the same as trusting it: verifying the signature needs the signing key, and a calculator is the wrong place to imply a token is genuine. jwt tells you what a token says; a malformed one is reported as an error rather than half read.

query parses a URL query string into JSON, decoding the percent-escapes and reading + as a space:

query("name=John+Doe&page=2") // {"name":"John Doe","page":"2"}

Both also have a from spelling, "..." from jwt and "..." from query, to match the decoders above. To read one value out of the JSON either returns, use field, on the pasted text page:

field(query("name=John+Doe&page=2"), "name") // John Doe

Notes

hex bytes is two words on purpose. as hex already means something different, a number shown in base 16, so the byte encoding is kept separate and neither reading is ambiguous:

255 as hex // 0xFF

Encoding expects text, so give it a "quoted string"; a number or other value is reported as an error rather than quietly turned into something. Decoding checks its input, so a string that is not valid base64 (or url, or hex bytes) is reported too, rather than handed back as mangled text. Multi-byte characters (accents, emoji) survive the round trip, because the text is encoded by its actual bytes.