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
programming 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
underscore (_). 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.
Constant 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
escape 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
include:
+--------------------------+
| ! != !~ ## ##= |
| % %= & && &= |
| ( ) * ** **= |
|*= + ++ += , |
| - -- -= . / |
|/= : ; < << |
|<<= <= = == > |
|>= >> >>= ? [ |
| ] ^ ^= { | |
||= || } ~ ~~ |
+--------------------------+
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
evaluated 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 executed.
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
operators 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
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: 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
argument 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
multiple 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
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.
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
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
aepconf(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 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
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: count() and keys() functions think the array
is empty; if you want a list of users, consult the passwd
array.)
FILES
The reports are kept in the /usr/share/aegis/report directory. The
reports are associated with a name by the /usr/share/aegis/report.index
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.24.3.D001
Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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: millerp@canb.auug.org.au
/\/\* WWW: http://www.canb.auug.org.au/~millerp/