Provided by: aegis_4.24.3-2_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/