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