Walnut/Ordinary Programming

From Erights

(Difference between revisions)
Jump to: navigation, search
Line 12: Line 12:
{{:Walnut/Ordinary_Programming/Hello_World}}
{{:Walnut/Ordinary_Programming/Hello_World}}
 +
{{:Walnut/Ordinary_Programming/Data_Types_and_Control_Flow}}
-
===Simple data types, simple control flow===
 
-
 
-
Here are some of the basics of the language:
 
-
 
-
<pre>
 
-
 
-
<nowiki># E sample
 
-
# Comment on this piece of code
 
-
 
-
def a := 3
 
-
var b := a + 2
 
-
b += 1
 
-
if (a < b) {
 
-
    println("a is less than b")
 
-
} else {
 
-
    println("Wow, the arithmetic logic unit in this processor is confused")
 
-
}</nowiki>
 
-
 
-
</pre>
 
-
 
-
Variable declarations in <span class="e">''E''</span> are made with the ''var'' statement. Variables that are only assigned a value once at creation (i.e., constants, or variables declared final) are created with the ''def'' statement. In E as in Java, "+=" is shorthand for adding the righthand value to the lefthand variable.
 
-
 
-
Single-line comments have a "#" at the beginning, and terminate with the end of line. The /**...*/ comment style is used only for writing javadoc-style <span class="e">''E''</span> comments, discussed later. <span class="note">link here</span>
 
-
 
-
Assignment uses the ":=" operator. ''The single equal sign "=" is never legal in E'', use ":=" for assignment and "==" for testing equality. The function "println" prints to the console. The "if" statement looks identical to its Java equivalent, but'' the braces are required''.
 
-
 
-
What is the end-of-statement delineator in E? In Java, you terminate a statement with a semi-colon. In <span class="e">''E''</span>, the end-of-line is also the end-of-statement ''unless'' there is an open operation at the end of the line. In the example, the "if" statement's first line ends with an open brace; <span class="e">''E''</span> knows the next line must be a continuation line. Some quick examples
 
-
 
-
<pre>
 
-
 
-
<nowiki>This works
 
-
? def a := 1 + 2 + 3 + 4
 
-
# value: 10
 
-
 
-
 
-
And this works
 
-
? def b := 1 + 2 +
 
-
>  3 + 4
 
-
# value: 10
 
-
 
-
 
-
But this does not work, because the first line can and does
 
-
evaluate without a continuation, so the second line is a syntax error:
 
-
? def c := 1 + 2
 
-
?  + 3 + 4
 
-
# example syntax error:
 
-
#  + 3 + 4
 
-
#  ^</nowiki>
 
-
 
-
</pre>
 
-
 
-
The end-of-line statement termination of <span class="e">''E''</span> makes it easy to use <span class="e">''E''</span> for command lines, as in rune.
 
-
 
-
If your organization uses a line continuation convention that puts the operator at the beginning of the second line, you can use the explicit continuation character "\" as here:
 
-
 
-
<pre>
 
-
 
-
<nowiki>This also works
 
-
? def c := 1 + 2 \
 
-
>  + 3 + 4
 
-
# value: 10</nowiki>
 
-
 
-
</pre>
 
-
 
-
====Basic Types and Operators====
 
-
 
-
The basic types in <span class="e">''E''</span> are int, float, string, char, and boolean. All integer arithmetic is unlimited precision, as if all integers were BigIntegers.
 
-
 
