SearchVarnish Enterprise
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.
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:
d, i, o, u, x, Xa, A, e, E, f, F, g, GcsThe following additional options are supported:
-, +, (space), #, 0, '(number), *.(number), .*h, hh, l, ll, j, z, tWhen using * or .* a width or precision must be added to the add function.
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);
}
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().
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 STRINGType: Function
Returns: None
Restricted to: client, backend
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
Restricted to: client, backend
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
Restricted to: client, backend
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
Restricted to: client, backend
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
Restricted to: client, backend
STRING get()
Return the formatted string.
Arguments: None
Type: Function
Returns: String
Restricted to: client, backend
VOID reset()
Reset the state started with set()
Arguments: None
Type: Function
Returns: None
Restricted to: client, backend
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
Restricted to: client, backend
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
The format VMOD is available in Varnish Enterprise version 6.0.7r1 and later.