Format

Description

The format vmod 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.

Format string options

The format strings uses the ANSI C printf format. A format string has two parts. Plain unformatted characters and formatted arguments. Formatted 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]specifier

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

The following specifiers are supported:

Integer: d, i, o, u, x, 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.

Examples

Build a JSON object:

sub vcl_deliver {
  format.set({"{ "key":"%s","something":%d}"});
  format.add_string(req.http.value);
  format.add_int(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);
}

API

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 expects 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 a printf like format to be able to format a string. Finish formatting by calling get(). Arguments must be added with the add_*() functions. Arguments must be added in order. All printf functionality is supported except for %p, %n and %m. Additionally flags, width, precision, and length can be used.

Arguments:

fmt accepts type STRING

Type: Function

Returns: None

add_string

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

Add a string argument with an optional width and precision. When value doesn’t exist and show_null is true, (null) will be added, otherwise an empty string is used.

Arguments:

value accepts type STRING
show_null accepts type BOOL with a default value of 1 optional
width accepts type INT
precision accepts type INT

Type: Function

Returns: None

add_int

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

Add an integer argument with an optional width and precision.

Arguments:

value accepts type INT
width accepts type INT
precision accepts type INT

Type: Function

Returns: None

add_float

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

Add a floating point argument with an optional width and precision.

Arguments:

value accepts type REAL
width accepts type INT
precision accepts type INT

Type: Function

Returns: None

add_char

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

Add a character argument with an optional width and precision.

Arguments:

value accepts type INT
width accepts type INT
precision accepts type INT

Type: Function

Returns: None

get

STRING get()

Return the formatted string.

Arguments: None

Type: Function

Returns: String

reset

VOID reset()

Reset the state started with set()

Arguments: None

Type: Function

Returns: None

quick

STRING quick(STRING fmt, STRING value1, [STRING value2], [STRING value3], [STRING value4], [STRING value5], [STRING value6], [STRING value7], [STRING value8], [STRING value9], [STRING value10], [STRING value11], [STRING value12], [STRING value13], [STRING value14], [STRING value15], [STRING value16], [STRING value17], [STRING value18], [STRING value19], [STRING value20], [STRING value21], [STRING value22], [STRING value23], [STRING value24], [STRING value25], [STRING value26], [STRING value27], [STRING value28], [STRING value29], [STRING value30], BOOL show_null = 1)

This function is a quick way to return a formatted string without needing to call set() and get(). Can only use string arguments.

Arguments:

fmt accepts type STRING
value1 accepts type STRING
show_null accepts type BOOL with a default value of 1 optional
value2 accepts type STRING
value3 accepts type STRING
value4 accepts type STRING
value5 accepts type STRING
value6 accepts type STRING
value7 accepts type STRING
value8 accepts type STRING
value9 accepts type STRING
value10 accepts type STRING
value11 accepts type STRING
value12 accepts type STRING
value13 accepts type STRING
value14 accepts type STRING
value15 accepts type STRING
value16 accepts type STRING
value17 accepts type STRING
value18 accepts type STRING
value19 accepts type STRING
value20 accepts type STRING
value21 accepts type STRING
value22 accepts type STRING
value23 accepts type STRING
value24 accepts type STRING
value25 accepts type STRING
value26 accepts type STRING
value27 accepts type STRING
value28 accepts type STRING
value29 accepts type STRING
value30 accepts type STRING

Type: Function

Returns: String

edgestash

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

Get a formatted string from an Edgestash template and a json. The boolean cache indicates if the template should be cached. If there is already a template in cache, it will indicate if the cached template should be used. If false, the template can be changed.

Arguments:

template accepts type STRING
json_string accepts type STRING
cache accepts type BOOL with a default value of 1 optional
sdelimiter accepts type STRING
edelimiter accepts type STRING

Type: Function

Returns: String

Availability

The format VMOD is available in Varnish Cache Plus version 6.0.7r1 and later.