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.2.4.tbz
sha256=b8ea432820154ec095132c4f7b244b06cd8553e0b2035185b844d9c4f30af8bb
sha512=b7e3ad8e6a9b587db2d517e15cd42df2945148f9223b2fa6f4bc2bcdd2709d53549cca4b65e54511d22466e4c9aa7f0b9c17305a07505519d8bf81d95de629b8

doc/caqti.template/Caqti_template/Query_fmt/index.html

Module Caqti_template.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, 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 : (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.

Sourceval query : Query.t t

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_template.Query.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