-
Floats are represented as 64-bit IEEE floating point numbers. The operators +, -, * have their traditional meanings for integers and floats. The normal division operator "/" ''always gives you a floating point result''. The ''floor divide'' operator "//" always gives you an integer, truncated towards negative infinity. So (-3.5 // 1) == -4.
 
-
 
-
<span class="e">''E''</span> has 2 modulo operations: "%", like the Java modulo operator, returns the remainder of division that truncates towards zero. E also supplies "%%", which returns a remainder of division that truncates towards negative infinity.
 
-
 
-
Operator precedence is generally the same as in Java. In a few cases E will throw a syntax error and require the use of parentheses.
 
-
 
-
<font color="#FF0000">"+" when used with strings is a concatenation operator as in Java. It automatically coerces other types on the right-hand if the left-hand operand is a string:</font>
 
-
 
-
<pre>
 
-
 
-
<font color="#FF0000"><nowiki># E sample
 
-
def x := 3
 
-
def printString := "Value of x is: " + x</nowiki></font>
 
-
 
-
</pre>
 
-
 
-
You can <font color="#FF0000">also</font> use quasi-literals, which enable the easy processing of complex strings as described in detail later; here is a very simple example:
 
-
 
-
<pre>
 
-
 
-
<nowiki># E sample
 
-
def printString := `Value of x is: $x`</nowiki>
 
-
 
-
</pre>
 
-
 
-
wherein the back-ticks denote a quasi-literal, and the dollar sign denotes a variable whose value is to be embedded in the string.
 
-
 
-
&& and || and ! have their traditional meanings for booleans; ''true'' and ''false'' are boolean constants.
 
-
 
-
Strings are enclosed in double quotes. Characters are enclosed in single quotes, and the backslash acts as an escape character as in Java: '\n' is the newline character, and '\\' is the backslash character. Strings in <span class="e">''E''</span> are so similar to strings in Java, it is easy to conclude they are identical when they are not. The [http://www.erights.org/javadoc/org/erights/e/elib/tables/Twine.html  protocol for <span class="e">''E''</span> strings] is detailed in the [http://www.erights.org/javadoc/index.html  <span class="e">''E''</span> javadoc].
 
-
 
-
<nowiki>== and != are the boolean tests for equality and inequality respectively. When the equality test is used between appropriately designated </nowiki><span class="note"> link to selfless here</span> ''transparent immutables'', such as integers, the values are compared to see if the values are equal; for other objects the references are compared to see if both the left and right sides of the operator refer to the same object. Chars, booleans, integers, and floating point numbers are all compared by value, as in Java. In addition, Strings, ConstLists, and ConstMaps <span class="note">link here</span> are also compared by value, which makes it different from, and more natural than, Java.
 
-
 
-
Other transparent immutables (notably ConstLists and ConstMaps) will be introduced later. Additional useful features of transparent immutables are discussed under Distributed Computing.
 
-
 
-
There are some special rules about the behavior of the basic operators because of E's distributed security. These rules are described in the Under the Covers section later in this chapter.
 
-
 
-
====Additional flow of control====
 
-
 
-
We have already seen the if/then/else structure. Other traditional structures include:
 
-
 
-
* while (booleanExpression) {...}
 
-
* try{...} catch errorVariable {...} finally{...}
 
-
* throw (ExceptionExpressionThatCanBeAString)
 
-
* break (which jumps out of a while or for loop; if the break keyword is followed by an expression, that expression is returned as the value of the loop)
 
-
* continue (which jumps to the end of a while or for, and starts the next cycle)
 
-
* switch (expression) {match==v1{...} match==v2{...} ... match _{defaultAction}}
 
-
 
-
One structure that is more powerful than its Java counterpart is the'' for ''loop.
 
-
 
-
<pre>
 
-
 
-
<nowiki># E sample
 
-
for i in 1..3 {
 
-
    println(i)
 
-
}
 
-
for j in ["a", 1, true] {println(j)}
 
-
</nowiki>
 
-
 
-
</pre>
 
-
 
-
In this simple example, i becomes 1, 2, 3 in succession. In the second, j becomes each of the elements of the list.
 
-
 
-
The for loop operates not only with number ranges, but also with lists, maps (i.e. hashtables), text files, directories, and other structures discussed later in this book. The expanded version of the for loop that is needed to get both keys and values out of maps is:
 
-
 
-
<pre>
 
-
 
-
<nowiki># E syntax
 
-
for key => value in theMap {
 
-
    println(`Key: $key Value: $value`)
 
-
}
 
-
# You can get the index and the value from a list at the same time the same way
 
-
for i => each in ["a", "b"] {
 
-
    println(`Index: $i Value: $each`)
 
-
}
 
-
</nowiki>
 
-
 
-
</pre>
 
-
 
-
You can create your own data structures over which the for loop can iterate. An example of such a structure, and a brief explanation of the iterate(function) method you need to implement, can be found in the ''Library Packages: emakers'' section later in this chapter, where we build a simple queue object.
 
-
 
-
====The Secret Lives of Flow Control Structures====
 
-
 
-
Flow control structures actually return values. For example, the if-else returns the last value in the executed clause:
 
-
 
-
<pre>
 
-
 
-
<nowiki># E sample
 
-
def a := 3
 
-
def b := 4
 
-
def max := if (a > b) {a} else {b}</nowiki>
 
-
 
-
</pre>
 
-
 
-
This behavior is most useful when used with the when-catch construct described in the chapter on Distributed Computing.
 
-
 
-
The ''break'' statement, when used in a for or a while loop, can be followed by an expression, in which case the loop returns the value of that expression.
 
-
 
-
(Note: the following patch of code is used by updoc.e, the <span class="e">''E''</span> testing tool, to enable execution of all the upcoming code that depends on Swing)
 
-
 
-
<pre>
 
-
 
-
?? in new vat awtVat.e-awt
 
-
? pragma.syntax("0.9")
 
-
 
-
</pre>
 
===Objects and Functions===
===Objects and Functions===

Revision as of 10:13, 29 November 2006


Contents

Ordinary Programming

In case you skipped the introduction, this is a last reminder that the fireworks start with Distributed Computing, and you can go there now, or continue to read about normal, ordinary computing in E, starting with Hello World.

But first, we need to declare what version of E we're using here.

 ? pragma.syntax("0.9")

Hello World

We will show Hello World as both an E program and a rune script. Rune first: just type

 ? println("Hello World")

when you hit the Enter key, you will get


 Hello World
 
 ?

To run an E program, put "println("Hello World")" into a text file. Make sure the file extension is ".e" (to run Swing-based apps, use extension ".e-awt", and to use SWT-based apps, use ".e-swt"). Type


 java -jar e.jar --rune textfilename.e

into a command shell (a DOS window under Windows, or a Cygwin or Unix shell, such as bash). The greeting will be printed to your display.

Now that you have started rune and run Hello World, it would be a good time to look at your trace log folder for the first time to make sure you know where to look. If you are on Windows 95, the trace log will default to <Windows directory>\temp\etrace. The etrace folder location can always be found in the eprops.txt file in the E installation directory (under Unix, you will have created eprops.txt yourself from eprops-template.txt). You should, after launching rune, find one file in the trace folder, which is the trace log created for the rune session. It will probably be empty, unless you have gone wild experimenting with Hello World.

Simple data types, simple control flow

Here are some of the basics of the language:


 # E sample
 # Comment on this piece of code
 
 def a := 3
 var b := a + 2
 b += 1
 if (a < b) {
     println("a is less than b")
 } else {
     println("Wow, the arithmetic logic unit in this processor is confused")
 }

Variable declarations in E are made with the var statement. Variables that are only assigned a value once at creation (i.e., constants, or variables declared final) are created with the def statement. In E as in Java, "+=" is shorthand for adding the righthand value to the lefthand variable.

Single-line comments have a "#" at the beginning, and terminate with the end of line. The /**...*/ comment style is used only for writing javadoc-style E comments, discussed later. link here

Assignment uses the ":=" operator. The single equal sign "=" is never legal in E, use ":=" for assignment and "==" for testing equality. The function "println" prints to the console. The "if" statement looks identical to its Java equivalent, but the braces are required.

What is the end-of-statement delineator in E? In Java, you terminate a statement with a semi-colon. In E, the end-of-line is also the end-of-statement unless there is an open operation at the end of the line. In the example, the "if" statement's first line ends with an open brace; E knows the next line must be a continuation line. Some quick examples


 This works
 ? def a := 1 + 2 + 3 + 4
 # value: 10
 
 
 And this works
 ? def b := 1 + 2 +
 >   3 + 4
 # value: 10
 
 
 But this does not work, because the first line can and does 
 evaluate without a continuation, so the second line is a syntax error:
 ? def c := 1 + 2
 ?   + 3 + 4
 # example syntax error:
 #   + 3 + 4
 #   ^

The end-of-line statement termination of E makes it easy to use E for command lines, as in rune.

If your organization uses a line continuation convention that puts the operator at the beginning of the second line, you can use the explicit continuation character "\" as here:


 This also works
 ? def c := 1 + 2 \
 >   + 3 + 4
 # value: 10

Basic Types and Operators

The basic types in E are int, float, string, char, and boolean. All integer arithmetic is unlimited precision, as if all integers were BigIntegers.

Floats are represented as 64-bit IEEE floating point numbers. The operators +, -, * have their traditional meanings for integers and floats. The normal division operator "/" always gives you a floating point result. The floor divide operator "//" always gives you an integer, truncated towards negative infinity. So (-3.5 // 1) == -4.

E has 2 modulo operations: "%", like the Java modulo operator, returns the remainder of division that truncates towards zero. E also supplies "%%", which returns a remainder of division that truncates towards negative infinity.

Operator precedence is generally the same as in Java. In a few cases E will throw a syntax error and require the use of parentheses.

E's quasi-literals enable the easy processing of complex strings as described in detail later; here is a very simple example:


 # E sample
 def printString := `Value of x is: $x`

wherein the back-ticks denote a quasi-literal, and the dollar sign denotes a variable whose value is to be embedded in the string.

"+" when used with strings is a concatenation operator as in Java. It automatically coerces other types on the right-hand if the left-hand operand is a string, but prints a warning as it does so.

&& and || and ! have their traditional meanings for booleans; true and false are boolean constants.

Strings are enclosed in double quotes. Characters are enclosed in single quotes, and the backslash acts as an escape character as in Java: '\n' is the newline character, and '\\' is the backslash character. Strings in E are so similar to strings in Java, it is easy to conclude they are identical when they are not. The protocol for E strings is detailed in the E javadoc.

== and != are the boolean tests for equality and inequality respectively. When the equality test is used between appropriately designated link to selfless here transparent immutables, such as integers, the values are compared to see if the values are equal; for other objects the references are compared to see if both the left and right sides of the operator refer to the same object. Chars, booleans, integers, and floating point numbers are all compared by value, as in Java. In addition, Strings, ConstLists, and ConstMaps link here are also compared by value, which makes it different from, and more natural than, Java.

Other transparent immutables (notably ConstLists and ConstMaps) will be introduced later. Additional useful features of transparent immutables are discussed under Distributed Computing.

There are some special rules about the behavior of the basic operators because of E's distributed security. These rules are described in the Under the Covers section later in this chapter.

Additional flow of control

We have already seen the if/then/else structure. Other traditional structures include:

  • while (booleanExpression) {...}
  • try{...} catch errorVariable {...} finally{...}
  • throw (ExceptionExpressionThatCanBeAString)
  • break (which jumps out of a while or for loop; if the break keyword is followed by an expression, that expression is returned as the value of the loop)
  • continue (which jumps to the end of a while or for, and starts the next cycle)
  • switch (expression) {match==v1{...} match==v2{...} ... match _{defaultAction}}

One structure that is more powerful than its Java counterpart is the for loop.


 # E sample
 for i in 1..3 {
    println(i)
 }
 for j in ["a", 1, true] {println(j)}
 

In this simple example, i becomes 1, 2, 3 in succession. In the second, j becomes each of the elements of the list.

The for loop operates not only with number ranges, but also with lists, maps (i.e. hashtables), text files, directories, and other structures discussed later in this book. The expanded version of the for loop that is needed to get both keys and values out of maps is:


 # E syntax
 for key => value in theMap {
     println(`Key: $key Value: $value`)
 }
 # You can get the index and the value from a list at the same time the same way
 for i => each in ["a", "b"] {
     println(`Index: $i Value: $each`)
 }
 

You can create your own data structures over which the for loop can iterate. An example of such a structure, and a brief explanation of the iterate(function) method you need to implement, can be found in the Library Packages: emakers section later in this chapter, where we build a simple queue object.

The Secret Lives of Flow Control Structures

Flow control structures actually return values. For example, the if-else returns the last value in the executed clause:


 # E sample
 def a := 3
 def b := 4
 def max := if (a > b) {a} else {b}

This behavior is most useful when used with the when-catch construct described in the chapter on Distributed Computing.

The break statement, when used in a for or a while loop, can be followed by an expression, in which case the loop returns the value of that expression.

(Note: the following patch of code is used by updoc.e, the E testing tool, to enable execution of all the upcoming code that depends on Swing)


 ?? in new vat awtVat.e-awt
 ? pragma.syntax("0.9")


Objects and Functions

As noted earlier, if the file is to use the Swing gui toolkit, it must have a suffix of ".e-awt". If the file is to use the SWT gui toolkit, it must have a suffix of ".e-swt". If the file will run headless, it should be placed in a file with suffix ".e".

Functions

A basic function looks like this:


 # E sample
 def addNumbers(a,b) {
     return a + b
 }
 # Now use the function
 def answer := addNumbers(3,4)

You can nest the definitions of functions and objects inside other functions and objects, giving you functionality comparable to that of inner classes in Java. Nested functions and objects play a crucial role in E, notably in the construction of objects as described shortly.

A parameterless function must still have an open/close paren pair. Calls to parameterless functions must also include the parens.

Functions can of course call themselves recursively, as in


 # E sample
 def factorial(n) {
     if (n == 0) {
         return 1
     } else {
         return n * factorial(n-1)
     }
 }    
 

Dynamic "type checking" and Guards

E guards perform many of the functions usually thought of as type checking, though they are so flexible, they also work as concise assertions. Guards can be placed on variables, parameters, and return values.

Guards are not checked during compilation. They are checked during execution, and will throw exceptions if the value cannot be coerced to pass the guard. Guards play a key role in protecting the security properties when working with untrusted code, as discussed in Secure Distributed Computing.

The available guards include the items below. Some of them are typical types (String, int). Others are used most often in distributed programming, and are explained later in the book. A detailed explanation of all the things you can do with guards is postponed to the Aditional Features chapter.

  • int
  • char
  • float64
  • boolean
  • String
  • void
  • notNull
  • nullOk
  • near
  • vow
  • rcvr
  • pbc
  • Data
  • Java classes
  • E interfaces
  • subranges and more complex expressions
import weakpointermaker
makevat 2 args 1)kind of vat, string"headless, awt, swt",
2)name of vat for debugging
import seedvatauthor
authorize it to get a seedvat function with uri getter
seedvat takes 2 args: 1)vat
2)string that is contents of a dot-e file except
all evaluated at once. seedvat function returns a promise for
the result of evaluating that expression. since it evaluates in foreighn vat,
it is a far reference.typical pattern: only do importing and construction 
in the expression string

