EWEScript language reference

This document

Introduction

This document is intended to be the most detailed available about the language EWEScript (aside from the source code of course ;). No background information for the decisions made is provided, just quite bare statements as to what is allowed and what is not.

It is assumed that the reader is familiar with a conventional procedural language, such as C, BASIC, Fortran and so on. Explanations of standard functions such as boolean AND will have to be sought elsewhere.

For more complete examples, see my page on EWEScript examples.

Typographical conventions

The document uses some conventions to show the type of information. Unfortunately as style sheets are not yet implemented universally, the conventions may not appear on your browser (or "user agent"). Hopefully the type of information is fairly obvious from the context anyway.

Examples that form complete lines that you can type into
the applet appear like this.

Abstract mathematically presented "rules" appear like this.

And results, or "answers" to presented examples appear like this.

General

EWEScript is intended to be a definitive type of notation, as opposed to procedural or functional, so may look a little unfamiliar to users who have not experienced this paradigm before. The structure is quite simple however - definitions, for example a IS b+c, and actions, for example TRIGGER catHungry DO feedCat, are contained within agents.

Line feeds, white space and splitting lines

White space (spaces and tabs) are ignored by the EWEScript parser, and so white space can be inserted anywhere in a script without changing its meaning.

Linefeeds (or carriage returns) are used as the separators between statements. Long input lines can be split into parts by using the line continuation character \ (slash). For example:

AGENT Long {
  largeDefinition IS 78.34524465656 - anotherAgent.longDefinitionName * \
    22.1
}

Comments: #

Any information preceded by a # (hash) character will be ignored by the parser. Comments run from a hash character to the end of the line, rather like UNIX shell languages (eg /bin/sh). Comments cannot include the line continuation character \ in order to construct a multi-line comment: each comment line must start with a hash character.

Case sensitivity

EWEScript is cAse sEnSitiVE. All keywords are in UPPER CASE. The user can define definitions using mixed case characters, but references to definitions must use the same case as the original, or the reference will fail.

Definitions: IS

Definitions are the basic entities within EWEScript. They are both the program and the data. A very basic definition is

a IS b+c

Now the value of a will always be ("IS") b added to c. If b or c are changed, a will be automatically updated. This update to a might then set off some changes to the values of other definitions that depend on a. You can see that a network-like structure of dependencies can be built.

More complex definitions are possible - the data types, operators and functions that can be used are described below.

Definition names (the a in this example) can consist of letters and digits, but the first character must be a letter.

Data types

These are the basic data types in EWEScript.

More complex types must be represented by combinations of these types, formed into lists. For example, the SEE() function returns a list including three integers, which are used to represent colour.

Operators: +, -, AND etc

EWEScript implements a few operators, which are really just sugared syntax for functions (for example, 2+3 is translated to ADD(2,3)). Some operators are infix (are placed in between two expressions), some are prefix (are placed before just one expression).

Definition types are dealt with automatically. For example, adding a floating point to an integer automatically makes the result floating point. The "casting" possible in other languages is not implemented in EWEScript (see limitations).

Functions: SIN(n), RANDOM([n]), SEE() etc

A number of functions exist in EWEScript, some of which are designed for direct use by the user. A function name must be followed by a pair of brackets, which surround the arguments to the function. As with all keywords in EWEScript, the function name must be entered in UPPER CASE.

Other functions also exist in EWEScript, but are probably not so useful to the user. Sugared syntax exists for the functions ADD, SUBTRACT, MULTIPLY, DIVIDE, OR, AND, EQUALITY, INEQUALITY, LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN_OR_EQUAL, MINUS and NOT. Some "internal functions" also exist, currently ACTION and DEREF.

If any function is passed UNDEFINED as an argument, it will return UNDEFINED.

List processing

Lists were added to EWEScript in an attempt to add generality of representation to the language. The methods of list processing are an attempt to add computational power to the language.

All the operators described in the operators section can process lists as well as the more basic data types. All infix operators handle lists in the same way. Unary operators have a similar scheme.

Unary operators

Unary operators descend through the list, looking into inner lists, and each basic value is evaluated with the operator. In this example, unaryTest will evaluate to be {-1, {-2, -7}, -3}.

myList IS {1,{2,7},3}
unaryTest IS -myList

This might be written as the general rule:

1. op {a, b} -> {op a, op b}

Infix operators

The general rule for list processing in infix operators is an attempt to overlay like onto like. The rules are given below. Note that the operators are missing from the result to save space.

2. {a,b} op c -> {ac,bc}
3. {a,b} op {c,d} -> {ac,bd}

