4
\chapter{Variable Expansion}
6
\index[general]{Variable Expansion }
7
\index[general]{Expansion!Variable }
9
% TODO: does the following mean that this should not be in book?
11
Please note that as of version 1.37, the Variable Expansion
12
is deprecated and replaced by Python scripting (not yet
15
Variable expansion is somewhat similar to Unix shell variable expansion.
16
Currently (version 1.31), it is used only in format labels, but in the future,
17
it will most likely be used in more places.
19
\section{General Functionality}
20
\index[general]{Functionality!General }
21
\index[general]{General Functionality }
23
This is basically a string expansion capability that permits referencing
24
variables, indexing arrays, conditional replacement of variables, case
25
conversion, substring selection, regular expression matching and replacement,
26
character class replacement, padding strings, repeated expansion in a user
27
controlled loop, support of arithmetic expressions in the loop start, step and
28
end conditions, and recursive expansion.
30
When using variable expansion characters in a Volume Label Format record, the
31
format should always be enclosed in double quotes ({\bf "}).
33
For example, {\bf \$\{HOME\}} will be replaced by your home directory as
34
defined in the environment. If you have defined the variable {\bf xxx} to be
35
{\bf Test}, then the reference {\bf \$\{xxx:p/7/Y/r\}} will right pad the
36
contents of {\bf xxx} to a length of seven characters filling with the
37
character {\bf Y} giving {\bf YYYTest}.
39
\section{Bacula Variables}
40
\index[general]{Bacula Variables }
41
\index[general]{Variables!Bacula }
43
Within Bacula, there are three main classes of variables with some minor
44
variations within the classes. The classes are:
49
\index[dir]{Counters }
50
Counters are defined by the {\bf Counter} resources in the Director's conf
51
file. The counter can either be a temporary counter that lasts for the
52
duration of Bacula's execution, or it can be a variable that is stored in
53
the catalog, and thus retains its value from one Bacula execution to another.
54
Counter variables may be incremented by postfixing a plus sign ({\bf +} after
57
\item [Internal Variables]
58
\index[dir]{Internal Variables }
59
Internal variables are read-only, and may be related to the current job (i.e.
60
Job name), or maybe special variables such as the date and time. The
61
following variables are available:
64
\item [Year] -- the full year
65
\item [Month] -- the current month 1-12
66
\item [Day] -- the day of the month 1-31
67
\item [Hour] -- the hour 0-24
68
\item [Minute] -- the current minute 0-59
69
\item [Second] -- the current second 0-59
70
\item [WeekDay] -- the current day of the week 0-6 with 0 being Sunday
71
\item [Job] -- the job name
72
\item [Dir] -- the Director's name
73
\item [Level] -- the Job Level
74
\item [Type] -- the Job type
75
\item [JobId] -- the JobId
76
\item [JobName] -- the unique job name composed of Job and date
77
\item [Storage] -- the Storage daemon's name
78
\item [Client] -- the Client's name
79
\item [NumVols] -- the current number of Volumes in the Pool
80
\item [Pool] -- the Pool name
81
\item [Catalog] -- the Catalog name
82
\item [MediaType] -- the Media Type
85
\item [Environment Variables]
86
\index[dir]{Environment Variables }
87
Environment variables are read-only, and must be defined in the environment
88
prior to executing Bacula. Environment variables may be either scalar or an
89
array, where the elements of the array are referenced by subscripting the
90
variable name (e.g. {\bf \$\{Months[3]\}}). Environment variable arrays are
91
defined by separating the elements with a vertical bar ({\bf |}), thus {\bf
92
set Months="Jan|Feb|Mar|Apr|..."} defines an environment variable named
93
{\bf Month} that will be treated as an array, and the reference {\bf
94
\$\{Months[3]\}} will yield {\bf Mar}. The elements of the array can have
99
\index[general]{Syntax!Full }
100
\index[general]{Full Syntax }
102
Since the syntax is quite extensive, below, you will find the pseudo BNF. The
103
special characters have the following meaning:
108
( ) grouping if the parens are not quoted
109
| separates alternatives
110
'/' literal / (or any other character)
111
CAPS a character or character sequence
112
* preceding item can be repeated zero or more times
113
? preceding item can appear zero or one time
114
+ preceding item must appear one or more times
118
And the pseudo BNF describing the syntax is:
124
| INDEX_OPEN input INDEX_CLOSE (loop_limits)?
126
variable ::= DELIM_INIT (name|expression)
127
name ::= (NAME_CHARS)+
128
expression ::= DELIM_OPEN
130
(INDEX_OPEN num_exp INDEX_CLOSE)?
133
command ::= '-' (TEXT_EXP|variable)+
134
| '+' (TEXT_EXP|variable)+
135
| 'o' NUMBER ('-'|',') (NUMBER)?
137
| '*' (TEXT_EXP|variable)+
138
| 's' '/' (TEXT_PATTERN)+
139
'/' (variable|TEXT_SUBST)*
140
'/' ('m'|'g'|'i'|'t')*
141
| 'y' '/' (variable|TEXT_SUBST)+
142
'/' (variable|TEXT_SUBST)*
145
'/' (variable|TEXT_SUBST)*
147
| '%' (name|variable)+
148
('(' (TEXT_ARGS)? ')')?
152
| operand ('+'|'-'|'*'|'/'|'%') num_exp
153
operand ::= ('+'|'-')? NUMBER
157
loop_limits ::= DELIM_OPEN
158
(num_exp)? ',' (num_exp)? (',' (num_exp)?)?
160
NUMBER ::= ('0'|...|'9')+
161
TEXT_PATTERN::= (^('/'))+
162
TEXT_SUBST ::= (^(DELIM_INIT|'/'))+
163
TEXT_ARGS ::= (^(DELIM_INIT|')'))+
164
TEXT_EXP ::= (^(DELIM_INIT|DELIM_CLOSE|':'|'+'))+
165
TEXT ::= (^(DELIM_INIT|INDEX_OPEN|INDEX_CLOSE))+
172
NAME_CHARS ::= 'a'|...|'z'|'A'|...|'Z'|'0'|...|'9'
177
\index[general]{Semantics }
179
The items listed in {\bf command} above, which always follow a colon ({\bf :})
180
have the following meanings:
184
- perform substitution if variable is empty
185
+ perform substitution if variable is not empty
186
o cut out substring of the variable value
187
# length of the variable value
188
* substitute empty string if the variable value is not empty,
189
otherwise substitute the trailing parameter
190
s regular expression search and replace. The trailing
191
options are: m = multiline, i = case insensitive,
192
g = global, t = plain text (no regexp)
193
y transpose characters from class A to class B
194
p pad variable to l = left, r = right or c = center,
196
% special function call (none implemented)
197
l lower case the variable value
198
u upper case the variable value
202
The {\bf loop\_limits} are start, step, and end values.
204
A counter variable name followed immediately by a plus ({\bf +}) will cause
205
the counter to be incremented by one.
208
\index[general]{Examples }
210
To create an ISO date:
214
DLT-${Year}-${Month:p/2/0/r}-${Day:p/2/0/r}
218
on 20 June 2003 would give {\bf DLT-2003-06-20}
220
If you set the environment variable {\bf mon} to
224
January|February|March|April|May|...
225
File-${mon[${Month}]}/${Day}/${Year}
229
on the first of March would give {\bf File-March/1/2003 }
added
removed
manual/vars.tex