Here are some quick examples of guards being declared:


 # E sample
 # guarding a variable
 def title :String := "abc"
 # guarding a parameter, and a return value. Note the guard on the 
 # return value is part of the def line for the function.
 def reciprocal(x :float64) :float64 {
     return 1 / x
 }
 

Different people use different strategies about how much type checking/guard information to include in their programs. In this book, the general style is to use guards sparingly, as might be typical in a rapid prototyping environment. One place where guards must be used with rigor is in the objects on the boundaries between trust realms, in security aware applications; see the Powerbox pattern in the Secure Distributed Programming section for an important example.

Objects

Objects, and object constructors, look considerably different in E than in Java or C++. We will start our exploration of objects with a simple singleton object.

A Singleton Object

Objects, functions, and variables are defined with the keyword "def"; all of these can be passed as arguments in parameter lists. Methods on an object, in contrast, are defined with the keyword "to":


 # E sample
 def origin {
     to getX() {return 0}
     to getY() {return 0}
 }
 # Now invoke the methods
 def myY := origin.getY()
 

Like functions, methods require a parenthesis pair even if there are no arguments. (But, Python programmers beware, methods are not functions. Methods are just the public hooks to the object that receive messages; functions are standalone objects).

When invoking the method, the object name and the method called are separated by a dot.

Stateful objects and object constructors

The "class" concept in Java is used to achieve multiple goals. In E, these goals are factored out in a different way. For example, Java classes supply a place to put constructors, which have a special syntax unique to constructors. In E, objects are constructed by ordinary functions.


 # E sample
 # Point constructor
 def makePoint(x,y) {
     def point {
         to getX() {return x}
         to getY() {return y}
         to makeOffsetPoint(offsetX, offsetY)  {
             return makePoint(x + offsetX, y + offsetY)
         }
         to makeOffsetPoint(offset) {
             return makePoint(x + offset, y + offset)
         }
     } 
     return point
 }
 # Create a point
 def origin := makePoint(0,0)
 # get the y value of the origin
 def y := origin.getY()

Inside the function makePoint, we define a point and return it. As demonstrated by the makeOffsetPoint method, the function (makePoint) can be referenced from within its own body. Also note that you can overload method names (two versions of makeOffsetPoint) as long as they can be distinguished by the number of parameters they take.

The (x, y) passed into the function are not ephemeral parameters that go out of existence when the function exits. Rather, they are true variables (implicitly declared with "def" ), and they persist as long as any of the objects that use them persist. Since the point uses these variables, x and y will exist as long as the point exists. This saves us the often tedious business in Java of copying the arguments from the parameter list into instance variables: x and y already are instance variables.

We refer to an object-making function such as makePoint as a "Maker". Let us look at a more serious example, with additional instance variables:


 # E sample
 def makeCar(var name) {
     var x := 0
     var y := 0
     def car {
         to moveTo(newX,newY) {
             x := newX
             y := newY
         }
         to getX() {return x}
         to getY() {return y}
         to setName(newName) {name := newName}
         to getName() {return name}
     } 
     return car
 }
 # Now use the makeCar function to make a car, which we will move and print
 def sportsCar := makeCar("Ferrari")
 sportsCar.moveTo(10,20)
 println(`The car ${sportsCar.getName()} is at X location ${sportsCar.getX()}`)
 

Inside the Maker, we create the instance variables for the object being made (x and y in this example), then we create the object (car). Note that the variable "name", passed into the function, is explicitly declared with "var", so that it can be altered later; in this case, it is reassigned in the setName() method.

Self-referencing objects

Sometimes in the body of an object you wish to refer to the object itself. A keyword like "this" is not required. The name given to the object is in scope in the body of the object, so just use it:


 # E sample
 def makeCar(name) {
     var x := 0
     var y := 0
     def <span class="hilite">car</span> {
         to moveDistance(newX,newY) {<span class="hilite">car</span>.moveTo(x + newX, y + newY)}
         # ....define other methods including moveTo as above ....
     }
     return car
 }

What if you need to reference the object during the object's construction, i.e., during the creation of the instance variables that precedes the definition of the object itself? In the below example, we give the car a weatherReportRadio that is supposed to alert the car to changing weather conditions. This radio requires, as a parameter during its construction, the car it will be alerting. So the radio needs the car during radio construction, and the car needs the radio during car construction.


 # E sample
 def makeRadio(car) {
     # define radios
 }
 def makeCar(name) { 
     var x := 0 
     var y := 0
     # using def with no assignment
     def car
     def myWeatherRadio := makeRadio(car)
     bind car {
         to receiveWeatherAlert(myWeatherRadio) {
             # ....process the weather report....
         } 
         to getX() {return x} 
         to getY() {return y}
         # ....list the rest of the car methods....
     }
     return car
 }

Here, we do a "def" of the car with no assignment, then we use the car, then we do a "bind" of the car which binds a value to the car. This looks and behaves like a "forward reference" from C. Under the covers, the statement "def car" creates a promise for the car, and the bind statement fulfills the promise. We discuss promises in greater depth in the Distributed Computing chapter, where they play a key role.

Secret Life of Functions, Multiple Constructors and "Static Methods"

Before we can talk about multiple constructors and the static-method-like behavior in E, it is time to reveal the truth about E functions. They are in fact simple objects with a single method, the "run" method, that is invoked by default if no other method is explicitly designated. For example, the following square function


 # E sample
 def square(x) {return x*x}

is really syntactic shorthand for


 # E sample
 def square {
     to run(x) {return x*x}
 }

In the second one, the run() method is explicitly defined. Using this explicit form in a Maker function, you can define multiple constructors, discriminated by the number of parameters they receive. Similarly, by adding methods to the Maker other than "run" methods, you get other "static methods". In the example below, we have a queue Maker with 2 constructors and a non-constructor method. The one-argument constructor requires an initial capacity; the no-argument constructor supplies an initial capacity of 10.


 # E sample
 def makeQueue {
    to run(initialCapacity) {
        # ....create a queue object with the specified initial capacity....
    }
    to run() {return makeQueue(makeQueue.getDEFAULT_CAPACITY())}
    to getDEFAULT_CAPACITY() {return 10}
 }
 # Now use both constructors
 def queue1 := makeQueue(100)
 def queue2 := makeQueue()
 println(`default capacity is: ${makeQueue.getDEFAULT_CAPACITY()}`)

Note also that one can use methods such as getDEFAULT_CAPACITY() to achieve the same effect as Java achieves with public static final variables.

Polymorphism

E enables polymorphism through method name matching. In this example, we move both a car and an airplane to a new location using a single common piece of code:


 # E sample
 def makeCar(name) {
     def car {
         to moveTo(x, y) {
              # move the car
         }
         # other methods
     }
     return car
 }
 def makeJet(name) {
     def jet { 
         to moveTo(x, y) { 
             # move the jet, very different code from the code for car 
         } 
         # other methods 
    } 
    return jet
 }
 def vehicles := [makeCar("car"), makeJet("jet")]
 for each in vehicles {
     each.moveTo(3,4)
 }       

Extends and Delegation

