Provided by: aegis_4.24.3-1_i386 bug

NAME

       aesub - aegis command substitutions

DESCRIPTION

       When other programs are invoked by the aegis program, it is usually via
       a command string in a configuration file.  This section describes the
       format of these command strings.

GENERAL FORM

       The command strings are very similar to shell variables.  An example
       will illustrate this:
               build_command =
                    "cook project=${project} change=${change}";
       In this command definition, the "${project}" part is a substitution:
       the name of the project will be substituted in the command at this
       point.

       Substitutions may take several forms:

       $name
               This is the same as saying "${name}".  The name must start with
               an alphabetic, and be followed by zero or more alphanumerics.

       ${name}
               The name in this form may contain any non-blank characters, and
               it may be subject to substitution.

       ${name arg...}
               The name and the arguments in this form may contain any non-
               blank characters, and it may be subject to further
               substitution.  Within the braces ({ and }) pairs of single
               quote characters (’blah blah’) may be used to insulate spaces
               and other special characters, or you may use the back quote (\)
               to escape a single character.

       $$
               This is replaced by a single $ character.  It avoid RCS
               expansions, you can also use ${$}.

       %%
               This is replaced by a single % character.  Percent (%) followed
               by anything else is illegal.

       $#...\n This is a comment, usually found in template files read in
               using the ${read_file} substitution.  It consumes all
               characters up to and including the next newline.  (See also
               ${comment}, below.)

       As another example, the dirname substitution is replaced by the
       directory name of the argument, rather like the dirname(1) command.  In
       the command
              history_query_command =
                   "get -t -g ${Dirname $History}/s.${Basename $History}";
       the Dirname and Basename substitutions are used to construct a suitable
       path to the SCCS file in the history directory.

ABBREVIATIONS

       The names of the various substitutions may be abbreviated.  In the
       above examples, and in the lists which follow, the minimum abbreviation
       is the uppercase letters.  All substitution name are case insensitive.

       The above example could be abbreviated to
              history_query_command =
                   "get -t -g ${d $h}/s.${b $h}";

       Ambiguous abbreviations will result in a fatal error message.

