package dune-private-libs

  1. Overview
  2. Docs
package dune-private-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Reading OCaml values from dune lang ones

type ast = Ast.t =
  1. | Atom of Stdune.Loc.t * Atom.t
  2. | Quoted_string of Stdune.Loc.t * string
  3. | Template of Template.t
  4. | List of Stdune.Loc.t * ast list
type hint = {
  1. on : string;
  2. candidates : string list;
}
type ('a, 'kind) parser

Monad producing a value of type 'a by parsing an input composed of a sequence of S-expressions.

The input can be seen either as a plain sequence of S-expressions or a list of fields. The 'kind parameter indicates how the input is seen:

  • with 'kind = [values], the input is seen as an ordered sequence of S-expressions
  • with !'kind = [fields], the input is seen as an unordered sequence of fields

A field is a S-expression of the form: (<atom> <values>...) where atom is a plain atom, i.e. not a quoted string and not containing variables. values is a sequence of zero, one or more S-expressions.

It is possible to switch between the two mode at any time using the appropriate combinator. Some primitives can be used in both mode while some are specific to one mode.

type values
type fields
type 'a t = ('a, values) parser
type 'a fields_parser = ('a, fields) parser
val parse : 'a t -> Stdune.Univ_map.t -> ast -> 'a

parse parser context sexp parse a S-expression using the following parser. The input consist of a single S-expression. context allows to pass extra information such as versions to individual parsers.

val set_input : ast list -> (unit, 'k) parser
val return : 'a -> ('a, _) parser
val (>>=) : ('a, 'k) parser -> ('a -> ('b, 'k) parser) -> ('b, 'k) parser
val (>>|) : ('a, 'k) parser -> ('a -> 'b) -> ('b, 'k) parser
val (>>>) : (unit, 'k) parser -> ('a, 'k) parser -> ('a, 'k) parser
val map : ('a, 'k) parser -> f:('a -> 'b) -> ('b, 'k) parser
val try_ : ('a, 'k) parser -> (exn -> ('a, 'k) parser) -> ('a, 'k) parser
val traverse : 'a list -> f:('a -> ('b, 'k) parser) -> ('b list, 'k) parser
val all : ('a, 'k) parser list -> ('a list, 'k) parser
val get : 'a Stdune.Univ_map.Key.t -> ('a option, _) parser

Access to the context

val set : 'a Stdune.Univ_map.Key.t -> 'a -> ('b, 'k) parser -> ('b, 'k) parser
val get_all : (Stdune.Univ_map.t, _) parser
val set_many : Stdune.Univ_map.t -> ('a, 'k) parser -> ('a, 'k) parser
val loc : (Stdune.Loc.t, _) parser

Return the location of the list currently being parsed.

val (<|>) : ('a, 'k) parser -> ('a, 'k) parser -> ('a, 'k) parser

a <|> b is either a or b. If a fails to parse the input, then try b. If b fails as well, raise the error from the parser that consumed the most input.