An object can refer calls to itself to another object (a "super-object", built by the "super-constructor", faintly similar to the way one uses superclasses in Java) using the extends keyword: think of better example


 ? def makePoint(x, y) { 
 >     def point { 
 >         to getX() {return x} 
 >         to getY() {return y}
 >         to getMagnitude() {return (x*x + y*y)**0.5} 
 >     }
 >     return point
 > } 
 # value: <makePoint>  
  
 ? def makePoint3D(x,y,z) { 
 >     def point3D extends makePoint(x,y) { 
 >         to getZ() {return z} 
 >         to getMagnitude() {
 >             def xy := super.getMagnitude()
 >             return (z*z + xy*xy)**0.5
 >         } 
 >     }
 >     return point3D 
 > } 
 # value: <makePoint3D>
 
 ? def place := makePoint3D(1,2,3)
 # value: <point3D>
 
 ? def x := place.getX()
 # value: 1
 
 ? def z := place.getZ()
 # value: 3

Here makePoint3D acts as an extension of makePoint. Inside the extends clause, we run the makePoint constructor to create the Point upon which the Point3D will be built. This specially constructed point is referred to in the point3D definition as "super"; you can see super being used in the getMagnitude method.

Using extends as described above follows the delegation pattern. Delegation is a simple pattern of object composition in which an object says, "if another object calls me with a method that I don't have defined here, just route the message to this other object, and send the result back to the caller." Delegation is similar to inheritance, but it is conceptually simpler.

Extends and Full Inheritance

Some experts consider inheritance to be a dangerous feature. A discussion of the pros and cons of inheritance is beyond the scope of this book. However, none of the full-blown examples in this book actually use full inheritance. Delegation, via the simple extends keyword plus polymorphism serve most of the purposes for which inheritance was intended, and is used everywhere here.

Having said that, there are times and places where full inheritance is the right answer. The extends keyword is also used, with one additional convention, to support such full inheritance. In inheritance, the "self" to which a super-object refers is the sub-object of which it is a part, so that the super-object can use methods in the sub-object:


 # E sample 
 def makeVehicle(self) {
     def vehicle {
         to milesTillEmpty() {
             return self.milesPerGallon() * self.getFuelRemaining()
         }
     }
     return vehicle
 }
 
 def makeCar() {
     var fuelRemaining := 20
     def car extends makeVehicle(car) {
         to milesPerGallon() {return 19}
         to getFuelRemaining() {return fuelRemaining}
     }
     return car
 }
 
 def makeJet() {
     var fuelRemaining := 2000
     def jet extends makeVehicle(jet) {
         to milesPerGallon() {return 2}
         to getFuelRemaining() {return fuelRemaining}
     }
     return jet
 }
 
 def car := makeCar()
 println(`The car can go ${car.milesTillEmpty()} miles.`)
     

As seen in the example, the super-object constructor specifies a parameter, "self", which can be used to refer to the sub-object. The sub-object includes itself in the the call to the super-object constructor, thus becoming "self".

General method name matching and E.call()

Delegation with extends does a straight pass-through of the method call. It is possible to intercept collections of calls before delegating them, using match. In this example, we count the number of calls made to a car:


 # E sample
 def makeCalledCountCar(name) {
     def myCar := makeCar(name) 
     var myCallCount := 0
     def car {
         to getCallCount() {return myCallCount}
         match [verb,args] {
             myCallCount += 1
             E.call(myCar,verb,args)
         }
     }
     return car
 }           

In "match[verb,args]", the verb is a string specifying the name of the method being called, and the args is a list of arguments. If the car is called with a method that is not defined in a "to" statement, the name of the method and the arguments are bound to the variables inside the square brackets. We then increment the call count, and finally forward the message using the E.call function. E.call(...) takes as arguments the target object for the action, the name of the method to call, and the list of arguments for the method to invoke. You can manually use E.call() like this:


 # E syntax
 def car := makeCar("mercedes")
 E.call(car, "moveTo", [3,4])
 # which is equivalent to
 car.moveTo(3,4)

In this example, the elements for the argument list are placed in square brackets to form an E ConstList, described later in this chapter.

The match construct is useful for making "adapters" when interfacing to Java. Here we build a singleton object that can be used anywhere a java.awt.event.MouseListener would be used; the match clause is used to absorb and discard events in which we are not interested:


 # E sample
 def mouseListener {
     to mouseClicked(event) {
         # process the event
     }
     match [verb,args] {}
 }

This general purpose matching is also useful in security applications when building facets and revocable capabilities, as described in the chapter on Secure Distributed Computing.

Edoc, the E equivalent of JavaDoc

E supports the construction of javadoc-style comments that can be postprocessed into HTML documentation. For this purpose, the "/** ... */" comment format has been specially reserved; comments of this style can only appear in front of a function/object definition (a "def" statement), or in front of an object method definition (a "to" statement):


 # E sample
 /**
  * Add 2 numbers together.
  * <p>
  * Currently works with any objects that support the "plus" method
  *
  * @param a the first number. 
  * @param b the second number
  * @return  the result of adding. 
  */
 def adder(a, b) {return a + b}

For more information on how to generate Edoc HTML from your E programs, see the Additional Features.

Under the covers: Everything is an Object

We have already discussed the fact that functions are really objects with a single method, "run". Functions-as-objects have one practical consequence that would be surprising in the absence of understanding. You cannot create two functions with different numbers of parameters and have them overloaded:


 # E syntax
 def times2(a) {return a * 2}
 def compute(a,b) {
     def times2(c,d) {return (c + d) * 2}
     # ....do computation...
     # The following line will throw an exception
     def answer := times2(a)
     return answer
 }

This would throw an exception because the inner definition of the function-like object times2 completely shadows the outer times2.

Not only functions, but also built-in constants like integers and floats, are objects. Operators such as "+" are really shorthands for message passing: 3.add(4) is identical to 3 + 4. This is why the operation


 <font color="#FF0000">"The number is " + 1</font>

works but


 <font color="#FF0000">1 + " is the number" </font>

does not. A string knows how to handle a concatenate message with a number as the argument, but an integer is clueless what to do with an add of a string.

Since "+" is really just shorthand for "add", you can construct objects that work with the "+" operator just by implementing an "add(argument)" method in the object.

Under the covers: Miranda Methods

There are a number of messages to which all normal objects respond, known as Miranda Methods. One example of such a method is the printOn(textWriter) method, which defines how an object will write itself out as by default. Other Miranda methods will be described in other sections of the book. The full list of Miranda methods can be found in the Appendix. You can also see them in rune by typing help(def obj{}) duplicate of next section, fix

One important note about Miranda methods: they are not forwarded by the extends structure, and they are not intercepted by the match[verb,args] structure. They are always directly interpreted by the object that receives them.

Getting Help About an Object With Rune

Another often convenient way of finding the list of methods associated with an object, be it a Java object or an E object or an object delivered as part of the E runtime, is to use the help(object) function of E, often used in rune.


 ? def add(a, b) {
 >     return a + b
 > }
 # value: <add>
 
 ? help(add)
 # value: an org.erights.e.elang.evm.EImplByProxy
 #        interface "__main$add" {
 #
 #            to run(:any, :any) :any
 #        }
 #
 ?

In this very simple example you see the "run" method listed here, which is the implicit method for a function. The rest of the methods shown are Miranda methods. For a more sophisticated object than a simple add function, each method in the object would be listed as well.

I/O

E file objects are created with the <file:name> expression (which produces a "tamed" Java File Object, i.e., a File object that follows capability security discipline). If you can hard-code the name, you usually do not need to use quotes (unless there is a space or another invalid url character). If the name is contained in a variable or is retrieved with a function call, you must XXX place a space between the colon and the representation of the name. If the word "file" is replaced with a single letter like "c", the letter is assumed to be the drive letter on a Windows machine:


 # E sample
 #File objects for hardwired files:
 def file1 := <file:myFile.txt>
 def file2 := <file:/home/marcs/myFile.txt>
 
 #Using a variable for a file name:
 def filePath := "c:\\docs\\myFile.txt"
 def file3 := <file>[filePath]
 
 #Using a single character to specify a Windows drive
 def file4 := <c:/docs/myFile.txt>
 def file5 := <c:\docs\myFile.txt>

Note that in the file4 example, we used slashes, not backslashes, to separate directories on a Windows drive. In E, the slash always works as a directory separator no matter the underlying operating system.

When constructing the filePath string we used double backslashes because in strings the backslash must be escaped by a backslash. A double backslash was not required in the hardwired file (file5).

File objects can represent directories as well as simple files. Files inside the directory can be accessed by indexing using square brackets:


 # E syntax
 def dir := <file:/home/marcs/dataDir/>
 def file6 := dir["myFile.txt"]

Both text files and directories work in conjunction with the "for" loop. With a directory, the loop iterates through the files in the directory. With a text file, the loop iterates through the lines of the file; each line-object is terminated with a newline ('\n') character. The lines in the loop are terminated with newline regardless of the underlying operating system, regardless of the operating system's end-of-line designation.

