table of contents
other sections
aesub(5) | File Formats Manual | aesub(5) |
NAME¶
aesub - aegis command substitutionsDESCRIPTION¶
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}";
- $name
-
- ${name}
-
- ${name arg...}
-
- $$
-
- %%
-
- $#...\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.)
history_query_command = "get -t -g ${Dirname $History}/s.${Basename $History}";
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 tohistory_query_command = "get -t -g ${d $h}/s.${b $h}";
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
-
- Administrator_List
-
- ARCHitecture
-
- BaseLine
-
- Basename
-
- 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
-
- CAPitalize
-
- 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.
- Change_Developer_List
-
- Change_Reviewer_List
-
- COMment
-
- 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
-
- DAte
-
- DELta
-
- DEVeloper
-
- DEVeloper_List
-
- Development_Directory
-
- DIFF
-
- Dirname
-
- Dirname_RELative
-
- DownCase
-
- 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.
- ENVironment
-
- ERrno
-
- 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
-
- 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.
- IDentifier
-
- INTegration_Directory
-
- INTegrator
-
- INTegrator_List
-
- 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
-
- LIBrary_DIRectory
-
- 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
-
- 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
-
- Read_File
-
- Read_File_Simple
-
- Reviewer
-
- Reviewer_List
-
- 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
-
- Source
-
- 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
-
- SUBSTitute
-
- SUBSTRing
-
- SWitch
-
- 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
-
- 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.
- 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
SEE ALSO¶
- aesub(1)
- Substitute and print strings.
COPYRIGHT¶
aegis version 4.24.3.D001AUTHOR¶
Peter Miller | E-Mail: | millerp@canb.auug.org.au |
/\/\* | WWW: | http://www.canb.auug.org.au/~millerp/ |
Aegis | Reference Manual |