Provided by: aegis_4.24.3-3_i386 bug

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/