Files respond to the following messages (see the Edoc for a complete list).

  • exists -- returns true if the file exists
  • deepReadOnly -- returns a file object that can be read, but not written. If the file is a directory, the readOnly nature is transitive to all files and directories reached via this object.
  • setText(textString) -- creates the file and/or replaces the file contents with the text. When written out, the end-of-line designator is automatically converted to the local end-of-line mark for the underlying operating system. On Windows, for example, each line is automatically terminated by a cr/lf pair.
  • getText -- returns the text from the file. Regardless of underlying operating system, the returned text uses a single newline character as the end-of-line mark.
  • getBytes() -- returns the bytes of the file in a byte ConstList
  • setBytes(byteList)

stdout and stderr are both TextWriters in the E environment.

Example: looping through a directory tree searching for a file that contains a particular line

write the example

Data Structures

In the next section, we will learn how to interface to Java, which will allow you to use most of the data structures supplied by the underlying jvm. E does offer a few data structures of its own, however, which are not only convenient, but which have special properties useful in distributed programming.

Flex and Const, List, Map and Set

There are three built-in data structures in E, Lists, Maps, and Sets. Each of these structures comes in two flavors, Flex (editable) and Const (immutable). The ConstList is the simplest:


 # E sample
 def list := ["a",2,true]
 #This is true: list[0] == "a"
 #This is true: list[2] == true
 def newList := list + ["last"]
 #This is true: newList[3] == "last"
 for each in newList {println(`Element: $each`)}
 for i => each in newList {println(`Element number $i is $each`)}
 def listSize := newList.size()
 # get subrange starting at 0, running up to element 2, but not including element 2
 def subrange := list(0,2)
 #This is true: subrange == ["a",2]

Lists are numerically indexed starting from 0, use the "+" operator to create a new list which is the concatenation of lists. Lists work with the for loop. The "size" method returns the number of elements. The E String type is a kind of ConstList in which all the elements are characters. So, for example, the mechanism for taking a subrange shown above gives you a substring if the ConstList is a String.

You can make a FlexList from a ConstList with the diverge method:


 # E sample
 def newList := []
 def editable := newList.diverge()
 editable.push(100)
 if (editable.pop() == 100) {
     println("Yeah, push and pop make a list work like a stack")
 }
 editable[0] := "b"
 def frozen := editable.snapshot() 

All the methods that work on a ConstList also work on a FlexList. In addition, there are editing operations for FlexLists, including push/pop (which allows the FlexList to behave like a stack) and element replacement that uses Java array-style syntax. You can get a ConstList from a FlexList with the snapshot method. Just as Java Strings are like ConstLists in which all elements are characters, Java StringBuffers are like FlexLists in which all elements are characters.

Maps are composed of key/value pairs. In the following example, in the ConstMap table, "a" is a key, and 1 is a value:


 # E sample
 def table := ["a" => 1, 2 => "b"]
 # This is true: table["a"] == 1
 # This is true: table[2] == "b"
 def emptyTable := [].asMap()
 def keyTable := ["a",1,true].asKeys()
 # This is true: keyTable[true] == null 
 # This is true: keyTable.maps("a") == true
 for key => value in table {println(`Key: $key Value: $value`)}
 for each in table {println(`Value: $each`)}
 def mapSize := table.size()

Elements in a map are retrieved using an array-like syntax, using the key as the index in the square brackets. Maps can be made from lists using asMap and asKeys; when you use asKeys, the values are nulls. The for loop works nicely with the map structures.

FlexMaps can be made from ConstMaps with the diverge method:


 # E sample
 def editableMap := table.diverge()
 editableMap["c"] := 3
 editableMap["a"] := "replacement"
 editableMap.removeKey(2)
 def frozenMap := editableMap.snapshot() 

Values in a FlexMap can be added and replaced with array-like syntax. Key-value pairs can be removed with removeKey(key). The snapshot method creates a ConstMap from a FlexMap.

Sets are quite similar, with ["a","b"].asSet() producing a ConstSet with 2 elements. Documentation for all the operations on Const and Flex lists, maps, and sets can be reached directly from the Javadoc For E index.

A String is actually a ConstList of characters. You can create a FlexList of elements of a specific type by specifying the type in the diverge/snapshot method:


 # E sample
 def aString := [].diverge(char)

This aString will not accept elements which are not of type char; the variable aString has many of the characteristics of a StringBuffer from Java.

One feature of E that Java/C programmers will find surprising but useful is the ability to define multiple variables by using a list:


 # E sample
 def [a,b] := [2,3] 
 #a holds the value 2
 #b holds the value 3

While this is an amusing way to initialize a random bunch of variables at once, the structure is most valuable when creating groups of variables that have no meaning in the absence of one another. The method Ref.promise(), described in Distributed Computing, is an important user of this pattern.

Equality Testing for Structures

One of the biggest differences between Flex and Const structures is the test for equality. Const structures are compared by value, and as such are considered equal if their contents are identical. The test for equality is, in other words, the same as the test for equality between Java integers.

Two Flex structures are considered equal if and only if they are the same structure, i.e., both of the variables being tested are references to a single object. This test for equality is, in other words, the same as the test for equality between Java StringBuffers.

Interfacing to Java

Importing classes from the Java API

We can import a class from the underlying Java virtual machine with the import statement, and speak to the Java object much as we would speak to an E object: replace vector as example


 # E sample
 #create a single vector with a direct call to Java
 def myVector := <unsafe:java.util.makeVector>()
 myVector.addElement("abc")
 #create a makeVector function which can be called repeatedly to make more vectors
 def makeVector := <unsafe:java.util.makeVector>
 def vector2 := makeVector()
 # create a shorthand for the java.util package, that gives quick access to all the 
 # classes in java.util
 def <util> := <unsafe:java.util.*>
 def vector3 := <util:makeVector>()

In the example, we showed 3 ways of getting a Java object, which are roughly comparable to the different styles of using "import" in Java. If you just want one vector, you can get it by directly calling the vector constructor. If you plan to make many vectors, you can import the class into a variable. And if you plan to use many classes in a particular package, you can create your own representative for the package that you can use instead of "unsafe:". fixNote the suffix "__uriGetter" on the util variable. This is a special suffix that allows the variable to be used in statements of the form <uri:name>.

We have now seen 3 of these uriGetters, file:, unsafe:, and the programmer-defined util:. Four other uriGetters are also predefined, swing: (for accessing javax.swing) and awt: (for accessing java.awt), resource: (for read-only access to resource files such as images, sounds, and static texts), and import:, described next.

The import: uriGetter is similar to unsafe:, except it only imports those parts of the Java API that have been audited for capability security and found to convey no authority (see the Appendix for a definition of "authority").put in link, think of better example. Remove vector from the book Since the Vector class conveys no authority, you could also get a vector with import:


 def vector4 := <unsafe:java.util.makeVector>()

As discussed later with Library Packages and Secure Mobile Code, emakers cannot use unsafe: unless the unsafe__uriGetter is explicitly handed to them. So import: is often useful in these security-aware situations. A complete list of safe versus unsafe classes, and the small percentage of Java API methods which are suppressed for security reasons, are listed in the Appendix.link

resource: mention it is safe, can be used in emakers

getting static public constants from Java: must put parens after the name as if it was a method returning a value, not a variable.

As noted earlier, E does not have an expression to directly represent public static final variables. To use such static finals from a Java class, put parentheses at the end of the variable name, making it syntactically look like a function call, prefix it with "get", uppercase the first letter, and E will get the value for you:


 # E sample
 <unsafe:java.util.makeCalendar>.getYEAR()

Speaking to Java objects with superclass/subclass overloaded methods

Speaking to Java objects is usually as easy as shown above, where we simply sent myVector an addElement(object) message as if it were an E object. A problem arises with some Java objects if they have overloaded methods for which the only distinguishing mark is the static typing of the parameters in which one of the methods specifies a type that is a superclass of the type in the other method--a rare but not unheard-of situation. coercion causes same problemIn that case, we need to revert to a more descriptive messaging convention.

We introduced the E.call() function earlier for communicating with E objects. It can also be used to call Java objects and to specify the signature of an overloaded method with the types of the parameters. In this example, we see that the print function for the System.out object is overloaded for both String and Object, with String being a subclass of Object, so the full signature is required:


 ? def out := <unsafe:java.lang.makeSystem>.getOut()
 # value: <a PrintStream>
 
 ? out.print("abc")
 # example problem: <IllegalArgumentException: ...>
 
 ? E.call(out, "print(String)", ["abc"])
 ? def myLabel := E.call(<swing:makeJLabel>, "run(String)",["label text"])

If you encounter one of these special cases that requires multiple parameters, the signatures must be laid out with exact spelling and exact spacing, notably with exactly one space between the comma and the next signature:


 E.call(javaObject, "method(String, int)", ["abc", 23])

Arrays and primitive types

