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.
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();
}
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());
}
sub vcl_synth {
set resp.body = format.quick("ERROR: %s\nREASON: %s\n",
resp.status, resp.reason);
return (deliver);
}
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:
d
, i
, o
, u
x
, X
a
, A
, e
, E
, f
, F
, g
, G
c
s
The following additional options are supported:
-
, +
, (space)
, #
, 0
, '
(number)
, *
.(number)
, .*
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
.
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()
.
VOID set(STRING fmt)
Set the ANSI C printf
format string. See above for available options.
Arguments
STRING fmt
- The format string.Returns
Nothing.
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.
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.
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.
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.
VOID get()
Get the formatted string.
Arguments
None.
Returns
The formatted string.
VOID reset()
Clear the internal state from set()
.
Arguments
None.
Returns
Nothing.
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.
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.