package caqti

  1. Overview
  2. Docs
On This Page
  1. Value Formatters
Unified interface to relational database libraries

Install 

dune-project
 Dependency

github.com Readme Changelog Edit opam file Versions (21)

Authors

  1. P
    Petter A. Urkedal <paurkedal@gmail.com>
  2. N
    Nathan Rebours <nathan@cryptosense.com>
  3. B
    Basile Clément

Maintainers

  1. P
    Petter A. Urkedal <paurkedal@gmail.com>

Sources

caqti-v2.1.2.tbz
sha256=ba4dfd5ff94376b5e003f682410b7b3b392c0bbaa0253679fe7671c2e07e895b
sha512=0416807fba620429ee4d64f3a6991238112e0e10dfba9703dced46cf332fd22135a9873007d025441228ce66fb192bf730d4bc776dd2c1a973d7604ab6e789e0

doc/caqti/Caqti_query_fmt/index.html

Module Caqti_query_fmtSource

Format-based query construction.

Sourcetype 'a t = Format.formatter -> 'a -> unit

The type of a function which formats values of type 'a or fragments based on an input of type 'a.

Sourceval qprintf : ('a, Format.formatter, unit, Caqti_query.t) format4 -> 'a

qprintf allows building Caqti queries using a printf-style interface.

When using qprintf, you can use the query, quote, env and param printers from this module to generate the corresponding query fragments.

In addition, you can use the "Q" and "E" string tags to delimit portions of the formatting string that should be interpreted as quotes and environment variables, respectively. The "Q" and "E" tags can not be nested: within the tags, qprintf behaves no differently than Format.asprintf and will generate a string, not a query (only when the tag is closed does the string get converted into a query).

The two following calls to qprintf:

  qprintf "FUNC(@{<Q>Quoted value with %d format(s)})" 1

and

  qprintf "FUNC(%a)" quote (Format.asprintf "Quoted value with %d format(s)" 1)

are functionally equivalent. Both compute

  S [L "FUNC("; Q "Quoted value with 1 format(s)"; L ")"]

but the first one is nicer to work with.

  • raises Failure

    if the "Q" and "E" tags are nested.

Sourceval kqprintf : (Caqti_query.t -> 'a) -> ('b, Format.formatter, unit, 'a) format4 -> 'b

kqprintf is the continuation-passing version of qprintf (like Format.kasprintf for Format.asprintf).

You usually want qprintf instead.

Sourceval param : int t

param is a formatter that includes the corresponding parameter in a query built by qprintf.

Note that to include a parameter in a query, param *must* be used: using literal "$" or "?" will be sent as-is to the SQL driver and will not be processed by Caqti.

Sourceval env : string t

env is a formatter that includes the corresponding environment variable in a query built by qprintf.

Note that to include an environment variable in a query, env *must* be used: using literal "$(...)" will be sent as-is to the SQL driver and will not be processed by Caqti.

Sourceval quote : string t

quote is a formatter that includes a TEXT literal in a query built by qprintf.

query can be used with qprintf to embed a query that was already parsed in the format string. Direct use of query should be rare, and param, env, or quote should be used instead when possible.

Using query with any other formatter will ignore the query and instead print a dummy value (currently "... SQL FRAGMENT ...") instead.

Value Formatters

The following formatters emit values of basic field types by passing them as parameters. This is done by emitting a Caqti_query.t.V node with a appropriate field type.

Sourceval bool : bool t
Sourceval int : int t
Sourceval float : float t
Sourceval string : string t
Sourceval octets : string t
Sourceval pdate : Ptime.t t
Sourceval ptime : Ptime.t t
Sourceval ptime_span : Ptime.span t