Debian Codegraph @

manuals/en/misc/vars.tex

raw
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}