git.sur5r.net Git - bacula/docs/blob - docs/manual-fr/vars.tex

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