SUBSTITUTIONS

       There are many substitutions which are always understood, and some
       which are specific to the command being substituted.  Specific entries
       will be defined in the relevant manual section.

       The following lists contains those substitutions which are always
       understood:

       Active_Directory
               The absolute path of the change’s development directory, if the
               change is between the being developed and awaiting integration
               states.  The absolute path of the change’s integration
               directory, if the change is in the being integrated state.  Not
               available when the change is in the awaiting development or
               completed states.  This rather like the default behaviour of
               the aecd(1) command.

       Add_Path_Suffix
               This substitution may be used to add a suffix to each element
               of a colon-separated path list.  The first argument is the
               suffix to use, the second and subsequent arguments are the
               colon-separated paths to work on.  The result is a single colon
               separated path.  Often used in combination with the
               ${search_path} substitution, below.

       Administrator_List
               Space separated list of the project’s administrators.  Takes an
               optional argument in the same form as the user substitution.

       ARCHitecture
               This substitution is replaced by the architecture name
               appropriate for the current execution environment.  Requires no
               arguments.  See the architecture field of aepconf(5) for more
               information.  When used in commands, you may need to surround
               this substitution with the quote substitution (see below), if
               any of your architecture names contain shell special
               characters.

       BaseLine
               Absolute path of the the project’s baseline.

       Basename
               This substitution takes one argument, a pathname.  The value of
               the substitution will be the last element of the pathname.
               This is similar to the basename(1) command.

       BAse_RElative
               This substitution takes at least one pathname.  The value of
               the substitution is the base-relative filenames, with any
               change-specific or project baseline specific leading path
               removed.  The file does not have to be a project source file.
               (This is almost the inverse of the $source substitution,
               below.)

       BINary_DIRectory
               The absolute path of Aegis’ architecture-specific binary
               (executables) directory.  This corresponds to the “./configure
               -bindir” option when Aegis was built.  This is where most of
               the Aegis executable programs are installed.

       CAPitalize
               This substitution takes at least one argument.  The value of
               the substitution will be the arguments with the first letter of
               each word forced to upper case and the rest forced to lower
               case.

       Change
               This substitution provides various information about the
               change, based on the argument it is given.

               attribute
                      This substitution takes an additional argument, the name
                      of a change attribute (see aeca(1) and aecattr(5) for
                      more information).  This returns the value listed in the
                      change attributes, or the empty string if the change
                      does not have the named attribute.

               cause   This returns the cause of the change.

               date format
                       This returns the completion date of the change.  See
                       DATE section for additional arguments.

               delta   This returns the delta number of the change.  Only
                       valid for completed changes.

               delta_uuid
                       This returns the delta UUID of the change, assigned on
                       integrate pass, a globally unique identifier for the
                       state of the project when this change was integrated
                       (different for all repositories).  Only valid for
                       being_integrated and completed changes.

               description
                       This returns the brief description of the change.

               developer
                       This returns the name of the developer of the change.

               development_directory
                       This returns the development directory of the change.

               integrator
                       This returns the name of the integrator of the change.

               integration_directory
                       This returns the integration directory of the change.

               number  This returns the number of the change.  (This is the
                       default if no argument is given.)

               reviewer
                       This returns the name of the reviewer of the change.

               state   This returns the state of the change.

               uuid    This returns the UUID of the change.

               version This returns the version of the change.

       Change_Attribute
               This substitution takes exactly one argument.  This argument is
               a name of a change attribute (see aeca(1) and aecattr(5) for
               more information).  This returns the value listed in the change
               attributes, or the empty string if the change does not have the
               named attribute.

       Change_Files
               This is replaced by a space separated list of change file
               names.  There are several qualifying arguments you can give to
               this substitution:

               action  You may give one or more file actions (e.g. modify).
                       Only files with one of the actions will be returned.
                       By default, all file actions are returned.

               type    You may give one or more file types (e.g. source).
                       Only files with one of the types will be returned.  By
                       default, all file types are returned.

               not     Inverts the sense of operations.  For example
                       ${change_files not remove} will return the names of all
                       change files not being removed.

               quote   This does not affect which file are selected, but it
                       causes the file names to be quoted if they contain
                       shell meta-characters.

               If you specify both actions and types, only files both
               qualifiers will be returned.  For example ${change_files modify
               test} will return only the names of automatic test files which
               are being modified.

       Change_Developer_List
               Space separated list of all the change’s developers.  Note that
               this is different than the Developer_List substitution.

       Change_Reviewer_List
               Space separated list of the change’s reviewers since the last
               develop end.  Note that this is different than the Reviewer_‐
               List substitution.  Bt using the review_policy_command field of
               the project configuration file this value can have more than
               one reviewer, because this allows a project to require a change
               to need to be reviewed more than once before it can be
               integrated.

       COMment
               Inserts exactly nothing; any and all arguments are ignored.
               Another form of comment is “$#” which extends to the end of the
               current line.

       Copyright_Years
               Inserts a comma separated list of copyright years from the
               project attributes.  This list of years is maintained by aegis
               at integrate begin, and so is only guaranteed to be up-to-date
               in the’being integrated’ state.  Do not use this substitution
               in new file templates, it is not guaranteed to be up-to-date in
               the ’being developed’ state; use the ${date %Y} substitution in
               new file templates.

               This list contains spaces, so if you use it to build commands,
               you will probably need to quote, it as well.

       DATa_DIRectory
               The absolute path of Aegis’ architecture-neutral library
               directory.  This corresponds to the “./configure -datadir”
               option when Aegis was built.  This is where most of the scripts
               included with Aegis are installed.

       DAte
               With no arguments, the output is the current date.  If there
               are arguments, they form a format string.  This is similar to
               the date(1) command on many UNIX systems.  For a description of
               the date formats, see the DATE section, below.

       DELta
               The delta number of the change.  This is only available when
               the change is in the being integrated state or the completed
               state.

       DEVeloper
               The name of the developer.  Takes an optional argument in the
               same form as the user substitution.

       DEVeloper_List
               Space separated list of the project’s developers.  Takes an
               optional argument in the same form as the user substitution.
               Note that this is different than the Change_DeveloperList
               substitution.

       Development_Directory
               The absolute path of the change’s development directory.  Only
               available when the change is between the being developed state
               and the being integrated state.

       DIFF
               The absolute path of the diff command, as discovered when Aegis
               was built.  It tries to locate GNU Diff at build time to
               provide maximum functionality.

       Dirname
               This substitution takes at least one argument, a pathname.  The
               value of the substitution will be everything but the last
               element of the pathname.  This is similar to the dirname(1)
               command.

       Dirname_RELative
               This substitution takes at least one argument, a pathname.  The
               value of the substitution will be everything but the last
               element of the pathname.  This is similar to the dirname
               substitution, except that if there are no directory components,
               it returns dot (“.”).

       DownCase
               This substitution takes at least one argument.  The value of
               the substitution will be the argument with any upper case
               letters mapped to lower case.

       EMail_Address
               This substitution takes one or more user names as arguments.
               It replaces them with email addresses.  (It is an error if any
               user name is unknown.)

               This substitution takes options.  You may specify one or more
               of them immediately after the substitution name.

               -Comma  This option may be used to specify that the email
                       addresses are to be separated by commas.

               -Quote  This option may be used to specify that the email
                       addresses are to be quoted to insulate shell special
                       characters.

               See aeuconf(5) for where this is set.

       ENVironment
               This substitution takes at least one argument.  The value of
               the substitution is the value of the corresponding environment
               variable, or empty of undefined.

       ERrno
               This substitution takes no arguments.  The value of the
               substitution will be the value if the errno variable provided
               by the system, as mapped through the strerror function.  Thus
               you may give the users informative system error messages.

       EXpression
               This substitution evaluates simple arithmetic expressions.
               Addition, subtraction, division, multiplication, modulo and
               negation are understood.  The 6 basic comparison operators are
               available.  The usual C syntax and precedence are used.  The
               arguments must constitute a valid expression, white space and
               word boundaries are ignored.

       History_Directory
               This substitution takes zero arguments.  It is replaced by the
               absolute path of the history directory of the project.

       History_Path
               This substitution takes one argument, the name of a source
               file.  It is replaced by the absolute path of the history file
               for that source file.  Note that you may beed to massage the
               file name a little for you proticular history tool, just as the
               history commands in the aegis.conf file do.
               This substitution takes zero arguments.  It is replaced by the
               absolute path of the history directory of the project.

       IDentifier
               This substitution takes at least one argument.  The value of
               the substitution will be the argument with all characters but
               alpha numerics mapped into an underscore (_), so as to form a
               legal C identifier.

       INTegration_Directory
               The absolute path of the change’s integration directory.  Only
               available when the change is in the being integrated state.

       INTegrator
               The name of the change’s integrator.  Only available when the
               change is in the being integrated state or the completed state.
               Takes an optional argument in the same form as the user
               substitution.

       INTegrator_List
               Space separated list of the project’s integrators.  Takes an
               optional argument in the same form as the user substitution.

       LEFt    This substitution extracts the left hand side of strings.  It
               takes two arguments: the first is the string, the second is the
               number of characters.

       LENgth  This substitution determines the length of strings, the result
               is a number.  It takes one argument: the string to be measured.

       LIBrary
               The absolute path of Aegis’ library directory.  This
               corresponds to the “./configure -datadir” option when Aegis was
               built.  This substitution is deprecated - please use ${datadir}
               instead.

       LIBrary_DIRectory
               The absolute path of Aegis’ architecture-specific library
               directory.  This corresponds to the “./configure -libdir”
               option when Aegis was built.

       Name_Maximum
               This substitution is used to get the maximum file name length
               within a file system.  It takes at least one argument: the name
               of a directory within the file system.  Frequently used with
               ${left} to crop filenames to the file system maximum.

       PAth_Reduce
               This function requires at least one argument.  It is used to
               remove duplicates from a command search path, such as may be
               found in the PATH environment variable.  If more than one
               argument is given, all are included in the results, as if they
               were separated by colons.

       PERL    This function requires zero arguments.  It is replaced by the
               absolute path of a Perl interpreter.

       PLural
               This function requires 2 or 3 arguments.  The first argument is
               evaluated as a number, if it is plural (not equal to 1) the
               second argument is the result, otherwise the third argument is
               the result (or empty if not given).  This is mostly used to
               pluralize sentences in Germainic error messages.

       PLural_Forms
               The plural_forms substitution is similar to the ${plural}
               substitution, except that it reads and understands the Plural-
               Forms: header in the message catalogue.  This means that it
               understands a greater range of pluralization mechanisms than
               the simple ${plural} substitution.  (For a description of the
               Plural-Forms: header, see the GNU Gettext manual.)

               The first argument is the number.  Second is the singular form
               (corresponding to the Plural-Forms: expression evaluating to
               zero), the third and subsequent arguments are the various
               plural forms (corresponding to the Plural-Forms: expression
               evaluating to 1, 2, 3, etc.

               The Plural-Forms: expression is required evaluate to less than
               nplurals.  If it does not, the second argument (the singular
               form) is used.  If there are too few arguments to this
               substitution, the second argument (the singular form) is again
               used.

               Note that in the default case (used for English and other
               Germanic languages), the arguments are the reverse of those
               expected by the ${plural} substitution.

       Project
               This substitution provides various information about the
               project, based on the argument it is given.

               name    This returns the name of the project.  (This is the
                       default if no argument is given.)

               description
                       This returns the description of the project (the one
                       which appears in the project listing).

               trunk_name
                       This returns the name of the trunk of the project (i.e.
                       no branch numbers included).

               trunk_description
                       This returns the description of the trunk of the
                       project.

               version This returns the version of the project.

               version_long
                       This returns the version of the project, including the
                       delta number.

       Project_Specific
               This substitution takes exactly one argument.  This argument is
               a name to be found in the project configuration file’s
               project_specific field (see aepconf(5) for more information).
               This returns the value listed in the project configuration
               file.  Unknown attributes will be replaced with the empty
               string.

       QUote
               This substitution may be used to quote shell special
               characters.  If no quoting is required, not quotes will be
               inserted.  This is used to insulate shell special characters in
               filenames when forming commands.

       Read_File
               Read a file and substitute the contents of the file.  Requires
               exactly one argument, the pathname of the file to be read.  If
               the pathname is a project source file, you will need to use the
               source substitution to resolve the path.  It is a fatal error
               if the file does not exist, or is not readable.  It is a fatal
               error if the pathname is not absolute (because the current
               directory is undefined).

       Read_File_Simple
               Read a file and without substituting the contents of the file.
               Requires exactly one argument, the pathname of the file to be
               read.  If the pathname is a project source file, you will need
               to use the source substitution to resolve the path.  It is a
               fatal error if the file does not exist, or is not readable.  It
               is a fatal error if the pathname is not absolute (because the
               current directory is undefined).

       Reviewer
               The name of the change’s reviewer.  Only available when the
               change is between the awaiting integration state and the
               completed state.  Takes an optional argument in the same form
               as the user substitution.

       Reviewer_List
               Space separated list of the project’s reviewers.  Takes an
               optional argument in the same form as the user substitution.
               Note that this is different than the Change_Reviewer_List
               substitution.

       RIght   This substitution extracts the right hand side of strings.  It
               takes two arguments: the first is the string, the second is the
               number of characters.

       Search_Path
               The Search_Path substitution is replaced by a colon separated
               list of absolute paths to search when building a change, it
               will point from a change to its branch and so on up to the
               project trunk.

       Search_Path_Executable
               The Search_Path_Executable substitution is usually the same as
               the Search_Path substitution.  However, during an “aegis -Test
               -BaseLine” command, it contains the baseline as the first
               element, rather then the development directory or the
               integration directory.  This is of most use when looking for
               executables and executable support files while running tests.

       SHell
               The absolute path of a Bourne shell which understands
               functions.  Requires exactly zero arguments.

       Source
               Resolve the argument filename into a pathname.  It is an error
               if the file is not a source file.  An optional second argument
               may be "Absolute" or "Relative", and may be abbreviated.
               Relative will attempt to provide a development-directory-
               relative pathname whenever possible, absolute will always
               result in an absolute path.  The default is "Relative".  (For
               the inverse mapping, see ${BAse_RElative}, above.)

       SPLit   This substitution may be used to split strings are specified
               separators.  The first argument is the separator character to
               be used, subsequent arguments are strings to be split.  The
               result is the collection is split strings of the second a
               follwoing arguments, separated by spaces.

       STate
               The state the current change is in.  It is an error if the
               substitution does not refer to a change.

       SUBSTitute
               Regular expression substitution.  The first argument is the
               pattern to match, the second argument is the replacement
               string.  The third and subsequent arguments are modified as
               specified by the first two arguments.  The search is not
               anchored, and the replacement will happen as many times as
               possible.  Use “^” to match the beginning, and “$” to match the
               end.

       SUBSTRing
               This substitution extracts a substring from the middle of
               strings.  It takes three arguments: the first is the string,
               the second is the star character (counting from zero), the
               third is the number of characters.

       SWitch
               Select amongst a set of values.  The first argument is expected
               to be a number.  If the number is zero, the second argument is
               used; if the number is one, the third argument is used; etc.
               If the number is negative, or exceeds the available arguments,
               the last argument is used.

       Trim_DIRectory
               This substitution takes one or two arguments.  If given one
               argument, one directory component (if present) is removed from
               the argument, which is assumed to be a file name.  If two
               arguments are present, the first is a directory count; at most
               this many directory components (if present) will be removed.
               The base file name is always left.

       Trim_EXTension
               This substitution takes one argument.  Any file name extension
               (a dot characters and the characters following) will be removed
               from the final filename section of the argument.

       UNSplit This substitution may be used to reverse the effects of the
               split substitution.  The first arguments is a seaparator
               character, the second and following arguments are strings to be
               joined together using the separator character.  The result is a
               single string.

       UpCase
               This substitution takes at least one argument.  The value of
               the substitution will be the argument with any lower case
               letters mapped to upper case.

       USer
               This substitution provides various information about the user
               who executed the command, based on the argument it is given.

               login   The login name of the user.  (This is the default if no
                       argument is given.)

               name    The full name of the user.

               email   The email address of the user.

               quoted_email
                       The email address of the user, quoted to avoid shell
                       special characters.

               home    The home directory of the user.

       Version
               The version of the change.  If the change is in the being
               integrated state or the completed state, the version will be of
               the form "a.b.Dddd", where "a" is the project’s major version
               number, "b" is the project’s minor version number, and "ddd" is
               the change’s delta number.  If the change is in any other
               state, the version will be of the form "a.b.Cccc", where "ccc"
               is the change number.

               delta_uuid
                       This variant gives the change’s delta-UUID assigned at
                       integrate pass.  Only valid for being_integrated and
                       completed changes.

       Zero_Pad
               This substitution is used to zero pad a string on the left.  It
               takes two arguments: the first is the string to be padded, the
               second is the minimum string width.

DATE

       This section describes the format specifiers accepted by the date
       substitution.  These are the same specifiers as defined by the ANSI C
       standard for the strftime function.

       %%      The percent character (%)

       %a      the abbreviated weekday name

       %A      the full weekday name

       %b      the abbreviated month name

       %B      the full month name

       %c      the date and time

       %d      the day of the month, zero padded

       %H      the hour of the 24-hour day

       %I      the hour of the 12-hour day

       %j      the day number of year, zero padded, one based

       %m      the month of the year, zero padded, one based

       %M      the minute of the hour, zero padded

       %p      meridian indicator, AM or PM as appropriate

       %S      the second of the minute

       %U      the Sunday week of the year

       %w      the day of the week, Sunday is 0

       %W      the Monday week of the year

       %x      the date, as mmm dd yyyy

       %X      the time, as hh:mm:ss

       %y      the year of the century

       %Y      the year including the century

       %Z      time zone abbreviation

       Using an undefined format specifier will produce random results,
       depending on the version of UNIX you are on.

SEE ALSO

       aesub(1)
               Substitute and print strings.

COPYRIGHT

       aegis version 4.24.3.D001
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
       2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Peter
       Miller

       The aegis program comes with ABSOLUTELY NO WARRANTY; for details use
       the ’aegis -VERSion License’ command.  This is free software and you
       are welcome to redistribute it under certain conditions; for details
       use the ’aegis -VERSion License’ command.

AUTHOR

       Peter Miller   E-Mail:   millerp@canb.auug.org.au
       /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/