silk.url.form.

Read and write application/x-www-form-urlencoded text, the format of HTML form bodies and of URL queries such as a=1&b=two+words.

When to use#

Use UrlForm.parse to read the fields of a form body or a URL query, and UrlForm.serialize to write them. The rules are those of the WHATWG URL Standard, which JavaScript's URLSearchParams uses.

Details#

The text is split at &, and each part at its first =. Empty parts are skipped. In names and values, + is a space and %XX escapes are decoded; invalid escapes stay as they are. The decoded bytes are read as UTF-8, with U+FFFD for each invalid sequence.

Examples#

Read and write a query#

silk
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
import silk.collections.list { List }
import silk.text.string { String }
import silk.url.form { UrlForm, UrlFormPair }

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let pairs = run UrlForm.parse("q=silk+lang&page=2") |> Effect.provideMut<Allocator>(&mut allocator)
  if List<UrlFormPair>.length(&pairs) != 2 || String.view(&List<UrlFormPair>.asSlice(&pairs)[0].value) != "silk lang" {
    return 1
  }
  let text = run UrlForm.serialize(List<UrlFormPair>.asSlice(&pairs)) |> Effect.provideMut<Allocator>(&mut allocator)
  if String.view(&text) != "q=silk+lang&page=2" {
    return 1
  }
  return 0
}

Import as UrlForm with import silk.url.form { UrlForm }.

Public declarations: 2.

UrlFormPair#

silk
pub struct UrlFormPair

One name and value of form text.

Field name#

silk
pub name: String

The decoded name.

Field value#

silk
pub value: String

The decoded value. It is empty when the part has no =.

UrlForm#

silk
pub struct UrlForm

Functions that read and write application/x-www-form-urlencoded text.

Implementation UrlForm#

silk
impl UrlForm

Associated function parse#

silk
pub effect fn parse(input: string) -> List<UrlFormPair>
    ! OutOfMemoryError
    ? &mut Allocator

Returns the names and values of the form text input, in order.

Errors#

  • OutOfMemoryError if the Allocator fails.

Associated function parseBytes#

silk
pub effect fn parseBytes(input: &[u8]) -> List<UrlFormPair>
    ! OutOfMemoryError
    ? &mut Allocator

Returns the names and values of the form bytes input, in order. input does not need to be UTF-8.

Errors#

  • OutOfMemoryError if the Allocator fails.

Associated function serialize#

silk
pub effect fn serialize(pairs: &[UrlFormPair]) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns pairs as form text: each name and value encoded, joined by =, and the pairs joined by &.

Details#

Space becomes +. Letters, digits, *, -, ., and _ stay as they are, and every other byte becomes %XX.

Errors#

  • OutOfMemoryError if the Allocator fails.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page