caqti 1.9.0 · OCaml Package

Query specification.

type t =

| L of string
(*
Literal code. May contain incomplete fragments.
*)
| Q of string
(*
Q s corresponds to a TEXT literal; passed as part of the query string if a suitable quoting function is available in the client library, otherwise passed as an additional parameter.
*)
| P of int
(*
P i refers to parameter number i, counting from 0.
*)
| E of string
(*
E name is expanded by the environemnt lookup function.
*)
| S of t list
(*
S frags is the concatenation of frags.
*)

A representation of a query string to send to a database, abstracting over parameter references and providing nested concatenation to simplify generation. For databases which only support linear parameters (typically denoted "?"), the driver will reshuffle, elide, and duplicate parameters as needed.

val normal : t -> t

normal q rewrites q to a normal form containing at most one top-level S constructor, containing no empty literals, and no consecutive literals. This function can be used to post-process queries before using equal and hash.

val equal : t -> t -> bool

Equality predicate for t.

val hash : t -> int

A hash function compatible with equal. This is currently Hashtbl.hash.

val pp : Format.formatter -> t -> unit

pp ppf q prints a human-readable representation of q on ppf. The printed string is not suitable for sending to an SQL database; doing so may lead to an SQL injection vulnerability.

val show : t -> string

show q is the same human-readable representation of q as printed by pp. The returned string is not suitable for sending to an SQL database; doing so may lead to an SQL injection vulnerability.

val concat : string -> t list -> t

concat sep frags is frags interfixed with sep if frags is non-empty and the empty string of frags is empty.

type expand_error

A description of the error caused during expand if the environment lookup function returns an invalid result or raises Not_found for a variable when the expansion is final.

val pp_expand_error : Format.formatter -> expand_error -> unit

Prints an informative error.

exception Expand_error of expand_error

The exception raised by expand when there are issues expanding an environment variable using the provided callback.

val expand : ?final:bool -> (string -> t) -> t -> t

expand f q replaces each occurrence of E v some some v with f v or leaves it unchanged where f v raises Not_found. The Not_found exception will not escape this call.

parameter final
If true, then an error is raised instead of leaving environment references unexpended if f raises Not_found. This is used by drivers for performing the final expansion. Defaults to false.

raises Expand_error
if ~final:true is passed and f raise Not_found or if f returns a query containing environment references.

val angstrom_parser : t Angstrom.t

Matches a single expression terminated by the end of input or a semicolon lookahead. The accepted languages is described in The Syntax of Query Templates.

val angstrom_parser_with_semicolon : t Angstrom.t

A variant of angstrom_parser which accepts unquoted semicolons as part of the a statement, which is allowed in some cases like for defining SQLite3 triggers. This is the parser used by Caqti_request, where it's assumed that the input is a single SQL statement.

val of_string : string -> (t, [ `Invalid of int * string ]) result

Parses a single expression using angstrom_parser_with_semicolon. The error indicates the byte position of the input string where the parse failure occurred in addition to an error message. See The Syntax of Query Templates for how the input string is interpreted.

val of_string_exn : string -> t

Like of_string, but raises an exception on error.

raises Failure
if parsing failed.

package caqti