Module rocket::form

source ·
Expand description

Parsing and validation of HTTP forms and fields.

See the forms guide for general form support documentation.

Field Wire Format

Rocket’s field wire format is a flexible, non-self-descriptive, text-based encoding of arbitrarily nested structure keys and their corresponding values. The general grammar is:

field := name ('=' value)?

name := key*

key := indices
      | '[' indices ']'
      | '.' indices

indices := index (':' index)*

index := STRING except ':', ']'

value := STRING

Each field name consists of any number of keys and at most one value. Keys are delimited by [ or .. A key consists of indices delimited by :.

The meaning of a key or index is type-dependent, hence the format is non-self-descriptive. Any structure can be described by this format. The delimiters ., [, :, and ] have no semantic meaning.

Some examples of valid fields are:

  • =
  • key=value
  • key[]=value
  • .0=value
  • [0]=value
  • people[].name=Bob
  • bob.cousin.names[]=Bob
  • map[k:1]=Bob
  • people[bob]nickname=Stan

See FromForm for full details on push-parsing and complete examples, and Form for how to accept forms in a request handler.

Modules

  • error
    Form error types.
  • name
    Types for field names, name keys, and key indices.
  • validate
    Form field validation routines.

Structs

  • Context
    A form context containing received fields, values, and encountered errors.
  • Contextual
    An infallible form guard that records form fields and errors during parsing.
  • DataField
    A multipart form field with an underlying data stream.
  • Error
    A form error, potentially tied to a specific form field.
  • Errors
    A collection of Errors.
  • Form
    A data guard for FromForm types.
  • Lenient
    A form guard for parsing form types leniently.
  • Options
    Form guard options.
  • Strict
    A form guard for parsing form types strictly.
  • ValueField
    A form field with a string value.

Traits

  • FromForm
    Trait implemented by form guards: types parseable from HTTP forms.
  • FromFormField
    Implied form guard (FromForm) for parsing a single form field.

Type Aliases