diff options
Diffstat (limited to 'doc/wydawca.texi')
-rw-r--r-- | doc/wydawca.texi | 156 |
1 files changed, 84 insertions, 72 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi index 2763b6d..8950987 100644 --- a/doc/wydawca.texi +++ b/doc/wydawca.texi @@ -728,52 +728,68 @@ example above: @end group @end smallexample -@anchor{meta-interpretation} -@cindex meta-interpretation -@cindex meta-variables -Depending on the context, the contents of a quoted string may be -subject to @dfn{meta-variable interpretation}. During this process, -any sequence +@anchor{variable expansion} +@cindex variable expansion +@cindex variables +Depending on the context, the quoted string may be subject to +@dfn{variable expansion}. -@smallexample -$@{@var{var}@} -@end smallexample +During variable expansion, references to variables +in the string are replaced with their actual values. A variable +reference has two basic forms: -@noindent -where @var{var} is the name of a defined meta-variable, is replaced with -the value of the variable. This sequence is called @dfn{meta- -reference}. For example, if the meta-variable @samp{user} has the -value @samp{smith}, then the string - -@smallexample -"where user = '$@{user@}'" -@end smallexample +@example + $@var{v} + $@{@var{v}@} +@end example @noindent -becomes +where @var{v} is the variable name. The notation in curly braces +serves several purposes. First, it should be used if the variable +reference is immediately followed by an alphanumeric symbol, which +will otherwise be considered part of it (as in @samp{$@{home@}dir}). +Secondly, this form allows for specifying the action to take if the +variable is undefined or expands to an empty value. -@smallexample -"where user = 'smith'" -@end smallexample - -If the name of the variable consists of a single character, the curly -braces around it may be omitted. Thus, @code{$@{u@}} and @code{$u} are -equivalent. +The following special forms are recognized: -If @var{var} is not defined, the meta-reference is left unchanged. +@table @asis +@item $@{@var{variable}:-@var{word}@} +@dfn{Use Default Values}. If @var{variable} is unset or null, the expansion +of @var{word} is substituted. Otherwise, the value of @var{variable} is +substituted. + +@item $@{@var{variable}:=@var{word}@} +@dfn{Assign Default Values}. If @var{variable} is unset or null, the +expansion of @var{word} is assigned to variable. The value of +@var{variable} is then substituted. + +The assigned value remains in effet during expansion of the current string. + +@item $@{@var{variable}:?@var{word}@} +@dfn{Display Error if Null or Unset}. If @var{variable} is null or unset, +the expansion of @var{word} (or a message to that effect if @var{word} is +not present) is output to the current logging channel. Otherwise, the +value of @var{variable} is substituted. + +@item $@{@var{variable}:+@var{word}@} +@dfn{Use Alternate Value}. If @var{variable} is null or unset, nothing is +substituted, otherwise the expansion of @var{word} is substituted. +@end table -The special sequence @samp{$-} causes removal of it and any character -following it. Most often it is used as a next-to-last character -on a line, right before the newline. In this position it causes the -removal of the trailing newline, similar to @samp{dnl} in @command{m4}. -@xref{listings, Triplet Listings}, for a detailed description and -examples of @samp{$-} use. +These constructs test for a variable that is unset or null. Omitting +the colon results in a test only for a variable that is unset. -To insert a literal @samp{$} character in a string that is subject to -meta-variable interpretation, duplicate it: @samp{$$}. +@anchor{handling of undefined variables} +@cindex expansion of undefined variables +@cindex undefined variable, expansion +If a string contains a reference to an undefined variable, +@command{wydawca} will report an error and abort. To +gracefully handle such cases, use the @dfn{default value construct}, +defined above. -The exact set of defined meta-variables and their values depend on the -context and are discussed in detail below. +@FIXME{Implement the expand-undefined setting, similar to the one in +rush}. @anchor{here-document} @item Here-document @@ -1496,41 +1512,42 @@ See below for a detailed description of these dictionary types. @anchor{query} @deffn {Config: dictionary} query string Sets the query used for retrieving the data. The @var{string} is -subject to meta-variable interpretation (@pxref{meta-interpretation}). The -following meta-variables are defined: +subject to variable expansion (@pxref{variable expansion}). The +following variables are defined in this context: @table @code -@kwindex p @kwindex project -@item p -@itemx project +@item project The system name of the project for which the triplet is submitted. It is defined as the value of directive @code{directory}, or, in case this value contains slashes, the shortest initial prefix of that value, not containing slashes. +@kwindex spool @item spool The name of the distribution spool where this upload originates (@pxref{spool}). +@kwindex url @item url The @acronym{URL} of the spool, as set in the @code{url} statement of the @code{spool} block (@pxref{spool, url}). +@kwindex dir @item dir Directory (relative to the project distribution root) where the files are going to be uploaded. -@item dest-dir +@kwindex dest_dir +@item dest_dir Spool destination directory (@pxref{spool, destination}). -@item source-dir +@kwindex source_dir +@item source_dir Spool source directory (@pxref{spool, source}). -@kwindex u @kwindex user -@item u -@itemx user +@item user @itemx user:name The system name of the user that submitted the triplet. This is defined only for @samp{project-owner} dictionaries. @@ -2010,8 +2027,9 @@ spool @var{tag} @{ @end smallexample The @var{tag} argument defines a unique identifier for this spool. It -will be used in log messages, timers (@pxref{spool-timers}) and in -meta-variable interpretation (@pxref{meta-interpretation}). +will be used in log messages, timers (@pxref{spool-timers}) and is +available for variable expansion (@pxref{variable expansion}) as the +@samp{$spool} variable. @end deffn @deffn {Config: spool} alias list @@ -2028,7 +2046,7 @@ description of this feature. @deffn {Config: spool} url string Defines download @acronym{URL}, associated with this spool. Its value -may be used as @samp{$@{url@}} meta-variable in mail notifications. +may be used as the variable @samp{$url} in mail notifications. @end deffn @deffn {Config: spool} source dir @@ -2215,11 +2233,11 @@ notification}) is generated. In case of non-zero return, the script may return additional diagnostics on the standard output. This diagnostics will be -available for use in notification messages via the @samp{check:diagn} -meta-variable. +available for use in notification messages via the @samp{$check:diagn} +variable. Additionally, the actual return code of the script, in decimal, is -available in the @samp{check:result} meta-variable. If the script +available in the @samp{$check:result} variable. If the script terminates on a signal, the value of this variable is @samp{SIG+@var{n}}, where @var{n} is the signal number. @end deffn @@ -2776,7 +2794,7 @@ mailer "|/bin/nullmail localhost -F$@{sender@} $@{rcpt@}" @cindex notification message template @cindex message template Each notification message is build from a message template, by -expanding meta-variables (@pxref{meta-interpretation}) within it. +expanding variables (@pxref{variable expansion}) within it. The message text may be specified either in place within the configuration directive it belongs to (@pxref{notification}), or defined by @code{define-message} statement. @@ -2874,8 +2892,8 @@ the @acronym{GPG} home directory (@pxref{gpg-homedir}). The statistics message is sent to addresses configured by @code{admin-address} statement (@pxref{mod_mailutils, admin-address}). -@cindex meta-variables in admin notifications -The meta-variables available for use in statistics reports are: +@cindex variables in admin notifications +The variables available for use in statistics reports are: @anchor{statistics variables} @multitable @columnfractions 0.30 0.70 @@ -2912,7 +2930,7 @@ triplets. @kwindex stat:rmsymlinks @item stat:rmsymlinks @tab Number of symbolic links removed. @kwindex stat:check-failures -@item stat:check-failures @tab Number of verification failures +@item stat:check_failures @tab Number of verification failures (@pxref{verification}). @end multitable @@ -3060,9 +3078,9 @@ template, or a reference to a template previously defined by a @kwindex dir @item dir @tab Directory (relative to the project distribution root) where the files where uploaded. -@kwindex dest-dir +@kwindex dest_dir @item dest-dir @tab Value of the @code{destination} keyword. -@kwindex source-dir +@kwindex source_dir @item source-dir @tab Value of the @code{source} keyword. @kwindex triplet:dist @item triplet:dist @tab File name of the main distribution file. @@ -3082,7 +3100,7 @@ $@{triplet:ls:dir@} @end smallexample }. @kwindex triplet:ls:upload -@item triplet:upload @tab Listing of the uploaded files (see below). +@item triplet:ls:upload @tab Listing of the uploaded files (see below). @kwindex triplet:dist @item triplet:ls:dist @tab Listing of the main distribution file (see below). @kwindex triplet:ls:sig @@ -3093,7 +3111,7 @@ $@{triplet:ls:dir@} @item user @tab System name of the user who uploaded the triplet. @kwindex user:name @item user:name @tab System name of the user who uploaded the triplet. -@kwindex user:real-name +@kwindex user:real_name @item user:real-name @tab Real name of the user who uploaded the triplet. @kwindex user:email @item user:email @tab Email of the user who uploaded the triplet. @@ -3164,14 +3182,8 @@ example, here is a possible @code{$@{triplet:ls:full@}} listing: -rw-r--r-- gray user 62 2007-09-06 22:14:35 tar-1.18.tar.gz.directive.asc @end smallexample - The following example shows how to configure success notification -for the user. Notice the use of the @samp{$-} after -@samp{$@{triplet:ls:upload@}}: it removes the newline character after -it and thus allows for more natural indentation of the next -line. Without it, the expanded message would have contained two -newlines after the full listing: one produced by -@samp{$@{triplet:ls:upload@}} and the second one taken verbatim from -the message template. + The example in the following subsection shows how to configure +success notification for the user. @node mod_mailutils example @subsubsection Example of mod_mailutils configuration @@ -3208,7 +3220,7 @@ module-init mailutils @{ files archived ..................... $@{stat:archives@} symlinks created ................... $@{stat:symlinks@} symlinks removed ................... $@{stat:rmsymlinks@} - verification failures .............. $@{stat:check-failures@} + verification failures .............. $@{stat:check_failures@} Timings: @@ -3247,7 +3259,7 @@ notify-event @{ Upload of $@{project@} to $@{url@}/$@{dir@} finished successfully. Files uploaded: - $@{triplet:ls:upload@}$- + $@{triplet:ls:upload@} Resource usage: $@{timer:triplet:real@}/$@{timer:wydawca:real@}r \ $@{timer:triplet:user@}/$@{timer:wydawca:user@}u \ @@ -3324,7 +3336,7 @@ files uploaded: $@{stat:uploads@} files archived: $@{stat:archives@} symlinks created: $@{stat:symlinks@} symlinks removed: $@{stat:rmsymlinks@} -check failures: $@{stat:check-failures@} +check failures: $@{stat:check_failures@} EOT; @end group @end example |