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