And for lists with a depth of one inner list, which might be thought of as two-dimensional:

4. {{a,b},{c,d}} op e -> {{ae,be},{ce,de}}
5. {{a,b},{c,d}} op {e,f} -> {{ae,bf},{ce,df}}
6. {{a,b},{c,d}} op {{e,f},{g,h}} -> {{ae,bf},{cg,dh}}

Continuing this scheme, for three dimensions, these rules follow:

7. {{{a,b},{c,d}},{{e,f},{g,h}}} op i -> {{{ai,bi},{ci,di}},{{ei,fi},{gi,hi}}}
8. {{{a,b},{c,d}},{{e,f},{g,h}}} op {i,j} -> {{{ai,bj},{ci,dj}},{{ei,fj},{gi,hj}}}
9. {{{a,b},{c,d}},{{e,f},{g,h}}} op {{i,j},{k,l}} -> {{{ai,bj},{ck,dl}},{{ei,fj},{gk,hl}}}
10. {{{a,b},{c,d}},{{e,f},{g,h}}} op {{{i,j},{k,l}},{{m,n},{o,p}}} -> {{{ai,bj},{ck,dl}},{{em,fn},{go,hp}}}

This scheme continues on into multiple dimensions, beyond the three dimensional examples given here. The reverse is also true in each case, for example rule 2 also means that:

11. c op {a,b} -> {ca,cb}

The above examples happen to be symmetrical. The general scheme is followed for non-symmetrical examples, though:

12. {{a,b},{c,d},{e,f}} op {g,h} -> {{ag,bh},{cg,dh},{eg,fh}}

All this, combined with the SUM(l) function, is very handy for applying "weightings" to lists. For example:

# SEE() returns {{distance, bearing, size, red, green, blue}, {distance...
# eg {{2.0, 270.0, 1.0, 202, 202, 202},
#     {1.798375003164016, 90.0, 0.6188082691734271, 0, 255, 0}}
view IS SEE()

# Form a weighting appropriately for one sighting. In this example, we
# are looking for something to eat, and so a large distance is bad, the
# bearing is not important, the bigger the size the better, and the
# green-ness of the object is very important.
weight IS {-0.5, 0, 0.5, 0, 1, 0}

# weightedViews is thus a list of weighting sightings
# eg {{-1.0, 0.0, 0.5, 0, 202, 0},
#     {-0.899187501582008, 0.0, 0.30940413458671356, 0, 255, 0}}
weightedViews IS view*weight

# Now sum each inner list (each sighting) to produce a list of "importance"
# results, one for each sighting.
# eg {201.5, 254.4102166330047}
summedViews IS SUM(weightedViews)

# And find the index of the sighting with the maximum "importance"
# eg 2
indexOfFavourite IS INDEXOFMAX(summedViews)

Agents: AGENT

What is an agent?

An "Agent" in the Empirical Modelling context means "an instigator of change". Agents trigger chains of cause and effect. It is useful to organise the observables (modelled by definitions) in the system using agents as a basis. Hence, in EWE, agents are containers for definitions, and can also perform actions. Note this is not the same definition as in some other branches of Computer Science, like "multi-agent systems" and "intelligent agents".

Defining agents

A definition for an agent looks like this:

AGENT Cheese {
  odour IS 2.3
}

This defines a new agent, whose name is Cheese. The definition odour is contained within this agent. Note that the line breaks must occur exactly where shown - saying AGENT Cheese { odour IS 2.3 } all one line is not possible (see limitations).

If we want some representation of this agent to appear visually on the screen, we must define the agent to be of a certain "agent type". One particular agent type is "VEGETABLE", so for example:

AGENT Prickly IS "VEGETABLE" {
  image IS "bush"
  x IS 0
  y IS 0
  h IS 0
  scale IS 1

  numberOfFlowers IS 22
}

This definition will cause an image of a bush to appear, at coordinates (0, 0). The heading, h is 0, and so the image will not be rotated, and scale is 1, so the image will be at the normal size. The definitions for image, x, y, h and scale are actually included automatically in a "VEGETABLE" agent, so there is actually no need to type them in as above. The definition numberOfFlowers, however, is not a default, and has been added as an observable of the agent Prickly.

There are a few agent types:

Any of these definitions can be redefined, with the corresponding effect on the image. Note that double quotes are required around the agent type, as it is a string. Note also that, as in the rest of EWEScript, the agent name and agent type is case-sensitive.

Short circuits

It is not actually necessary for all definitions to be contained within an agent - definitions can be typed in without a surrounding agent, for example:

test IS 3+22.5