It is possible to make Java arrays of Java primitive types, as in this example:


 # E sample
 def makeFlexList := <elib:tables.makeFlexList>
 def byteArray := makeFlexList.fromType(<type:byte>, 300)
 byteArray.setSize(300)
 byteArray[0] := 3

Here we have created a 300-element editable array of bytes. The individual elements can be accessed with square bracket notation.

XXX Now that this example has been corrected, does it still serve its purpose? Also, it's not technically correct to say this makes a Java array. It makes an E FlexList, which, on E-on-Java, currently happens to be implemented by wrapping a Java array. However, if your program depends on this fact, it is probably broken.

Java Adapters and Interfaces

As described earlier, you can use the match[verb,args] construct to aid in writing adapters and other objects that must meet a Java interface specification. E will automatically manipulate the resulting E objects and the java virtual machine so that Java understands that the E object meets the interface specification. It is not possible to make subclasses of Java classes in E. However, because the developers of the Java API have wisely moved aggressively to make sure that interfaces, rather than subclasses, are core to Java object interoperability, there is virtually no Java interfacing goal that cannot be achieved with this machinery.

The Java API versus capability security

A final note: almost all of the objects and methods in the Java API are available in E for version 1.0 through the unsafe_uriGetter; unfortunately very few have been audited sufficiently to be included with the import__uriGetter. In the future, more of the API will be accessible through the import__uriGetter; however, some parts of the Java API will be altered and/or suppressed even in unsafe__uriGetter to achieve a more secure yet easier to use computing framework. This is discussed further in the chapter on Mobile Code. You can see the list of suppressed methods and unsafe classes in the Javadoc.

Quasi-Literals and Quasi-Parsers

E supports quasi-parsers. A quasi-parser allows one to compress large numbers of operations into a succinct notation (a quasi-literal) in a specific problem domain. Writing your own quasi-parsers (which can be done in E itself, as the JPanel quasiparser described below was written) is beyond the scope of this book. However, E comes with several quasi-parsers built in: a simple quasi-parser, a regular expression quasi-parser, a JPanel quasi-parser for Swing, and a swtGrid quasi-parser for SWT.

Simple quasi-parser

The default quasi-parser is a text manipulating parser capable of extracting data from strings and constructing new strings. In its simplest form, it is a clean and simple way of constructing strings for printing:


 # E sample
 def a := 3
 def answerString := `The value a is $a, and a times two is ${2 * a}.`
 println(answerString)

Here we use a simple quasi-parser to build an output string in a fashion similar to the printf statement in C. Quasi literals are enclosed in back-ticks. A dollar sign denotes the beginning of a description of a value to be inserted at the dollar sign location. If the dollar sign is immediately followed by a variable name, the value of that variable is used. If the dollar sign is followed by an open brace, everything up to the close brace is evaluated to compute the value to be substituted (so you could put "$" inside the braces to put a dollar sign in the string, as well as doing arithmetic as in the above example). Quasi-literals can span multiple lines, in which case the carriage return is part of the structure.

A more sophisticated use of simple quasi-literals is for pattern matching. Here we parse a sentence:


 # E sample
 def line := "By the rude bridge that arched the flood"
 if (line =~ `@word1 @{word2} rude @remainder`) {
     println(`text matches, word1 = $word1`)
 }

The string on the left of =~ is compared to the quasi literal on the right, evaluating true if the string can be parsed in conformance with the quasi literal. The "@" asserts that any text can match this part of the string, and the variable declared after the "@" contains that text at the end of the evaluation. The variable "word2" is enclosed in braces to offset it from the word "rude" immediately following it, which would look like part of the variable name without the offset.

In this example, the minimal string that can get a match would be space-space-"rude ", in which case the data extracted for variables word1, word2, and remainder would all be zero-length strings. As it is, at the end of the evaluation, word1=="By", word2=="the", and remainder == "bridge that arched the flood".

A single quasi-literal can contain dollar signs as well as "@"'s, in which case the results of the dollar sign evaluations will be included in the matching conditions.

Quasi-literals can almost always be treated as strings. They accept almost all of the string protocol (technically, the quasi-literals are of type "twine"). The one place where they cannot be treated as strings is in comparisons to actual strings. To compare a quasi-literal to a string, use the "bare" method: this is now wrong! all strings seem to now be twines

def equalStrings := "abc".bare() == `abc`.bare()

Regular expression quasi parser

The regular expression quasi-parser gives E much of the CGI scripting power that Perl and Python share. Since E runs on top of a jvm with all the startup time such jvms entail, using E for CGI scripts per se is not recommended. However, if one uses the distributed computing power of E to run CGI-like E programs as services for a Web server, one can achieve the same effect, and receive a number of bonuses unavailable in Perl and Python. The example Web server written in E, shown at the end of the book, was designed with just this thought in mind.

JPanel

The JPanel quasi-parser processes visually understandable strings into complex window panel layouts for gui applications. It is a most remarkable and useful example of quasi-parsers in action, giving the developer a rather WYSIWYG presentation of his windows. Thus the E programmer has no need to resort to the typical inflexible IDE-specific drawing tools that produce code no one can read and absolutely no one can edit. Under the covers, the JPanel uses the GridBagLayout manager to compose the panel, giving it a flexibility comparable to the TK layout system from TCL (which actually inspired the JPanel). Unlike the typical visual layout editors in Java IDEs, the JPanel system is able to define a broad range of resizable windows simply and intuitively.


 # E syntax
 # define the panels explanation,label, field, okButton, cancelButton, logo
 # pad1, pad2, which are label fields before 
 # this example begins
 def composedPanel := 
 JPanel`$explanation.Y     >              >
 $label                    $field         >
 $okButton                 $cancelButton  $pad1.X
 V                         $pad2          $logo`

In this layout, the explanation (presumably a textArea) is at the top of the composedPanel, with the label and field left-to-right underneath, and the okButton to the left of the cancelButton/logo area arranged top-to-bottom. This is a layout for a 3-wide, 4-high grid of cells, though some the panes fill multiple cells, and the rules for which cells grow are sophisticated, as described next:

The ".Y" says that the explanation should soak up any extra vertical space. The ".X" says the field should soak up any extra horizontal space. The two ">" symbols say that the explanation should span all three of the columns of this pane. The field fills two horizontal cells as denoted by the ">" which follows it. The "V" in the lower lefthand corner says that the okButton should fill two vertical cells.

When this pane is part of a resizable window, enlarging vertically makes the explanation larger. Enlarging the window horizontally enlarges the field but not the label. Both the cancel button and the okButton should remain the same size regardless of resizing since the extra space is being soaked up elsewhere.

If several elements have ".Y", the extra vertical space is divided evenly among them; similarly fields with ".X" share extra horizontal space.

The space characters used to separate the elements of this layout have no meaning to the quasi-parser; we have used the space to create a visual representation of the layout that makes it easy to see the layout even though this is just code.

It is not possible to lay out all possible compositions with a single JPanel, but JPanels can dramatically reduce the nesting of panels compared to Java applications, while making the layout visually clear in the code itself. And of course, you can always place JPanel-laid-out panels inside of other JPanel layouts. The result is tremendously more compact, easier to understand, and easier to maintain than the result of nesting large numbers of Swing Box layouts.

A similar quasi-parser, the swtGrid, is included for layout of SWT panels. The main difference, as shown in later example code, is that the swtGrid requires a first entry that is the parent panel for the laid out components improve this discussion

Library Packages: emakers

The E library package system is based on emakers. An emaker is an E source file named with ".emaker" as the suffix.

When an emaker is imported into an application, the code is executed at the time of import, and the result of that execution is returned to the importing program.


 # E sample
 def makeQueue() {
     var head := null
     var tail := null
     def makeCarrier(obj) :near {
         var next := null
         def carrier {
             to attach(nextCarrier) {next := nextCarrier}
             to get() {return obj}
             to next() {return next}
         }
     }
     def queue {
         to push(obj) {
             if (head == null) {
                 head := makeCarrier(obj)
                 tail := head
             } else {
                 tail.attach(makeCarrier(obj))
                 tail := tail.next()
             }
         }
         to pop() {
             def current := head
             head := head.next()
             return current.get()
         }
         to iterate(func) {
             var current := head
             var i := 0
             while (current != null) {
                 func(i, current.get())
                 current := current.next()
                 i += 1
             }
         }
     }
     return queue
 }

Side Note: ''This queue does have one interesting characteristic: the iterate method is the feature required to work correctly with E's for-loop. Iterate receives a function that expects 2 arguments: a key and an object. In this queue, the key value is filled with the index of the value in the queue. Iterate walks the entire data structure, invoking the function once for each element.

