Ubuntu Manpage: aesub - aegis command substitutions

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.

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.

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/

Reference Manual                                      Aegis                                             aesub(5)