Revision as of 01:04, 13 October 2011

This overview introduces the EGL language as implemented in EGL Core and as extended by Eclipse IDE for the EGL Developer. 

Introduction

In many ways, EGL is like other programming languages. It includes familiar constructs such as loops and transfers of control. It is built on a set of types, each of which defines the operations that are available for each value of the type. Last, it involves a process for validating source code and for converting the source code into a less abstract form, closer to the runtime need.

EGL is special in its reliance on stereotypes, which are declarations used by the software that transforms the source code to another form such as Java or JavaScript.

Stereotypes offer simplicity. First, they ensure that the output created for a source-code element such as "Handler" includes details for a particular use; for example, to be runnable on a full-page web browser. The developer who writes a customized Handler element and declares the appropriate stereotype does not need to know a lot about a browser to write the code. He can rely on the pre-tested logic that an EGL JavaScript generator creates automatically. 

Second, stereotypes provide a way to extend the language. The creation of a new kind of stereotype enables an existing source-code element to have an alternative use. For example, a future stereotype might allow a developer to write a customized Handler element and then to create output for a mobile device that runs under the Android operating system. This alternative option requires that the extender create Java classes that supplement existing logic. 

The mechanism for using stereotypes is a characteristic of EGL Core, which includes the basic rules of EGL syntax. Specific stereotypes are a characteristic of an EGL extension, the first of which is Eclipse IDE for the EGL Developer. 

General comments on types and values

In general usage, a type such as integer or string defines a set of values and a set of operations that can be applied to those values. For example, integers are whole numbers that can be added, subtracted, and so forth; and the number 5 is a value of that type.

The meaning is much the same in EGL, where every value is “of a type.” The type defines the structure of the value and the set of operations that can be applied to the value.

Types can be categorized in different ways, and we initially distinguish between reference and value types:  

• A reference type defines an object, which is a value in a memory area that was separately allocated to hold the value. The object is referenced from some logic and is an instance of the type. In this case, the words "value," "object," and "instance" are interchangeable.
• A value type defines a value that is embedded in an object.

A field declaration is a coded statement that declares a value in a memory area. If the value is based on a reference type, the memory area either represents a null or holds an address that points to the value. If the value is based on a value type, the memory area contains the value itself.

A field declaration typically includes an identifier that names the memory area. If the code that embeds the field declaration is allowed to update the area, the identifier is a variable. If the update is disallowed, the identifier is a constant. Later in this overview is a field declaration that does not name a memory area at all. Such a field declaration is said to be anonymous.

Consider the following field declarations:

   // variable declaration
   NumberOfCars INT;    
   
   // constant declaration
   const MINIMUMNUMBER INT = 2; 

The type is each case is INT, which is a value type for four-byte integers. The first statement declares a value variable, the second declares a value constant.

For a second example, you might declare a list of five integers by coding a statement like one of these:

   // variable declaration
   NumberOfVehicles INT[5];

   // constant declaration
   const MINIMUMNUMBERS INT[5] = [1,2,3,4,5];

The type in this case is INT List or INT[], which is a reference type. The first statement declares a reference variable, which means that you can assign a different list to NumberOfVehicles later. Incidentally, you can also change the values inside the list and can change the number of elements.

The second statement declares a reference constant, which means that you cannot assign a different list to MINIMUMNUMBERS. However, even in this case, you can alter the values inside the list and can change the number of elements.

The behavior is consistent because each declaration in the second example identifies a memory area that contains an address of a second memory area. The constant is only constant in the sense that the area identified as MINIMUMNUMBERS must always contain the same address, which refers to the same list. The following, subsequent assignment is not valid even though the values are the same:

   // An invalid assignment
   MINIMUMNUMBERS = [1,2,3,4,5]; 

EGL native types

EGL Core defines a set of native types, which are implemented only by extensions such as Eclipse IDE for EGL Developers. The most elemental are the simple types. They have no sub-fields and can be categorized as follows:

• Character types 
• Timestamp types
• Large object types
• Numeric types
• Miscellaneous types:
  
  • BOOLEAN, which is the basis of a field that contains the logical true or false.
  • ANY, which is the basis of an instance that itself can reference a value of any type.

The following native types are also built into EGL Core for implementation by an extension: 

• List types, each of which is the basis of a list. A list is a dynamic array: an ordered sequence of elements that can be increased or decreased in number and otherwise updated at run time.
• Dictionary type, which is the basis of a dictionary. A dictionary is composed of key-value
  pairs that can be increased or decreased in number and otherwise updated at run time.

Custom types and EGL classifiers

EGL provides a variety of classifiers, each of which is a kind of type. The capabilities of a classifier are made available to your code in various situations; most often, when you define a custom type that is based on a classifier.

Characteristics of custom types

Depending on the classifier, a custom type can have some or all of the following characteristics:

• A header, which is always required. The header includes the classifier name; the name of the custom type; and, in some cases, a stereotype.
• The end keyword, which is the last detail in the type definition.
• A set of members:
  • Fields, each of which is based on a native or custom type.
  • Functions, each of which is a logical unit that is equivalent to a function or method in another language. EGL functions do not embed other functions.
  • Constructors, each of which is a logical unit that creates an instance of a reference type.

The members in a custom type are typically accessible in the same type. However, if you declare a member to be private, the member is protected from external access; it can be accessed only within the same type. If you do not declare a member to be private, it is said to be public.

Kinds of classifiers

The next table lists the classifier provided in EGL Core. 

To extend a capability, an extender makes an additional stereotype available for use with an existing classifier. The list itself is a fixed aspect of the language.

Annotations

When you write EGL source code, you set annotations. They are values used by some aspect of EGL, including the tooling, if any, and the EGL compiler. 

Annotations help ensure that your EGL-created output reflects your intent. You can set them when you define custom types; when you declare variables and constants; when you code a subset of EGL statements; and, in some cases, when you declare functions.

For example, when you declare a field in a user-interface form, you might set a YES value in the InputRequired annotation. That setting causes the EGL generator to store a detail in the generated output, and the detail ensures that the user can submit the form only if the specified field has content.

Annotation types

An annotation represents an area of memory and is based on an EGL type. To understand these points, consider the following declaration:

myCarCount NumberOfCars { InputRequired = yes }; 

That code has effects at two different stages:

• It declares the myCarCount variable. The appropriate declaration statement is generated into the output code, and the related instance is available at run time. The type of the variable is NumberOfCars, which is an alias of type INT. Here is the alias, or data item:

DataItem
   NumberOfCars INT
End

• The example also identifies an instance that is available at transformation time. The type of that instance is InputRequired.
  
  Here is the EGL Record type:

Record InputRequired type Annotation
   value Boolean;
End

All annotations are based on one or another EGL Record type.

Annotation syntax

The InputRequired declaration in the earlier source code did not set the value field explicitly. The InputRequired = Yes assignment is a shorthand form of the following code:

@InputRequired { value = yes }

The at sign (@) indicates that you are declaring an annotation, and the characters InputRequired indicate that the annotation is based on the InputRequired Record type. The next characters then assign content to the fields in the annotation. The braces ({ and }) represents a set values block, as described in "EGL Syntax."

A shorthand form such as InputRequired = Yes is available whenever the Record type for the annotation has a single field, regardless of the name of that field. If an annotation has multiple fields, only the long form of the declaration is valid, as in the following example:

@AnotherAnnotation { field01 = "test", field02 = 5 }

An annotation can be based on a Record type that has no fields. In that case, the mere presence of the annotation is meaningful to the EGL system code, and only the at sign (@) is required. Here is an example declaration:

@ThirdAnnotation 

In many cases, you can declare multiple annotations, one separated from the next by a comma. For example, the following code declares the InputRequired and DisplayName annotations: 

myCarCount NumberOfCars {
   InputRequired = yes, 
   DisplayName   = "Number of cars: " };

 Annotation overrides

You can declare an annotation when you define a type, and then override the annotation when you declare a variable that is based on the type.

Here is a data item with two annotations:

DataItem
   NumberOfCars { 
      InputRequired = no, 
      DisplayName = "Number of cars: "}
End

The following variable declaration overrides the previous value of the InputRequired annotation:

myCarCount NumberOfCars { InputRequired = yes }; 

If a data item or part includes several annotations and a few are overridden in a variable declaration, the annotations that were not overridden are still in effect. In the previous example, the myCarCount variable is associated with both the InputRequired and DisplayName annotations.

The ability to set multiple annotations is particularly important for data items. For example, a data item might be defined with annotations that are meaningful for user interface and for accessing a relational database. The benefit of being able to specify multiple annotations is that you can retain data items in a library and use those data items for many purposes. When you use a data item to declare a variable for one purpose such as database access, the annotations relevant to other purposes such as user interface have no effect.

Most annotations have a relatively small effect. For example, the InputRequired annotation specifies whether a field in a user-interface form is generated in one way or another. But a stereotype is an annotation that affects a series of decisions; the effect is greater.

Stereotypes

A stereotype is an annotation that you set to communicate a major decision to the EGL compiler. In response to the annotation, the compiler responds in accordance with a pattern that differs from one stereotype to another.

The difference in output is often related to the statements you code. For example, you might define a Record type that is the basis of a record used during sequential-file access. In this case, statements such as add and update do file I/O.

Here is the Record part, which is stereotyped by the CSVRecord stereotype: Record MyCSVRecordPart type CSVRecord { fileName = "employ",

                                  delimiter = "," }

employeeID INT;

       employeeName STRING;

salary DECIMAL(7,2); end

The fileName field refers to an entry in a build part that in turn identifies the file, and the delimiter field indicates how one value in the file is separated from the next. Alternatively, you might define a Record part that is the basis of a record used during relational-database access. In this case, statements such as add and update access a database management system.

Here is the Record part, which is stereotyped by the SQLRecord stereotype: Record EmployeeType type SQLRecord { tableNames = "employee",

keyItems = [employeeID] }

employeeID INT { Column = "empid" }; employeeName STRING { Column = "empname"}; salary DECIMAL(7,2) { Column = "salary"}; end

The tableNames field references a database table, and the keyItems field indicates which fields are referencing a table key. In both the preceding examples, the word “type” is an abbreviation for “stereotype.”

To see that a stereotype is a kind of annotation, compare the earlier of MyCSVRecordPart with the following, equivalent one: Record MyCSVRecordPart {@CSVRecord {fileName = "employ",

delimiter = ","}}

employeeID INT; employeeName STRING; salary DECIMAL(7,2); end

Although the second, longer form is rarely used, the at sign (@) again declares a value used by EGL. In this case, the declaration is based on the CSVRecord Record part, which includes several fields:

Record CSVRecord type Stereotype fileName STRING; delimiter CHAR(1); end

You declare a stereotype only when you define a part. If the part can include fields, the stereotype identifies a set of member annotations, which are annotations that apply to those fields. For example, consider the EmployeeType Record part again: Record EmployeeType type SQLRecord { TableNames = "EMPLOYEE",

KeyItems = [employeeID] }

employeeID INT { Column = "EMPID" }; employeeName STRING { Column = "EMPNAME"}; salary DECIMAL(7,2) { Column = "SALARY"}; end

The Column annotation relates the employeeID, employeeName, and salary fields with relational-database table columns; specifically, with the EMPID, EMPNAME, and SALARY columns. The SQLRecord stereotype causes the Column annotation to be available in any Record part that is defined with the stereotype.

Each classifier such as Record or Program supports zero to many stereotypes. You select from the list when you define a custom part.

EGL Syntax

EGL source code is a sequence of tokens, which are the smallest units of meaning. At a more composite level, the language includes the following constructs: type definitions, expressions, statements, and set-values blocks.
The EGL tokens are as follows:
Keywords.

