aer - report script language definition

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 ' database files.

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

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

Names

Integer Constants

Floating Point Constants

String Constants

Symbols

White Space

Comments

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

The Expression Statement

x = 42;
print("Hello, World!n");

The If Statement

if (x == 42)
	x = 1;
if (x * x < 1)
	print("no");
else
	print("yes");

The For Statement

for (expr1; expr2; expr3)
	stmt

for (j = 0; j < 10; ++j)
	print(j);

for (name in keys(passwd))
	print(name, passwd[name].pw_comment);

The Break Statement

for (j = 0; ; j = 2 * j + 4)
{
	print(j);
	if (j >= 0x800)
		break;
}

The Continue Statement

for (j = 0; j < 1000; j = 2 * j + 4)
{
	if (j < 42)
		continue;
	print(j);
}

The While Statement

line = 0;
while (line < 7)
{
	print("");
	++line;
}

The Do Statement

do
	print("yuck");
while
	(line++ < 7);

The Compound Statement

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

auto x, y, z;
x = 42;

The Null Statement

for (n = 0, bit = 1; n < bit_num; ++n, bit <<= 1)
	;

The Try Catch Statement

try
	statement1
catch (variable)
	statement2

Expressions are much the same as in C, using the same operators. The following table describes operator precedence and associativity: tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). [ ];subscripting;value [ expr ] ( );function call;expr ( expr_list ) ( );grouping;( expr ) tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). ++;post increment;lvalue ++ ++;pre increment;++lvalue --;post decrement;lvalue -- --;pre decrement;--lvalue ~;compliment;~ expr !;not;! expr -;unary minus;- expr +;unary plus;+ expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). **;exponentiation;expr ** expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). *;multiply;expr * expr /;divide;expr / expr %;modulo (remainder);expr % expr ~~;matches;expr ~~ expr !~;does not match;expr !~ expr in;list member;expr in expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). +;addition (plus);expr + expr -;subtraction (minus);expr - expr ##;list and string join;expr ## expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). <<;shift left;expr << expr >>;shift right;expr >> expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). <;less than;expr < expr <=;less than or equal;expr <= expr >;greater than;expr > expr >=;greater than or equal;expr >= expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). ==;equal;expr == expr !=;not equal;expr != expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). &;bitwise AND;expr & expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). ^;bitwise exclusive OR;expr ^ expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). |;bitwise inclusive OR;expr | expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). ? :;arithmetic if;expr ? expr : expr tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). =;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 tab(;); lf(CW)w(0.5i) lw(2.5i) lf(CW)w(1). ,;comma (sequencing);expr , expr

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

Exponentiation

Match

Not Match

String Join

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 determine 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: CWtrue and CWfalse. 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 (0). 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.

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 argument is a structure containing some or all of the following fields: center,tab(;); l lw(4). left;T{ the left margin, counting characters from 0 on the left T} right;T{ the right margin, plus one T} width;T{ the width in characters, defaults to 7 if right not specified T} padding;T{ white space between columns, defaults to 1 if not set T} title;T{ the title for this column, separate multiple lines with \n T} 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 variable. 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 argument. 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 output 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. Columns 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 special 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 special characters; these include ``[]'' and non-printing characters. This is most often used to generate suitable text for TCL interface scripts.

quote_url

This function quotes its argument string to insulate URL special characters; these include ``?+#:&='' and non-printing characters. 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 second 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 expression. 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 argument 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 starting 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 (%) followed by two hex digits. This is replaced by a single character 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 similar to the wrap functions, except thatit inserts HTML paragraph breaks <p> or line breaks <br> to reflect the newlines within the string (2 or 1, respectively). TYPES section.

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 expression 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 aepconfgP(5).

project_name

The name of the project containing the change.

src

This gives access to the change files, and when indexed 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 project, indexed by name. Each array element is a structure, containing center,tab(;); l l. 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 aepstate(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 either 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: CW]count() and CW]keys() functions think the array is empty; if you want a list of users, consult the CW]passwd array.)

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

aer(1)

report generator

aecstate(5)

change state description

aepstate(5)

project state description

aerptidx(5)

report index file format

version

Copyright Peter Miller; All rights reserved.

The program comes with ABSOLUTELY NO WARRANTY; for details use the ' -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the ' -VERSion License' command.

tab(;); l r l. Peter Miller;E-Mail:;millerp@canb.auug.org.au CW/\/\*;WWW:;http://www.canb.auug.org.au/~millerp/