This is one of the STIPPLE Documentation pages.

STIPPLE Prelude Declarations

The syntax for a STIPPLE source file is:

source_file

prelude_declarations
{ type_declaration }*
{ object_declaration }*
{ routine_declaration }*

prelude_declarations

language_declaration
version_declaration
{ identify_declaration }
{ configuration_variables_declaration }*
{ extension_declaration }*
module_declaration
{ import_declaration }*
{ export_declaration }*

Only the language, version, and module declarations are required for all source files. As can be seen by the grammar, the order in which declarations are supplied is specified by the language (see Why constrain declaration order.)

The Language Declaration

The syntax for the language declaration is:

language_declaration

language_name eol

language_name

identifier

The very first symbol in a source module is the native language name. STIPPLE supports programming in native languages other than English. The native language name is used to specify the spelling of the STIPPLE keywords. The native language name is spelled as it would be in the native language; for example, for Spanish, the native is language name is Español.

For the rest of this manual, only the English keywords are used.

The version Declaration

The syntax for the version declaration is:

version_declaration

version version_string eol

version_string

untranslated_string

The version declaration must immediately follow the language declaration.

The version declaration specifies which version of the STIPPLE language the rest of module is written in. The first version of STIPPLE is "1.0". Upward compatible versions of the language will increment the number to the right of the decimal point (e.g. "1.1" and "1.2".) Non-upward compatible versions of the language will increment the number to the left of the decimal point (e.g. "2.0" and "3.0".) Version strings must always be enclosed in double quotes.

The identify Declaration

The syntax for the identify declaration is:

identify_declaration

identify identify_string eol

identify_string

untranslated_string

If present, the identify declaration must immediately follow the version statement.

The identify declaration permits the user to supply an identification string to be stored with the object file. In Unix, an SCCS identification string is frequently stored in the identify declaration. The identify string must always be enclosed in double quotes. Depending upon the compilation system, the resulting object file may or may not contain the identify string.

Conditional Compiliation

STIPPLE directly supports conditional compilation via the configuration_variables declaration and the configuration_if and configuration_error statements (see Why support conditional compilation).

{The syntax and grammar in this section is pretty messed up and confused. It needs to worked on to integrate into overall grammar.}

The configuration_variables Declaration

The syntax for the configuration_variables declaration is:

configuration_variables_declaration

configuration_variables configuration_variable_declaration ,... eol

configuration_variable_declaration

configuration_variable { = configuration_expression }

configuration_variable

identifier

configuration_expression

logical_expression

If present, configuration_variables declarations always come after any version or identify declarations.

Each configuration variable declaration defines one or more configuration variables. A configuration variable may be declared exactly once. The scope of each configuration variable is from immediately after the declaration through to the source file end. The initial value of each new configuration variable is false unless it is explicitly assigned a value using a configuration expression. A configuration expression is a boolean expression consisting entirely of previously declared configuration variables, the logical constants true and false and the logical operators. Via compiler options, the default settings of any and all configuration variables may be set.

The configuration_if Statement

The syntax for the configuration_if statement is:

configuration_if_statement

configuration_if configuration_expression eol
configuration_statements_or_declarations
{ configuration_else_if_clause }*
{ configuration_else_clause }

configuration_else_if_clause

configuration_else_if configuration_expression eol
configuration_statement_or_declaration configuration_statements_or_declarations

configuration_else_clause

configuration_else eol
configuration_statements_or_declarations

configuration_expression

logical_expression

configuration_statements_or_declarations

indent
configuration_statement_or_declaration
outdent

configuration_statement_or_declaration

declaration
statement
configuration_error_statement

The configuration_if statement can occur anywhere after the last configuration_variables declaration, including in the middle of declarations. The statement_or_declaration rule matches any valid portion of a statement or declaration. The configuration_if statement can not occur in the middle of a line that is being continued.

The configuration_if statement evaluates its configuration expressions in order until one of them evaluates to true. The statements and/or declarations under the first true clause are compiled as if they occurred at the same nesting level as the configuration_if. All other statements and/or declarations in the other clauses are neither parsed nor compiled; however they must be lexically correct. If all configuration expressions evaluate to false and there is a configuration_else clause, the statements and/or declarations under the configuration_else clause are compiled as if they occurred at the same nesting level as the configuration_if.