Place this queuemaker in a file named makeQueue.emaker, and put the file in the classpath, either with the -cp command line argument to Java, or by placing the file in a subdirectory under lib/ext in the java directory system. You can use Java-style package specifications: as in Java, you can put the file in a jar in lib/ext. In the below example, we place the file under lib/ext/emakers/com/yourdomain/e/queueMaker.emaker (in your jre directory), and import:


 # E syntax
 def makeQueue := <import:com.yourdomain.e.makeQueue>
 def queue := makeQueue()
 queue.push(1)
 queue.push(2)
 for each in queue {println(each)}

There are several ways of making E aware of the availability of an emaker, corresponding to the several ways Java can become aware of a class. You can place it in a zip or a jar and place it in the jvm's ext directory. Or you can place it in a subfolder in the jvm's ext directory. Or you can place it, or a jar that contains it, on the classpath when you start up the jvm.

Emakers have an important security property: they come to life contained in a world with no authority. Such a world is even more restrictive than the Java sandbox used for applets. However, this world is more flexible than the sandbox because authority can be granted and revoked during operation using capabilities, as described in the chapter on Secure Distributed Computing.

The makeQueue function example is a nice first example of emakers in action because makeQueue and the queues it makes need no authority. For emakers that require authority, by convention we use the Authorizer pattern. Here is an infoWindowMakerAuthor: the infoWindowMaker needs the authority to create windows, so we wrap it in an Authorizer:


 # E syntax
 #emaker in file lib/ext/com/skyhunter/infoWindowMakerAuthor.emaker
 def infoWindowMakerAuthor(frameMaker) {
     def infoWindowMaker(infoText) {
         def frame := frameMaker("Information")
         def label := <swing:makeJLabel>(infoText)
         frame.getContentPane().add(label)
         frame.pack()
         frame.show()
         return frame
     }
     return infoWindowMaker
 }
 #.....in using program....
 def makeInfoWindow := <import:com.skyhunter.infoWindowMakerAuthor> (<swing:makeJFrame>)
 def infoBox := makeInfoWindow("First Bit Of Info")
 def detailedInfoBox := makeInfoWindow("Second Bit Of Info")

By convention, authors follow the pattern of functions, using an implied run() method to return the Maker that is being wrapped.

The meticulous reader may have noticed that the JFrame was a capability that needed to be authorized, whereas the JLabel was not. The vast bulk of the Java API is non-capability-transferring, and can just be acquired using import:. Commonly-used exceptions are the JFrame, everything have to do with files in java.io, and the URL object in java.net. For a complete listing of suppressed methods (which are inaccessible in E though documented in Java), safe classes (which can be imported directly by emakers), and unsafe classes (which can only be imported using the unsafe__uriGetter, which is not directly available to emakers), see the JavaDoc for E.

obsolete:Emakers can also just be functions, in which case the naming convention uses "Func" to distinguish it from a Maker:


 # E syntax
 #emaker in file lib/ext/org/erights/computeSquareFunc.emaker
 def computeSquareFunc(number) {
     return number * number
 }
 
 #...in using program...
 def computeSquare := <import:org.erights.computeSquareFunc>
 def squareOfThree := computeSquare(3)

There are also functions that require capabilities before they can become operational, in which case they are by convention wrapped in Authorizers, for example, analyzeOutlineFuncAuthor.

