On this page:
2.1 Functions
uri-encode
uri-decode
form-urlencoded-encode
form-urlencoded-deecode
alist->form-urlencoded
form-urlencoded->alist
current-alist-separator-mode
Version: 4.1

2 URI Codec: Encoding and Decoding URIs

 (require net/uri-codec)

The net/uri-codec module provides utilities for encoding and decoding strings using the URI encoding rules given in RFC 2396 [RFC2396], and to encode and decode name/value pairs using the application/x-www-form-urlencoded mimetype given the in HTML 4.0 specification. There are minor differences between the two encodings.

The URI encoding uses allows a few characters to be represented as-is: a through z, A through Z, 0-9, -, _, ., !, ~, *, ', ( and ). The remaining characters are encoded as %xx›, where ‹xx› is the two-character hex representation of the integer value of the character (where the mapping character–integer is determined by US-ASCII if the integer is less than 128).

The encoding, in line with RFC 2396’s recommendation, represents a character as-is, if possible. The decoding allows any characters to be represented by their hex values, and allows characters to be incorrectly represented as-is.

The rules for the application/x-www-form-urlencoded mimetype given in the HTML 4.0 spec are:

These rules differs slightly from the straight encoding in RFC 2396 in that + is allowed, and it represents a space. The net/uri-codec library follows this convention, encoding a space as + and decoding + as a space. In addtion, since there appear to be some brain-dead decoders on the web, the library also encodes !, ~, ', (, and ) using their hex representation, which is the same choice as made by the Java’s URLEncoder.

2.1 Functions

(uri-encode str)  string?

  str : string?

Encode a string using the URI encoding rules.

(uri-decode str)  string?

  str : string?

Decode a string using the URI decoding rules.

(form-urlencoded-encode str)  string?

  str : string?

Encode a string using the application/x-www-form-urlencoded encoding rules. The result string contains no non-ASCII characters.

(form-urlencoded-deecode str)  string?

  str : string?

Decode a string encoded using the application/x-www-form-urlencoded encoding rules.

(alist->form-urlencoded alist)  string?

  alist : (listof (cons/c symbol? string?))

Encode an association list using the application/x-www-form-urlencoded encoding rules.

The current-alist-separator-mode parameter determines the separator used in the result.

(form-urlencoded->alist str)

  (listof (cons/c symbol? string?))

  str : string

Decode a string encoded using the application/x-www-form-urlencoded encoding rules into an association list. All keys are case-folded for conversion to symbols.

The current-alist-separator-mode parameter determines the way that separators are parsed in the input.

(current-alist-separator-mode)

  (one-of/c 'amp 'semi 'amp-or-semi 'semi-or-amp)

(current-alist-separator-mode mode)  void?

  mode : (one-of/c 'amp 'semi 'amp-or-semi 'semi-or-amp)

A parameter that determines the separator used/recognized between associations in form-urlencoded->alist, alist->form-urlencoded, url->string, and string->url.

The default value is 'amp-or-semi, which means that both & and ; are treated as separators when parsing, and & is used as a separator when encoding. The other modes use/recognize only of the separators.

Examples:

  > (define ex '((x . "foo") (y . "bar") (z . "baz")))

  > (current-alist-separator-mode 'amp) ; try 'amp...

  > (form-urlencoded->alist "x=foo&y=bar&z=baz")

  ((x . "foo") (y . "bar") (z . "baz"))

  > (form-urlencoded->alist "x=foo;y=bar;z=baz")

  ((x . "foo;y=bar;z=baz"))

  > (alist->form-urlencoded ex)

  "x=foo&y=bar&z=baz"

  > (current-alist-separator-mode 'semi) ; try 'semi...

  > (form-urlencoded->alist "x=foo;y=bar;z=baz")

  ((x . "foo") (y . "bar") (z . "baz"))

  > (form-urlencoded->alist "x=foo&y=bar&z=baz")

  ((x . "foo&y=bar&z=baz"))

  > (alist->form-urlencoded ex)

  "x=foo;y=bar;z=baz"

  > (current-alist-separator-mode 'amp-or-semi) ; try 'amp-or-semi...

  > (form-urlencoded->alist "x=foo&y=bar&z=baz")

  ((x . "foo") (y . "bar") (z . "baz"))

  > (form-urlencoded->alist "x=foo;y=bar;z=baz")

  ((x . "foo") (y . "bar") (z . "baz"))

  > (alist->form-urlencoded ex)

  "x=foo&y=bar&z=baz"

  > (current-alist-separator-mode 'semi-or-amp) ; try 'semi-or-amp...

  > (form-urlencoded->alist "x=foo&y=bar&z=baz")

  ((x . "foo") (y . "bar") (z . "baz"))

  > (form-urlencoded->alist "x=foo;y=bar;z=baz")

  ((x . "foo") (y . "bar") (z . "baz"))

  > (alist->form-urlencoded ex)

  "x=foo;y=bar;z=baz"