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

FreeBSD Manual Pages

  
 
  

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

NAME
	aer - aegis report script language definition

DESCRIPTION
	This manual entry describes the	report generator script	language used
	by the aer(1) command.	The language resembles C, with a touch of awk
	and perl for flavour.  It also closely resembles the appearance	of
	aegis' database	files.

	This language grew out of the need to have a general purpose program-
	ming language to describe reports, and yet be as familiar as possible
	to the people who will be using	it.

WORDS AND SYMBOLS
	This section describes the various words and symbols understood	by the
	language.

   Names
	A name is a contiguous set of alphanumeric characters, including un-
	derscore (_).  It must not start with a	digit.	Names may be of	any
	length.	 Names are case	sensitive, so uppercase	and lowercase letters
	are unique.

	Here are some examples of names

			    +-----------------------------+
			    | print	  sqrt	     if	  |
			    |how_long	UpperCase   dig57 |
			    +-----------------------------+
	Some words are reserved	as keywords.  These are	the words which	appear
	in bold	in the statement descriptions, below.

   Integer Constants
	An integer constant may	be decimal, any	sequence of digits.  Constants
	may be octal, any sequence of octal digits starting with a zero.  Con-
	stant may be hexadecimal, any sequence of hexadecimal digits, starting
	with a 0x prefix.  These are represented by the	internal long type, so
	significance is	limited.

	Here are some examples of integer constants:

		       +---------------------------------------+
		       |	43	      015	0xbeEf |
		       |2147483647   017777777777   0x7FFFFFFF |
		       +---------------------------------------+
   Floating Point Constants
	A floating point constant has an integer part, a fraction part and an
	exponent part.

	Here are some examples of floating point constants:

			     +---------------------------+
			     |1.2e3   4.2e+1   1.628e-94 |
			     |0.567	 5e6	     .67 |
			     +---------------------------+
   String Constants
	A string constant is represented as characters within double quotes
	(").  All characters in	the script file	are required to	be printable,
	so special characters are represented by escape	sequences.  These es-
	cape sequences are:

			    +-----------------------------+
			    |\"	    the	" character	  |
			    |\\	    the	\ character	  |
			    |\n	    Newline		  |
			    |\f	    Form Feed		  |
			    |\r	    Carriage Return	  |
			    |\b	    Backspace		  |
			    |\t	    Horizontal Tab	  |
			    |\nnn   octal character value |
			    +-----------------------------+
	Here are some examples of string constants:

		 +---------------------------------------------------+
		 |"Hello, World!"     "Go away"		   ""	     |
		 |   "The End0	    "slosh is \\"   "Say \"Please\"" |
		 +---------------------------------------------------+
   Symbols
	The non-alphanumeric characters	are used to represent symbols, usually
	expression operators or	statement terminators.	The symbols used in-
	clude:

			     +--------------------------+
			     | !    !=	 !~    ##   ##=	|
			     | %    %=	  &    &&   &=	|
			     | (    )	  *    **   **=	|
			     |*=    +	 ++    +=    ,	|
			     | -    --	 -=    .     /	|
			     |/=    :	  ;    <    <<	|
			     |<<=   <=	  =    ==    >	|
			     |>=    >>	 >>=   ?     [	|
			     | ]    ^	 ^=    {     |	|
			     ||=    ||	  }    ~    ~~	|
			     +--------------------------+
   White Space
	White space serves to separate words and symbols, and has no other
	significance.  The language is free-form.  White space includes	the
	SPACE, TAB, FF,	and NEWLINE characters.

   Comments
	Comments are delimited by /* and */ pairs, and are treated as a	single
	white space character.

STATEMENTS
	Statement serve	to control the flow of execution of the	program, or
	the existence of variables.

   The Expression Statement
	The commonest statement	consists of an expression terminated by	a
	semicolon.  The	expression is evaluated, and any result	is discarded.

	Examples of this statement include
		x = 42;
		print("Hello, World!0);

   The If Statement
	The if statement is used to conditionally execute portions of code.
	Examples if the	if statement include:
		if (x == 42)
		    x =	1;
		if (x *	x < 1)
		    print("no");
		else
		    print("yes");

   The For Statement
	The for	statement has two forms.  The first form is described as
		for (expr1; expr2; expr3)
		    stmt
	The expr1 is done before the loop begins.  The expr2 controls, the
	loop; if it does not evaluate to true the loop terminates.  The	loop
	body is	the stmt.  The loop increment is done by the expr3, and	the
	the test is performed again.

	Each of	the expressions	is optional; any or all	may be omitted.

	Here is	an example of a	for loop:
		for (j = 0; j <	10; ++j)
		    print(j);

	The second form	of the for statement looks like	this:
		for (name in keys(passwd))
		    print(name,	passwd[name].pw_comment);

   The Break Statement
	The break statement is used to break out of a loop.

	Here is	an example of a	break statement:
		for (j = 0; ; j	= 2 * j	+ 4)
		{
		    print(j);
		    if (j >= 0x800)
			break;
		}
	The break statement works within all loop statements.

   The Continue	Statement
	The continue statement is used to terminate the	loop body and start
	another	repetition.

	Here is	an example of a	continue statement:
		for (j = 0; j <	1000; j	= 2 * j	+ 4)
		{
		    if (j < 42)
			continue;
		    print(j);
		}
	The continue statement works within all	loop statements.

   The While Statement
	The while statement is another loop construct.	The condition is eval-
	uated before the loop body.
		line = 0;
		while (line < 7)
		{
		    print("");
		    ++line;
		}

   The Do Statement
	The do statement is another loop construct.  The condition is evaluate
	after the loop body.
		do
		    print("yuck");
		while
		    (line++ < 7);

   The Compound	Statement
	The compound statement is a way	of grouping other statements together.
	It is enclosed in curly	braces.
		if ( lines < 7)
		{
		    print("This\n");;
		    print("could\n");;
		    print("have\n");;
		    print("been\n");;
		    print("seven\n");;
		    print("blank\n");;
		    print("lines.\n");;
		}

   The Local Statement
	The auto statement is used to declare variables	and initialize them to
	be nul.
		auto x,	y, z;
		x = 42;
	All user-defined variables must	be declared before they	are used.

   The Null Statement
	The null statement does	nothing.  It consists of a single semicolon.
	It is most often seen as a loop	body.
		for (n = 0, bit	= 1; n < bit_num; ++n, bit <<= 1)
		    ;

   The Try Catch Statement
	The try	catch statement	is used	to catch errors	which would usually
	cause the report to fail.
		try
		    statement1
		catch (variable)
		    statement2
	The first statement is executed.  If no	error occurs, nothing else is
	done.  If an error occurs in the execution of the first	statement the
	firsdt statement execution is terminated and then the given variable
	is set to a description	of the error and the second statement is exe-
	cuted.

EXPRESSIONS
	Expressions are	much the same as in C, using the same operators.  The
	following table	describes operator precedence and associativity:

	[ ]	subscripting		    value [ expr ]
	( )	function call		    expr ( expr_list )
	( )	grouping		    ( expr )

	++	post increment		    lvalue ++
	++	pre increment		    ++lvalue
	--	post decrement		    lvalue --
	--	pre decrement		    --lvalue
	~	compliment		    ~ expr
	!	not			    ! expr
	-	unary minus		    - expr
	+	unary plus		    + expr

	**	exponentiation		    expr ** expr

	*	multiply		    expr * expr
	/	divide			    expr / expr
	%	modulo (remainder)	    expr % expr
	~~	matches			    expr ~~ expr
	!~	does not match		    expr !~ expr
	in	list member		    expr in expr

	+	addition (plus)		    expr + expr
	-	subtraction (minus)	    expr - expr
	##	list and string	join	    expr ## expr

	<<	shift left		    expr << expr
	>>	shift right		    expr >> expr

	<	less than		    expr < expr
	<=	less than or equal	    expr <= expr
	>	greater	than		    expr > expr
	>=	greater	than or	equal	    expr >= expr

	==	equal			    expr == expr
	!=	not equal		    expr != expr

	&	bitwise	AND		    expr & expr

	^	bitwise	exclusive OR	    expr ^ expr

	|	bitwise	inclusive OR	    expr | expr

	? :	arithmetic if		    expr ? expr	: expr

	=	simple assignment	    expr = expr
	*=	multiply and assign	    expr *= expr
	/=	divide and assign	    expr /= expr
	%=	modulo and assign	    expr %= expr
	+=	add and	assign		    expr += expr
	-=	subtract and assign	    expr -= expr
	<<=	shift left and assign	    expr <<= expr
	>>=	shift right and	assign	    expr >>= expr
	&=	AND and	assign		    expr &= expr
	^=	exclusive OR and assign	    expr ^= expr

	|=	inclusive OR and assign	    expr |= expr

	,	comma (sequencing)	    expr , expr

	Most of	these operators	behave as they do in C,	but some of these op-
	erators	will require some explanation.

   Exponentiation
	The ** operator	raises the left	argument to the	right'th power.	 It is
	right associative.

   Match
	The ~~ operator	compares two strings.  It returns a number between 0.0
	and 1.0.  Zero means completely	different, one means identical.	 Case
	is significant.

   Not Match
	The !~ is used to compare two strings, and returns the opposite	of the
	~~ operator; one if completely different, and zero if identical.

   String Join
	The ## operator	is used	to join	two strings together.

TYPES
	There are several types	used within the	report language.

	array	Values of this type contain other values, indexed by a string.
		If you attempt to index	by an arithmetic type, it will be
		silently converted to a	string.	 Use the keys function to de-
		termine	all of the keys; use the count function	to determine
		how many entries an array has.	The type of an array element
		is not restricted, only	the index must be a string.

	boolean	This type has two values: true and false.  These value arise
		from the boolean operators described earlier.

	integer	This type is represented by the	long C type.  It has a limited
		range of values	(usually -2e9 to 2e9 approximately).  If used
		in a string context, it	will be	silently converted to a
		string.	 For exact control of the format, used the sprintf
		function.

	list	Values of this type contain a list of other values.  The type
		of these values	is not restricted.  The	array index operator
		(e[e]) may be used to access list elements; indexes start at
		zero (0).

	string	Values of this type are	an arbitrary string of C characters,
		except the NUL character ( ).  Strings may be of any length.

	struct	Values of this type contain additional values.	These values
		are accessed using the "dot" operator.	These values may also
		be treated as if they were arrays.

	real	This type is represented the the double	C type.	 If used in a
		string context,	it will	be silently converted to a string.
		For exact control of the format, used the sprintf function.

FUNCTIONS
	There are a number of built-in functions.

	basename
		This function is used to extract the last element from a file
		path.

	capitalize
		This function converts it argument to a	capitalized string in
		Title Case.

	ceil	This function is used to round a number	to an integer, towards
		positive infinity.

	change_number
		This function is used to determine the change number.  It may
		be set by the -Change command line option, or it may default.
		The return value is an integer.

	change_number_set
		This function maybe used to determine if the change number was
		set by the -Change command line	option.	 The return value is a
		boolean.

	columns	This function is used to define	the report columns.  Each ar-
		gument is a structure containing some or all of	the following
		fields:

		      left	the left margin, counting characters
				from 0 on the left
		      right	the right margin, plus one
		      width	the width in characters, defaults to 7
				if right not specified
		      padding	white space between columns, defaults to
				1 if not set
		      title	the title for this column, separate mul-
				tiple lines with \n
		The columns must be defined before the print function is used.

	count	This function is used to count the number of elements in a
		list or	array.

	dirname	This function is used to extract all but the last element from
		a file path.

	downcase
		This functions converts	its argument to	lower case.

	eject	This function is used to start a new page of output.

	floor	This function is used to round a number	to an integer, towards
		negative infinity.

	getenv	This function is used to get the value of an environment vari-
		able.  Will return the empty string if not set.

	gettime	This function is used to parse a string	to produce a time.  It
		understands a variety of different date	formats.

	getuid	This function takes no arguments, and returns the user ID of
		the process which invoked the report generator.	The return
		value is an integer.

	keys	This function may be given an array or a list as argument.  It
		returns	a list of keys which may be used to index the argu-
		ment.  Most often seen in for loops.

	length	This function is used to find the length of a string.

	mktime	This a synonym for the gettime function.

	mtime	This function may be used to obtain the	modification time of a
		file.

	need	This function is used to insert	a page break into the report
		if the required	number of lines	is not available before	the
		end of page.  If sufficient lines are available, only a	single
		blank line will	be inserted.  The return value is void.

	now	This function takes no arguments, and returns the current
		time.

	page_length
		This function may be used to determine the length of the out-
		put page in lines.  The	return value is	an integer.

	page_width
		This function may be used to determine the width of the	output
		page in	columns.  The return value is an integer.

	print	This function is used to print into the	defined	columns.  Col-
		umns will wrap around.

	project_name
		This function is used to determine the project name.  It may
		be set by the -Project command line option, or it may default.
		The return value is a string.

	project_name_set
		This function maybe used to determine if the project name was
		set by the -Project command line option.  The return value is
		a boolean.

	quote_html
		This function quotes its argument string to insulate HTML spe-
		cial characters; these include "less than" (<),	"ampersand"
		(&) and	non-printing characters.  This is most often used to
		generate suitable text for web pages.

	quote_tcl
		This function quotes its argument string to insulate TCL spe-
		cial characters; these include "[]" and	non-printing charac-
		ters.  This is most often used to generate suitable text for
		TCL interface scripts.

	quote_url
		This function quotes its argument string to insulate URL spe-
		cial characters; these include "?+#:&="	and non-printing char-
		acters.	 This is most often used to generate suitable text for
		web pages.

	round	This function is used to round a number	to an integer, towards
		the closest integer.

	sort	This function must be given a list as argument.	 The values
		are sorted into	ascending order.  A new	list is	returned.

	split	This function is used to split a string	into a list of
		strings.  The first argument is	the string to split, the sec-
		ond argument is	the character to split around.

	sprintf	This function is used to build strings.	 It is similar to the
		sprintf(3) function.

	strftime
		This function is used to format	times as strings.  The first
		argument is the	format string, the second argument is a	time.
		See the	strftime(3) man	page for more the format specifiers.

	subst	This function is used to substitute strings by regular expres-
		sion.  The first argument is the pattern to match, the second
		argument is the	substitution pattern, the third	argument is
		the input string to be substituted.  The option	fourth argu-
		ment is	the number of substitutions to perform;	the default is
		as many	as possible.

	substr	This function is used to extract substrings from strings.  The
		first argument is a string, the	second argument	is the start-
		ing position, starting from 0, and the third argument is the
		length.

	terse	This function may be used to determine of the -TERse command
		line option was	used.  The return type is a boolean.

	title	This function is used to set the title of the report.  It
		takes at most two arguments, one for each available title
		line.

	trunc	This function is used to round a number	to an integer, towards
		zero.

	typeof	This function is used to determine the type of a value.	 The
		return type is a string	containing the name of the type, as
		described in the

	unquote_url
		This function will remove URL quoting from the argument
		string.	 URL quoting takes the form of a percent sign (%) fol-
		lowed by two hex digits.  This is replaced by a	single charac-
		ter with the value represented by the hex digits.

	upcase	This functions converts	its argument to	upper case.

	working_days
		This function is used to determine the number of working days
		between	two times.

	wrap	This function is used to wrap a	string into a list of strings.
		The first argument is the wring	to wrap, the second argument
		is the maxmium width of	the output strings.

	wrap_html
		This function is used to wrap a	string into a list of strings.
		The first argument is the wring	to wrap, the second argument
		is the maxmium width of	the output strings.  This is very sim-
		ilar to	the wrap functions, except thatit inserts HTML para-
		graph breaks <p> or line breaks	<br> to	reflect	the newlines
		within the string (2 or	1, respectively).  TYPES section.

VARIABLES
	There are a number of built-in variables.

	arg	This variable is a list	containing the arguments passed	on the
		aer(1) command line.

	change
		There is a special type	of variable created by using an	ex-
		pression similar to project[project_name()].state.change[n]
		which contains all of the fields described in aecstate(5),
		plus some extras:

		change	Branches have a	change array, just like	project	below.

		change_number
			The number of the change.

		config	This gives access to all of the	fields described in
			aepconf(5).

		project_name
			The name of the	project	containing the change.

		src	This gives access to the change	files, and when	in-
			dexed by file name, yields a value conataining fields
			as described in	aefstate(5), for the src field.

	group	This variable is an array containing all of the	entries	in the
		/etc/group file.  Each entry is	a structure with fields	as
		documented in the group(5) manual entry.  The gr_mem element
		is a list of strings.  This array may be indexed by either a
		string,	treated	as a group name, or by an integer, treated as
		a GID.

	passwd	This variable is an array containing all of the	entries	in the
		/etc/passwd file.  Each	entry is a structure with fields as
		documented in the passwd(5) manual entry.  This	array may be
		indexed	by either a string, treated as a user name, or by an
		integer, treated as a uid.

	project	This variable is an array containing one entry for each	aegis
		project, indexed by name.  Each	array element is a structure,
		containing

		      name	  the project name
		      directory	  the root of the project directory tree
		      state	  the project state
		The project state contains the fields documented in the	aep-
		state(5) manual	entry.	Except:	the change field is not	a list
		of change numbers, it is an array indexed by change number of
		change states, as documented in	the aecstate(5)	manual entry.
		(See change, above.)

	user	This variable is an array containing the .aegisrc file of each
		user.  Each entry is a structure with fields as	documented in
		the aeuconf(5) manual entry.  This array may be	indexed	by ei-
		ther a string, treated as a user name, or by an	integer,
		treated	as a uid.  Files which are unreadable or absent	will
		generate an error, so you need to wrap accesses	in a try/catch
		statement.  (Note: count() and keys() functions	think the ar-
		ray is empty; if you want a list of users, consult the passwd
		array.)

FILES
	The reports are	kept in	the /usr/local/share/report directory.	The
	reports	are associated with a name by the /usr/local/share/report.in-
	dex file.  Their names use the command line argument abbreviation
	scheme,	so that	report names may be abbreviated.

SEE ALSO
	aer(1)	report generator

	aecstate(5)
		change state description

	aepstate(5)
		project	state description

	aerptidx(5)
		report index file format

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				aer(5)

NAME | DESCRIPTION | WORDS AND SYMBOLS | STATEMENTS | EXPRESSIONS | TYPES | FUNCTIONS | VARIABLES | FILES | SEE ALSO | COPYRIGHT | AUTHOR

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

home | help