The EGL reserved words; for example, add.
Identifiers.

The names of parts, functions, variables, and constants. An example is myCarCount, which is a variable name.
Literals.

Fixed values of a given type. Examples are the integer 5, the string “yes!”, and the Boolean value TRUE.
Operators.

Symbols that affect operands, which might be keywords, identifiers, or literals. An operand is on the left or right of an operator. For example, the < operator is part of a condition that tests whether the operand on the left has a lesser value than the operand on the right.
Special characters.

Punctuation marks that divide tokens, as necessary for the parsing done by the EGL compiler. For example, parentheses (( )) surround a condition such as this:
(myVariable < yourVariable)
At a more composite level, the language includes the following constructs:
Type definitions.
Sequences of tokens that define a part. Here is an example:
DataItem
NumberOfCars INT
End

Expressions.

Sequences of tokens that express unnamed instances. For example, 4 + 5 might be assigned to a variable, but is itself a value of type INT.
Statements.

An instruction that causes work to occur at run time or that organizes code at development and transformation time:
The runtime work might be variable declaration, data manipulation, logic invocation, input to (or output from) a user interface or persistent data storage, and so forth.

The organization work might include assigning types to packages, importing types from other packages, and enabling a shortcut for referencing identifiers that are in libraries.
Most statements begin with an EGL keyword. For example, the following statement writes “yes!” to the standard output:
SysLib.writeStdOut("yes!");

Set-values blocks.

Code areas that set annotations and field values and are delimited by curly brackets ({}), as shown in the following declaration:

myCarCount NumberOfCars
{ InputRequired = yes, DisplayName = "Number of cars: " };

The example set-values block assigns values to the InputRequired and DisplayName annotations for the myCarCount variable.

Set-values blocks are used in various ways in type definitions, statements, expressions, and other set-values blocks.

Class classifier

The Class classifier is the basis of the ANY type, List types and Dictionary type, all of which are reference types. You cannot use the Class classifier to define custom types. Instead, use the Handler classifier. 

DataItem classifier

The capabilities of the DataItem classifier are made available when you code a data
item. A data item is an alias of another type and can include multiple annotations.

• Handler classifier
  
  The Handler classifier is the basis of a custom type that includes all the possible kinds of members. In the absence of a stereotype, the custom type defines an object, for any kind of use.  In the presence of a stereotype, the custom type handles a series of interactions with the user or with other EGL logic, as necessary to support one or another user interface technology. 
  
  The next table lists the stereotypes that are available for a Handler part.
   
  

Examples of custom types 

One classifier is Record, which enables you to define a type with multiple fields. For example, you might use this classifier to define a type named CarPolicy:

Record CarPolicy 
   thePolicyID STRING;
   theCarCount INT;
   theDriverCount INT;
end

You can use a type such as CarPolicy to declare a variable named myCarPolicy:

myCarPolicy CarPolicy;

The variable is called a record, and you can now assign values to its fields: 

myCarPolicy.thePolicyID = "ABC123";
myCarPolicy.theCarCount = 2;
myCarPolicy.theDriverCount = 2;

Another classifier is Program. You use this classifier to define a program, which is a static type: a coded unit that runs and is not the basis of a variable. For example, here is the program AssignPolicyValues:

Program AssignPolicyValues

   myCarPolicy CarPolicy;
   const CONSTANT_TWO INT = 2

   function main()
      myCarPolicy.thePolicyID = "ABC123";
      myCarPolicy.theCarCount = CONSTANT_TWO;
      myCarPolicy.theDriverCount = CONSTANT_TWO;
   end
 end  

AssignPolicyValues embeds fields and functions that are program global, which means that they are accessible throughout the type.

Incidentally, EGL documentation often drops the word “type” when referring to a type that is based on a classifier other than Record. For example, AssignPolicyValues is said to be a “program” rather than a “Program type.”