The configuration_error Statement

The syntax for the configuration_error statement is:

configuration_error_statement

configuration_error configuration_error_message eol

configuration_error_message

translated_string

A configuration_error statement may occur immediately after a configuration_if, configuration_else_if, or configuration_else at the next indentation level. If a configuration_error statement occurs in a configuration_if clause that is enabled, a fatal configuration error message is generated by the compiler. The error message must be enclosed in single-quotes.

A Conditional Compilation Example

The following example shows some correct and incorrect usage of conditional compilation:

    English
    version "1.0"
    configuration_variables red_ok, green_ok := true, blue_ok
    configuration_variables purple_ok := red_ok && blue_ok
    configuration_variables a_ok, b_ok := a_ok	# Illegal - a_ok is not in scope

    module example
    type color
	enumeration
	    configuration_if red_ok
		red
	    configuration_if green_ok
		green
	    configuration_else
		configuration_error `green_ok must always be configured'
	    configuration_if blue_ok
		blue
	    configuration_if purple_ok
		purple

For the above example, if no configuration variable settings are specified to the compiler, the following configuration is seen by the compiler:

    English
    version "1.0"

    module example
    type color
	enumeration
	    green

For the above example, if the red_ok and green_ok variable settings are set to true via compiler options, the following configuration is seen by the compiler:


    English
    version "1.0"

    module example
    type color
	enumeration
	    red
	    green
	    blue
	    purple

Finally, for the above example, if the green_ok variable is set to false via a compiler option, a fatal error message containing `green_ok must always be configured' is generated.

The extension Declaration

The syntax for the extension declaration is:

extension_declaration

extension extension_name eol

extension_name

identifier

If present, extension declarations come after any version, or identify, or configuration_variables declarations.

Any extensions added to the STIPPLE compiler are assigned an identifier. The extensions are enabled by specifying the identifier in an extension declaration. When an extension gets promoted to the language specification proper, the STIPPLE version number is incremented and the extension identifier becomes illegal in code compiled at the new level. (This forces programmers to remove stale extension declarations when they are upgrading their code.) All extensions are implemented by modifying the compiler.

The module Declaration

The syntax for the module declaration is:

module_declaration

module module_name eol

module_name

identifier

The module declaration is mandatory and must occur after any version, identify, configuration_variables, or extension declarations. One or more source can have the same module name. When the compiler is being used to extract an interface file, all source files with the same module declaration name must be supplied to the compiler. Module names are also used in the import and export declarations.

The import Declaration

The syntax for the import declaration is:

import_declaration

import eol
indent
{ import_clause }+
outdent

import_clause

module_name { import_language_declartion } eol

import_language_declaration

using language_name { import_preference_declaration }

import_preference_declaration

preferring language_name ,...
preferring_native

module_name

identifier

language_name

identifier

If present, all import declarations must come after the module declaration. The import declaration specifies that a source file needs to access the types, objects and procedures of another named module. It is the responsibility of the compilation system to keep track of the correspondence between module names and interface files. The source file must reference at least one type, object, or procedure from the imported module, otherwise the compiler will flag the import declaration as being stale.

The interface to a module can be provided in multiple native languages (e.g. English, French, Spanish, etc.) For each native language, the type, object, and procedure names will be different. By default, when a module is imported, the source file native language is selected as the desired interface. However, sometimes there is no source file native language interface available. In this situation, the programmer going to have no choice but to use a non-native interface to the module. This is accomplished by specifying the desired interface native language using the using clause to the import declaration. For example, in an English source file,

    import peso using Spanish

specifies that the module interface named peso is to be accessed using the Spanish native language. Note that the language identifier is Spanish, not Español. The language identifier for the using clause is always the native language spelling of the foreign language. If there is no native language interface for the language specified by a using clause, an error is generated.