The good news is that, because emakers come to life without authority, they can always be imported with import:, so any emaker can bring in any other emaker (though you won't be able to run the authorizer without sufficient authority). The bad news is that, if you are writing standalone E applications in which the emakers are fully trustworthy (or at least as trustworthy as the program that calls them), it can seem a substantial nuisance at first to be granting lists of authorities just to break your program into packages. If you are writing pure E applications that use emakers of your own construction, emakers which you trust totally with the full authority of the system, and you have no qualms about flouting the wisdom of architectural purists around the world, you can take a shortcut by simply granting the unsafe__uriGetter. For example:


 # E sample
 def powerfulObjectMakerAuthor(unsafe__uriGetter) {
     def file := <unsafe:java.io.File>("name")
     def swing__uriGetter := <unsafe:javax.swing.*>
     def frame := <swing:makeJFrame>("powerful object window title")
     def powerfulObjectMaker() {
         #....define the objectMaker and the object it makes...
     }
     return powerfulObjectMaker()
 }

Note that in this example, one of the things we created from our unsafe__uriGetter was our own swing__uriGetter. Emakers, when they come to life, do have a swing__uriGetter of their own; however, their built-in swing: accesses only the safe subset of swing, much as import: accesses only the safe subset of unsafe:. In the example we create our own swing: that overrides the default swing:, which enables us access unsafe classes such as the JFrame.

For even more information on the security properties of emakers, see the chapter on Secure Mobile Code.

Ordinary Computing Examples

Pretty E

Racetrack Game for a single computer

Below is a simple game of racetrack: 3 cars are set on the track, to race between walls around curves to the finish line. Each driver can choose to accelerate or decelerate his car by +/- 1 space/turn during each turn. Do not build up too much velocity, you won't be able to slow down!

The example has just about everything in it: JPanels, objects, functions, Java API calls, it's all there. We will come back to this example later in the book, to make the track distributed and secure. Then we shall invite Satan for a little competition, with souls on the line.


 # E sample
  
 #!/usr/bin/env rune
 
 # Copyright 2002 Combex, Inc. under the terms of the MIT X license
 # found at http://www.opensource.org/licenses/mit-license.html
 pragma.syntax("0.9")
 
 def traceln(text) { stderr.println(text) }
 
 def attachAction(component,target,verb) {
     def listener {
         to actionPerformed(event) {
             E.call(target, verb, [])
         }
     }
     component.addActionListener(listener)
 }
 
 def newButton(labelText, verb, target) {
     def button := <swing:makeJButton>(labelText)
     button.setBackground(<awt:makeSystemColor>.getControl())
     attachAction(button,target,verb)
     return button
 }
 
 def abs(number) {return if (number >= 0) {number} else {-number}}
 
 def makeCoord(x,y) {
     def coord {
         to getX() {return x}
         to getY() {return y}
         to printOn(writer) {writer.print(`coord: $x,$y`)}
         to samePlace(coord2) :boolean {
             return x == coord2.getX() &&  y == coord2.getY()
         }
 
         /**
          * The "add" method is the underlying function for the "+" operator.
          * Here, by writing an "add" method, we make coordinates work with "+"
          */
         to add(coord2) {return makeCoord(x + coord2.getX(),y + coord2.getY())}
 
         /**
          * The "subtract" method is the underlying function for the "-" operator
          */
         to subtract(coord2) {return makeCoord(x - coord2.getX(),y - coord2.getY())}
     }
     return coord
 }
 
 def makeInstrumentPanel(car) :near {
     def makeIndicator(speed,positiveText,negativeText):pbc {
         var answer := ""
         var direction := positiveText
         if (speed < 0) {direction := negativeText}
         for i in 1..abs(speed) {answer := answer + direction}
         if (speed == 0) {answer := "0"}
         return answer
     }
     def makeXIndicator(speed) {return makeIndicator(speed,">","<")} 
     def makeYIndicator(speed) {return makeIndicator(speed,"^\n","V\n")} 
     def frame := <swing:makeJFrame>(`Car ${car.getName()} Instrument Panel`)
     def lbl(text) {return <swing:makeJLabel>(text)} 
     def xLabel := lbl("Horizontal Speed:") 
     def xIndicator := <swing:makeJTextArea>() 
     xIndicator.setText("0") 
     def yLabel := <swing:makeJTextArea>("V \ne\nr\nt\ni\nc\na\nl") 
     yLabel.setBackground(<awt:makeSystemColor>.getControl()) 
     def yIndicator := <swing:makeJTextArea>() 
     yIndicator.setText("0") 
     def statusPane := lbl("Running...") 
     def instrumentPanel 
     def btn(name,action) {return newButton(name,action,instrumentPanel)} 
     def submitButton := btn("Submit","submit") 
     var acceleration := makeCoord(0,0) 
     def realPane :=JPanel`
         ${lbl("")}  $xLabel     >                      >                  > 
         V           $xIndicator >                      >                  > 
         $yLabel.Y   $yIndicator ${btn("\\","upLeft")}  ${btn("^","up")}   ${btn("/","upRight")} 
         V           V           ${btn("<","left")}     ${btn("0","zero")} ${btn(">","right")}
         V           V           ${btn("/","downLeft")} ${btn("V","down")} ${btn("\\","downRight")}
         V           V           $submitButton.X        >                  >
         $statusPane >           >                      >                  >`
     frame.setDefaultCloseOperation(<swing:makeWindowConstants>.getDO_NOTHING_ON_CLOSE())
     frame.getContentPane().add(realPane)
     frame.pack()
     frame.show()
     bind instrumentPanel {
         to submit() {
             submitButton.setEnabled(false)
             car.accelerate(acceleration)
         }
         to prepareForNextTurn() {
             xIndicator.setText(makeXIndicator(car.getVelocity().getX()))
             yIndicator.setText(makeYIndicator(-(car.getVelocity().getY())))
             acceleration := makeCoord(0,0)
             submitButton.setEnabled(true)
             # Note, public static transferFocus on awt Component is not Java API, added in E environment
             <awt:makeComponent>.transferFocus([frame.getContentPane()], statusPane)
         }
         to setStatus(status) {statusPane.setText(status)}
         to upLeft() {acceleration := makeCoord(-1,-1)}
         to up() {acceleration := makeCoord(0,-1)}
         to upRight() {acceleration := makeCoord(1,-1)}
         to left() {acceleration := makeCoord(-1,0)}
         to zero() {acceleration := makeCoord(0,0)}
         to right() {acceleration := makeCoord(1,0)}
         to downLeft() {acceleration := makeCoord(-1,1)}
         to down() {acceleration := makeCoord(0,1)}
         to downRight() {acceleration := makeCoord(1,1)}
     }
 }
 
 def makeCar(name,startLocation,raceMap)  {
     var location := startLocation
     var acceleration := makeCoord(0,0)
     var velocity := makeCoord(0,0)
     var hasCrashed := false
     var hasFinished := false
     def instrumentPanel
     def sign(x) {
         return if (x > 0) {
             1
         } else if (x < 0) {
             -1
         } else {0}
     }
     
     def accelReactors := [].asMap().diverge()
 
     /**
      * Compute the path the car will take from the location at the
      * beginning of this turn to the end; return the result
      * as a list of coords
      */
     def computeIntermediateLocations(start,finish)  {
         def locations := [].diverge()
         def slope := (finish.getY() - start.getY()) / (finish.getX() - start.getX())
         def computeRemainingLocations(current) {
             var nextX := current.getX()
             var nextY := current.getY()
             var distToGo := 0
             #if the car is traveling faster in the x direction than
             #in the y direction, increment x position by one along
             #the path and compute the new y
             if (slope < 1.0 && slope > -1.0) {
                 distToGo := finish.getX() - current.getX()
                 nextX += sign(distToGo)
                 def distTraveled := nextX - start.getX()
                 nextY := start.getY() + ((slope * distTraveled) + 0.5) //1
                 #if the car is traveling faster in the y direction than
                 #in the x direction, increment y position by one along
                 #the path and compute new x
             } else {
                 distToGo := finish.getY() - current.getY()
                 nextY += sign(distToGo)
                 def distTraveled := nextY - start.getY()
                 nextX := start.getX() + ((distTraveled/slope) + 0.5) //1
             }
             def next := makeCoord(nextX,nextY)
             locations.push(next)
             if (!(next.samePlace(finish))) {
                 computeRemainingLocations(next)
             }
         }
         computeRemainingLocations(start)
         return locations
     }
     def car {
         to accelerate(accel) {
             traceln(`accelerating car $name`)
             acceleration := accel
             for each in accelReactors {
                 each.reactToAccel(car)
             }
         }
         to move(){
             traceln("into move")
             velocity += acceleration
             def newLocation := location + velocity
             traceln("got newlocation")
             def path := computeIntermediateLocations(location,newLocation)
             location := newLocation
             traceln("assigned  location")
             hasCrashed := hasCrashed || raceMap.causesCrash(path)
             hasFinished := hasFinished || raceMap.causesFinish(path)
             traceln("got crash finish")
             if (hasCrashed) {
                 instrumentPanel.setStatus("Crashed")
             } else if (hasFinished) {instrumentPanel.setStatus("Finished")}
             traceln("out of move")
         }
         to getLocation() {return location}
         to getVelocity() {return velocity}
         to hasCrashed() {return hasCrashed}
         to hasFinished() {return hasFinished}
         to getName() {return name}
         to prepareForNextTurn() {instrumentPanel.prepareForNextTurn()}
         to addAccelReactor(reactor) {accelReactors[reactor] := reactor}
         to removeAccelReactor(reactor) {accelReactors.remove(reactor)}
     }
     bind instrumentPanel := makeInstrumentPanel(car)
     return car
 }
 
 def makeTrackViewer(initialTextMap)  {
     def frame := <swing:makeJFrame>("Track View")
     def mapPane := <swing:makeJTextArea>(initialTextMap)
     def statusPane := <swing:makeJLabel>(" ")
     def realPane :=
       JPanel`$mapPane.Y
              $statusPane`
     frame.getContentPane().add(realPane)
     def windowListener {
         to windowClosing(event) {
             interp.continueAtTop()
         }
         match [verb,args] {}
     }
     frame.addWindowListener(windowListener)
     frame.pack()
     frame.show()
     def trackViewer {
         to refresh(textMap) {mapPane.setText(textMap)}
         to showStatus(status) {statusPane.setText(status)}
     }
     return trackViewer
 }
 
 def makeRaceMap() {
     def baseMap := [
         "..........W...............",
         "..........W...........FFFF",
         "......W...WW..............",
         "......W....W..............",
         "......W....WWW............",
         "......W........W..........",
         "......W.....W.............",
         "......W.....W.............",
         "......W...................",
         "......W..................."]
 
     def isWall(coord) :boolean {return baseMap[coord.getY()] [coord.getX()] == 'W' }
     def isFinish(coord) :boolean {return baseMap[coord.getY()] [coord.getX()] == 'F'}
     def pointCrash(coord) :boolean {
         var result := false
         if (coord.getX() < 0 || coord.getY() < 0 ||
               coord.getX() >= baseMap[0].size() || coord.getY() >= baseMap.size()) {
             result := true
         } else if (isWall(coord)) {
             result := true
         }
         return result
     }
     def raceMap {
         to getAsTextWithCars(cars) {
             def embedCarsInLine(index,line) {
                 def inBounds(xLoc) :boolean {return xLoc >= 0 && xLoc < line.size()}
                 var result := line
                 for each in cars {
                     if (each.getLocation().getY() == index && 
                           inBounds(each.getLocation().getX())) {
                         def editable := result.diverge(char)
                         editable[each.getLocation().getX()] := (each.getName())[0]
                         result := editable.snapshot()
                     }
                 }
                 return result
             }
             var result := ""
             for i => each in baseMap {
                 result := result + embedCarsInLine(i,each) + "\n"
             }
             return result
         }
         to causesCrash(path) :boolean {
             var result := false
             for each in path {
                 if (pointCrash(each)) {
                     result := true
                     break()
                 }
             }
             return result
         }
         to causesFinish(path) :boolean {
             var result := false
             for each in path {
                 if (pointCrash(each)) {
                     break()
                 } else if (isFinish(each)) {
                     result := true
                     break()
                 }
             }
             return result
         }
     }
     return raceMap
 }
 
 /**
  * create the cars, place them in a flex map to be used as a set
  */
 def makeCars(raceMap) {
     def carList := [ 
         makeCar("1",makeCoord(1,9),raceMap),
         makeCar("2",makeCoord(2,9),raceMap),
         makeCar("3",makeCoord(3,9),raceMap)]
     def carSet := [].asMap().diverge()
     for each in carList {carSet[each] := each}
     return carSet
 }
 
 /**
  * @author [mailto:marcs@skyhunter.com Marc Stiegler]
  */
 def makeRaceTrack() {
     def raceMap := makeRaceMap()
     def cars := makeCars(raceMap)
     var carsReadyToMove  := [].asMap().diverge()
     def mapViewer := makeTrackViewer(raceMap.getAsTextWithCars(cars))
     def raceTrack {
         to reactToAccel(car) {
             traceln("racetrack reacting to accel")
             carsReadyToMove[car] := car
             if (carsReadyToMove.size() >= cars.size()) {
                 raceTrack.completeNextTurn()
             }
         }
         to completeNextTurn() {
             def winners := [].diverge()
             for each in cars {
                 each.move()
                 if (each.hasCrashed()) {
                     cars.removeKey(each)
                 } else if (each.hasFinished()) {
                     winners.push(each)
                 }
             }
             mapViewer.refresh(raceMap.getAsTextWithCars(cars) )
             if (winners.size() == 1) {
                 mapViewer.showStatus(`Car ${winners[0].getName()} has won!`)
             } else if (winners.size() > 1) {
                 mapViewer.showStatus("It's a tie!")
             } else if (cars.size() == 0) {
                 mapViewer.showStatus("Everyone's dead!")
             } else {raceTrack.prepareForNextTurn()}
         }
         to prepareForNextTurn() {
             traceln("into prepare for next turn")
             carsReadyToMove := [].asMap().diverge()
             for each in cars {
                 each.prepareForNextTurn()
             }
         }
     }
     for each in cars {each.addAccelReactor(raceTrack)}
     return raceTrack
 }
 
 makeRaceTrack()
 # In actual code, the following line would not be commented out
 # interp.blockAtTop()


Next section: Distributed Computing

Personal tools
more tools