Module Multipart_formSource

Multipart-form.

The MIME type multipart/form-data is used to express values submitted through a <form>. This module helps the user to extract these values from an input.

Sourcemodule Field_name : sig ... end
Sourcemodule Content_type : sig ... end
Sourcemodule Content_encoding : sig ... end
Sourcemodule Content_disposition : sig ... end
Sourcemodule Field : sig ... end
Sourcemodule Header : sig ... end
Sourcetype 'id emitters = Header.t -> (Bigstringaf.t Faraday.iovec option -> unit) * 'id

Type of emitters.

An emitters is able to produce from the given header a pusher which is able to save contents and a unique ID to be able to get the content furthermore.

Sourcetype 'a elt = {
  1. header : Header.t;
  2. body : 'a;
}

Type of a simple element.

An element is a part in sense of the multipart/form-data format. A part can contains multiple parts. It has systematically a Header.t.

Sourcetype 'a t =
  1. | Leaf of 'a elt
  2. | Multipart of 'a t option list elt

Type of multipart/form-data contents.

  • a Leaf is a content with a simple header.
  • a Multipart is a list of possibly empty (option) sub-elements - indeed, we can have a multipart inside a multipart.
Sourceval parser : emitters:'id emitters -> Content_type.t -> max_chunk_size:int -> 'id t Angstrom.t

parser ~emitters content_type creates an angstrom's parser which can process a multipart/form-data input. For each Leaf, the parser calls emitters to be able to save contents and get a reference of it.

A simple use of it is to generate an unique ID and associate it to a Buffer.t such as:

  let gen = let v = ref (-1) in fun () -> incr v ; !v in
  let tbl = Hashtbl.create 0x10 in
  let emitters () =
    let idx = gen () in
    let buf = Buffer.create 0x100 in
    (function None -> ()
            | Some str -> Buffer.add_string buf str), idx in
  parser ~emitters content_type

With such style, a mapping exists between the returned value t and tbl. At the end, the user is able to extract contents with these values.

In some contexts, something else such as an Lwt_stream.t/asynchronous stream can be used instead a Buffer.t.

Sourcetype 'a stream = unit -> 'a option
Sourceval of_stream : string stream -> Content_type.t -> (int t * (int * string) list, [> `Msg of string ]) result

of_stream stream content_type returns, if it succeeds, a value t with an associative list of unique ID and contents.

Sourceval of_string : string -> Content_type.t -> (int t * (int * string) list, [> `Msg of string ]) result

of_string str content_type returns, if it succeeds, a value t with an associative list of unique ID and contents.

Sourcetype part
Sourceval part : ?header:Header.t -> ?disposition:Content_disposition.t -> ?encoding:Content_encoding.t -> (string * int * int) stream -> part
Sourcetype multipart
Sourceval multipart : rng:(?g:'g -> int -> string) -> ?g:'g -> ?header:Header.t -> ?boundary:string -> part list -> multipart
Sourceval to_stream : multipart -> Header.t * (string * int * int) stream