val either : ('a, 'k) parser -> ('b, 'k) parser -> (('a, 'b) Stdune.Either.t, 'k) parser
val atom_matching : (string -> 'a option) -> desc:string -> 'a t

atom_matching f expects the next element to be an atom for which f returns Some v. desc is used to describe the atom in case of error. f must not raise.

val keyword : string -> unit t

keyword s is a short-hand for

atom_matching (String.equal s) ~desc:(sprintf "'%s'" s)
val until_keyword : string -> before:'a t -> after:'b t -> ('a list * 'b option) t

Use before to parse elements until the keyword is reached. Then use after to parse the rest.

type kind =
  1. | Values of Stdune.Loc.t * string option
  2. | Fields of Stdune.Loc.t * string option

What is currently being parsed. The second argument is the atom at the beginnig of the list when inside a sum ... or field ....

val kind : (kind, _) parser
val repeat : 'a t -> 'a list t

repeat t uses t to consume all remaining elements of the input until the end of sequence is reached.

val repeat1 : 'a t -> 'a list t

Like repeat but the list of elements must be non-empty.

val capture : ('a t -> 'a) t

Capture the rest of the input for later parsing

val enter : 'a t -> 'a t

enter t expect the next element of the input to be a list and parse its contents with t.

val fields : 'a fields_parser -> 'a t

fields fp converts the rest of the current input to a list of fields and parse them with fp. This operation fails if one the S-expression in the input is not of the form (<atom> <values>...)

val string : string t

Consume the next element of the input as a string, int, bool, ...

val int : int t
val float : float t
val bool : bool t
val pair : 'a t -> 'b t -> ('a * 'b) t
val triple : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t
val maybe : 'a t -> 'a option t

maybe t is a short-hand for:

(let+ x = t in
 Some x)
<|> return None
val duration : int t

Consume the next element as a duration, requiring 's', 'm' or 'h' suffix

val bytes_unit : int64 t

Consume the next element as a number of bytes, requiring 'B', 'KB', 'MB' or 'GB' suffix

val raw : ast t

Unparsed next element of the input

val peek : ast option t

Inspect the next element of the input without consuming it

val peek_exn : ast t

Same as peek but fail if the end of input is reached

val junk : unit t

Consume and ignore the next element of the input

val junk_everything : (unit, _) parser

Ignore all the rest of the input

val plain_string : (loc:Stdune.Loc.t -> string -> 'a) -> 'a t

plain_string f expects the next element of the input to be a plain string, i.e. either an atom or a quoted string, but not a template nor a list.

val filename : string t

A valid filename, i.e. a string other than "." or ".."

val relative_file : string t

A relative filename

val fix : ('a t -> 'a t) -> 'a t
val located : ('a, 'k) parser -> (Stdune.Loc.t * 'a, 'k) parser
val enum : (string * 'a) list -> 'a t
val sum : ?force_parens:bool -> (string * 'a t) list -> 'a t

Parser that parse a S-expression of the form (<atom> <s-exp1> <s-exp2> ...) or <atom>. <atom> is looked up in the list and the remaining s-expressions are parsed using the corresponding list parser.

If force_parens is true, then the form <atom> is never accepted. The default is false.

val map_validate : ('a, 'k) parser -> f:('a -> ('b, Stdune.User_message.t) Stdune.Result.t) -> ('b, 'k) parser

Check the result of a list parser, and raise a properly located error in case of failure.

Parsing record fields

val field : string -> ?default:'a -> ?on_dup:(Stdune.Univ_map.t -> string -> Ast.t list -> unit) -> 'a t -> 'a fields_parser
val field_o : string -> ?on_dup:(Stdune.Univ_map.t -> string -> Ast.t list -> unit) -> 'a t -> 'a option fields_parser
val fields_mutually_exclusive : ?on_dup:(Stdune.Univ_map.t -> string -> Ast.t list -> unit) -> ?default:'a -> (string * 'a t) list -> 'a fields_parser

Parser for mutually exclusive fields. If default is provided, allow fields absence.

val field_b : ?check:unit t -> ?on_dup:(Stdune.Univ_map.t -> string -> Ast.t list -> unit) -> string -> bool fields_parser

Test if the field is present

val field_o_b : ?check:unit t -> ?on_dup:(Stdune.Univ_map.t -> string -> Ast.t list -> unit) -> string -> bool option fields_parser

Differentiate between not present and set to true or false

val multi_field : string -> 'a t -> 'a list fields_parser

A field that can appear multiple times

val leftover_fields_as_sums : (string * 'a t) list -> 'a list fields_parser

Treat the remainig fields as a list of sum values

val field_present_too_many_times : Stdune.Univ_map.t -> string -> Ast.t list -> _

Default value for on_dup. It fails with an appropriate error message.

val leftover_fields : Ast.t list fields_parser
val let* : ('a, 'k) parser -> ('a -> ('b, 'k) parser) -> ('b, 'k) parser
val let+ : ('a, 'k) parser -> ('a -> 'b) -> ('b, 'k) parser
val and+ : ('a, 'k) parser -> ('b, 'k) parser -> ('a * 'b, 'k) parser
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct