summaryrefslogtreecommitdiffabout
path: root/src/vmod-variable.3
blob: f249ad34c2466ae88a2f3d274f1c1f971508b9ea (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
.\" This file is part of Vmod-variable -*- nroff -*-
.\" Copyright (C) 2015 Sergey Poznyakoff
.\"
.\" Vmod-variable is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" Vmod-variable is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with vmod-variable.  If not, see <http://www.gnu.org/licenses/>.
.TH VMOD-VARIABLE 1 "February 16, 2015" "VMOD-VARIABLE" "User Reference"
.SH NAME
vmod-variable \- variable support for Varnish Cache
.SH SYNOPSIS

\fBimport variable\fR [\fIPATH\fR]\fB;\fR

.SH DESCRIPTION
This module provides enhanced variable support for \fBVCL\fR scripts.
.PP
There are two kind of variables: \fIsession-specific\fR and \fIglobal\fR.
Session-specific variables have a lifespan of one HTTP session and cease to
exist when it is closed.  Such variables can be of almost any VCL type:
.BR STRING ,
.BR INT ,
.BR REAL ", or"
.BR DURATION .
For each of these types a pair of functions is provided for setting the
variable and obtaining its value.
.PP
Two functions are provided for setting several variables at once.  The
\fBregset\fR function parses its input according to a regular expression
and sets variables to the captured strings, using sophisticated declaration
patterns.
.PP
The \fBqueryset\fR function parses its input as a HTTP query string and
sets the variables defined in it.
.PP
The \fIglobal\fR variables are shared between all threads and sessions.  They
can hold only string values.
.SH VMOD_VARIABLE VS. VMOD_VAR
This module doesn't share any code with \fBvmod_var\fR.  Compared with
the latter, it provides the following new features:
.PP
.nr step 1 1
.IP \n[step].
Both Varnish 3 and 4 are supported;
.IP \n+[step].
Variables are stored in hash tables with open addressing, to
speed up accesses (\fBvmod_var\fR keeps them in singly-linked lists).
.IP \n+[step].
Functions for testing existence and types of variables, and for
unsetting a variable:
.BR defined() ,
.BR type_of() ", and"
.BR unset() .
.IP \n+[step].
The \fBregset()\fR and \fBqueryset()\fR functions.
.IP \n+[step].
Additional functions for global variables:
.BR global_clear() ,
.BR global_defined() ", and"
.BR global_unset() .
.PP
To facilitate transition, \fBvmod_variable\fR uses the same naming
scheme as \fBvmod_var\fR, so switching to using it in your VCL script
is as simple as replacing \fBs/var\\./variable./\fR.
.SH FUNCTIONS
The function below operate on session-local variables.
.PP
.TP
\fBVOID set(STRING \fIname\fB, STRING \fIvalue\fB)\fR
Assigns \fIvalue\fR to the string variable \fIname\fR.
.TP
\fBSTRING get(STRING \fIname\fB)\fR
Returns value of the string variable \fIname\fR.  If the variable is not
defined, \fBNULL\fR is returned.
.TP
\fBVOID set_int(STRING \fIname\fB, INT \fIvalue\fB)\fR
Assigns \fIvalue\fR to the integer variable \fIname\fR.
.TP
\fBINT get_int(STRING \fIname\fB)\fR
Returns value of the integer variable \fIname\fR.  If the variable is not
defined, \fB0\fR is returned.
.TP
\fBVOID set_string(STRING \fIname\fB, STRING \fIvalue\fB)\fR
Same as \fBset\fR.
.TP
\fBSTRING get_string(STRING \fIname\fB)\fR
Same as \fBget\fR.
.TP
\fBVOID set_real(STRING \fIname\fB, REAL \fIvalue\fB)\fR
Assigns \fIvalue\fR to the floating-point variable \fIname\fR.
.TP
\fBREAL get_real(STRING \fIname\fB)\fR
Returns value of the floating-point variable \fIname\fR.  If the variable is
not defined, \fB0.000\fR is returned.
.TP
\fBVOID set_duration(STRING \fIname\fB, DURATION \fIvalue\fB)\fR
Assigns \fIvalue\fR to the duration variable \fIname\fR.
.TP
\fBDURATION get_duration(STRING \fIname\fB)\fR
Returns value of the duration variable \fIname\fR.  If the variable is not
defined, \fB0.000\fR is returned.
.TP
\fBVOID regset(STRING \fIvardcl\fB, STRING \fIregex\fB, STRING \fIinput\fB)\fR
If \fIinput\fR matches regular expression \fIregex\fR, initializes variables
declared in \fIvardcl\fR to parts of \fIinput\fR captured by parenthesized
groups in \fIregex\fR.

The parameter \fIvardcl\fR contains one or more comma-separated declarations.
Each declaration is a variable name, optionally followed by the following
constructs, in that order: \fB:\fITYPE\fR and \fB=\fIREPL\fR.

The \fB:\fITYPE\fR construct declares the type of the variable.  \fITYPE\fR
can be one of
.BR STRING ,
.BR INT ,
.BR REAL ,
.BR DURATION ,
or any abbreviation of these (case-insensitive).  E.g. \fBx:r\fR means
that the variable \fBx\fR is of \fBREAL\fR type.  If this part is omitted,
\fBSTRING\fR type is assumed.

The \fB=\fIREPL\fR suffix instructs the function to set the variable to the
value computed according to \fIREPL\fR, which is a replacement expression in
the sense of \fBregsub\fR.

If this part is omitted, the variable is initialized to the value of the
\fBN\fRth capture group from \fIregex\fR, where \fBN\fR is the position
of that declaration in \fIvardcl\fR.

Both parts can be used together, for example: \fBtime:d=\\1m\fR will set
the \fBtime\fR variable to the duration obtained by concatenating first
captured group with the suffix \fBm\fR.

Backreferences referring to unexisting capturing groups are retained
verbatim.
.TP
\fBVOID queryset(STRING \fIvardcl\fB, STRING \fIinput\fB)\fR
Parses \fIinput\fR as HTTP query string and assigns variables according
to \fIvardcl\fR.

If \fIvardcl\fR is empty, the function will define all variables present
in \fIinput\fR to string values.  Otherwies, only the named variables
will be set.

The value of the \fIvardcl\fR variable is a comma-separated list of variable
names, optionally followed by \fB:\fITYPE\fR construct, whose meaning is
the same as in \fBregset\fR.
.TP
.B VOID clear()
Re-initializes session-local variable table.  All variables are forgotten.
.PP
.TP
\fBBOOL defined(STRING \fIname\fB)\fR
Returns \fBTRUE\fR if the variable \fIname\fR is defined.
.TP
\fBSTRING type_of(STRING \fIname\fB)\fR
Returns type of the variable \fIname\fR.  Available types are:
.BR UNSET ,
.BR STRING ,
.BR INT ,
.BR REAL ,
.BR DURATION .
.TP
\fBVOID unset(STRING \fIname\fB)\fR
Unsets the variable \fIname\fR.
.SS Global variables
.PP
The functions below operate on global variables.  Global variables can
be hold only string values.
.PP
.TP
\fBVOID global_set(STRING \fIname\fB, STRING \fIvalue\fB)\fR
Assigns \fIvalue\fR to the global variable \fIname\fR.
.TP
\fBSTRING global_get(STRING \fIname\fB)\fR
Returns value of the global variable \fIname\fR.  If the variable is not
defined, \fBNULL\fR is returned.
.TP
\fBBOOL global_defined(STRING \fIname\fB)\fR
Returns \fBTRUE\fR if the global variable \fIname\fR is defined.
.TP
\fBVOID global_unset(STRING \fIname\fB)\fR
Unsets global variable \fIname\fR.
.TP
.B VOID global_clear()
Re-initializes global variable table.  All variables are forgotten.
.SH EXAMPLES
.nr step 1 1
.TP
.IP \n[step].
Set ttl and grace parameters of the object according to the
\fBSurrogate\-Control\fR header.
.PP
.EX
variable.regset("ttl:d=\\1s,grace:d=\\2s",
                "^(?:.*,)?\s*max\-age=([0\-9]+)(?:\+([0\-9]+))",
                beresp.http.Surrogate\-Control);
set beresp.ttl = variable.get_duration("ttl");
set beresp.grace = variable.get_duration("grace");
.EE
.TP
.IP \n+[step].
Set local variables from GET parameters.
.PP
.EX
if (req.request == "GET") {
  variable.queryset("", regsub(req.url, ".*\\?(.+)", "\\1"));
}
.EE
.\"
.\" The MANCGI variable is set by man.cgi script on Ulysses.
.\" The download.inc file contains the default DOWNLOAD section
.\" for man-based doc pages.
.if "\V[MANCGI]"WEBDOC" \{\
.	ds package vmod-variable
.	ds version 1.0
.	so download.inc
\}
.SH "SEE ALSO"
.BR vcl (7),
.BR varnishd (1).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray@gnu.org>.
.SH COPYRIGHT
Copyright \(co 2015 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.