WPL - The WISE Programming Language (version 1.0)


This file briefly describes the syntax and semantics of the WISE Programming Language (WPL - pronounced "whipple"). We are currently working on a more comprehensive WPL manual, but we put this description file together quickly for the initial distribution. The Web Integrated Software Project Management and Metrics Tool (WISE) (patch level 0) for Solaris 2.X Copyright © 1995 John R.Callahan, Sudhakar Ramakrishnan, Wei Sun, and Nicholay Gredetsky.

HISTORY

Our prototype version of WISE was implemented with an Oracle backend that was difficult to reconfigure. We soon found that a project's issue forms and roles change often during project execution and needed an easier configuration scheme. In the next version of WISE, a server was reconfigured by editing the wise.h configuration file directly. To avoid this complexity, we put WPL together to simplify the task of configuring and reconfiguring WISE. The genconfig program that interprets WPL specifications is used to generate several files including the wise.h file. The genconfig tool is built using an extension of Yacc - called NewYacc - that greatly simplifies the translation process.

Why is the WISE configuration statically configured in the site.wpl file? Two reasons: performance and security. We found that dynamic lookups of permissions, roles, etc. on the Oracle and MSQL backends significantly decreased usability of WISE. The format of project forms, roles, and other parameters of a WISE server are defined statically in the site.wpl file in order to improve performance by needing only one query to the backend database of issues. Also, each project can only be reconfigured by an administrator rather than any user. We felt that this increased the confidence in the tool since the static configuration strictly limits access to sensitive project information in the database.

OVERVIEW

The following sections describe the syntactic constructs of WISE and their semantics for purposes of defining projects, issue forms, the appearance of to-do lists, roles, viewing privileges of roles, and permitted actions by roles. It is VERY useful to look at an example site.wpl file in order to understand the descriptions below.

COMMENTS

A comment in WPL is any line or remainder of a line that begins with the "#" character. The comment include the "#" character and the remainder of the line.

HEADER

Each WPL specification MUST specify the following fields somewhere in the file. Each item is specified by a key-value pair, i.e., by its corresponding keyword (e.g., HOST) followed by any whitespace, followed by its value.

HOST hostid

This directive specifies the Internet hostname of your WWW server. Fully specify this name if your WISE server will be accessible from other domains. For local access only, simply specify the machine name without the domain extensions. Do NOT put quotes around the hostname.

PORT number

Specifies the port number of your HOST WWW server. The default is 80 but you may specify any valid port number. Do NOT put quotes around the port number.

ORGANIZATION "quoted name"

This directive gives a name to the organization (e.g., company, research group, etc.) under which multiple projects in WISE will be managed.

IMAGE imagelink

Specifies the http address of an image file as a logo for the organization.

ROOT path

Specifies the absolute path of the root of the WISE installation directory.

BACKGROUND imagelink

Specifies the default background for each WISE listing. The default is a chalk background at our distribution site.

PROJECT

A WPL configuration file (e.g., conf/site.wpl) may specify one or more projects. Each project description should list the mSQL database name, the mSQL server host Internet address, the mSQL server port, the project's logo image, and a list of fields for each record in the project's database. The syntax for a PROJECT clause is (keywords are capitalized):

PROJECT projname "project label" {
DATABASE dbname
HOST hostid
PORT number
IMAGE imagelink
field1name fieldtype
field2name fieldtype
...
}

Each fieldtype has a different syntax (see below). The DATABASE, HOST, PORT, and IMAGE specifiers are mandatory. They must appear in all PROJECT clause descriptions.

DATABASE dbname

Specifies the mSQL database name for the project.

HOST hostid

Specifies the Internet host name of the project's mSQL server.

PORT number

Specifies the port number of the project's mSQL server at the specified host name.

IMAGE imagelink

Specifies the http address of the project's logo to be displayed at the top of a project's To-Do list.

FIELD TYPES

There are many types of fields in WISE. Below is a listing of field types as specified in a PROJECT clause.

TEXT number

This field type allows for arbitrary input of one line of text input. The number specifies the maximum length of the input field.

TEXTAREA number

This field type allows for arbitrary input of multiple lines of text input. The number specifies the maximum length of the input field.

DATE

This field type is used for dates. Currently, a date is a 10 character field that is formatted as YYYY-MM-DD by convention for purposes of sorting the field using regular ASCII-based sorting. This will be enhanced with the release of data support in future versions of mSQL and integration of WISE with other database backends.

SELECT

A select field allows for a text value from a finite, enumerated set of values. No maximum length need be specified for this field type.

RADIO

This field type will appear as plain text if the field is viewed as readonly (see VIEWACCESS below) and as an exclusionary radio button if viewed as read-write. Like select, this field type requires no maximum length specified.

CHECKBOX

Similar to radio button but allows for multiple selection from a finite set of enumerated values. No maximum length need be specified.

HTML number