However this is only recommended for testing purposes. Definitions entered using this "short circuit" are added to the overall parent agent, which cannot be easily referenced.

The system agent

The system agent is added whenever EWE is initialised, and so should always exist. The current definition is:

AGENT system {
  clock IS 0
  tick IS clock==clock
  TRIGGER tick PRIORITY 99 DO nextState

  nextState: clock=clock+1

  seeDepends IS {}
}

The definitions useful to the user here are system.clock and system.tick. The value of clock will increment on every "step", and tick will always have been "touched" and have the value TRUE.

Actions: TRIGGER, DO etc

Why are actions needed?

Definitions can be added or changed (redefined) in several different ways. They can be added by the system, like the system agent. They can be added by the user. Scripts can also be written that modify themselves. If this phrase makes you shudder as you think of self-modifying code (perhaps in assembler?), do not worry - this is a designed part of the language.

Why do scripts need to be able to make changes to themselves? Well, without this facility, we can only construct what I call static definitions. For example:

AGENT Left IS "ANIMAL" {
}
AGENT Right IS "ANIMAL" {
  x IS left.x + 25
}

Now the sheep Right will always be 25 units away from the sheep Left (see the section on references for an explanation of left.x). But the distance will always be 25, unless the user redefines it. We could make the value dependant on time, by using system.clock for example, and maybe use functions like SIN(n) to make a more complex relationship, but this is all a little limited.

Using actions

An action is a set of redefinitions. Actions are triggered by changes to "guarded commands", a little like Edsger Dijkstra's guarded command language of 1976.

Take a look at the following example:

AGENT TestActions {
  a IS 0
  guard IS FALSE

  TRIGGER guard DO changeA

  changeA: {
    a IS 1
  }
}

As this example stands, the value of a will stay at 0. However, if, say the user changes the value of guard to TRUE, then the action block changeA will be triggered, and a will be redefined to the value 1.

The keyword TRIGGER is meant to imply that two things must happen in order for an action block to be evaluated. "The guard must change to TRUE" is a simplification. The guard must be reevaluated, or "touched" (it might be redefined from TRUE to TRUE for example), and it must evaluate to TRUE.

Action blocks can include more than one redefinition:

AGENT TwoRedefines {
  TRIGGER someGuardOrOther DO redefines

  redefines: {
    a IS 3.2
    b IS a-4
    c IS "dinky doo"
  }
}

If an action block contains just one redefinition, it can be written in short form without the surrounding brackets:

AGENT QuickToType {
  TRIGGER go DO doIt

  doIt: x IS 69
}

Note that this is only possible with action blocks, and not AGENT definitions. Also note that a DO statement must have a correspondingly named action block within the agent currently being defined, and all action blocks within an agent definition must have a corresponding DO statement (see limitations).

Procedural redefinitions

So we can now create automatic agents. However, action blocks can only make standard "IS" redefinitions. This is no good if we want to model a procedural style change in state. For example, we cannot say a IS a + 1. Remember, IS means "will always be". So, as a definition, this is clearly meaningless: a cannot "always be" one more than itself. In fact, entering the definition a IS a + 1 will cause an error about cyclic dependencies - a definition cannot depend upon itself. It is also possible to create cyclic dependencies in more complex ways: consider a IS b together with b IS a for example.

The single equals, or procedural redefinition syntax, = has been introduced into EWEScript to solve this problem. The redefinition a = a + 1 will increment a by one, this one time only, and then the redefinition will be forgotten: the opposite of IS and "will always be". This syntax can only be used within action blocks, as it is clearly concerned with time, which standard IS definitions are not (they hold for all time).

One change can set off a stream of changes. We can now set up loops - this example defines a clock mechanism.

AGENT myClock {
  time IS 0

  TRIGGER time==time DO incrementTime

  incrementTime: {
    time = time + 1
  }
}

Priorities: PRIORITY

EWE maintains a queue of actions waiting to be performed (ie those whose guard has been "touched" and evaluate to TRUE). If the queue contains more than one action, then by default their ordering is not defined. However, in some circumstances, it is useful to be able to force a certain ordering.

For example, in the system agent, it is useful to force the incrementing of system.clock to happen at a certain time. Say that some other definitions use the value of system.clock. If the change to system.clock happens at the wrong time, some definitions could see the old value, and some the new. So it is useful to be able to force the updating to happen either before all the user defined actions have occurred, or after - preferably not somewhere in the middle.

