tourist/param
query-string parser and path-capture helpers.
Since: v0.1.0
tourist-ctx-caps
(tourist-ctx-caps [ctx : Ctx] :)
raw __tourist_caps handle stored in a ctx.
| ctx | :int tourist context handle |
Captures -- captures handle (may be the null handle, i.e. (:: 0 :Captures))
Since: v0.1.0 (typed as Captures in v0.2.1; ctx retyped to Ctx in v0.2.6)
tourist-ctx-strip-path
(tourist-ctx-strip-path [ctx : Ctx new-path : cstr] :)
swap ctx->path with new-path and return the old.
| ctx | :int tourist ctx handle | |
| new-path | :cstr new value for ctx->path |
:cstr -- previous ctx->path value; pass it back in to restore.
Since: v0.2.0
req-full-path
(req-full-path [ctx : Ctx] :)
original request path before any url-map! stripping.
| ctx | :int tourist ctx handle |
:cstr -- the original (unstripped) request path
;; Request: GET /api/users ;; sub-app mounted at /api (req-path ctx) ;; => "/users" (req-full-path ctx) ;; => "/api/users"
Since: v0.2.0
tourist-ctx-new
(tourist-ctx-new [req : int caps : int] :)
wrap an httpd request + captures into a tourist ctx.
| req | :int httpd request handle (caller retains ownership) | |
| caps | :int captures handle from router-match (ctx takes ownership) |
Ctx -- tourist ctx handle; free with tourist-ctx-free
(let [ctx (tourist-ctx-new req caps)]
...)
Since: v0.1.0 (return retyped to Ctx in v0.2.6)
tourist-ctx-free
(tourist-ctx-free [ctx : Ctx] :)
release a tourist ctx and its owned resources.
| ctx | :int tourist ctx handle, or 0 (no-op) |
:void
(tourist-ctx-free ctx)
Since: v0.1.0
param
(param [ctx : Ctx key : cstr] :)
look up a query parameter by key.
| ctx | :Ctx tourist context (from tourist-ctx-new or passed by app) | |
| key | query parameter name, e.g. "q" for ?q=hello |
(Result cstr cstr) -- ok(value) if found, err("missing") otherwise
(let [r (param req "q")]
(when (ok? r) (ok-val r)))
Since: v0.1.0 (typed as Result in 0.2.0; ctx retyped to Ctx in 0.2.2)
capture
(capture [ctx : Ctx name : cstr] :)
look up a path-segment capture by name.
| ctx | :Ctx tourist context | |
| name | capture name, e.g. "id" for ":id", or "*" for wildcard |
(Result cstr cstr) -- ok(value) if found, err("missing") otherwise
(let [r (capture req "name")]
(when (ok? r) (ok-val r)))
Since: v0.1.0 (typed as Result in 0.2.0; ctx retyped to Ctx in 0.2.2)
ctx-attr-get
(ctx-attr-get [ctx : Ctx key : cstr] :)
look up a per-request attribute by key.
| ctx | :Ctx tourist context | |
| key | attribute name (key compared by strcmp) |
(Option int) -- (some value) if set, (none) otherwise
(let [o (ctx-attr-get ctx "request-id")]
(when (some? o) (println-int (unwrap o))))
Since: v0.2.0
ctx-attr-set!
(ctx-attr-set! [ctx : Ctx key : cstr val : int] :)
set or replace a per-request attribute.
| ctx | :Ctx tourist context | |
| key | attribute name (will be strdup'd) | |
| val | :int payload (any int64-sized value, including cast pointers) |
:void
(ctx-attr-set! ctx "request-id" 0x1234)
Since: v0.2.0
ctx-add-header!
(ctx-add-header! [ctx : Ctx name : cstr value : cstr] :)
queue a response header to be applied after dispatch.
| ctx | :Ctx tourist context | |
| name | HTTP header name (e.g. "X-Request-Id") | |
| value | header value |
:void
(ctx-add-header! ctx "X-Request-Id" "abc-123")
Since: v0.2.0
tourist-ctx-resp-headers
(tourist-ctx-resp-headers [ctx : Ctx] :)
raw head pointer of the resp_headers cons list.
| ctx | :int tourist context handle |
:int -- head cell pointer, or 0 if no headers were queued
Since: v0.2.0
tourist-ctx-clear-resp-headers
(tourist-ctx-clear-resp-headers [ctx : Ctx] :)
free the resp_headers list and reset to 0.
| ctx | :int tourist context handle |
:void
Since: v0.2.0
tourist-ctx-req
(tourist-ctx-req [ctx : Ctx] :)
the httpd Request a ctx was built from.
| ctx | tourist ctx |
Request -- the request handle (valid while the request is served)
Since: v0.3.0
tourist-ctx-around-rest
(tourist-ctx-around-rest [ctx : Ctx] :)
internal: use-around! items still to run.
tourist-ctx-set-around-rest!
(tourist-ctx-set-around-rest! [ctx : Ctx rest : ItemList] :)
internal: record the use-around! position.
tourist-ctx-own!
(tourist-ctx-own! [ctx : Ctx s : cstr] :)
internal: make a malloc'd string the ctx's, freed
| ctx | tourist ctx | |
| s | a malloc'd string (ownership moves to the ctx) |
:cstr -- s
Since: tourist-on-stdlib-httpd H5
Internal definitions
__parse-qp-- parse a raw query string into parallel key/value arrays.__tourist-ctx-alloc__ctx-free-attrs-- release the attrs cons list (keys are owned cstr copies).__ctx-free-resp-headers-- release the resp_headers cons list (owned cstrs).__ctx-free-qp__ctx-free-struct__ctx-free-owned-- release the strings tourist-ctx-own! collected.