Format

Description

VMOD format brings formatted strings to VCL for easy string building. This can be used for templating, formatting, and removing the need for large, hard to read, and or ugly string concatenation. This VMOD uses the ANSI C printf format with ordered arguments. Additionally formatting can be specified with Edgestash syntax and a JSON object.

Examples

Build a JSON object

sub vcl_deliver {
    format.set({"{ "key":"%s","something":%d}"});
    format.add_string(req.http.value);
    format.add_integer(resp.status);
    set resp.http.json = format.get();
}

Sign an authoritative header

sub vcl_recv {
    format.set("%s\n%s\n%s\n");
    format.add_string(req.method);
    format.add_string(req.url);
    format.add_string(req.http.Date);
    set req.http.auth = crypto.hmac(sha256, "secret",
        format.get());
}

Quickly build a string in one function

sub vcl_synth {
    set resp.body = format.quick("ERROR: %s\nREASON: %s\n",
        resp.status, resp.reason);
    return (deliver);
}

Format string options

The format strings uses the ANSI C printf format. A format string has two parts. Plain unformatted characters and formatted arguments. Fromatted arguments start with % and end with a specifier. Optionally flags, width, precision and size can be added.

The order is as follows:

%[flags][width][precision][length]specifer

There are four types of specifiers: integers, floating point numbers, characters and strings.

The following specifiers are supported:

Integer: d, i, o, ux, X
Float: a, A, e, E, f, F, g, G
Character: c
String: s

The following additional options are supported:

Flags: -, +, (space), #, 0, '
Width: (number), *
Precision: .(number), .*
Length: h, hh, l, ll, j, z, t

When using * or .* a width or precision must be added to the add function.

For more information see the man page for printf.

Functions

There are two ways to produce a formatted string. The first way is by building the formatted string by setting the format string with set(). Followed by adding ordered arguments with add_int, add_float, add_char, and add_string. Once all the arguments have been added, the formatted string can be produced with get(). Arguments added out of order, or too few/many arguments will cause an error. Adding a width or precision in the add functions without a variable width or precision in the format string will result in an error. Missing the width or precision in the add functions when the argument expectes a variable width will result in an error.

The second way to produce a format string is with an inline function where the format and the arguments are in the same function. This is done with quick() and edgestash().

set

VOID set(STRING fmt)

Set the ANSI C printf format string. See above for available options.

Arguments

STRING fmt - The format string.

Returns

Nothing.

add_int

VOID add_int(INT value, [INT width], [INT precision])

Add an integer argument.

Arguments

INT value - The argument to use in the formatted string.
INT width optional - The variable width to use in the format string.
INT precision optional - The variable precision to use in the format string.

Returns

Nothing.

add_float

VOID add_float(REAL value, [INT width], [INT precision])

Add a floating point argument.

Arguments

REAL value - The argument to use in the formatted string.
INT width optional - The variable width to use in the format string.
INT precision optional - The variable precision to use in the format string.

Returns

Nothing.

add_char

VOID add_char(INT value, [INT width], [INT precision])

Add a character argument.

Arguments

INT value - The argument to use in the formatted string.
INT width optional - The variable width to use in the format string.
INT precision optional - The variable precision to use in the format string.

Returns

Nothing.

add_string

VOID add_string(INT value, [INT width], [INT precision], BOOL show_null = true)

Add a string argument.

Arguments

STRING value - The argument to use in the formatted string.
INT width optional - The variable width to use in the format string.
INT precision optional - The variable precision to use in the format string.
BOOL show_null optional - Indicate whether to show (null) or nothing when value exists.

Returns

Nothing.

get

VOID get()

Get the formatted string.

Arguments

None.

Returns

The formatted string.

reset

VOID reset()

Clear the internal state from set().

Arguments

None.

Returns

Nothing.

quick

STRING quick(STRING fmt, STRING value1, STRING value2, ..., BOOL show_null = true)

Produce a formatted string with one function. The format can only contain strings. There is a maximum of 30 arguments named value1 to value30.

Arguments

STRING fmt - The format string.
STRING value1 - The argument to use in the formatted string.
STRING value# optional - Additional arguments where # can be 2 to 30.
BOOL show_null optional - Indicate whether to show (null) or nothing when value exists.

Returns

The formatted string.

edgestash

STRING edgestash(STRING template, STRING json_string, [STRING sdelimiter], [STRING edelimiter], BOOL cache = true)

Produce a formatted string from an Edgestash template and a JSON object.

Arguments

STRING template - The Edgestash template.
STRING json_string - The set of variables to use in the template.
STRING sdelimiter optional - The starting delimiter to use in the template.
STRING edelimiter optional - The ending delimiter to use in the template.
BOOL cache optional - Indicate if the template should be cached. If there is already a template in cache, indicate if the cached template should be used. If false the template can be changed.

Returns

The formatted string.