The PRIORITY keyword can be used to assign a numeric priority to an action definition. The syntax for the entire TRIGGER definition is now TRIGGER guard [PRIORITY priValue] DO action. The square brackets [] imply that the PRIORITY section is optional. priValue can be an integer or a floating point value - the default if none is supplied is 0.5. The action with the highest priority will be performed first, running in order through to the action with the lowest priority.

References

Referencing definitions

Most of the examples so far have just used number and list literals. It is of course possible to reference other definitions to refer to their values. A simple reference could be a IS b. However, consider multiple agents, each with a definition for b. In this simple reference, b implicitly refers to the b in the current agent. To refer to a definition in another agent, we use the dot notation, for example Cheese.b, which references the value of b in the agent Cheese. We have already seen this example when we use the system agent, for example system.tick.

Referencing list elements

The other type of reference is to individual elements within lists. This is achieved by the syntax element IS a[3], which references the third item in the list a. List indexes start from 1, not 0, in an attempt to be nice to non-computer scientists. If there was no item 3 in the example, element would be set to UNDEFINED.

Multi-dimensional lists (or lists with inner lists - same thing, just a different way of looking at it) can be indexed by using the syntax shown in this example:

AGENT Lists {
  list IS {1, 2, 3, {4, {5, 6}}}
  one IS list[1]            # 1
  four IS list[4]           # {4, {5, 6}}  
  inner IS list[4,1]        # 4
  innermost IS list[4,2,1]  # 5
}

Evaluation

Precedence

This is the order of precedence used within expressions, highest first.

EWE is not lazy. In some systems, an expression such as b OR c would mean that c is not evaluated if b is TRUE, as this is clearly wasted computation. This feature is not present in EWE.

Grouping brackets

Grouping brackets, ( and ) can of course be used to force a certain order of evaluation. A simple example is z IS (2+3)*5.

Resources

Currently the images available are "bush", "ewelogo", "larry", "moddinside", "puddle" and "wmb".

The sounds currently available are "baa", "chewgulp", "glug", "multibaa", "rapturebaa", "singbaa" and "zzzz".

Language definition in BNF

The BNF below is automatically generated from the parser input file, and so is the most accurate statement of the language syntax available.

"Limitations", "problems", or just plain bugs

Here are the ones I know about. If you find more, please let me know - thanks.

• Action blocks and DOs must come in pairs. It would be nice to be able to pre-define, say the moveForward action block commonly used in "ANIMAL" agent definitions, but it is not possible yet.
• List literals don't work with functions. For example, list IS {1,2,-1,-2} * 5 fails with an unexpected type error. This can be worked around. For example, say a IS {1,2,-1,-2} and list IS a * 5 instead.
• The SEE() function should only be re-evaluated if something on the screen has moved. There is a minor problem with this, and instead I've made SEE() re-evaluate every system.tick which obviously slows things down.
• Exponential format numbers are not implemented (although this would be quite easy to add - ask me if you want them).
• You cannot "escape" double quotes to enable them to be included in strings.
• Integer division cannot be performed, as all division currently returns a floating point. Maybe I should implement a DIV function. Tell me if you want it.
• There is no "if/then/else" procedural style branching, or other procedural statements. This was a deliberate design decision - I hoped I could get this kind of functionality through using other things such as lists. I've got only some way towards this. The lack of procedural statements helps to stop the programmer thinking in a procedural way - they should be thinking in an empirical style!
• Casting is not implemented.
• Resources available to PLAY(s) and the definition image are limited to those that I install on the website here. Java security would prevent the use of resources on the client workstation (which is running the applet). I could add the possibility of referencing URLs if required.
• "VEGETABLE" agents can use the SEE() function. It would be fairly easy to restrict this.
• The EWEScript parser is fussy about line breaks, partly as I was attempting to avoid the need for separators (eg semi-colons in C).
• Once added, an agent cannot be removed from the model.
• Support for the string data type is quite limited - you cannot concatenate strings and so on.
• It is not possible to redefine TRIGGER statements and action blocks within an agent without redefining the entire agent.
• Lists could be combined with references to enable examples like

  AGENT one {
  }
  AGENT two {
  }
  AGENT init {
    list IS {one, two}
    list.x IS 2
  }
  

which is intended to initialise x in both agents one and two to the value 2. This example does not work as intended at the moment, though - lists of complex types like references need more thought.
• Agent communication is a bit limited. Say a sheep is eating a bush - it would be good to be able to decrement the size of the bush. However this is not possible in EWE unless we already know the name of the bush.
• Constructing agents within agents is not possible with the EWEScript parser.
• Comments might not be allowed absolutely everywhere by the parser.
• SEE() seems to ignore the setting of h if it is negative.