Jump to: navigation, search

Difference between revisions of "EDT:Language Overview"

 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This overview introduces the EGL language as defined in EGL Core and as extended by Eclipse IDE for the EGL Developer. Reference details are in the EDT help system, which is made available when you install a download from the following site:  [http://www.eclipse.org/edt/download/ www.eclipse.org/edt/download/].
+
<span style="font-size:smaller;">&lt;&nbsp;[[EDT| EDT wiki home]]</span>
  
= Introduction<br> =
+
This overview introduces the EGL language as&nbsp;defined&nbsp;in EGL Core and as extended&nbsp;by Eclipse IDE for the EGL Web Developer.&nbsp;Reference details are in the EDT help system, which is made available when you install a download from the following site:&nbsp; [http://www.eclipse.org/edt/download/ www.eclipse.org/edt/download/].
  
 
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.  
 
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.  
Line 11: Line 11:
 
Second, stereotypes provide a way to extend the language.&nbsp;The creation of a&nbsp;new kind of stereotype&nbsp;enables an existing source-code element&nbsp;to have an&nbsp;alternative use. For example, a&nbsp;future stereotype might allow a developer to write a custom Handler element and then to&nbsp;create output for a mobile device that&nbsp;runs under&nbsp;the Android operating system. This alternative&nbsp;option requires that the extender&nbsp;create Java classes that&nbsp;add to the&nbsp;existing generator logic.&nbsp;  
 
Second, stereotypes provide a way to extend the language.&nbsp;The creation of a&nbsp;new kind of stereotype&nbsp;enables an existing source-code element&nbsp;to have an&nbsp;alternative use. For example, a&nbsp;future stereotype might allow a developer to write a custom Handler element and then to&nbsp;create output for a mobile device that&nbsp;runs under&nbsp;the Android operating system. This alternative&nbsp;option requires that the extender&nbsp;create Java classes that&nbsp;add to the&nbsp;existing generator logic.&nbsp;  
  
The mechanism for using stereotypes is provided by&nbsp;EGL Core, which includes the&nbsp;basic rules of EGL syntax.&nbsp;Most stereotypes are provided by an EGL extension, and the first extension is Eclipse IDE for the EGL&nbsp;Developer.<br>
+
The mechanism for using stereotypes is provided by&nbsp;EGL Core, which includes the&nbsp;basic rules of EGL syntax.&nbsp;Most stereotypes are provided by an EGL extension, and the first extension is Eclipse IDE for the EGL&nbsp;Developer.<br>  
  
= EGL Syntax  =
+
We describe stereotypes in the&nbsp;first of&nbsp;the following pages and&nbsp;proceed to&nbsp;other aspects of the language:&nbsp;<br>
  
EGL source code is a sequence of '''tokens''', which are the smallest units of meaning. The EGL tokens are categorized as follows:  
+
*[[EDT:Language Overview02|EGL types and values]]
 +
*[[EDT:Language Overview03|Packages and type-name resolution]]
 +
*[[EDT:Language Overview04|Syntax and scope]]
  
*'''Keywords''', which are the the EGL reserved words; for example, Record.&nbsp;
+
<br> <br>  
*'''Identifiers'''.&nbsp;which are the&nbsp;names of types, functions, variables, and constants. An example is <code>myCarCount</code>, which is a variable name.
+
*'''Literals''', which are fixed&nbsp;values of a given type. Examples are the integer 5, the string “yes!”, and the Boolean value TRUE.
+
*'''Operators''', which are symbols that affect a value.&nbsp;The value, or operand,&nbsp;is on the left or right of an operator. For example, the &lt; 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''',&nbsp;which are punctuation marks that divide tokens, as necessary for the parsing done by the EGL compiler. For example, parentheses (( )) might surround a condition such as <code>myVariable &lt; yourVariable</code>.&nbsp;
+
  
At a more composite level, the language includes the following constructs:
+
&nbsp;
  
*'''Type definitions''', which are sequences of tokens that define a type.
+
&nbsp;  
*'''Expressions''', which are&nbsp;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''', which is an&nbsp;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, output to&nbsp;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.<br>
+
  
:Most statements begin with an EGL keyword. For example, the following statement writes “yes!” to the standard output:&nbsp; <code>SysLib.writeStdOut("yes!");</code>
+
[[Category:EDT]]
 
+
*'''Set-values blocks''', which are code areas that set annotations and field values and are delimited by curly brackets ({}), as shown in the following declaration:
+
 
+
:<pre>myCarCount NumberOfCars { InputRequired = yes };</pre>
+
 
+
:The example set-values block declares&nbsp;an '''InputRequired''' annotation for the <code>myCarCount</code> variable.<br><br>Set-values blocks are used in various ways in type definitions, statements, expressions, and other set-values blocks.
+
 
+
= EGL types and values  =
+
 
+
The next sections move from general comments to a review of EGL native types, custom types, classifiers, annotations, and stereotypes.
+
 
+
== 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&nbsp;reference&nbsp;and value types:&nbsp;&nbsp;
+
 
+
*A '''reference type''' defines an '''object''', which is a value in a memory area that was separately allocated to hold&nbsp;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&nbsp;'''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&nbsp;an address&nbsp;that&nbsp;points&nbsp;to the value. If the value is based on a value type, the memory area contains the value itself.
+
 
+
A named field&nbsp;declaration&nbsp;includes&nbsp;an identifier&nbsp;that names the memory area&nbsp;for subsequent use.&nbsp;If the embedding code is allowed to&nbsp;update the area, the identifier is a '''variable'''.&nbsp;If&nbsp;the update is disallowed, the identifier is a '''constant'''.&nbsp;
+
 
+
Consider the following&nbsp;field declarations:
+
<pre>&nbsp;&nbsp;&nbsp;// variable declaration
+
&nbsp;&nbsp; NumberOfCars INT;&nbsp;&nbsp;&nbsp;&nbsp;
+
&nbsp;&nbsp;
+
&nbsp;&nbsp; // constant declaration
+
&nbsp;&nbsp; const MINIMUMNUMBER INT = 2; </pre>
+
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:<br>
+
<pre>  // variable declaration
+
  NumberOfVehicles INT[5];
+
 
+
  // constant declaration
+
  const MINIMUMNUMBERS INT[5] = [1,2,3,4,5];</pre>
+
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 <code>NumberOfVehicles</code> 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 <code>MINIMUMNUMBERS</code>. 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 <code>MINIMUMNUMBERS</code> 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:<br>
+
<pre>  // An invalid assignment
+
  MINIMUMNUMBERS = [1,2,3,4,5]; </pre>
+
== EGL native types  ==
+
 
+
EGL Core defines a set of '''native types''', which are implemented only by extensions such as&nbsp;Eclipse IDE for EGL Developers.&nbsp;The most elemental are the '''simple&nbsp;types'''. They have no sub-fields and can be categorized as follows:
+
 
+
*Boolean, which is the basis of a field that contains the logical true or false.
+
*Character types&nbsp;
+
*Timestamp types
+
*Large object types
+
*Numeric types
+
 
+
The following native types are also defined in EGL Core and implemented by&nbsp;Eclipse IDE for the EGL Developer:&nbsp;
+
 
+
*ANY, which is the basis of an instance that can reference a value of any type.
+
*Dictionary type, which is the basis of a dictionary. A dictionary is composed of key-value<br>pairs that can be increased or decreased in number and otherwise updated at run time.
+
*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.
+
 
+
== 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&nbsp;a classifier.
+
 
+
=== Characteristics of custom types  ===
+
 
+
Depending on the classifier, a custom type&nbsp;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&nbsp;some cases, a stereotype.
+
*The '''end''' keyword, which is the&nbsp;last&nbsp;detail in&nbsp;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&nbsp;custom type&nbsp;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.&nbsp;
+
 
+
{| border="2" cellspacing="2" cellpadding="2" width="80%"
+
|+ Kinds&nbsp;of classifiers
+
|-
+
| &nbsp;&nbsp;&nbsp;&nbsp;'''&nbsp;&nbsp; Name&nbsp;&nbsp;&nbsp;&nbsp;'''
+
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; '''Purpose&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'''
+
|-
+
| Class
+
| To provide the Any, Dictionary, and List types.
+
|-
+
| DataItem
+
| To alias&nbsp;a native or custom type.
+
|-
+
| Delegate
+
| To define a type that identifies&nbsp;a kind of&nbsp;function.&nbsp;The related variable is like&nbsp;a function pointer in C language.
+
|-
+
| Enumeration
+
| To define a type that holds a collection of named values. The value of the related variable is one of those values.&nbsp;
+
|-
+
| ExternalType
+
| To define&nbsp;a type&nbsp;that&nbsp;identifies non-EGL code. The related variable provides access to the code.
+
|-
+
| Handler
+
| To define a type that&nbsp;includes all the possible kinds of members. The related variable either defines a general purpose object or allows for interaction with a user interface technology.
+
|-
+
| Interface
+
|
+
To define a type that represents a&nbsp;contract between&nbsp;a unit of logic such as a service and the&nbsp;logic requester.&nbsp;Uses are twofold:
+
 
+
*To enable access of the unit of logic, EGL code declares a&nbsp;variable that is based&nbsp;on the Interface type.&nbsp;
+
*To ensure that&nbsp;design decisions are fulfilled, you can code&nbsp;the unit of logic to reference&nbsp;an Interface type.
+
 
+
|-
+
| Library
+
| To define a static type that&nbsp;contains fields and functions that are&nbsp;local to other EGL logic.&nbsp;The fields retain values across requesters.
+
|-
+
| Program
+
| To define a static type that has a single entry point.
+
|-
+
| Record
+
| To define a type that includes fields.
+
|-
+
| Service
+
| To define a static type that has multiple entry points and that might be accessed locally or remotely.&nbsp; The type also can be the basis of a variable that provides access to the logic from other EGL code.
+
|}
+
 
+
To extend a capability, an extender makes an additional stereotype available for use with an existing classifier. The list&nbsp;of classifiers&nbsp;is a fixed aspect of the language.
+
 
+
== Annotations  ==
+
 
+
When you write EGL source code, you set '''annotations'''.&nbsp;They are values used by some aspect of EGL technology; in most cases, by the&nbsp;EGL compiler.&nbsp;
+
 
+
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<br> ===
+
 
+
An annotation represents an area of memory and is based on an EGL type. To understand these points, consider the following declaration:<br>
+
<pre>myCarCount NumberOfCars { InputRequired = yes }; </pre>
+
That code has effects at two different stages:
+
 
+
*It declares the <code>myCarCount</code> 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 <code>NumberOfCars</code>, which is an alias of type INT. Here is the alias, or data item:
+
<pre>DataItem
+
  NumberOfCars INT
+
End</pre>
+
*The example also identifies an instance that is available at transformation time. The type of that instance is '''InputRequired'''.<br><br>Here is the EGL Record type:
+
<pre>Record InputRequired type Annotation
+
  value Boolean;
+
End</pre>
+
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 <code>InputRequired = Yes</code> assignment is a shorthand form of the following code:
+
<pre>@InputRequired { value = yes }</pre>
+
The at sign (@) indicates that you are declaring an annotation, and the characters&nbsp;"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 here:&nbsp; [http://wiki.eclipse.org/EDT:Language_Overview#EGL_Syntax wiki.eclipse.org/EDT:Language_Overview#EGL_Syntax].<br><br>A shorthand form such as <code>InputRequired = Yes</code> is available whenever the Record&nbsp;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:
+
<pre>@AnotherAnnotation { field01 = "test", field02 = 5 }</pre>
+
An annotation can be based on a Record&nbsp;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:<br>
+
<pre>@ThirdAnnotation&nbsp;</pre>
+
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:&nbsp;
+
<pre>myCarCount NumberOfCars {
+
  InputRequired = yes,
+
  DisplayName  = "Number of cars: " };</pre>
+
=== 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:<br>
+
<pre>DataItem
+
  NumberOfCars {
+
      InputRequired = no,
+
      DisplayName = "Number of cars: "}
+
End</pre>
+
The following variable declaration overrides the previous value of the&nbsp;'''InputRequired''' annotation:<br>
+
<pre>myCarCount NumberOfCars { InputRequired = yes }; </pre>
+
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 <code>myCarCount</code> 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&nbsp;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.<br>
+
 
+
== 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.
+
 
+
For example, you might want to display a web page that&nbsp;responds as follows to a button click: by changing&nbsp;the button text from "Toggle on" to "Toggle off" or from "Toggle off" to "Toggle on".&nbsp;&nbsp;The logic is in the following handler, which includes a declaration for the '''RUIHandler''' stereotype:
+
<pre>Handler MyHandler type RUIhandler{
+
  initialUI =[myButton],
+
  onConstructionFunction = start}
+
 
+
  myButton DojoButton{
+
      onClick&nbsp;::= myButton_onClick };
+
 
+
  function start()
+
      myButton.text = "Toggle on";
+
  end
+
 
+
  function myButton_onClick(event Event in)
+
      if (myButton.text == "Toggle on")
+
        myButton.text = "Toggle off";
+
      else
+
        myButton.text = "Toggle on";
+
      end
+
  end
+
end </pre>
+
You might want to provide the same capability on a mobile device that runs on the Android operating system. In this case, an extender might&nbsp;provide a pair of constructs...&nbsp;&nbsp;??
+
<pre>Handler MyHandler type WindowHandler
+
  { createLayout = true, contentView = }
+
 
+
  &nbsp;????
+
 
+
  myButton DojoButton{
+
      text = "Toggle on",
+
      onClick&nbsp;::= myButton_onClick };
+
 
+
  function myButton_onClick(event Event in)
+
      if (myButton.text == "Toggle on")
+
        myButton.text = "Toggle off";
+
      else
+
        myButton.text = "Toggle on";
+
      end
+
  end
+
end</pre>
+
[ Explain ]<br><br>To see that a stereotype is a kind of annotation, compare the following, equivalent&nbsp;outlines for the '''MyHandler''' handler:
+
<pre>Handler MyHandler type RUIHandler
+
                  {
+
                      initialUI =[myButton],
+
                      onConstructionFunction = start
+
                  }
+
 
+
  // handler members are here
+
 
+
end
+
 
+
Handler MyHandler { @RUIHandler
+
                    {
+
                      initialUI = [myButton],
+
                      onConstructionFunction = start
+
                    }
+
                  }
+
 
+
  // handler members are here
+
 
+
end</pre>
+
Although the second, longer form is rarely used, the at sign (@) again declares a value used by an EGL compiler.&nbsp;In this case, the declaration is based on the Record type named '''RUIHandler''', which includes several fields:
+
<pre>Record RUIHandler type Annotation
+
  {
+
      targets = [ElementKind.handlerPart],
+
      @Stereotype {defaultSuperType=View},
+
      validationProxy =
+
 
+
        // split onto two lines for better display
+
        "org.eclipse.edt.compiler.binding.
+
        annotationType.RUIHandlerAnnotationTypeBinding"
+
  }
+
  onConstructionFunction FunctionMemberRef;
+
  includeFile String;
+
  cssFile String;
+
  title String;
+
  theme String;
+
end</pre>
+
The '''RUIHandler''' Record type declares three&nbsp;annotations:
+
 
+
*'''targets''' indicates the custom types for which the stereotype applies.&nbsp;The term "part" is sometimes used in place of the term "custom type," and the '''ElementKind.handlerPart '''value indicates that&nbsp;a&nbsp;Handler type can be annotated with&nbsp;a&nbsp;value of type '''RUIHandler'''.&nbsp;The absence of any other '''ElementKind''' value indicates that no other kind of custom type can be annotated in the same way.
+
*'''@Stereotype''' indicates that the Record type is defining a stereotype.&nbsp;Fields in the '''View''' supertype are available to the Handler type being stereotyped.&nbsp;In particular, the&nbsp;custom Handler&nbsp;type has access to the&nbsp;'''initialUI'''&nbsp;field, which&nbsp;lists the widgets&nbsp;for initial&nbsp;display on the web page.
+
*'''validationProxy''' identifies a&nbsp;Java class that validates the stereotype value with which the custom Handler type is annotated.
+
 
+
The '''RUIHandler''' Record type also declares a set of fields, which are available to&nbsp;any custom type that declares a '''RUIHandler''' stereotype.&nbsp;The earlier code identified only one of those fields: '''onConstructionFunction''', which references&nbsp;a constructor that runs initially, before the&nbsp;user&nbsp;accesses the web page.&nbsp;These fields are properly called&nbsp;annotation fields or, more specifically, '''stereotype fields'''.&nbsp;&nbsp;&nbsp;
+
 
+
If you annotate a custom type with a stereotype, and if the custom type can include fields of its own, the stereotype can declare an annotation of type '''MemberAnnotations'''.&nbsp;The purpose is to&nbsp;list the annotations that can be appled to each&nbsp;field of the custom type.&nbsp;Here is an example of such an annotation:
+
<pre>Record ExampleStereotype type Annotation
+
{
+
  targets = [ElementKind.recordPart],
+
  memberAnnotations = [Annotation01, Annotation02]
+
  @Stereotype {}
+
}
+
 
+
// stereotype fields are here
+
 
+
end</pre>
+
The developer of the custom type can annotate each&nbsp;field&nbsp;with '''Annotation01''' and '''Annotation02''', which are also Record types of type '''Annotation'''.
+
 
+
Each classifier supports zero to many stereotypes. For example, a Handler type can include a declaration of '''RUIHandler''' or '''RUIWidget'''.&nbsp;A developer who codes a custom type selects from the stereotype list that is specific to a classifier.
+
 
+
= EGL Packages<br> =
+
 
+
An '''EGL package''' is a container of EGL types, each of which has a name that is unique to the package. For example, a program and a data item of the same name cannot be in the same package. In general terms, the package is a namespace, which is a container in which the immediately subordinate names are unique.
+
 
+
The package corresponds to a set of subfolders in a directory. The subfolders correspond to the package name.
+
 
+
== Package names  ==
+
 
+
A package name is a sequence of names with intervening periods (.). Here is an example:<br>
+
<pre>com.myOrg.myPkg</pre>
+
Each name is that of a subfolder in a hierarchy. The hierarchy for the current example is expressed as follows on a Windows platform:
+
<pre>com\myOrg\myPkg</pre>
+
The EGL parts are in files in the bottommost subfolder; here, the <code>myPkg</code> subfolder.<br>
+
 
+
You might invert the list of qualifiers in your company's Internet domain name and assign the resulting list to the start of your package names. For example, if the domain name is <code>mycompany.mydivision.mydepartment.com</code>, you might start your package names with <code>com.mydepartment.mydivision.mycompany</code>. This convention is often used.&nbsp;A benefit is that your packages will be unique even if your company merges or collaborates with another.
+
 
+
Package names are case sensitive; <code>myPkg</code> is different from <code>MYpkg</code>.
+
 
+
Although a package corresponds to a set of subfolders, an EGL package is a collection of types. The subfolders and related files represent only how those types are stored.
+
 
+
== Package statement  ==
+
 
+
Each EGL source file in a named package must start with a statement that identifies the package. The statement provides a kind of documentation, as in the following example:
+
<pre>package myPkg;</pre>
+
== Default package  ==
+
 
+
An Eclipse project includes a default package, which is a package that has no name. Other packages cannot access the types that are defined in a default package.
+
 
+
When you use a default package, the directory that contains the package includes all the EGL source files that are in that package. In this case, a source file does not start with a package statement.<br>
+
 
+
== Package import&nbsp;  ==
+
 
+
The EGL '''import''' statement provides access to the types in a second, named package. The '''import''' statement is used in two ways:
+
 
+
*A statement that explicitly provides access to a specific part in a package in called a&nbsp;'''one-type import statement'''. The type is always available at compilation time.<br><br>Here is an example statement:
+
 
+
:<pre>import myPkg.MyProgram;</pre>
+
 
+
*A statement that provides access to a set of types&nbsp;in a package is called an '''on-demand import statement''' because the types that are actually required are made available only as needed.<br><br>Here is an example statement:
+
 
+
:<pre>import myPkg.*; </pre>
+
 
+
:The example makes available all the types in the <code>myPkg</code> package.<br>
+
 
+
An '''import''' statement can give access to&nbsp;types that are in another package repository, which is a directory or compressed file that holds one or more packages. Access requires that you reference the package repository in the '''EGL build path''', which is a list of repositories.
+
 
+
= Type-name resolution  =
+
 
+
The rules for type-name resolution&nbsp;define the search order that the compiler follows to resolve a type reference; for example, in a variable declaration. The compiler considers the current package directory and&nbsp;the repositories in the EGL build path. The compiler stops the search only when the same-named type is found or, if no type is found, only after all locations are searched.
+
 
+
The rest of this description assumes that the compiler is seeking the <code>myType</code> type in the <code>myPkg</code> package. Also,&nbsp;change "current project"&nbsp;to&nbsp;"current directory" if the search occurs in the EGL SDK.
+
 
+
If the reference is fully qualified, as in the case of <code>myPkg.myType</code>, the compiler seeks the type in the current project and then in every repository in the EGL build path. The search through the repositories is in build-path order.
+
 
+
If the reference is not fully qualified, as in the case of <code>myType</code>, the compiler gives priority to packages in the following order:
+
 
+
#The package identified in a one-type import statement such as <br><code>import myPkg.myType;</code><br><br>The compiler seeks the type in the current project and&nbsp;then in every repository in the EGL build path, in build-path order.<br><br>
+
#The current package. <br><br>The compiler seeks the type in the current project and then in every repository in the EGL build path, in build-path order.<br><br>
+
#The package identified in an on-demand import statement such as <br><code>import myPkg.*;</code>.<br><br>The compiler seeks the type in the current project or directory&nbsp;and then in every repository in the EGL build path, in build-path order. The search ends as soon as a type is found. However, if multiple on-demand import statements reference the same type, the search results in an error.
+
 
+
= <br>Scope  =
+
 
+
The scoping rules tell whether a given variable, constant, parameter, or function is visible to an expression.&nbsp;&nbsp;
+
 
+
The order of priority for resolving a reference is as follows:
+
 
+
#First in precedence are declarations that are local to the function where the expression resides. This category includes&nbsp;variable, constant, and function-parameter declarations.
+
#Second in precedence are declarations that are outside of a function but are inside the type where the expression resides. Each field is '''program global''', which means that it is accessible to all members in the type. This category includes variable, constant, program-parameter, and function declarations.
+
#Third are declarations that are outside a function but are inside a library that is accessible to the expression. Each public field is '''run-unit global''', which means that it is accessible to all functions that run as a unit such that an unhandled exception terminates the unit. This category includes the variable, constant, and function declarations in the library. Those declarations are program global to other functions in the same library.
+
 
+
A reference in an expression can include a series of identifiers, with a period (.) separating one from the next. Here is an expression in which each operand is fully qualified:<br>
+
<pre>autoPkg.AutoLibrary.numberInFleet –
+
autoPkg.CarLibrary.DebtRecord.carLimit </pre>
+
As appropriate, the identifiers can include a package name,&nbsp;the name of a container type,&nbsp;the name of a contained type, and a field name. A contained type can itself be a container type, to any level of depth.
+
 
+
The package and type names are especially useful for accessing values and functions in a library, as suggested in the example. However, for library access you can code a&nbsp;'''use''' statement, which offers&nbsp;the convenience of referring more directly to the declarations inside the library.
+
 
+
If a local declaration has the same name as the '''program-global declaration''', only the local declaration is visible to the expression; but you can override that rule by using the '''this''' keyword.
+

Latest revision as of 10:41, 10 July 2012

EDT wiki home

This overview introduces the EGL language as defined in EGL Core and as extended by Eclipse IDE for the EGL Web Developer. Reference details are in the EDT help system, which is made available when you install a download from the following site:  www.eclipse.org/edt/download/.

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 custom 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 is created by an EGL JavaScript generator. The pre-tested logic supplements the custom logic.   

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 custom 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 add to the existing generator logic. 

The mechanism for using stereotypes is provided by EGL Core, which includes the basic rules of EGL syntax. Most stereotypes are provided by an EGL extension, and the first extension is Eclipse IDE for the EGL Developer.

We describe stereotypes in the first of the following pages and proceed to other aspects of the language: