

aesub(5)						 aesub(5)


NNAAMMEE
       aesub - available command substitutions

DDEESSCCRRIIPPTTIIOONN
       When other programs are invoked by the _a_e_g_i_s program, it
       is usually via a	command	string in a configuration file.
       This section describes the format of these command
       strings.

GGEENNEERRAALL	FFOORRMM
       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 _a_r_g...}
	       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
	       (''_b_l_a_h _b_l_a_h'') 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 _d_i_r_n_a_m_e substitution is replaced
       by the directory	name of	the argument, rather like the
       _d_i_r_n_a_m_e(1) command.  In the command
	      history_query_command =
		   "get	-t -g ${Dirname	$History}/s.${Basename $History}";
       the _D_i_r_n_a_m_e and _B_a_s_e_n_a_m_e	substitutions are used to
       construct a suitable path to the	SCCS file in the history
       directory.

AABBBBRREEVVIIAATTIIOONNSS
       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.

SSUUBBSSTTIITTUUTTIIOONNSS
       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:

       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	_u_s_e_r substitution.

       ARCHitecture
	       This substitution is replaced by	the architecture
	       name appropriate	for the	current	execution
	       environment.  Requires no arguments.  See the
	       _a_r_c_h_i_t_e_c_t_u_r_e field of _a_e_p_c_o_n_f(5)	for more
	       information.  When used in commands, you	may need
	       to surround this	substitution with the _q_u_o_t_e
	       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
	       _b_a_s_e_n_a_m_e(1) command.

       BINary_DIRectory
	       The absolute path of Aegis' architecture-specific
	       binary (executables) directory.	This corresponds
	       to the ``_._/_c_o_n_f_i_g_u_r_e _-_b_i_n_d_i_r'' option when Aegis
	       was built.  This	is where most of the Aegis
	       executable programs are installed.

       CAPitalize
	       This substitution takes one argument.  The value
	       of the substitution will	be the argument	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.

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

	       description
		       This returns the	brief description of the
		       change.

       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	_a_e_g_i_s at integrate begin, and so
	       is only guaranteed to be	up-to-date in the'_b_e_i_n_g
	       _i_n_t_e_g_r_a_t_e_d' state.  Do not use this substitution
	       in new file templates, it is not	guaranteed to be
	       up-to-date in the '_b_e_i_n_g	_d_e_v_e_l_o_p_e_d' 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
	       ``_._/_c_o_n_f_i_g_u_r_e _-_d_a_t_a_d_i_r''	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 _d_a_t_e(1) command on many
	       UNIX systems.  For a description	of the date
	       formats,	see the	_D_A_T_E section, below.

       DELta
	       The delta number	of the change.	This is	only
	       available when the change is in the _b_e_i_n_g
	       _i_n_t_e_g_r_a_t_e_d state	or the _c_o_m_p_l_e_t_e_d state.

       DEVeloper
	       The name	of the developer.  Takes an optional
	       argument	in the same form as the	_u_s_e_r
	       substitution.

       DEVeloper_List
	       Space separated list of the project's developers.
	       Takes an	optional argument in the same form as the
	       _u_s_e_r substitution.

       Development_Directory
	       The absolute path of the	change's development
	       directory.  Only	available when the change is
	       between the _b_e_i_n_g _d_e_v_e_l_o_p_e_d state and the _b_e_i_n_g
	       _i_n_t_e_g_r_a_t_e_d state.

       Dirname
	       This substitution takes one argument, a pathname.
	       The value of the	substitution will be everything
	       but the last element of the pathname.  This is
	       similar to the _d_i_r_n_a_m_e(1) command.

       Dirname_RELative
	       This substitution takes one argument, a pathname.
	       The value of the	substitution will be everything
	       but the last element of the pathname.  This is
	       similar to the _d_i_r_n_a_m_e substitution, except that
	       if there	are no directory components, it	returns
	       dot (``.'').

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

       ENVironment
	       This substitution takes 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 _e_r_r_n_o
	       variable	provided by the	system,	as mapped through
	       the _s_t_r_e_r_r_o_r function.  Thus you	may give the
	       users informative system	error messages.

       EXpression
	       This substitution evaluates simple arithmetic
	       expressions.  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.

       IDentifier
	       This substitution takes 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 _b_e_i_n_g _i_n_t_e_g_r_a_t_e_d state.

       INTegrator
	       The name	of the change's	integrator.  Only
	       available when the change is in the _b_e_i_n_g
	       _i_n_t_e_g_r_a_t_e_d state	or the _c_o_m_p_l_e_t_e_d state.	 Takes an
	       optional	argument in the	same form as the _u_s_e_r
	       substitution.

       INTegrator_List
	       Space separated list of the project's integrators.
	       Takes an	optional argument in the same form as the
	       _u_s_e_r 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 ``_._/_c_o_n_f_i_g_u_r_e _-_d_a_t_a_d_i_r''
	       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
	       ``_._/_c_o_n_f_i_g_u_r_e _-_l_i_b_d_i_r'' option when Aegis was
	       built.

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

       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 error messages.

       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.

       Project_Specific
	       This substitution takes exactly one argument.
	       This argument is	a name to be found in the project
	       _c_o_n_f_i_g file's _p_r_o_j_e_c_t___s_p_e_c_i_f_i_c field (see
	       _a_e_p_c_o_n_f(5) for more information).  This returns
	       the value listed	in the project _c_o_n_f_i_g file.

       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
	       _s_o_u_r_c_e 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
	       _s_o_u_r_c_e 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 _a_w_a_i_t_i_n_g
	       _i_n_t_e_g_r_a_t_i_o_n state and the _c_o_m_p_l_e_t_e_d state.  Takes
	       an optional argument in the same	form as	the _u_s_e_r
	       substitution.

       Reviewer_List
	       Space separated list of the project's reviewers.
	       Takes an	optional argument in the same form as the
	       _u_s_e_r 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".

       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.

       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.

       UpCase
	       This substitution takes 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 _b_e_i_n_g _i_n_t_e_g_r_a_t_e_d state or the _c_o_m_p_l_e_t_e_d state,
	       the version will	be of the form "_a.._b..DD_d_d_d", 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..CC_c_c_c", where "ccc" is the change number.

       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.

DDAATTEE
       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 _m_m_m	_d_d _y_y_y_y

       %X      the time, as _h_h_:_m_m_:_s_s

       %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.

SSEEEE AALLSSOO
       aaeessuubb(1)
	       Substitute and print strings.

CCOOPPYYRRIIGGHHTT
       aegis version .C001
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997,
       1998, 1999, 2000, 2001 Peter Miller; All	rights reserved.

       The aegis program comes with ABSOLUTELY NO WARRANTY; for
       details use the '_a_e_g_i_s _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e'	command.  This is
       free software and you are welcome to redistribute it under
       certain conditions; for details use the '_a_e_g_i_s _-_V_E_R_S_i_o_n
       _L_i_c_e_n_s_e'	command.

AAUUTTHHOORR
       Peter Miller   E-Mail:	millerp@canb.auug.org.au
       /\/\*		 WWW:	http://www.canb.auug.org.au/~millerp/


Reference Manual	      Aegis				1