This powerful field type allows for arbitrary input of HTML links into a WISE form. Internally, this field is stored as two values: (1) the hypertext link (http, ftp, file, mailto, etc.) and (2) the hypertext itself. A maximum length needs to be specified as number.

LOG

Another powerful field type allows for append-only access to a log file for a WISE field.

INT

The field is an arbitrary integer value.

PASSWD number

The field is an arbitrary, one line text value that is masked from the user.

Future releases of WISE will expand field for multiple selections, automatic mail notification, subissue relations, better date support, real numbers, images, and multiple assignments.

TDL

The TDL clause has the syntax:

TDL projname {
field1name length
field2name length
...
}

where field1name, field2name, etc. are the names of fields in the PROJECT clause for the project named "projname" that will appear in the To-Do list for this project. I.e., this lists the subset of fieldnames that appear in the list of records.

ROLE

The syntax for the ROLE clause is:

ROLE name ISA rolename ON PROJECT projname ;

where name is the name of a user or pseudo-user and rolename is a role on the project named "projname" defined by a PROJECT clause. A rolename is an abstraction that is granted specific access to records and views of a project's database.

TDLVIEW

The TDLVIEW clause specifies under what conditions should a record (i.e.,, issue) show up on a role's To-Do list. The syntax for a TDLVIEW clause is:

TDLVIEW rolename
SEES [ ALL | fieldname ]
[ | WHEN expression ]
ON PROJECT projname ;

where ALL implies all fields are visible (the default) or fieldname specifies a specific field under conditions of the optional WHEN phrase. The expression on the WHEN phrase can be a string of AND and OR terms where a term is defined as a:

fieldname op value

where op is a =, <>, <, <=, >, >=, and LIKE as defined by mSQL. The TDLVIEW clause allows restricted viewing access on a field or ALL fields based on the value of fields in a record.

VIEWACCESS

Similar to TDLVIEW, the VIEWACCESS clause allows for specification of viewing and editing access to individual fields when viewing a single issue in WISE. The syntax for the VIEWACCESS clause is:

VIEWACCESS [ ALL | rolename ]
HAS [ READONLY | READWRITE | WRITEONLY ] ACCESS
ON FIELD fieldname
[ | WHEN expression ]
ON PROJECT projname [ | = valuelist ] ;

or it has the syntax for hidden fields:

VIEWACCESS FIELD fieldname
IS HIDDEN TO [ ALL | rolename ]
[ | WHEN expression ]
ON PROJECT projname ;

The VIEWACCESS clause defines under what conditions (the WHEN phrase) that a role can see (hidden, readonly) or edit (readwrite, writeonly) a field when viewing an individual record (i.e., issue) in WISE. The valuelist is useful for TEXT, TEXTAREA, DATE, SELECT, RADIO, CHECKBOX, INT and HTML field types. If specified, it sets the default value of the field. This will override any value in the database for the field of the viewed record. In the case of SELECT, RADIO, CHECKBOX, and HTML fields, the valuelist is a comma-separated list of string values without quotes. Spaces may be embedded within each value element. Special values may be embedded in the values (see below).

VALUES

The following is a list of special values that may be used in VIEWACCESS and NEWACCESS clauses of WPL 1.0. Each special value is delimited by a beginning "$" and an ending "$". If the enclosed identifier is not one of the following names, this causes an error in WISE:

$TODAY$ - specifies today's date as YYY-MM-DD
$USER$ - specifies the name of the remote user that is logged in (not the role)
$REMOTE_HOST$ - specifies the Internet host name of the client's machine

We realize that this is a rather limited set of special values. More special values will be added in later versions of WISE.

NEWACCESS

This clause is VERY similar to the VIEWACCESS clause but specifies the default values and access for new records (i.e., issues). The syntax is identical to the syntax for the VIEWACCESS clause except for the NEWACCESS keyword.

TDLACTION

The TDLACTION clause specifies what actions are listed at the top of the To-Do list view such as creating a new issue, metrics, and other potential WISE activities that depend on the user's role on a project. The syntax of the TDLACTION clause is:

TDLACTION [ ALL | rolename ]
CAN CALL [ NEWISSUE ]
LABEL "button string"
ON PROJECT projname ;

where currently NEWISSUE is the only selectable action. If not explicitly specified, then a role does not have the ability to add new records to the project database.

VIEWACTION

Like the TDLACTION clause, but specifies allowed actions when viewing a single record (i.e., issue). The syntax for VIEWACTION is similar but more actions are available:

VIEWACTION [ ALL | rolename ]
CAN CALL [ DELETEISSUE | SUBMITISSUE ]
LABEL "button string"
ON PROJECT projname ;

where DELETEISSUE and SUBMITISSUE allow the role or ALL to delete an issue from the database or SUBMIT changes to an issue. If not explicitly specified, then WISE assumes no actions are legal upon viewing an individual record.