Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
aesub(5)		      File Formats Manual		      aesub(5)

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 alphanu-
		merics.

	${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 substitu-
		tion.  Within the braces ({ and	}) pairs of single quote char-
		acters ('blah blah') may be used to insulate spaces and	other
		special	characters, or you may use the back quote (\) to es-
		cape a single character.

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

	%%
		This is	replaced by a single % character.  Percent (%) fol-
		lowed by anything else is illegal.

	$#...\n	This is	a comment, usually found in template files read	in us-
		ing 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	direc-
	tory 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 suit-
	able 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 abbrevia-
	tion is	the uppercase letters.	All substitution name are case insen-
	sitive.

	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 un-
	derstood:

	Active_Directory
		The absolute path of the change's development directory, if
		the change is between the being	developed and awaiting inte-
		gration	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 substitu-
		tion.

	ARCHitecture
		This substitution is replaced by the architecture name appro-
		priate for the current execution environment.  Requires	no ar-
		guments.  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 charac-
		ters.

	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 re-
		moved.	The file does not have to be a project source file.
		(This is almost	the inverse of the $source substitution, be-
		low.)

	BINary_DIRectory
		The absolute path of Aegis' architecture-specific binary (exe-
		cutables) 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.

		debian-version
			This returns a Debian-esque version stamp for the
			change.

		rpm-version
			This returns an	RPM-esque version stamp	for the
			change.

		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 be-
			ing_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 quali-
		fiers 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} substitu-
		tion 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 di-
		rectory.  This corresponds to the "./configure --datadir" op-
		tion 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 sub-
		stitution.

	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 sub-
		stitution, 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 let-
		ters 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 ad-
			dresses	are to be separated by commas.

		-Quote	This option may	be used	to specify that	the email ad-
			dresses	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	sub-
		stitution 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 mea-
		sured.

	LIBrary
		The absolute path of Aegis' library directory.	This corre-
		sponds 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 di-
		rectory.  This corresponds to the "./configure --libdir" op-
		tion 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 ar-
		gument 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} sub-
		stitution, 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 plu-
		ral forms (corresponding to the	Plural-Forms: expression eval-
		uating 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 substi-
		tution,	the second argument (the singular form)	is again used.

		Note that in the default case (used for	English	and other Ger-
		manic languages), the arguments	are the	reverse	of those ex-
		pected 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 charac-
		ters.  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 cur-
		rent 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 com-
		pleted 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 op-
		tional argument	in the same form as the	user substitution.
		Note that this is different than the Change_Reviewer_List sub-
		stitution.

	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 ele-
		ment, 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 func-
		tions.	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.  Rel-
		ative 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 an-
		chored,	and the	replacement will happen	as many	times as pos-
		sible.	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 ex-
		pected to be a number.	If the number is zero, the second ar-
		gument is used;	if the number is one, the third	argument is
		used; etc.  If the number is negative, or exceeds the avail-
		able 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 ar-
		guments	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	re-
		moved 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 char-
		acter, 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 let-
		ters 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 in-
		tegrated 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 sub-
	stitution.  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, de-
	pending	on the version of UNIX you are on.

SEE ALSO
	aesub(1)
		Substitute and print strings.

COPYRIGHT
	aegis version 4.25.D510
	Copyright (C) 1991, 1992, 1993,	1994, 1995, 1996, 1997,	1998, 1999,
	2000, 2001, 2002, 2003,	2004, 2005, 2006, 2007,	2008, 2009, 2010,
	2011, 2012 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:	 pmiller@opensource.org.au
	/\/\*		  WWW:	 http://miller.emu.id.au/pmiller/

Reference Manual		     Aegis			      aesub(5)

NAME | DESCRIPTION | GENERAL FORM | ABBREVIATIONS | SUBSTITUTIONS | DATE | SEE ALSO | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=aesub&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help