CDE/cde/osf/wml

/* $XConsortium: README /main/4 1996/07/15 14:38:42 drk $ */
This memo documents the Widget MetaLanguage (WML) facility which generates
the Uil compiler language description.

1. Introduction

The Uil compiler's language definition has the following components:
- Invariant parts of the language grammar. This consists of the
basic syntax and keywords, for example, the 'arguments' directive.
- Dynamic parts of the language. This consists of the widget/gadget
classes supported by the language, including all resources
(arguments and reasons), and the definitions of legal relationships
among these parts (which classes are legal controls (children)
of any given class, default values, and so on).
- The data types supported by the compiler. The code which supports
the data types is invariant, but the data types must also be
declared and made known in WML in order to provide a clean
specification.

The dynamic parts of the language definition in the compiler are represented
as follows. The representation falls into two classes:
- Definitions of the language used for validity checking and
reporting:
o A set of #define literals name all data types, classes,
arguments, and reasons in the language.
o A set of statically compiled tables defines the names and
legal relationships among these entities.
- All data types, classes, arguments, and reasons are treated as
keywords in the Uil grammar. This is supported by:
o A set of #define literals which names all the tokens in
the language. Some of these tokens receive identical
values to the literals mentioned above (this identity is
crucial to the compiler's correct functioning).
o A set of statically compiled tables used by lexical
analysis to detect and classify the language keywords.
o A yacc grammar including these token definitions which
generates a compilable Uil language parser.

These representations are all contained in .h files except for the parser,
which is contained in a .y file and its resulting .c file.

The WML system's task is to generate all these literals and tables based on
a specification of the dynamic parts of the Uil language - the data types,
widget/gadget classes, arguments, and reasons. The components of the system
are:
- A specification of the of set of widgets to be supported. This
specification is an ASCII file containing a WML language
specification as described below. The WML language is a simple
declarative language whose syntax is similar to Uil itself.
- A process named wml, which parses the WML specification and
produces the following output:
o The .h files which define the first class of language
representations - the validity checking and reporting
information.
o A set of .dat files which are used by succeeding processes
to produce the Uil grammar.
o A report file which describes the toolkit being supported.
o A .mm file to be incorporated in the Uil language
documentation, which tabulates the built-in language
tables for Uil user reference.
- A process named wmluily which generates the Uil grammar.
- A process named wmltokens which generates token data
- A process named wmlkeyword which generates the token and lexical
analysis tables.

A shell script is provided which runs the system. The individual processes
and inputs can usually be ignored.


2. Environment

The generation and use of the WML system requires the following:
- The C language compiler and runtime system (cc).
- The lexical generator facility (lex)
- the compiler compiler facility (yacc)

The WML facility is found in directory /wmlsrc. It assumes the following
directories also exist:
/uilsrc - the directory to which the output files are to be moved
/mrmsrc/Mrm - contains MrmCmpr.h and other .h files required to
compile the uil compiler.

The tables produced by WML must be consistent with the Mrm compression
code tables emboded in /mrmsrc/Mrm/MrmCmpr.h and /mrmsrc/Mrm/MrmCmprTbl.h.
If in doubt, refer to /mrmsrc/Mrm/urmc.README for details.


3. WML input

Input to WML consists of:
- A description of the widget set (toolkit) to be suppported in
the WML specification language.
- Data files supplied with WML facility, and which you will
usually not need to modify. These are:
o grammar.y - specifies the invariant part of the
Uil grammar
o charset.dat - specifies the character sets supported by
the compiler when handling compound strings
Any other .dat files found in /wmlsrc are the result of running
the facility, and may be ignored.

3.A. WML specification language

The WML specification is a simple declarative language whose syntax is
similar to that of Uil itself. It models the widget set to be suppored in
a way that is very similar to the Uil language. It differs in having class
inheritance similar to Xt widget classes, which minimizes the amount of
specification and reduces errors. The properties of the model are:
- Class properties
o Classes are differentiated into two types - metaclasses
and classes. Metaclasses cannot instantiate widgets.
Typically, a WML metaclass is generated for each metaclass
in the widget set to be supported.
o A regular class is defined for every low-level create
routine in the widget set. There are typically more WML
classes that widget set classes. For instance, there
is one XmRowColumn class, with six WML classes (XmRowColumn
XmMenuBar, XmOptionMenu, XmPopupMenu, XmPulldownMenu,
XmRadioBox).
o Gadgets are modelled as variants of a corresponding
widget class.
o A class may have zero or one superclasses. A class
inherits all the resources and controls of its superclass
(recursively). An inherited resource may have some of
its properties overridden.
o A class is given a name which becomes its Uil language
keyword (for regular classes). Metaclass names do
not appear in Uil.
o A class is identified to Mrm by its creation
convenience function (low-level create function). Examples
are XmCreateLabel, XmCreatePushButtonGadget.
- Resource properties
o Resources are divided into two classes - arguments and
and reasons. This models the Uil language distinction
between callbacks and all other resources.
o A resource is considered to have universal scope. Once
defined, it may be used in any class. Its name and datatype
are invariant, but its default value may be overridden.
o A resource is included in a class by referencing it.
Resources are inherited. Inherited resources may be
excluded, which meancs they are not available in the
class which provides this override (and its subclasses).
This corresponds to the Motif toolkit N/A access value.
o A resource is given a name which becomes its Uil language
keyword.
o A resource is identified to Mrm by the toolkit literal
used to name it in arglists. Examples are
XmNheight, XmNancestorSensitive, XmNhelpCallback. The
resource literal defaults to the resource name, and need
not be explicitly specified where they are identical.
- Control properties
o A control is a class which is permitted as the child
of some other class.
o Naming the controls of a class is a WML feature which
supports validity checking. There is no coresponding
explicit feature in any Xt widget set.

3.A.1 WML syntax and semantics

The WML syntax can be quickly inferred from the standard input file
provided with WML - motif-tables.wml. A quick BNF is provided in section 7.


WML semantics are:
- '!' introduces a comment. Comments run from '!' to EOL.
- A string value may be quoted by enclosing in double quotes '"'.
Names as well as values may be quoted. Keywords may not.
- All names are case-sensitive. Forward and backward references
are allowed. All references to be resolved are to items defined
in WML. These are:
o Type =
o SuperClass =
WidgetClass =
o Resources { };
o Controls {
statements> };
- A convenience function name is required for all classes except
Metaclasses.
- Datatypes are required for all Arguments, Constraints, and
SubResources.
- Arguments and SubResources are functionally identical, and
are distinguished only because they are different kinds of
resources in Xt widget sets. Constraints apply only to the
referencing class's children. The same name may not be
used for both an Argument and a Constraint (once a Constraint,
always a Constraint).
- If a resource occurs in the widget set with more than one
datatype, the Uil datatype 'any' must be used.
- The ResourceLiteral attribute for resources is optional, and
need only be specified when the name is not identical to the literal.
- The DocName and Default attributes are only used for documentation.
They are arbitrary strings.
- The WidgetClass attribute identifies the Widget class
associated with a Gadget class, and is required.
- The DialogClass attribute is optional.
- The ControlList statement is a simply macro for lists of
controls. It avoids tedious repetition of identical lists.
A Controls block in a Class statement allows Class and
ControlList names to be freely mixed.


4. WML output
- The .h files and parser required by the compiler. These
are automatically moved to /uilsrc by the runwml script.
- A report describing the supported widget set, always named
wml.report. This report is intended to aid in validating
the WML source. The report is organized in a way which makes
if fairly easy to compare the Uil langauge against widget
set documentation as exemplified by the Motif Programmer's
Reference Manual. The reported is sorted as follows:
- alphabetically by class name
- Resources ordered by ancestor (top of tree first).
Resources are listed alphabetically, with datatype
and default always shown.
- Reasons ordered by ancestor (top of tree first),
then alphabetically.
- Controls listed alphabetically.
- A file which provides documentation for the language, intended
to be an appendix to a Uil manual as exemplified by the
Guide to the Motif User Interface Language Compiler. This file
is named wml-uil.mm


5. Generating and running WML

The script file /wmlsrc/genwml will build WML. The script file /wmlsrc/runwml
will run WML with motif-tables.src as input.


6. Gotchas and problems in current WML implementation

The script files genwml and runwml should be replaced by Makefiles.

The documentation file ?.mm is relatively untested. The tables should
probably be modified, as they are currently too big to print cleanly.
The handling of the DocName attribute is incorrect.

The specification of the Motif toolkit in motif-tables.wml has not been
fully validated against the latest toolkit documentation. We believe there
are no or very few errors in the actual resources and the classes which
use them. There may be errors in the default values, which will appear
in the documentation.


7. WML BNF

WML-specification : statement_block_list

statement_block_list:

statement_block_list statement_block

statement_block:
class_statement_block
| resource_statement_block
| datatype_statement_block
| control_list_statement_block

class_statement_block:
'Class' class_statement_list

resource_statement_block:
'Resource' resource_statement_list

datatype_statement_block:
'Datatype' datatype_statement_list

control_list_statement_block:
'ControlList' control_list_statement_list

class_statement_list:
class_statement ';'
| class_statement_list class_statement ';'

resource_statement_list:
resource_statement ';'
| resource_statement_list resource_statement ';'

datatype_statement_list:
datatype_statement ';'
| datatype_statement_list datatype_statement ';'

control_list_statement_list:
control_list_statement ';'
| control_list_statement_list control_list_statement ';'

class_statement:
':' class_type class_definition

class_type:
'MetaClass' | 'Widget' | 'Gadget'

class_definition:

| '{' '}'
| '{' class_attribute_list '}'

class_attribute_list:
class_attribute_name '=' ';'
| class_boolean_attribute_name '=' boolean_attribute_value ';'
| class_resources ';'
| class_controls ';'

class_attribute_name:
'SuperClass' | 'Alias' | 'ConvenienceFunction' | 'WidgetClass' |
'DocName'

class_boolean_attribute_name:
'DialogClass'

boolean_attribute_value:
'True' | 'False'

class_resources:
'Resources' class_resources_block

class_resources_block:

'{' '}'
'{' class_resource_list '}'

class_resource_list:
class_resource_element
| class_resource_list class_resource_element

class_resource_element:
class_resource_attributes ';'

class_resource_attributes:

'{' '}' ';'
'{' class_resource_attribute_list '}'

class_resource_attribute_list:
class_resource_attribute_element
| class_resource_attribute_list class_resource_attribute_element

class_attribute_element
class_resource_attribute_name '=' ';'
| boolean_class_resource_attribute_name '=' boolean_attribute_value ';'

class_resource_attribute_name:
'Default'

boolean_class_resource_attribute_name:
'Exclude'

class_controls:
'Controls' class_controls_block

class_controls_block:

| '{' '}' ';'
| '{' class_controls_list '}'

class_controls_list:
class_controls_element
class_controls_list class_controls_element

class_controls_element:
;

resource_statement:
':' resource_type resource_definition

resource_type:
'Argument' | 'Reason' | 'Constraint' | 'SubResource'

resource_definition:

'{' '}'
'{' resource_attribute_list '}'

resource_attribute_list:
resource_attribute
resource_attribute_list resource_attribute

resource_attribute:
resource_attribute_name '=' ';'

resource_attribute_name:
'Type' | 'ResourceLiteral' | 'Alias' | 'Related' | 'Default' |
'DocName'

datatype_statement:
datatype_definition

datatype_definition:

| '{' '}'
| '{' datatype_attribute_list '}'

datatype_attribute_list:
datatype_attribuute
datatype_attribute_list datatype_attribute

datatype_attribute:
datatype-attribute_name '=' ';'

datatype_attribute_name:
'Alias' | 'DocName'

control_list_statement:
control_list_definition

control_list_definition:

'{' '}'
'{' control_list_controls_list '}'

control_list_controls_list:
control_list_control
control_list_controls_list control_list_control

control_list_control:
';'