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 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.
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:
selection |
value . member |
|
[ ] |
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¶