/ 
HTTP-API-Client-1.26
/ HTTP::API::DataTypeMarker

NAME

HTTP::API::DataTypeMarker - mark request data so it serializes as a specific type, since Perl scalars have no native boolean and no native "comma list"

SYNOPSIS

use HTTP::API::Client;    # re-exports everything below

$api->post( $url, {
    enabled => xTRUE,          # JSON: true            / form: 1
    legacy  => xTrue,          # JSON/form string: "True"
    tags    => xCSV(1, 2, 3),  # form: "tags=1,2,3"
} );

DESCRIPTION

Every value here is a blessed arrayref - either HTTP::API::DataTypeMarker::BOOL (from "xBOOLEAN($value)") or HTTP::API::DataTypeMarker::CSV (from "xCSV(@values)"), referred to below by their unqualified names, BOOL and CSV, for brevity - namespaced deliberately (not bare 'BOOL'/ 'CSV') so an unrelated class of the same short name elsewhere in a calling application can't collide with what kvp2json_each/ kvp2str_each's ref($v) eq ... checks are actually looking for. BOOL is recognized and unwrapped specially by both kvp2json_each and kvp2str_each, since a bare Perl scalar (1, 0, "true", ...) is always ambiguous about whether it means a JSON boolean, a string, or a number. CSV is only special-cased by kvp2str_each, which joins it into one comma-separated key=value,value instead of a key repeated per element - a form-urlencoded-specific problem JSON doesn't have. kvp2json_each has no CSV handling at all; a blessed CSV arrayref satisfies Perl's reftype-based ARRAY check regardless of blessing, so it falls through to the plain-array branch and JSON-encodes as an ordinary array (xCSV(1,2,3) becomes [1,2,3]) - which is the natural JSON representation of a list anyway.

xCSV(@values)

Mark a list so it serializes as one comma-joined value instead of one repeated key per element. xCSV(1, 2, 3) becomes a=1,2,3 in a form-urlencoded request instead of the default a=1&a=2&a=3. Each value is copied at call time - xCSV($x, $y) then reassigning $x does not change what was already captured.

xBOOLEAN($value)

The building block every x* boolean marker below is made of. Wraps $value (a plain scalar or a scalar ref) so kvp2json_each/ kvp2str_each unwrap and emit it verbatim instead of treating it as an array. Use one of the named markers below rather than this directly unless none of them fit.

A plain scalar is copied at call time, the same as xCSV's values - xBOOLEAN($flag) then reassigning $flag does not change what was already captured. Pass a scalar ref instead (xBOOLEAN(\$flag)) to opt into tracking $flag live - the marker then always reflects whatever $flag currently holds when it's later read. Only a plain scalar or a scalar ref is accepted - wrapping anything else (an arrayref, a hashref) dies with a clear message when the marker is later encoded, rather than silently stringifying it.

xTRUE / xFALSE

A real JSON boolean: true / false with no quotes in JSON output, and 1 / 0 in a form-urlencoded request.

xTrue / xFalse

The literal string "True" / "False", quoted like any other string in JSON, unescaped in a form-urlencoded request.

xtrue / xfalse

The literal string "true" / "false" (lowercase).

xt__e / xf___e

The single-character string "t" / "f".