--- /dev/null
+%%
+%%
+
+\chapter{Variable Expansion}
+\label{VarsChapter}
+\index[general]{Variable Expansion }
+\index[general]{Expansion!Variable }
+
+% TODO: does the following mean that this should not be in book?
+
+Please note that as of version 1.37, the Variable Expansion
+is deprecated and replaced by Python scripting (not yet
+documented).
+
+Variable expansion is somewhat similar to Unix shell variable expansion.
+Currently (version 1.31), it is used only in format labels, but in the future,
+it will most likely be used in more places.
+
+\section{General Functionality}
+\index[general]{Functionality!General }
+\index[general]{General Functionality }
+
+This is basically a string expansion capability that permits referencing
+variables, indexing arrays, conditional replacement of variables, case
+conversion, substring selection, regular expression matching and replacement,
+character class replacement, padding strings, repeated expansion in a user
+controlled loop, support of arithmetic expressions in the loop start, step and
+end conditions, and recursive expansion.
+
+When using variable expansion characters in a Volume Label Format record, the
+format should always be enclosed in double quotes ({\bf "}).
+
+For example, {\bf \$\{HOME\}} will be replaced by your home directory as
+defined in the environment. If you have defined the variable {\bf xxx} to be
+{\bf Test}, then the reference {\bf \$\{xxx:p/7/Y/r\}} will right pad the
+contents of {\bf xxx} to a length of seven characters filling with the
+character {\bf Y} giving {\bf YYYTest}.
+
+\section{Bacula Variables}
+\index[general]{Bacula Variables }
+\index[general]{Variables!Bacula }
+
+Within Bacula, there are three main classes of variables with some minor
+variations within the classes. The classes are:
+
+\begin{description}
+
+\item [Counters]
+ \index[general]{Counters }
+ Counters are defined by the {\bf Counter} resources in the Director's conf
+file. The counter can either be a temporary counter that lasts for the
+duration of Bacula's execution, or it can be a variable that is stored in
+the catalog, and thus retains its value from one Bacula execution to another.
+Counter variables may be incremented by postfixing a plus sign ({\bf +} after
+the variable name).
+
+\item [Internal Variables]
+ \index[general]{Internal Variables }
+ Internal variables are read-only, and may be related to the current job (i.e.
+Job name), or maybe special variables such as the date and time. The
+following variables are available:
+
+\begin{itemize}
+\item [Year] -- the full year
+\item [Month] -- the current month 1-12
+\item [Day] -- the day of the month 1-31
+\item [Hour] -- the hour 0-24
+\item [Minute] -- the current minute 0-59
+\item [Second] -- the current second 0-59
+\item [WeekDay] -- the current day of the week 0-6 with 0 being Sunday
+\item [Job] -- the job name
+\item [general] -- the Director's name
+\item [Level] -- the Job Level
+\item [Type] -- the Job type
+\item [JobId] -- the JobId
+\item [JobName] -- the unique job name composed of Job and date
+\item [Storage] -- the Storage daemon's name
+\item [Client] -- the Client's name
+\item [NumVols] -- the current number of Volumes in the Pool
+\item [Pool] -- the Pool name
+\item [Catalog] -- the Catalog name
+\item [MediaType] -- the Media Type
+ \end{itemize}
+
+\item [Environment Variables]
+ \index[general]{Environment Variables }
+ Environment variables are read-only, and must be defined in the environment
+prior to executing Bacula. Environment variables may be either scalar or an
+array, where the elements of the array are referenced by subscripting the
+variable name (e.g. {\bf \$\{Months[3]\}}). Environment variable arrays are
+defined by separating the elements with a vertical bar ({\bf |}), thus {\bf
+set Months="Jan|Feb|Mar|Apr|..."} defines an environment variable named
+{\bf Month} that will be treated as an array, and the reference {\bf
+\$\{Months[3]\}} will yield {\bf Mar}. The elements of the array can have
+differing lengths.
+\end{description}
+
+\section{Full Syntax}
+\index[general]{Syntax!Full }
+\index[general]{Full Syntax }
+
+Since the syntax is quite extensive, below, you will find the pseudo BNF. The
+special characters have the following meaning:
+
+\footnotesize
+\begin{verbatim}
+ ::= definition
+ ( ) grouping if the parens are not quoted
+ | separates alternatives
+ '/' literal / (or any other character)
+ CAPS a character or character sequence
+ * preceding item can be repeated zero or more times
+ ? preceding item can appear zero or one time
+ + preceding item must appear one or more times
+\end{verbatim}
+\normalsize
+
+And the pseudo BNF describing the syntax is:
+
+\footnotesize
+\begin{verbatim}
+ input ::= ( TEXT
+ | variable
+ | INDEX_OPEN input INDEX_CLOSE (loop_limits)?
+ )*
+ variable ::= DELIM_INIT (name|expression)
+ name ::= (NAME_CHARS)+
+ expression ::= DELIM_OPEN
+ (name|variable)+
+ (INDEX_OPEN num_exp INDEX_CLOSE)?
+ (':' command)*
+ DELIM_CLOSE
+ command ::= '-' (TEXT_EXP|variable)+
+ | '+' (TEXT_EXP|variable)+
+ | 'o' NUMBER ('-'|',') (NUMBER)?
+ | '#'
+ | '*' (TEXT_EXP|variable)+
+ | 's' '/' (TEXT_PATTERN)+
+ '/' (variable|TEXT_SUBST)*
+ '/' ('m'|'g'|'i'|'t')*
+ | 'y' '/' (variable|TEXT_SUBST)+
+ '/' (variable|TEXT_SUBST)*
+ '/'
+ | 'p' '/' NUMBER
+ '/' (variable|TEXT_SUBST)*
+ '/' ('r'|'l'|'c')
+ | '%' (name|variable)+
+ ('(' (TEXT_ARGS)? ')')?
+ | 'l'
+ | 'u'
+ num_exp ::= operand
+ | operand ('+'|'-'|'*'|'/'|'%') num_exp
+ operand ::= ('+'|'-')? NUMBER
+ | INDEX_MARK
+ | '(' num_exp ')'
+ | variable
+ loop_limits ::= DELIM_OPEN
+ (num_exp)? ',' (num_exp)? (',' (num_exp)?)?
+ DELIM_CLOSE
+ NUMBER ::= ('0'|...|'9')+
+ TEXT_PATTERN::= (^('/'))+
+ TEXT_SUBST ::= (^(DELIM_INIT|'/'))+
+ TEXT_ARGS ::= (^(DELIM_INIT|')'))+
+ TEXT_EXP ::= (^(DELIM_INIT|DELIM_CLOSE|':'|'+'))+
+ TEXT ::= (^(DELIM_INIT|INDEX_OPEN|INDEX_CLOSE))+
+ DELIM_INIT ::= '$'
+ DELIM_OPEN ::= '{'
+ DELIM_CLOSE ::= '}'
+ INDEX_OPEN ::= '['
+ INDEX_CLOSE ::= ']'
+ INDEX_MARK ::= '#'
+ NAME_CHARS ::= 'a'|...|'z'|'A'|...|'Z'|'0'|...|'9'
+\end{verbatim}
+\normalsize
+
+\section{Semantics}
+\index[general]{Semantics }
+
+The items listed in {\bf command} above, which always follow a colon ({\bf :})
+have the following meanings:
+
+\footnotesize
+\begin{verbatim}
+ - perform substitution if variable is empty
+ + perform substitution if variable is not empty
+ o cut out substring of the variable value
+ # length of the variable value
+ * substitute empty string if the variable value is not empty,
+ otherwise substitute the trailing parameter
+ s regular expression search and replace. The trailing
+ options are: m = multiline, i = case insensitive,
+ g = global, t = plain text (no regexp)
+ y transpose characters from class A to class B
+ p pad variable to l = left, r = right or c = center,
+ with second value.
+ % special function call (none implemented)
+ l lower case the variable value
+ u upper case the variable value
+\end{verbatim}
+\normalsize
+
+The {\bf loop\_limits} are start, step, and end values.
+
+A counter variable name followed immediately by a plus ({\bf +}) will cause
+the counter to be incremented by one.
+
+\section{Examples}
+\index[general]{Examples }
+
+To create an ISO date:
+
+\footnotesize
+\begin{verbatim}
+ DLT-${Year}-${Month:p/2/0/r}-${Day:p/2/0/r}
+\end{verbatim}
+\normalsize
+
+on 20 June 2003 would give {\bf DLT-2003-06-20}
+
+If you set the environment variable {\bf mon} to
+
+\footnotesize
+\begin{verbatim}
+ January|February|March|April|May|...
+ File-${mon[${Month}]}/${Day}/${Year}
+\end{verbatim}
+\normalsize
+
+on the first of March would give {\bf File-March/1/2003 }
projects / bacula / docs / blobdiff