aer(5) aer(5) NNAAMMEE aer - report script language definition DDEESSCCRRIIPPTTIIOONN This manual entry describes the report generator script language used by the _a_e_r(1) command. The language resembles C, with a touch of _a_w_k and _p_e_r_l 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. WWOORRDDSS AANNDD SSYYMMBBOOLLSS This section describes the various words and symbols understood by the language. NNaammeess 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 _r_e_s_e_r_v_e_d as keywords. These are the words which appear in bboolldd in the statement descriptions, below. IInntteeggeerr CCoonnssttaannttss 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 | +---------------------------------------+ FFllooaattiinngg PPooiinntt CCoonnssttaannttss 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 | +---------------------------+ SSttrriinngg CCoonnssttaannttss 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 _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s_. These escape sequences are: +-----------------------------+ |\" the " character | |\\ the \ character | |\n Newline | |\f Form Feed | |\r Carriage Return | |\b Backspace | |\t Horizontal Tab | |\_n_n_n octal character value | +-----------------------------+ Here are some examples of string constants: +---------------------------------------------------+ |"Hello, World!" "Go away" "" | | "The End0 "slosh is \\" "Say \"Please\"" | +---------------------------------------------------+ SSyymmbboollss The non-alphanumeric characters are used to represent symbols, usually expression operators or statement terminators. The symbols used include: +--------------------------+ | ! != !~ ## ##= | | % %= & && &= | | ( ) * ** **= | |*= + ++ += , | | - -- -= . / | |/= : ; < << | |<<= <= = == > | |>= >> >>= ? [ | | ] ^ ^= { | | ||= || } ~ ~~ | +--------------------------+ WWhhiittee SSppaaccee 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. CCoommmmeennttss Comments are delimited by /* and */ pairs, and are treated as a single white space character. SSTTAATTEEMMEENNTTSS Statement serve to control the flow of execution of the program, or the existence of variables. TThhee EExxpprreessssiioonn SSttaatteemmeenntt 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); TThhee IIff SSttaatteemmeenntt The _i_f statement is used to conditionally execute portions of code. Examples if the _i_f statement include: if (x == 42) x = 1; if (x * x < 1) print("no"); else print("yes"); TThhee FFoorr SSttaatteemmeenntt The _f_o_r statement has two forms. The first form is described as for (_e_x_p_r_1; _e_x_p_r_2; _e_x_p_r_3) _s_t_m_t The _e_x_p_r_1 is done before the loop begins. The _e_x_p_r_2 controls, the loop; if it does not evaluate to true the loop terminates. The loop body is the _s_t_m_t. The loop increment is done by the _e_x_p_r_3, 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 _f_o_r loop: for (j = 0; j < 10; ++j) print(j); The second form of the _f_o_r statement looks like this: for (name in keys(passwd)) print(name, passwd[name].pw_comment); TThhee BBrreeaakk SSttaatteemmeenntt The _b_r_e_a_k statement is used to break out of a loop. Here is an example of a _b_r_e_a_k statement: for (j = 0; ; j = 2 * j + 4) { print(j); if (j >= 0x800) break; } The _b_r_e_a_k statement works within all loop statements. TThhee CCoonnttiinnuuee SSttaatteemmeenntt The _c_o_n_t_i_n_u_e statement is used to terminate the loop body and start another repetition. Here is an example of a _c_o_n_t_i_n_u_e statement: for (j = 0; j < 1000; j = 2 * j + 4) { if (j < 42) continue; print(j); } The _c_o_n_t_i_n_u_e statement works within all loop statements. TThhee WWhhiillee SSttaatteemmeenntt The _w_h_i_l_e statement is another loop construct. The condition is evaluated before the loop body. line = 0; while (line < 7) { print(""); ++line; } TThhee DDoo SSttaatteemmeenntt The _d_o statement is another loop construct. The condition is evaluate after the loop body. do print("yuck"); while (line++ < 7); TThhee CCoommppoouunndd SSttaatteemmeenntt The _c_o_m_p_o_u_n_d 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");; } TThhee LLooccaall SSttaatteemmeenntt The _l_o_c_a_l statement is used to declare variables and initialize them to be nul. local x, y, z; x = 42; All user-defined variables must be declared before they are used. TThhee NNuullll SSttaatteemmeenntt The _n_u_l_l 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) ; EEXXPPRREESSSSIIOONNSS Expressions are much the same as in C, using the same operators. The following table describes operator precedence and associativity: [ ] subscripting _v_a_l_u_e [ _e_x_p_r ] ( ) function call _e_x_p_r ( _e_x_p_r___l_i_s_t ) ( ) grouping ( _e_x_p_r ) ++ post increment _l_v_a_l_u_e ++ ++ pre increment ++_l_v_a_l_u_e -- post decrement _l_v_a_l_u_e -- -- pre decrement --_l_v_a_l_u_e ~ compliment ~ _e_x_p_r ! not ! _e_x_p_r - unary minus - _e_x_p_r + unary plus + _e_x_p_r ** exponentiation _e_x_p_r ** _e_x_p_r * multiply _e_x_p_r * _e_x_p_r / divide _e_x_p_r / _e_x_p_r % modulo (remainder) _e_x_p_r % _e_x_p_r ~~ matches _e_x_p_r ~~ _e_x_p_r !~ does not match _e_x_p_r !~ _e_x_p_r in list member _e_x_p_r in _e_x_p_r + addition (plus) _e_x_p_r + _e_x_p_r - subtraction (minus) _e_x_p_r - _e_x_p_r ## list and string join _e_x_p_r ## _e_x_p_r << shift left _e_x_p_r << _e_x_p_r >> shift right _e_x_p_r >> _e_x_p_r < less than _e_x_p_r < _e_x_p_r <= less than or equal _e_x_p_r <= _e_x_p_r > greater than _e_x_p_r > _e_x_p_r >= greater than or equal _e_x_p_r >= _e_x_p_r == equal _e_x_p_r == _e_x_p_r != not equal _e_x_p_r != _e_x_p_r & bitwise AND _e_x_p_r & _e_x_p_r ^ bitwise exclusive OR _e_x_p_r ^ _e_x_p_r | bitwise inclusive OR _e_x_p_r | _e_x_p_r ? : arithmetic if _e_x_p_r ? _e_x_p_r : _e_x_p_r = simple assignment _e_x_p_r = _e_x_p_r *= multiply and assign _e_x_p_r *= _e_x_p_r /= divide and assign _e_x_p_r /= _e_x_p_r %= modulo and assign _e_x_p_r %= _e_x_p_r += add and assign _e_x_p_r += _e_x_p_r -= subtract and assign _e_x_p_r -= _e_x_p_r <<= shift left and assign _e_x_p_r <<= _e_x_p_r >>= shift right and assign _e_x_p_r >>= _e_x_p_r &= AND and assign _e_x_p_r &= _e_x_p_r ^= exclusive OR and assign _e_x_p_r ^= _e_x_p_r |= inclusive OR and assign _e_x_p_r |= _e_x_p_r , comma (sequencing) _e_x_p_r , _e_x_p_r Most of these operators behave as they do in C, but some of these operators will require some explanation. EExxppoonneennttiiaattiioonn The ** operator raises the left argument to the right'th power. It is right associative. MMaattcchh 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. NNoott MMaattcchh The !~ is used to compare two strings, and returns the opposite of the ~~ operator; one if completely different, and zero if identical. SSttrriinngg JJooiinn The ## operator is used to join two strings together. TTYYPPEESS 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 _k_e_y_s function to determine all of the keys; use the _c_o_u_n_t 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 _l_o_n_g 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 _s_p_r_i_n_t_f 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 _d_o_u_b_l_e C type. If used in a string context, it will be silently converted to a string. For exact control of the format, used the _s_p_r_i_n_t_f function. FFUUNNCCTTIIOONNSS There are a number of built-in functions. basename This function is used to extract the last element from a file path. 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 --CChhaannggee 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 --CChhaannggee 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 _p_r_i_n_t 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. 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 _g_e_t_t_i_m_e 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 --PPrroojjeecctt 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 --PPrroojjeecctt 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. ceil 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 _s_p_r_i_n_t_f(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 _s_t_r_f_t_i_m_e(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 --TTEERRssee 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. 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 _w_r_a_p functions, except thatit inserts HTML paragraph breaks
or line breaks
to
reflect the newlines within the string (2 or 1,
respectively). _T_Y_P_E_S section.
VVAARRIIAABBLLEESS
There are a number of built-in variables.
arg This variable is a list containing the arguments
passed on the _a_e_r(1) command line.
change
There is a special type of variable created by
using an expression similar to
_p_r_o_j_e_c_t_[_p_r_o_j_e_c_t___n_a_m_e_(_)_]_._s_t_a_t_e_._c_h_a_n_g_e_[_n_] which
contains all of the fields described in
aecstate_(_5_)_, _p_l_u_s _s_o_m_e _e_x_t_r_a_s_:
_c_h_a_n_g_e Branches have a change array, just like
_p_r_o_j_e_c_t below.
change_number
The number of the change.
config This gives access to all of the fields
described in _a_e_p_c_o_n_f_(_5_)_.
_p_r_o_j_e_c_t___n_a_m_e
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
_a_e_f_s_t_a_t_e(5), for the _s_r_c field.
group This variable is an array containing all of the
entries in the _/_e_t_c_/_g_r_o_u_p file. Each entry is a
structure with fields as documented in the
_g_r_o_u_p(5) manual entry. The _g_r___m_e_m 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 _/_e_t_c_/_p_a_s_s_w_d file. Each entry is a
structure with fields as documented in the
_p_a_s_s_w_d(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 _a_e_p_s_t_a_t_e(5) manual entry. Except: the
_c_h_a_n_g_e field is not a list of change numbers, it
is an array indexed by change number of change
states, as documented in the _a_e_c_s_t_a_t_e(5) manual
entry. (See _c_h_a_n_g_e, above.)
user This variable is an array containing the _._a_e_g_i_s_r_c
file of each user. Each entry is a structure with
fields as documented in the _a_e_u_c_o_n_f(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.)
FFIILLEESS
The reports are kept in the _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_a_e_g_i_s_/_r_e_p_o_r_t
directory. The reports are associated with a name by the
_/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_a_e_g_i_s_/_r_e_p_o_r_t_._i_n_d_e_x file. Their names use
the command line argument abbreviation scheme, so that
report names may be abbreviated.
SSEEEE AALLSSOO
_a_e_r(1) report generator
_a_e_c_s_t_a_t_e(5)
change state description
_a_e_p_s_t_a_t_e(5)
project state description
_a_e_r_p_t_i_d_x(5)
report index file format
CCOOPPYYRRIIGGHHTT
aegis version .C001
Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997,
1998, 1999, 2000, 2001 Peter Miller; All rights reserved.
The aegis program comes with ABSOLUTELY NO WARRANTY; for
details use the '_a_e_g_i_s _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command. This is
free software and you are welcome to redistribute it under
certain conditions; for details use the '_a_e_g_i_s _-_V_E_R_S_i_o_n
_L_i_c_e_n_s_e' command.
AAUUTTHHOORR
Peter Miller E-Mail: millerp@canb.auug.org.au
/\/\* WWW: http://www.canb.auug.org.au/~millerp/
Reference Manual Aegis 1