When a particular source file is first written, it may not have access to native language interfaces for all of its import declarations. However, as time goes on, native language interfaces may be produced. The preferring and preferring_native clauses of the import declaration are used to specify the desire to use a different native language interface. If the preferring_native clause is specified, the first time the compiler discovers that a source file native language interface to the module exists, it will generate a warning message. The preferring clause specifies one or more languages that are preferred over the language specified by the using clause. Whenever the compiler detects that an interface in one of the languages specified by the preferring clause is available, it will generate a warning message. For an English source file,

    import peso using Spanish preferring English

and

    import peso using Spanish preferring_native

are essentially equivalent; to encourage uniformity, the compiler disallows a preferring clause that is only followed by the native language. Thus, the preferring clause must have at least one language that is different from the native language.

The export Declaration

The syntax for the export declaration is:

export_declaration

export eol
{ export_clause }+

export_clause

export_from_clause to export_to_clause eol

export_from_clause

all
object object_name ,...
routine routine_name ,...
routine_suffix routine_name ,...
type type_name ,...

export_to_clause

all
module module_name ,...
routine routine_name ,...
type type_name ,...

object_name

identifier { @ type_name }

routine_name

identifier { @ type_name }

module_name

identifier

type_name

identifier

If present, all export declarations must occur after the import and module declarations.

The export declaration provides the ability to control which objects and routines are accessible by other procedures. Each export declaration has a from clause and a to clause separated by the to keyword. The from clause specifies a set of one or more objects and/or routines. The to clause specifies another set of routines. Each object or routine specified by the from clause can be directly reference by all of the routines specified by the to clause.

For the from clause, the objects and routines are either directly or indirectly specified. One or more objects can be directly specified using the object clause and one or more routines can be directly specified using the routine clause. The all, type, and routine_suffix clauses are used to indirectly specify sets of objects and routines. The all clause specifies all of the objects and routines in the entire module. (Note: the module may be contained in multiple source files.) The type clause specifies all objects and procedures that are members of a named type that are defined in the current module. The procedure_suffix clause specifies all routines that end in a specified suffix (e.g. "get" or "set") that are defined in the current module.

For the to clause, the routines are specified either directly or indirectly. Routines from any other module can be directly specified using the routine clause. All routines in all modules through-out the entire application are specified using the all clause. All routines in a named module are specified using the module clause. All routines that are a member of a named type are specified using the type clause.

By default, all objects and procedures in a given module are accessible by all of the other procedures in the module. For example, for a module named M, this is equivalent to:

    export
	all to module M

Some examples of export declarations are shown below:

    export
	procedure_suffix get to all
	    # All of the modules procedures ending in
	    #, "_get" are accessible by all modules
	    #, through-out the entire application.

	procedure new@new to procedure special_invert
	    # The procedure new@matrix is accessible
	    #, by the procedure special_invert.

	object error@node to type parse
	    #, The object error@node is accessible to
	    #, procedures associated with type parse
	    #, defined in any other module.

	type node to module parse, print, check
	    # All of the procedures and objects
	    #, associated with type node in the current
	    #, module are accessible to the procedures
	    #, defined in the parse, print, and check
	    #, modules.

	all to all
	    # All procedures and objects in the current
	    #, module are accessible from any procedure
	    #, defined in any other module.

An Example Prelude

The following is an example prelude for a STIPPLE source file:

    English		# This module is written in English
    			#, using the STIPPLE 1.0 version of the language
    version "1.0"
    identify "parser.sts 1.16 91/01/29 Copyright© Mumbletron Corp."
    extension chemistry
			# Use some language extensions for
			#, chemistry applications
    configuration_variables debug, demo
			# Define two conditional compilation variables
			#, - one for debugging and another for a
			#, demonstration version
    module distill
			# This module implements a library of
			#, distillation routines
    import
	beer using German preferring_native
			# It uses the procedures/objects from the beer
			#, module which is available only in German.
        configuration_if debug
			# The debugging version uses the
			#, {process_monitor} module
	    process_monitor
    export
	all to all
			# All of this modules procedures/objects
			#, are exported

From here you can go to either the next chapter on STIPPLE Type Declarations or back to the table of contents.