git.sur5r.net Git - bacula/docs/blob - docs/manuals/en/misc/vars.tex

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