@database beginner.guide @Master beginner @Width 75 This is the AmigaGuideŽ file beginner.guide, produced by Makeinfo-1.55 from the input file beginner. @Node Main "beginner.guide" @{" Search " SYSTEM "RUN SearchGuide :beginner.guide"} Copyright (c) 1994-1995, Jason R. Hulance. A Beginner's Guide to Amiga E ***************************** This Guide gives an introduction to the Amiga E programming language and, to some extent, programming in general. Part One: Getting Started @{" Introduction to Amiga E " Link "Introduction to Amiga E"} @{" Understanding a Simple Program " Link "Understanding a Simple Program"} @{" Variables and Expressions " Link "Variables and Expressions"} @{" Program Flow Control " Link "Program Flow Control"} @{" Summary " Link "Summary"} Part Two: The E Language @{" Format and Layout " Link "Format and Layout"} @{" Procedures and Functions " Link "Procedures and Functions"} @{" Constants " Link "Constants"} @{" Types " Link "Types"} @{" More About Statements and Expressions " Link "More About Statements and Expressions"} @{" E Built-In Constants Variables and Functions " Link "E Built-In Constants Variables and Functions"} @{" Modules " Link "Modules"} @{" Exception Handling " Link "Exception Handling"} @{" Memory Allocation " Link "Memory Allocation"} @{" Floating-Point Numbers " Link "Floating-Point Numbers"} @{" Recursion " Link "Recursion"} @{" Object Oriented E " Link "Object Oriented E"} Part Three: Worked Examples @{" Introduction to the Examples " Link "Introduction to the Examples"} @{" String Handling and I-O " Link "String Handling and I-O"} @{" Timing Expressions " Link "Timing Expressions"} @{" Argument Parsing " Link "Argument Parsing"} @{" Gadgets IDCMP and Graphics " Link "Gadgets IDCMP and Graphics"} @{" Recursion Example " Link "Recursion Example"} Part Four: Appendices @{" Common Problems " Link "Common Problems"} @{" Other Information " Link "Other Information"} Indices @{" E Language Index " Link "E Language Index"} @{" Main Index " Link "Main Index"} @EndNode @Node "Introduction to Amiga E" "beginner.guide/Introduction to Amiga E" @Next "Understanding a Simple Program" @Prev "Main" @Toc "Main" Introduction to Amiga E *********************** To interact with your Amiga you need to speak a language it understands. Luckily, there is a wide choice of such languages, each of which fits a particular need. For instance, BASIC (in most of its flavours) is simple and easy to learn, and so is ideal for beginners. Assembly, on the other hand, requires a lot of effort and is quite tedious, but can produce the fastest programs so is generally used by commercial programmers. These are two extremes and most businesses and colleges use C or Pascal/Modula-2, which try to strike a balance between simplicity and speed. E programs look very much like Pascal or Modula-2 programs, but E is based more closely on C. Anyone familiar with these languages will easily learn E, only really needing to get to grips with E's unique features and those borrowed from other languages. This guide is aimed at people who haven't done much programming and may be too trivial for competent programmers, who should find the `E Reference Manual' more than adequate (although some of the later sections offer different explanations to the @{b}Reference Manual@{ub}, which may prove useful). Part One (this part) goes through some of the basics of the E language and programming in general. Part Two delves deeper into E, covering the more complex topics and the unique features of E. Part Three goes through a few example programs, which are a bit longer than the examples in the other Parts. Finally, Part Four contains the Appendices, which is where you'll find some other, miscellaneous information. @{" A Simple Program " Link "A Simple Program"} @EndNode @Node "A Simple Program" "beginner.guide/A Simple Program" @Toc "Introduction to Amiga E" A Simple Program ================ If you're still reading you're probably desperate to do some programming in E but you don't know how to start. We'll therefore jump straight in the deep end with a small example. You'll need to know two things before we start: how to use a text editor and the Shell/CLI. @{" The code " Link "The code"} @{" Compilation " Link "Compilation"} @{" Execution " Link "Execution"} @EndNode @Node "The code" "beginner.guide/The code" @Next "Compilation" @Toc "A Simple Program" The code -------- Enter the following lines of code into a text editor and save it as the file @{b}simple.e@{ub} (taking care to copy each line accurately). (Just type the characters shown, and at the end of each line press the RETURN or ENTER key.) PROC main() WriteF('My first program') ENDPROC Don't try to do anything different, yet, to the code: the case of the letters in each word is significant and the funny characters are important. If you're a real beginner you might have difficulty finding the ' character. On my GB keyboard it's on the big key in the top left-hand corner directly below the ESC key. On a US and most European keyboards it's two to the right of the L key, next to the ; key. @EndNode @Node "Compilation" "beginner.guide/Compilation" @Next "Execution" @Prev "The code" @Toc "A Simple Program" Compilation ----------- Once the file is saved (preferably in the RAM disk, since it's only a small program), you can use the E compiler to turn it into an executable program. All you need is the file @{b}ec@{ub} in your @{b}C:@{ub} directory or somewhere else on your search path (advanced users note: we don't need the @{b}Emodules:@{ub} assignment because we aren't using any modules). Assuming you have this and you have a Shell/CLI running, enter the following at the prompt after changing directory to where you saved your new file: ec simple If all's well you should be greeted, briefly, by the E compiler. If anything went wrong then double-check the contents of the file @{b}simple.e@{ub}, that your CLI is in the same directory as this file, and that the program @{b}ec@{ub} is in your @{b}C:@{ub} directory (or on your search path). @EndNode @Node "Execution" "beginner.guide/Execution" @Prev "Compilation" @Toc "A Simple Program" Execution --------- Once everything is working you can run your first program by entering the following at the CLI prompt: simple As a help here's the complete transcript of the whole compilation and execution process (the CLI prompt, below, is the bit of text beginning with @{b}1.@{ub} and ending in @{b}>@{ub}): 1.System3.0:> cd ram: 1.Ram Disk:> ec simple Amiga E Compiler/Assembler/Linker/PP v3.1a registered (c) '91-95 Wouter lexical analysing ... parsing and compiling ... no errors 1.Ram Disk:> simple My first program1.Ram Disk:> Your display should be something similar if it's all worked. Notice how the output from the program runs into the prompt (the last line). We'll fix this soon. @EndNode @Node "Understanding a Simple Program" "beginner.guide/Understanding a Simple Program" @Next "Variables and Expressions" @Prev "Introduction to Amiga E" @Toc "Main" Understanding a Simple Program ****************************** To understand the example program we need to understand quite a few things. The observant amongst you will have noticed that all it does is print out a message, and that message was part of a line we wrote in the program. The first thing to do is see how to change this message. @{" Changing the Message " Link "Changing the Message"} @{" Procedures " Link "Procedures"} @{" Parameters " Link "Parameters"} @{" Strings " Link "Strings"} @{" Style Reuse and Readability " Link "Style Reuse and Readability"} @{" The Simple Program " Link "The Simple Program"} @EndNode @Node "Changing the Message" "beginner.guide/Changing the Message" @Next "Procedures" @Toc "Understanding a Simple Program" Changing the Message ==================== Edit the file so that line contains a different message between the two ' characters and compile it again using the same procedure as before. Don't use any ' characters except those around the message. If all went well, when you run the program again it should produce a different message. If something went wrong, compare the contents of your file with the original and make sure the only difference is the message between the ' characters. @{" Tinkering with the example " Link "Tinkering with the example"} @{" Brief overview " Link "Brief overview"} @EndNode @Node "Tinkering with the example" "beginner.guide/Tinkering with the example" @Next "Brief overview" @Toc "Changing the Message" Tinkering with the example -------------------------- Simple tinkering is a good way to learn for yourself so it is encouraged on these simple examples. Don't stray too far, though, and if you start getting confused return to the proper example pretty sharpish! @EndNode @Node "Brief overview" "beginner.guide/Brief overview" @Prev "Tinkering with the example" @Toc "Changing the Message" Brief overview -------------- We'll look in detail at the important parts of the program in the following sections, but we need first to get a glimpse of the whole picture. Here's a brief description of some fundamental concepts: @{b}*@{ub} @{i}Procedures:@{ui} We defined a procedure called @{b}main@{ub} and used the (built-in) procedure @{b}WriteF@{ub}. A procedure can be thought of as a small program with a name. @{b}*@{ub} @{i}Parameters:@{ui} The message in parentheses after @{b}WriteF@{ub} in our program is the parameter to @{b}WriteF@{ub}. This is the data which the procedure should use. @{b}*@{ub} @{i}Strings:@{ui} The message we passed to @{b}WriteF@{ub} was a series of characters enclosed in ' characters. This is known as a @{fg shine}string@{fg text}. @EndNode @Node "Procedures" "beginner.guide/Procedures" @Next "Parameters" @Prev "Changing the Message" @Toc "Understanding a Simple Program" Procedures ========== As mentioned above, a procedure can be thought of as a small program with a name. In fact, when an E program is run the procedure called @{b}main@{ub} is executed. Therefore, if your E program is going to do anything you must define a @{b}main@{ub} procedure. Other (built-in or user-defined) procedures may be run (or @{fg shine}called@{fg text}) from this procedure (as we did @{b}WriteF@{ub} in the example). For instance, if the procedure @{b}fred@{ub} calls the procedure @{b}barney@{ub} the code (or mini-program) associated with @{b}barney@{ub} is executed. This may involve calls to other procedures, and when the execution of this code is complete the next piece of code in the procedure @{b}fred@{ub} is executed (and this is generally the next line of the procedure). When the end of the procedure @{b}main@{ub} has been reached the program has finished. However, lots can happen between the beginning and end of a procedure, and sometimes the program may never get to finish. Alternatively, the program may @{fg shine}crash@{fg text}, causing strange things to happen to your computer. @{" Procedure Definition " Link "Procedure Definition"} @{" Procedure Execution " Link "Procedure Execution"} @{" Extending the example " Link "Extending the example"} @EndNode @Node "Procedure Definition" "beginner.guide/Procedure Definition" @Next "Procedure Execution" @Toc "Procedures" Procedure Definition -------------------- Procedures are defined using the keyword @{b}PROC@{ub}, followed by the new procedure's name (in lowercase letters), a description of the parameters it takes (in parentheses), a series of lines forming the code of the procedure and then the keyword @{b}ENDPROC@{ub}. Look at the example program again to identify the various parts. See @{"The code" Link "The code"}. @EndNode @Node "Procedure Execution" "beginner.guide/Procedure Execution" @Next "Extending the example" @Prev "Procedure Definition" @Toc "Procedures" Procedure Execution ------------------- Procedures can be called (or executed) from within the code part of another procedure. You do this by giving its name, followed by some data in parentheses. Look at the call to @{b}WriteF@{ub} in the example program. See @{"The code" Link "The code"}. @EndNode @Node "Extending the example" "beginner.guide/Extending the example" @Prev "Procedure Execution" @Toc "Procedures" Extending the example --------------------- Here's how we could change the example program to define another procedure: PROC main() WriteF('My first program') fred() ENDPROC PROC fred() WriteF('...slightly improved') ENDPROC This may seem complicated, but in fact it's very simple. All we've done is define a second procedure called @{b}fred@{ub} which is just like the original program--it outputs a message. We've @{fg shine}called@{fg text} this procedure in the @{b}main@{ub} procedure just after the line which outputs the original message. Therefore, the message in @{b}fred@{ub} is output after this message. Compile the program as before and run it so you don't have to take my word for it. @EndNode @Node "Parameters" "beginner.guide/Parameters" @Next "Strings" @Prev "Procedures" @Toc "Understanding a Simple Program" Parameters ========== Generally we want procedures to work with particular data. In our example we wanted the @{b}WriteF@{ub} procedure to work on a particular message. We passed the message as a @{fg shine}parameter@{fg text} (or @{fg shine}argument@{fg text}) to @{b}WriteF@{ub} by putting it between the parentheses (the @{b}(@{ub} and @{b})@{ub} characters) that follow the procedure name. When we called the @{b}fred@{ub} procedure, however, we did not require it to use any data so the parentheses were left empty. When defining a procedure when define how much and what type of data we want it to work on, and when calling a procedure we give the specific data it should use. Notice that the procedure @{b}fred@{ub} (like the procedure @{b}main@{ub}) has empty parentheses in its definition. This means that the procedure cannot be given any data as parameters when it is called. Before we can define our own procedure that takes parameters we must learn about variables. We'll do this in the next chapter. See @{"Global and local variables" Link "Global and local variables"}. @EndNode @Node "Strings" "beginner.guide/Strings" @Next "Style Reuse and Readability" @Prev "Parameters" @Toc "Understanding a Simple Program" Strings ======= A series of characters between two ' characters is known as a string. Almost any character can be used in a string, although the \ and ' characters have a special meaning. For instance, a linefeed is denoted by the two characters @{b}\n@{ub}. We now know how to stop the message running into the prompt. Change the program to be: PROC main() WriteF('My first program\n') fred() ENDPROC PROC fred() WriteF('...slightly improved\n') ENDPROC Compile it as before, and run it. You should notice that the messages now appear on lines by themselves, and the second message is separated from the prompt which follows it. We have therefore cured the linefeed problem we spotted earlier (see @{"Execution" Link "Execution"}). @EndNode @Node "Style Reuse and Readability" "beginner.guide/Style Reuse and Readability" @Next "The Simple Program" @Prev "Strings" @Toc "Understanding a Simple Program" Style, Reuse and Readability ============================ The example has grown into two procedures, one called @{b}main@{ub} and one called @{b}fred@{ub}. However, we could get by with only one procedure: PROC main() WriteF('My first program\n') WriteF('...slightly improved\n') ENDPROC What we've done is replace the call to the procedure @{b}fred@{ub} with the code it represents (this is called @{fg shine}inlining@{fg text} the procedure). In fact, almost all programs can be easily re-written to eliminate all but the @{b}main@{ub} procedure. However, splitting a program up using procedures normally results in more readable code. It is also helpful to name your procedures so that their function is apparent, so our procedure @{b}fred@{ub} should probably have been named @{b}message@{ub} or something similar. A well-written program in this style can read just like English (or any other spoken language). Another reason for having procedures is to reuse code, rather than having to write it out every time you use it. Imagine you wanted to print the same, long message fairly often in your program--you'd either have to write it all out every time, or you could write it once in a procedure and call this procedure when you wanted the message printed. Using a procedure also has the benefit of having only one copy of the message to change, should it ever need changing. @EndNode @Node "The Simple Program" "beginner.guide/The Simple Program" @Prev "Style Reuse and Readability" @Toc "Understanding a Simple Program" The Simple Program ================== The simple program should now (hopefully) seem simple. The only bit that hasn't been explained is the built-in procedure @{b}WriteF@{ub}. E has many built-in procedures and later we'll meet some of them in detail. The first thing we need to do, though, is manipulate data. This is really what a computer does all the time--it accepts data from some source (possibly the user), manipulates it in some way (possibly storing it somewhere, too) and outputs new data (usually to a screen or printer). The simple example program did all this, except the first two stages were rather trivial. You told the computer to execute the compiled program (this was some user input) and the real data (the message to be printed) was retrieved from the program. This data was manipulated by passing it as a parameter to @{b}WriteF@{ub}, which then did some clever stuff to print it on the screen. To do our own manipulation of data we need to learn about variables and expressions. @EndNode @Node "Variables and Expressions" "beginner.guide/Variables and Expressions" @Next "Program Flow Control" @Prev "Understanding a Simple Program" @Toc "Main" Variables and Expressions ************************* Anybody who's done any school algebra will probably know what a variable is--it's just a named piece of data. In algebra the data is usually a number, but in E it can be all sorts of things (e.g., a string). The manipulation of data like the addition of two numbers is known as an @{fg shine}expression@{fg text}. The result of an expression can be used to build bigger expressions. For instance, @{b}1+2@{ub} is an expression, and so is @{b}6-(1+2)@{ub}. The good thing is you can use variables in place of data in expressions, so if @{b}x@{ub} represents the number 1 and @{b}y@{ub} represents 5, then the expression @{b}y-x@{ub} represents the number 4. In the next two sections we'll look at what kind of variables you can define and what the different sorts of expressions are. @{" Variables " Link "Variables"} @{" Expressions " Link "Expressions"} @EndNode @Node "Variables" "beginner.guide/Variables" @Next "Expressions" @Toc "Variables and Expressions" Variables ========= Variables in E can hold many different kinds of data (called @{fg shine}types@{fg text}). However, before a variable can be used it must be defined, and this is known as @{fg shine}declaring@{fg text} the variable. A variable declaration also decides whether the variable is available for the whole program or just during the code of a procedure (i.e., whether the variable is @{fg shine}global@{fg text} or @{fg shine}local@{fg text}). Finally, the data stored in a variable can be changed using @{fg shine}assignments@{fg text}. The following sections discuss these topics in slightly more detail. @{" Variable types " Link "Variable types"} @{" Variable declaration " Link "Variable declaration"} @{" Assignment " Link "Assignment"} @{" Global and local variables " Link "Global and local variables"} @{" Changing the example " Link "Changing the example"} @EndNode @Node "Variable types" "beginner.guide/Variable types" @Next "Variable declaration" @Toc "Variables" Variable types -------------- In E a variable is a storage place for data (and this storage is part of the Amiga's RAM). Different kinds of data may require different amounts of storage. However, data can be grouped together in @{fg shine}types@{fg text}, and two pieces of data from the same type require the same amount of storage. Every variable has an associated type and this dictates the maximum amount of storage it uses. Most commonly, variables in E store data from the type @{b}LONG@{ub}. This type contains the integers from -2,147,483,648 to 2,147,483,647, so is normally more than sufficient. There are other types, such as @{b}INT@{ub} and @{b}LIST@{ub}, and more complex things to do with types, but for now knowing about @{b}LONG@{ub} is enough. @EndNode @Node "Variable declaration" "beginner.guide/Variable declaration" @Next "Assignment" @Prev "Variable types" @Toc "Variables" Variable declaration -------------------- Variables must be declared before they can be used. They are declared using the @{b}DEF@{ub} keyword followed by a (comma-separated) list of the names of the variables to be declared. These variables will all have type @{b}LONG@{ub} (later we will see how to declare variables with other types). Some examples will hopefully make things clearer: DEF x DEF a, b, c The first line declares the single variable @{b}x@{ub}, whilst the second declares the variables @{b}a@{ub}, @{b}b@{ub} and @{b}c@{ub} all in one go. @EndNode @Node "Assignment" "beginner.guide/Assignment" @Next "Global and local variables" @Prev "Variable declaration" @Toc "Variables" Assignment ---------- The data stored by variables can be changed and this is normally done using @{fg shine}assignments@{fg text}. An assignment is formed using the variable's name and an expression denoting the new data it is to store. The symbol @{b}:=@{ub} separates the variable from the expression. For example, the following code stores the number two in the variable @{b}x@{ub}. The left-hand side of the @{b}:=@{ub} is the name of the variable to be affected (@{b}x@{ub} in this case) and the right-hand side is an expression denoting the new value (simply the number two in this case). x := 2 The following, more complex example uses the value stored in the variable before the assignment as part of the expression for the new data. The value of the expression on the right-hand side of the @{b}:=@{ub} is the value stored in the variable @{b}x@{ub} plus one. This value is then stored in @{b}x@{ub}, over-writing the previous data. (So, the overall effect is that @{b}x@{ub} is incremented.) x := x + 1 This may be clearer in the next example which does not change the data stored in @{b}x@{ub}. In fact, this piece of code is just a waste of CPU time, since all it does is look up the value stored in @{b}x@{ub} and store it back there! x := x @EndNode @Node "Global and local variables" "beginner.guide/Global and local variables" @Next "Changing the example" @Prev "Assignment" @Toc "Variables" Global and local variables (and procedure parameters) ----------------------------------------------------- There are two kinds of variable: @{fg shine}global@{fg text} and @{fg shine}local@{fg text}. Data stored by global variables can be read and changed by all procedures, but data stored by local variables can only be accessed by the procedure to which they are local. Global variables must be declared before the first procedure definition. Local variables are declared within the procedure to which they are local (i.e., between the @{b}PROC@{ub} and @{b}ENDPROC@{ub}). For example, the following code declares a global variable @{b}w@{ub} and local variables @{b}x@{ub} and @{b}y@{ub}. DEF w PROC main() DEF x x:=2 w:=1 fred() ENDPROC PROC fred() DEF y y:=3 w:=2 ENDPROC The variable @{b}x@{ub} is local to the procedure @{b}main@{ub}, and @{b}y@{ub} is local to @{b}fred@{ub}. The procedures @{b}main@{ub} and @{b}fred@{ub} can read and alter the value of the global variable @{b}w@{ub}, but @{b}fred@{ub} cannot read or alter the value of @{b}x@{ub} (since that variable is local to @{b}main@{ub}). Similarly, @{b}main@{ub} cannot read or alter @{b}y@{ub}. The local variables of one procedure are, therefore, completely different to the local variables of another procedure. For this reason they can share the same names without confusion. So, in the above example, the local variable @{b}y@{ub} in @{b}fred@{ub} could have been called @{b}x@{ub} and the program would have done exactly the same thing. DEF w PROC main() DEF x x:=2 w:=1 fred() ENDPROC PROC fred() DEF x x:=3 w:=2 ENDPROC This works because the @{b}x@{ub} in the assignment in @{b}fred@{ub} can refer only to the local variable @{b}x@{ub} of @{b}fred@{ub} (the @{b}x@{ub} in @{b}main@{ub} is local to @{b}main@{ub} so cannot be accessed from @{b}fred@{ub}). If a local variable for a procedure has the same name as a global variable then in the rest of the procedure the name refers only to the local variable. Therefore, the global variable cannot be accessed in the procedure, and this is called @{fg shine}descoping@{fg text} the global variable. The parameters of a procedure are local variables for that procedure. We've seen how to pass values as parameters when a procedure is called (the use of @{b}WriteF@{ub} in the example), but until now we haven't been able to define a procedure which takes parameters. Now we know a bit about variables we can have a go: DEF y PROC onemore(x) y:=x+1 ENDPROC This isn't a complete program so don't try to compile it. Basically, we've declared a variable @{b}y@{ub} (which will be of type @{b}LONG@{ub}) and a procedure @{b}onemore@{ub}. The procedure is defined with a parameter @{b}x@{ub}, and this is just like a (local) variable declaration. When @{b}onemore@{ub} is called a parameter must be supplied, and this value is stored in the (local) variable @{b}x@{ub} before execution of @{b}onemore@{ub}'s code. The code stores the value of @{b}x@{ub} plus one in the (global) variable @{b}y@{ub}. The following are some examples of calling @{b}onemore@{ub}: onemore(120) onemore(52+34) onemore(y) A procedure can be defined to take any number of parameters. Below, the procedure @{b}addthem@{ub} is defined to take two parameters, @{b}a@{ub} and @{b}b@{ub}, so it must therefore be called with two parameters. Notice that values stored by the parameter variables (@{b}a@{ub} and @{b}b@{ub}) can be changed within the code of the procedure. DEF y PROC addthem(a, b) a:=a+2 y:=a*b ENDPROC The following are some examples of calling @{b}addthem@{ub}: addthem(120,-20) addthem(52,34) addthem(y,y) @EndNode @Node "Changing the example" "beginner.guide/Changing the example" @Prev "Global and local variables" @Toc "Variables" Changing the example -------------------- Before we change the example we must learn something about @{b}WriteF@{ub}. We already know that the characters @{b}\n@{ub} in a string mean a linefeed. However, there are several other important combinations of characters in a string, and some are special to procedures like @{b}WriteF@{ub}. One such combination is @{b}\d@{ub}, which is easier to describe after we've seen the changed example. PROC main() WriteF('My first program\n') fred() ENDPROC PROC fred() WriteF('...brought to you by the number \d\n', 236) ENDPROC You might be able to guess what happens, but compile it and try it out anyway. If everything's worked you should see that the second message prints out the number that was passed as the second parameter to @{b}WriteF@{ub}. That's what the @{b}\d@{ub} combination does--it marks the place in the string where the number should be printed. Here's the output the example should generate: My first program ...brought to you by the number 236 Try this next change: PROC main() WriteF('My first program\n') fred() ENDPROC PROC fred() WriteF('...the number \d is quite nice\n', 16) ENDPROC This is very similar, and just shows that the @{b}\d@{ub} really does mark the place where the number is printed. Again, here's the output it should generate: My first program ...the number 16 is quite nice We'll now try printing two numbers. PROC main() WriteF('My first program\n') fred() ENDPROC PROC fred() WriteF('...brought to you by the numbers \d and \d\n', 16, 236) ENDPROC Because we're printing two numbers we need two lots of @{b}\d@{ub}, and we need to supply two numbers as parameters in the order in which we want them to be printed. The number 16 will therefore be printed before the word `and' and before the number 236. Here's the output: My first program ...brought to you by the numbers 16 and 236 We can now make a big step forward and pass the numbers as parameters to the procedure @{b}fred@{ub}. Just look at the differences between this next example and the previous one. PROC main() WriteF('My first program\n') fred(16, 236) ENDPROC PROC fred(a,b) WriteF('...brought to you by the numbers \d and \d\n', a,b) ENDPROC This time we pass the (local) variables @{b}a@{ub} and @{b}b@{ub} to @{b}WriteF@{ub}. This is exactly the same as passing the values they store (which is what the previous example did), and so the output will be the same. In the next section we'll manipulate the variables by doing some arithmetic with @{b}a@{ub} and @{b}b@{ub}, and get @{b}WriteF@{ub} to print the results. @EndNode @Node "Expressions" "beginner.guide/Expressions" @Prev "Variables" @Toc "Variables and Expressions" Expressions =========== The E language includes the normal mathematical and logical operators. These operators are combined with values (usually in variables) to give @{fg shine}expressions@{fg text} which yield new values. The following sections discuss this topic in more detail. @{" Mathematics " Link "Mathematics"} @{" Logic and comparison " Link "Logic and comparison"} @{" Precedence and grouping " Link "Precedence and grouping"} @EndNode @Node "Mathematics" "beginner.guide/Mathematics" @Next "Logic and comparison" @Toc "Expressions" Mathematics ----------- All the standard mathematical operators are supported in E. You can do addition, subtraction, multiplication and division. Other functions such as sine, modulus and square-root can also be used as they are part of the Amiga system libraries, but we only need to know about simple mathematics at the moment. The @{b}+@{ub} character is used for addition, @{b}-@{ub} for subtraction, @{b}*@{ub} for multiplication (it's the closest you can get to a multiplication sign on a keyboard without using the letter @{b}x@{ub}), and @{b}/@{ub} for division (be careful not to confuse the @{b}\ @{ub} used in strings with @{b}/@{ub} used for division). The following are examples of expressions: 1+2+3+4 15-5 5*2 330/33 -10+20 3*3+1 Each of these expressions yields ten as its result. The last example is very carefully written to get the precedence correct (see @{"Precedence and grouping" Link "Precedence and grouping"}). All the above expressions use integer operators, so they manipulate integers, giving integers as results. @{fg shine}Floating-point@{fg text} numbers are also supported by E, but using them is quite complicated (see @{"Floating-Point Numbers" Link "Floating-Point Numbers"}). (Floating-point numbers can represent both very small fractions and very large integers, but they have a limited accuracy, i.e., a limited number of @{i}significant@{ui} digits.) @EndNode @Node "Logic and comparison" "beginner.guide/Logic and comparison" @Next "Precedence and grouping" @Prev "Mathematics" @Toc "Expressions" Logic and comparison -------------------- Logic lies at the very heart of a computer. They rarely guess what to do next; instead they rely on hard facts and precise reasoning. Consider the password protection on most games. The computer must decide whether you entered the correct number or word before it lets you play the game. When you play the game it's constantly making decisions: did your laser hit the alien, have you got any lives left, etc. Logic controls the operation of a program. In E, the constants @{b}TRUE@{ub} and @{b}FALSE@{ub} represent the truth values true and false (respectively), and the operators @{b}AND@{ub} and @{b}OR@{ub} are the standard logic operators. The comparison operators are @{b}=@{ub} (equal to), @{b}>@{ub} (greater than), @{b}<@{ub} (less than), @{b}>=@{ub} (greater than or equal to), @{b}<=@{ub} (less than or equal to) and @{b}<>@{ub} (not equal to). All the following expressions are true: TRUE TRUE AND TRUE TRUE OR FALSE 1=1 2>1 3<>0 And these are all false: FALSE TRUE AND FALSE FALSE OR FALSE 0=2 2<1 (2<1) AND (-1=0) The last example must use parentheses. We'll see why in the next section (it's to do with precedence, again). The truth values @{b}TRUE@{ub} and @{b}FALSE@{ub} are actually numbers. This is how the logic system works in E. @{b}TRUE@{ub} is the number -1 and @{b}FALSE@{ub} is zero. The logic operators @{b}AND@{ub} and @{b}OR@{ub} expect such numbers as their parameters. In fact, the @{b}AND@{ub} and @{b}OR@{ub} operators are really bit-wise operators (see @{"Bitwise AND and OR" Link "Bitwise AND and OR"}), so most of the time any non-zero number is taken to be @{b}TRUE@{ub}. It can sometimes be convenient to rely on this knowledge, although most of the time it is preferable (and more readable) to use a slightly more explicit form. Also, these facts can cause a few subtle problems as we shall see in the next section. @EndNode @Node "Precedence and grouping" "beginner.guide/Precedence and grouping" @Prev "Logic and comparison" @Toc "Expressions" Precedence and grouping ----------------------- At school most of us are taught that multiplications must be done before additions in a sum. In E it's different--there is no operator precedence. This means that expressions like @{b}1+3*3@{ub} do not give the results a mathematician might expect. In fact, @{b}1+3*3@{ub} represents the number 12 in E. This is because the addition, @{b}1+3@{ub}, is done before the multiplication, since it occurs before the multiplication. If the multiplication were written before the addition it would be done first (like we would normally expect). Therefore, @{b}3*3+1@{ub} represents the number 10 in E and in school mathematics. To overcome this difference we can use parentheses to group the expression. If we'd written @{b}1+(3*3)@{ub} the result would be 10. This is because we've forced E to do the multiplication first. Although this may seem troublesome to begin with, it's actually a lot better than learning a lot of rules for deciding which operator is done first (in C this can be a real pain, and you usually end up writing the brackets in just to be sure!). The logic examples above contained the expression: (2<1) AND (-1=0) This expression was false. If we'd left the parentheses out, E would have seen it as: ((2<1) AND -1) = 0 Now the number -1 shouldn't really be used to represent a truth value with @{b}AND@{ub}, but we do know that @{b}TRUE@{ub} is the number -1, so E will make sense of this and the E compiler won't complain. We will soon see how @{b}AND@{ub} and @{b}OR@{ub} really work (see @{"Bitwise AND and OR" Link "Bitwise AND and OR"}), but for now we'll just work out what E would calculate for this expression: 1. Two is not less than one so @{b}2<1@{ub} can be replaced by @{b}FALSE@{ub}. (FALSE AND -1) = 0 2. @{b}TRUE@{ub} is -1 so we can replace -1 by @{b}TRUE@{ub}. (FALSE AND TRUE) = 0 3. @{b}FALSE AND TRUE@{ub} is @{b}FALSE@{ub}. (FALSE) = 0 4. @{b}FALSE@{ub} is really the number zero, so we can replace it with zero. 0 = 0 5. Zero is equal to zero, so the expression is @{b}TRUE@{ub}. TRUE So E calculates the expression to be true. But the original expression (with parentheses) was false. Bracketing is therefore very important! It is also very easy to do correctly. @EndNode @Node "Program Flow Control" "beginner.guide/Program Flow Control" @Next "Summary" @Prev "Variables and Expressions" @Toc "Main" Program Flow Control ******************** A computer program often needs to repeatedly execute a series of statements or execute different statements according to the result of some decision. For example, a program to print all the numbers between one and a thousand would be very long and tedious to write if each print statement had to be given individually--it would be much better to use a variable and repeatedly print its value and increment it. Also, things sometimes go wrong and a program must decide whether to continue or print an error message and stop--this part of a program is a typical example of a conditional block. @{" Conditional Block " Link "Conditional Block"} @{" Loops " Link "Loops"} @EndNode @Node "Conditional Block" "beginner.guide/Conditional Block" @Next "Loops" @Toc "Program Flow Control" Conditional Block ================= There are two kinds of conditional block: @{b}IF@{ub} and @{b}SELECT@{ub}. Examples of these blocks are given below as fragments of E code (i.e., the examples are not complete E programs). IF x>0 x:=x+1 WriteF('Increment: x is now \d\n', x) ELSEIF x<0 x:=x-1 WriteF('Decrement: x is now \d\n', x) ELSE WriteF('Zero: x is 0\n') ENDIF In the above @{b}IF@{ub} block, the first part checks if the value of @{b}x@{ub} is greater than zero, and, if it is, @{b}x@{ub} is incremented and the new value is printed (with a message saying it was incremented). The program will then skip the rest of the block, and will execute the statements which follow the @{b}ENDIF@{ub}. If, however, @{b}x@{ub} it is not greater than zero the @{b}ELSEIF@{ub} part is checked, so if @{b}x@{ub} is less than zero it will be decremented and printed, and the rest of the block is skipped. If @{b}x@{ub} is not greater than zero and not less than zero the statements in the @{b}ELSE@{ub} part are executed, so a message saying @{b}x@{ub} is zero is printed. The @{b}IF@{ub} conditional is described in more detail below. @{" IF block " Link "IF block"} @{" IF expression " Link "IF expression"} SELECT x CASE 0 WriteF('x is zero\n') CASE 10 WriteF('x is ten\n') CASE -2 WriteF('x is -2\n') DEFAULT WriteF('x is not zero, ten or -2\n') ENDSELECT The @{b}SELECT@{ub} block is similar to the @{b}IF@{ub} block--it does different things depending on the value of @{b}x@{ub}. However, @{b}x@{ub} is only checked against specific values, given in the series of @{b}CASE@{ub} statements. If it is not any of these values the @{b}DEFAULT@{ub} part is executed. There's also a variation on the @{b}SELECT@{ub} block (known as the @{b}SELECT..OF@{ub} block) which matches ranges of values and is quite fast. The two kinds of @{b}SELECT@{ub} block are described in more detail below. @{" SELECT block " Link "SELECT block"} @{" SELECT..OF block " Link "SELECT..OF block"} @EndNode @Node "IF block" "beginner.guide/IF block" @Next "IF expression" @Toc "Conditional Block" @{b}IF@{ub} block -------- The @{b}IF@{ub} block has the following form (the bits like @{fg shine}expression@{fg text} are descriptions of the kinds of E code which is allowed at that point--they are not proper E code): IF @{fg shine}expressionA@{fg text} @{fg shine}statementsA@{fg text} ELSEIF @{fg shine}expressionB@{fg text} @{fg shine}statementsB@{fg text} ELSE @{fg shine}statementsC@{fg text} ENDIF This block means: @{b}*@{ub} If @{fg shine}expressionA@{fg text} is true (i.e., represents @{b}TRUE@{ub} or any non-zero number) the code denoted by @{fg shine}statementsA@{fg text} is executed. @{b}*@{ub} If @{fg shine}expressionA@{fg text} is false (i.e., represents @{b}FALSE@{ub} or zero) and @{fg shine}expressionB@{fg text} is true the @{fg shine}statementsB@{fg text} part is executed. @{b}*@{ub} If both @{fg shine}expressionA@{fg text} and @{fg shine}expressionB@{fg text} are false the @{fg shine}statementsC@{fg text} part is executed. There does not need to be an @{b}ELSE@{ub} part but if one is present it must be the last part (immediately before the @{b}ENDIF@{ub}). Also, there can be any number of @{b}ELSEIF@{ub} parts between the @{b}IF@{ub} and @{b}ELSE@{ub} parts. An alternative to this vertical form (where each part is on a separate line) is the horizontal form: IF @{fg shine}expression@{fg text} THEN @{fg shine}statementA@{fg text} ELSE @{fg shine}statementB@{fg text} This has the disadvantage of no @{b}ELSEIF@{ub} parts and having to cram everything onto a single line. Notice the presence of the @{b}THEN@{ub} keyword to separate the @{fg shine}expression@{fg text} and @{fg shine}statement@{fg text}. This horizontal form is closely related to the @{b}IF@{ub} expression, which is described below (see @{"IF expression" Link "IF expression"}). To help make things clearer here are a number of E code fragments which illustrate the allowable @{b}IF@{ub} blocks: IF x>0 THEN x:=x+1 ELSE x:=0 IF x>0 x:=x+1 ELSE x:=0 ENDIF IF x=0 THEN WriteF('x is zero\n') IF x=0 WriteF('x is zero\n') ENDIF IF x<0 Write('Negative x\n') ELSEIF x>2000 Write('Too big x\n') ELSEIF (x=2000) OR (x=0) Write('Worrying x\n') ENDIF IF x>0 IF x>2000 WriteF('Big x\n') ELSE WriteF('OK x\n') ENDIF ELSE IF x<-800 THEN WriteF('Small x\n') ELSE Write('Negative OK x') ENDIF In the last example there are @{fg shine}nested@{fg text} @{b}IF@{ub} blocks (i.e., an @{b}IF@{ub} block within an @{b}IF@{ub} block). There is no ambiguity in which @{b}ELSE@{ub} or @{b}ELSEIF@{ub} parts belong to which @{b}IF@{ub} block because the beginning and end of the @{b}IF@{ub} blocks are clearly marked. For instance, the first @{b}ELSE@{ub} line can only be interpreted as being part of the innermost @{b}IF@{ub} block. As a matter of style the conditions on the @{b}IF@{ub} and @{b}ELSEIF@{ub} parts should not @{fg shine}overlap@{fg text} (i.e., at most one of the conditions should be true). If they do, however, the first one will take precedence. Therefore, the following two fragments of E code do the same thing: IF x>0 WriteF('x is bigger than zero\n') ELSEIF x>200 WriteF('x is bigger than 200\n') ELSE WriteF('x is too small\n') ENDIF IF x>0 WriteF('x is bigger than zero\n') ELSE WriteF('x is too small\n') ENDIF The @{b}ELSEIF@{ub} part of the first fragment checks whether @{b}x@{ub} is greater than 200. But, if it is, the check in the @{b}IF@{ub} part would have been true (@{b}x@{ub} is certainly greater than zero if it's greater than 200), and so only the code in the @{b}IF@{ub} part is executed. The whole @{b}IF@{ub} block behaves as if the @{b}ELSEIF@{ub} was not there. @EndNode @Node "IF expression" "beginner.guide/IF expression" @Next "SELECT block" @Prev "IF block" @Toc "Conditional Block" @{b}IF@{ub} expression ------------- @{b}IF@{ub} is such a commonly used construction that there is also an @{b}IF@{ub} expression. The @{b}IF@{ub} block is a statement and it controls which lines of code are executed, whereas the @{b}IF@{ub} expression is an expression and it controls its own value. For example, the following @{b}IF@{ub} block: IF x>0 y:=x+1 ELSE y:=0 ENDIF can be written more succinctly using an @{b}IF@{ub} expression: y:=(IF x>0 THEN x+1 ELSE 0) The parentheses are unnecessary but they help to make the example more readable. Since the @{b}IF@{ub} block is just choosing between two assignments to @{b}y@{ub} it isn't really the lines of code that are different (they are both assignments), rather it is the values that are assigned to @{b}y@{ub} that are different. The @{b}IF@{ub} expression makes this similarity very clear. It chooses the @{i}value@{ui} to be assigned in just the same way that the @{b}IF@{ub} block choose the @{i}assignment@{ui}. As you can see, @{b}IF@{ub} expressions are written like the horizontal form of the @{b}IF@{ub} block. However, there must be an @{b}ELSE@{ub} part and there can be no @{b}ELSEIF@{ub} parts. This means that the expression will always have a value, and it isn't cluttered with lots of cases. Don't worry too much about @{b}IF@{ub} expressions, since there are only useful in a handful of cases and can always be rewritten as a more wordy @{b}IF@{ub} block. Having said that they are very elegant and a lot more readable than the equivalent @{b}IF@{ub} block. @EndNode @Node "SELECT block" "beginner.guide/SELECT block" @Next "SELECT..OF block" @Prev "IF expression" @Toc "Conditional Block" @{b}SELECT@{ub} block ------------ The @{b}SELECT@{ub} block has the following form: SELECT @{fg shine}variable@{fg text} CASE @{fg shine}expressionA@{fg text} @{fg shine}statementsA@{fg text} CASE @{fg shine}expressionB@{fg text} @{fg shine}statementsB@{fg text} DEFAULT @{fg shine}statementsC@{fg text} ENDSELECT The value of the selection variable (denoted by @{fg shine}variable@{fg text} in the @{b}SELECT@{ub} part) is compared with the value of the expression in each of the @{b}CASE@{ub} parts in turn. If there's a match, the statements in the (first) matching @{b}CASE@{ub} part are executed. There can be any number of @{b}CASE@{ub} parts between the @{b}SELECT@{ub} and @{b}DEFAULT@{ub} parts. If there is no match, the statements in the @{b}DEFAULT@{ub} part are executed. There does not need to be a @{b}DEFAULT@{ub} part but if one is present it must be the last part (immediately before the @{b}ENDSELECT@{ub}). It should be clear that @{b}SELECT@{ub} blocks can be rewritten as @{b}IF@{ub} blocks, with the checks on the @{b}IF@{ub} and @{b}ELSEIF@{ub} parts being equality checks. For example, the following code fragments are equivalent: SELECT x CASE 22 WriteF('x is 22\n') CASE (y+z)/2 WriteF('x is (y+x)/2\n') DEFAULT WriteF('x isn't anything significant\n') ENDSELECT IF x=22 WriteF('x is 22\n') ELSEIF x=(y+z)/2 WriteF('x is (y+x)/2\n') ELSE WriteF('x isn't anything significant\n') ENDIF Notice that the @{b}IF@{ub} and @{b}ELSEIF@{ub} parts come from the @{b}CASE@{ub} parts, the @{b}ELSE@{ub} part comes from the @{b}DEFAULT@{ub} part, and the order of the parts is preserved. The advantage of the @{b}SELECT@{ub} block is that it's much easier to see that the value of @{b}x@{ub} is being tested all the time, and also we don't have to keep writing @{b}x=@{ub} in the checks. @EndNode @Node "SELECT..OF block" "beginner.guide/SELECT..OF block" @Prev "SELECT block" @Toc "Conditional Block" @{b}SELECT..OF@{ub} block ---------------- The @{b}SELECT..OF@{ub} block is a bit more complicated than the normal @{b}SELECT@{ub} block, but can be very useful. It has the following form: SELECT @{fg shine}maxrange@{fg text} OF @{fg shine}expression@{fg text} CASE @{fg shine}constA@{fg text} @{fg shine}statementsA@{fg text} CASE @{fg shine}constB1@{fg text} TO @{fg shine}constB2@{fg text} @{fg shine}statementsB@{fg text} CASE @{fg shine}range1@{fg text}, @{fg shine}range2@{fg text} @{fg shine}statementsC@{fg text} DEFAULT @{fg shine}statementsD@{fg text} ENDSELECT The value to be matched is @{fg shine}expression@{fg text}, which can be any expression, not just a variable like in the normal @{b}SELECT@{ub} block. However, the @{fg shine}maxrange@{fg text}, @{fg shine}constA@{fg text}, @{fg shine}constB1@{fg text} and @{fg shine}constB2@{fg text} must all be explicit numbers, i.e., constants (see @{"Constants" Link "Constants"}). @{fg shine}maxrange@{fg text} must be a positive constant and the other constants must be between zero and @{fg shine}maxrange@{fg text} (including zero but excluding @{fg shine}maxrange@{fg text}). The @{b}CASE@{ub} values to be matched are specified using @{fg shine}ranges@{fg text}. A simple range is a single constant (the first @{b}CASE@{ub} above). The more general range is shown in the second @{b}CASE@{ub}, using the @{b}TO@{ub} keyword (@{fg shine}constB2@{fg text} must be greater than @{fg shine}constB1@{fg text}). A general @{b}CASE@{ub} in the @{b}SELECT..OF@{ub} block can specify a number of possible ranges to match against by separating each range with a comma, as in the third @{b}CASE@{ub} above. For example, the following @{b}CASE@{ub} lines are equivalent and can be used to match any number from one to five (inclusive): CASE 1 TO 5 CASE 1, 2, 3, 4, 5 CASE 1 TO 3, 3 TO 5 CASE 1, 2 TO 3, 4, 5 CASE 1, 5, 2, 4, 3 CASE 2 TO 3, 5, 1, 4 If the value of the @{fg shine}expression@{fg text} is less than zero, greater than or equal to @{fg shine}maxrange@{fg text}, or it does not match any of the constants in the @{b}CASE@{ub} ranges, then the statements in the @{b}DEFAULT@{ub} part are executed. Otherwise the statements in the first matching @{b}CASE@{ub} part are executed. As in the normal @{b}SELECT@{ub} block, there does not need to be a @{b}DEFAULT@{ub} part. The following @{b}SELECT..OF@{ub} block prints the (numeric) day of the month nicely: SELECT 32 OF day CASE 1, 21, 31 WriteF('The \dst day of the month\n', day) CASE 2, 22 WriteF('The \dnd day of the month\n', day) CASE 3, 23 WriteF('The \drd day of the month\n', day) CASE 4 TO 20, 24 TO 30 WriteF('The \dth day of the month\n', day) DEFAULT WriteF('Error: invalid day=\d\n', day) ENDSELECT The @{fg shine}maxrange@{fg text} for this block is 32, since 31 is the maximum of the values used in the @{b}CASE@{ub} parts. If the value of @{b}day@{ub} was 100, for instance, then the statements in the @{b}DEFAULT@{ub} part would be executed, signalling an invalid day. This example can be rewritten as an @{b}IF@{ub} block: IF (day=1) OR (day=21) OR (day=31) WriteF('The \dst day of the month\n', day) ELSEIF (day=2) OR (day=22) WriteF('The \dnd day of the month\n', day) ELSEIF (day=3) OR (day=23) WriteF('The \drd day of the month\n', day) ELSEIF ((4<=day) AND (day<=20)) OR ((24<=day) AND (day<=30)) WriteF('The \dth day of the month\n', day) ELSE WriteF('Error: invalid day=\d\n', day) ENDIF The comma separating two ranges in the @{b}CASE@{ub} part has been replaced by an @{b}OR@{ub} of two comparison expressions, and the @{b}TO@{ub} range has been replaced by an @{b}AND@{ub} of two comparisons. (It is worth noticing the careful bracketing of the resulting expressions.) Clearly, the @{b}SELECT..OF@{ub} block is much more readable than the equivalent @{b}IF@{ub} block. It is also a lot faster, mainly because none of the comparisons present in @{b}IF@{ub} block have to be done in the @{b}SELECT..OF@{ub} version. Instead the value to be matched is used to immediately locate the correct @{b}CASE@{ub} part. However, it's not all good news: the @{fg shine}maxrange@{fg text} value directly affects the size of compiled executable, so it is recommended that @{b}SELECT..OF@{ub} blocks be used only with small @{fg shine}maxrange@{fg text} values. See the `Reference Manual' for more details. @EndNode @Node "Loops" "beginner.guide/Loops" @Prev "Conditional Block" @Toc "Program Flow Control" Loops ===== Loops are all about making a program execute a series of statements over and over again. Probably the simplest loop to understand is the @{b}FOR@{ub} loop. There are other kinds of loops, but they are easier to understand once we know how to use a @{b}FOR@{ub} loop. @{" FOR loop " Link "FOR loop"} @{" WHILE loop " Link "WHILE loop"} @{" REPEAT..UNTIL loop " Link "REPEAT..UNTIL loop"} @EndNode @Node "FOR loop" "beginner.guide/FOR loop" @Next "WHILE loop" @Toc "Loops" @{b}FOR@{ub} loop -------- If you want to write a program to print the numbers one to 100 you can either type each number and wear out your fingers, or you can use a single variable and a small @{b}FOR@{ub} loop. Try compiling this E program (the space after the @{b}\d@{ub} in the string is needed to separate the printed numbers): PROC main() DEF x FOR x:=1 TO 100 WriteF('\d ', x) ENDFOR WriteF('\n') ENDPROC When you run this you'll get all the numbers from one to 100 printed, just like we wanted. It works by using the (local) variable @{b}x@{ub} to hold the number to be printed. The @{b}FOR@{ub} loop starts off by setting the value of @{b}x@{ub} to one (the bit that looks like an assignment). Then the statements between the @{b}FOR@{ub} and @{b}ENDFOR@{ub} lines are executed (so the value of @{b}x@{ub} gets printed). When the program reaches the @{b}ENDFOR@{ub} it increments @{b}x@{ub} and checks to see if it is bigger than 100 (the limit we set with the @{b}TO@{ub} part). If it is, the loop is finished and the statements after the @{b}ENDFOR@{ub} are executed. If, however, it wasn't bigger than 100, the statements between the @{b}FOR@{ub} and @{b}ENDFOR@{ub} lines are executed all over again, and this time @{b}x@{ub} is one bigger since it has been incremented. In fact, this program does exactly the same as the following program (the @{b}...@{ub} is not E code--it stands for the 97 other @{b}WriteF@{ub} statements): PROC main() WriteF('\d ', 1) WriteF('\d ', 2) ... WriteF('\d ', 100) WriteF('\n') ENDPROC The general form of the @{b}FOR@{ub} loop is as follows: FOR @{fg shine}var@{fg text} := @{fg shine}expressionA@{fg text} TO @{fg shine}expressionB@{fg text} STEP @{fg shine}number@{fg text} @{fg shine}statements@{fg text} ENDFOR The @{fg shine}var@{fg text} bit stands for the loop variable (in the example above this was @{b}x@{ub}). The @{fg shine}expressionA@{fg text} bit gives the start value for the loop variable and the @{fg shine}expressionB@{fg text} bit gives the last allowable value for it. The @{b}STEP@{ub} part allows you to specify the value (given by @{fg shine}number@{fg text}) which is added to the loop variable on each loop. Unlike the values given for the start and end (which can be arbitrary expressions), the @{b}STEP@{ub} value must be a constant (see @{"Constants" Link "Constants"}). The @{b}STEP@{ub} value defaults to one if the @{b}STEP@{ub} part is omitted (as in our example). Negative @{b}STEP@{ub} values are allowed, but in this case the check used at the end of each loop is whether the loop variable is @{i}less than@{ui} the value in the @{b}TO@{ub} part. Zero is not allowed as the @{b}STEP@{ub} value. As with the @{b}IF@{ub} block there is a horizontal form of a @{b}FOR@{ub} loop: FOR @{fg shine}var@{fg text} := @{fg shine}expA@{fg text} TO @{fg shine}expB@{fg text} STEP @{fg shine}expC@{fg text} DO @{fg shine}statement@{fg text} @EndNode @Node "WHILE loop" "beginner.guide/WHILE loop" @Next "REPEAT..UNTIL loop" @Prev "FOR loop" @Toc "Loops" @{b}WHILE@{ub} loop ---------- The @{b}FOR@{ub} loop used a loop variable and checked whether that variable had gone past its limit. A @{b}WHILE@{ub} loop allows you to specify your own loop check. For instance, this program does the same as the program in the previous section: PROC main() DEF x x:=1 WHILE x<=100 WriteF('\d ', x) x:=x+1 ENDWHILE WriteF('\n') ENDPROC We've replaced the @{b}FOR@{ub} loop with an initialisation of @{b}x@{ub} and a @{b}WHILE@{ub} loop with an extra statement to increment @{b}x@{ub}. We can now see the inner workings of the @{b}FOR@{ub} loop and, in fact, this is exactly how the @{b}FOR@{ub} loop works. It is important to know that our check, @{b}x<=100@{ub}, is done before the loop statements are executed. This means that the loop statements might not even be executed once. For instance, if we'd made the check @{b}x>=100@{ub} it would be false at the beginning of the loop (since @{b}x@{ub} is initialised to one in the assignment before the loop). Therefore, the loop would have terminated immediately and execution would pass straight to the statements after the @{b}ENDWHILE@{ub}. Here's a more complicated example: PROC main() DEF x,y x:=1 y:=2 WHILE (x<10) AND (y<10) WriteF('x is \d and y is \d\n', x, y) x:=x+2 y:=y+2 ENDWHILE ENDPROC We've used two (local) variables this time. As soon as one of them is ten or more the loop is terminated. A bit of inspection of the code reveals that @{b}x@{ub} is initialised to one, and keeps having two added to it. It will, therefore, always be an odd number. Similarly, @{b}y@{ub} will always be even. The @{b}WHILE@{ub} check shows that it won't print any numbers which are greater than or equal to ten. From this and the fact that @{b}x@{ub} starts at one and @{b}y@{ub} at two we can decide that the last pair of numbers will be seven and eight. Run the program to confirm this. It should produce the following output: x is 1 and y is 2 x is 3 and y is 4 x is 5 and y is 6 x is 7 and y is 8 Like the @{b}FOR@{ub} loop, there is a horizontal form of the @{b}WHILE@{ub} loop: WHILE @{fg shine}expression@{fg text} DO @{fg shine}statement@{fg text} Loop termination is always a big problem. @{b}FOR@{ub} loops are guaranteed to eventually reach their limit (if you don't mess with the loop variable, that is). However, @{b}WHILE@{ub} loops (and all other loops) may go on forever and never terminate. For example, if the loop check were @{b}1<2@{ub} it would always be true and nothing the loop could do would prevent it being true! You must therefore take care that you make sure your loops terminate in some way if you want to program to finish. There is a sneaky way of terminating loops using the @{b}JUMP@{ub} statement, but we'll ignore that for now. @EndNode @Node "REPEAT..UNTIL loop" "beginner.guide/REPEAT..UNTIL loop" @Prev "WHILE loop" @Toc "Loops" @{b}REPEAT..UNTIL@{ub} loop ------------------ A @{b}REPEAT..UNTIL@{ub} loop is very similar to a @{b}WHILE@{ub} loop. The only difference is where you specify the loop check, and when and how the check is performed. To illustrate this, here's the program from the previous two sections rewritten using a @{b}REPEAT..UNTIL@{ub} loop (try to spot the subtle differences): PROC main() DEF x x:=1 REPEAT WriteF('\d ', x) x:=x+1 UNTIL x>100 WriteF('\n') ENDPROC Just as in the @{b}WHILE@{ub} loop version we've got an initialisation of @{b}x@{ub} and an extra statement in the loop to increment @{b}x@{ub}. However, this time the loop check is specified at the end of the loop (in the @{b}UNTIL@{ub} part), and the check is only performed at the end of each loop. This difference means that the code in a @{b}REPEAT..UNTIL@{ub} loop will be executed at least once, whereas the code in a @{b}WHILE@{ub} loop may never be executed. Also, the logical sense of the check follows the English: a @{b}REPEAT..UNTIL@{ub} loop executes @{i}until@{ui} the check is true, whereas the @{b}WHILE@{ub} loop executes @{i}while@{ui} the check is true. Therefore, the @{b}REPEAT..UNTIL@{ub} loop executes while the check is false! This may seem confusing at first, but just remember to read the code as if it were English and you'll get the correct interpretation. @EndNode @Node "Summary" "beginner.guide/Summary" @Next "Format and Layout" @Prev "Program Flow Control" @Toc "Main" Summary ******* This is the end of Part One, which was hopefully enough to get you started. If you've grasped the main concepts you are good position to attack Part Two, which covers the E language in more detail. This is probably a good time to look at the different parts of one of the examples from the previous sections, since we've now used quite a bit of E. The following examination uses the @{b}WHILE@{ub} loop example. Just to make things easier to follow, each line has been numbered (don't try to compile it with the line numbers on!). 1. PROC main() 2. DEF x,y 3. x:=1 4. y:=2 5. WHILE (x<10) AND (y<10) 6. WriteF('x is \d and y is \d\n', x, y) 7. x:=x+2 8. y:=y+2 9. ENDWHILE 10. ENDPROC Hopefully, you should be able to recognise all the features listed in the table below. If you don't then you might need to go back over the previous chapters, or find a much better programming guide than this! @{i}Line(s)@{ui} @{i}Observation@{ui} --------------------------------------------------------- 1-10 The procedure definition. 1 The declaration of the procedure @{b}main@{ub}, with no parameters. 2 The declaration of local variables @{b}x@{ub} and @{b}y@{ub}. 3, 4 Initialisation of @{b}x@{ub} and @{b}y@{ub} using assignment statements. 5-9 The @{b}WHILE@{ub} loop. 5 The loop check for the @{b}WHILE@{ub} loop using the logical operator @{b}AND@{ub}, the comparison operator @{b}<@{ub}, and parentheses to group the expression. 6 The call to the (built-in) procedure @{b}WriteF@{ub} using parameters. Notice the string, the place holders for numbers, @{b}\d@{ub}, and the linefeed, @{b}\n@{ub}. 7, 8 Assignments to @{b}x@{ub} and @{b}y@{ub}, adding two to their values. 9 The marker for the end of the @{b}WHILE@{ub} loop. 10 The marker for the end of the procedure. @EndNode @Node "Format and Layout" "beginner.guide/Format and Layout" @Next "Procedures and Functions" @Prev "Summary" @Toc "Main" Format and Layout ***************** In this chapter we'll look at the rules which govern the format and layout of E code. In the previous Part we saw examples of E code that were quite nicely indented and the structure of the program was easily visible. This was just a convention and the E language does not constrain you to write code in this way. However, there are certain rules that must be followed. (This chapter refers to some concepts and parts of the E language which were not covered in Part One. Don't let this put you off--those things will be dealt with in later chapters, and it's maybe a good idea to read this chapter again when they have been.) @{" Identifiers " Link "Identifiers"} @{" Statements " Link "Statements"} @{" Spacing and Separators " Link "Spacing and Separators"} @{" Comments " Link "Comments"} @EndNode @Node "Identifiers" "beginner.guide/Identifiers" @Next "Statements" @Toc "Format and Layout" Identifiers =========== An @{fg shine}identifier@{fg text} is a word which the compiler must interpret rather than treating literally. For instance, a variable is an identifier, as is a keyword (e.g., @{b}IF@{ub}), but anything in a string is not (e.g., @{b}fred@{ub} in @{b}'fred and wilma'@{ub} is not an identifier). Identifiers can be made up of upper- or lower-case letters, numbers and underscores (the @{b}_@{ub} character). There are only two constraints: 1. The first character cannot be a number (this would cause confusion with numeric constants). 2. The case of the first few characters of identifiers is significant. For keywords (e.g., @{b}ENDPROC@{ub}), constants (e.g., @{b}TRUE@{ub}) and assembly mnemonics (e.g., @{b}MOVE.L@{ub}) the first two characters must both be uppercase. For E built-in or Amiga system procedures/functions the first character must be uppercase and the second must be lowercase. For all other identifiers (i.e., local, global and procedure parameter variables, object names and element names, procedure names and code labels) the first character must be lowercase. Apart from these constraints you are free to write identifiers how you like, although it's arguably more tasteful to use all lowercase for variables and all uppercase for keywords and constants. @EndNode @Node "Statements" "beginner.guide/Statements" @Next "Spacing and Separators" @Prev "Identifiers" @Toc "Format and Layout" Statements ========== A @{fg shine}statement@{fg text} is normally a single line of an instruction to the computer. Each statement normally occupies a single line. If a procedure is thought of as a paragraph then a statement is a sentence. Variables, expressions and keywords are the words which make up the sentence. So far in our examples we have met only two kinds of statement: the single line statement and the multi-line statement. The assignments we have seen were single line statements, and the vertical form of the @{b}IF@{ub} block is a multi-line statement. The horizontal form of the @{b}IF@{ub} block was actually the single line statement form of the @{b}IF@{ub} block. Notice that statements can be built up from other statements, as is the case for @{b}IF@{ub} blocks. The code parts between the @{b}IF@{ub}, @{b}ELSEIF@{ub}, @{b}ELSE@{ub} and @{b}ENDIF@{ub} lines are sequences of statements. Single line statements can often be very short, and you may be able to fit several of them onto an single line without the line getting too long. To do this in E you use a semi-colon (the @{b};@{ub} character) to separate each statement on the line. For example, the following code fragments are equivalent: fred(y,z) y:=x x:=z+1 fred(y,z); y:=x; x:=z+1 On the other hand you may want to split a long statement over several lines. This is a bit more tricky because the compiler needs to see that you haven't finished the statement when it gets to the end of a line. Therefore you can only break a statement at certain places. The most common place is after a comma that is part of the statement (like in a procedure call with more than one parameter), but you can also split a line after binary operators and anywhere between opening and closing brackets. The following examples are rather silly but show some allowable line breaking places. fred(a, b, c, d, e, f) /* After a comma */ x:=x+ y+ z /* After a binary operator */ x:=(1+2 +3) /* Between open...close brackets */ list:= [ 1,2, [3,4], ] /* Between open...close brackets */ The simple rule is this: if a complete line can be interpreted as a statement then it will be, otherwise it will be interpreted as part of a statement which continues on the following lines. Strings may also get a bit long. You can split them over several lines by breaking them into several separate strings and using @{b}+@{ub} between them. If a line ends with a @{b}+@{ub} and the previous thing on the line was a string then the E compiler takes the next string to be a continuation. The following calls to @{b}WriteF@{ub} print the same thing: WriteF('This long string can be broken over several lines.\n') WriteF('This long string ' + 'can be broken over several lines.\n') WriteF('This long' + ' string can be ' + 'broken over several ' + 'lines.\n') @EndNode @Node "Spacing and Separators" "beginner.guide/Spacing and Separators" @Next "Comments" @Prev "Statements" @Toc "Format and Layout" Spacing and Separators ====================== The examples we've seen so far used a rigid indentation convention which was intended to illuminate the structure of the program. This was just a convention, and the E language places no constraints on the amount of @{fg shine}whitespace@{fg text} (spaces, tabs and linefeeds) you place between statements. However, within statements you must supply enough spacing to make the statement readable. This generally means that you must put whitespace between adjacent identifiers which start or end with a letter, number or underscore (so that the compiler does not think it's one big identifier!). In practice this means you should put a space after a keyword if it might run into a variable or procedure name. Most other times (like in expressions) identifiers are separated by non-identifier characters (a comma, parenthesis or other symbol). @EndNode @Node "Comments" "beginner.guide/Comments" @Prev "Spacing and Separators" @Toc "Format and Layout" Comments ======== A @{fg shine}comment@{fg text} is something that the E compiler ignores and is only there to help the reader. Remember that one day in the future you may be the reader, and it may be quite hard to decipher your own code without a few decent comments! Comments are therefore pretty important. You can write comments anywhere you can write whitespace that isn't part of a string. There are two kinds of comment: one uses @{b}/*@{ub} to mark the start of the comment text and @{b}*/@{ub} to mark the end, and the other uses @{b}->@{ub} to mark the start, with the comment text continuing to the end of the line. You must be careful not to write @{b}/*@{ub}, @{b}*/@{ub} or @{b}->@{ub} as part of the comment text, unless part of a nested comment. In practice a comment is best put on a line by itself or after the end of the code on a line. /* This line is a comment */ x:=1 /* This line contains an assignment then a comment */ /* y:=2 /* This whole line is a comment with a nested comment */*/ x:=1 -> Assignment then a comment -> y:=2 /* A nested comment comment */ @EndNode @Node "Procedures and Functions" "beginner.guide/Procedures and Functions" @Next "Constants" @Prev "Format and Layout" @Toc "Main" Procedures and Functions ************************ A @{fg shine}function@{fg text} is a procedure which returns a value. This value can be any expression so it may depend on the parameters with which the function was called. For instance, the addition operator @{b}+@{ub} can be thought of as a function which returns the sum of its two parameters. @{" Functions " Link "Functions"} @{" One-Line Functions " Link "One-Line Functions"} @{" Default Arguments " Link "Default Arguments"} @{" Multiple Return Values " Link "Multiple Return Values"} @EndNode @Node "Functions" "beginner.guide/Functions" @Next "One-Line Functions" @Toc "Procedures and Functions" Functions ========= We can define our own addition function, @{b}add@{ub}, in a very similar way to the definition of a procedure. (The only difference is that a function explicitly returns a value.) PROC main() DEF sum sum:=12+79 WriteF('Using +, sum is \d\n', sum) sum:=add(12,79) WriteF('Using add, sum is \d\n', sum) ENDPROC PROC add(x, y) DEF s s:=x+y ENDPROC s This should generate the following output: Using +, sum is 91 Using add, sum is 91 In the procedure @{b}add@{ub} the value @{b}s@{ub} is returned using the @{b}ENDPROC@{ub} label. The value returned from @{b}add@{ub} can be used in expressions, just like any other value. You do this by writing the procedure call where you want the value to be. In the above example we wanted the value to be assigned to @{b}sum@{ub} so we wrote the call to @{b}add@{ub} on the right-hand side of the assignment. Notice the similarities between the uses of @{b}+@{ub} and @{b}add@{ub}. In general, @{b}add(a,b)@{ub} can be used in exactly the same places that @{b}a+b@{ub} can (more precisely, it can be used anywhere @{b}(a+b)@{ub} can be used). The @{b}RETURN@{ub} keyword can also be used to return values from a procedure. If the @{b}ENDPROC@{ub} method is used then the value is returned when the procedure reaches the end of its code. However, if the @{b}RETURN@{ub} method is used the value is returned immediately at that point and no more of the procedure's code is executed. Here's the same example using @{b}RETURN@{ub}: PROC add(x, y) DEF s s:=x+y RETURN s ENDPROC The only difference is that you can write @{b}RETURN@{ub} anywhere in the code part of a procedure and it finishes the execution of the procedure at that point (rather than execution finishing when it reaches the end of the code). In fact, you can use @{b}RETURN@{ub} in the @{b}main@{ub} procedure to prematurely finish the execution of a program. Here's a slightly more complicated use of @{b}RETURN@{ub}: PROC limitedadd(x,y) IF x>10000 RETURN 10000 ELSEIF x<-10000 RETURN -10000 ELSE RETURN x+y ENDIF /* The following code is redundant */ x:=1 IF x=1 THEN RETURN 9999 ELSE RETURN -9999 ENDPROC This function checks to see if @{b}x@{ub} is greater than 10,000 or less than -10,000, and if it is a limited value is returned (which is generally not the correct sum!). If @{b}x@{ub} is between -10,000 and 10,000 the correct answer is returned. The lines after the first @{b}IF@{ub} block will never get executed because execution will have finished at one of the @{b}RETURN@{ub} lines. Those lines are therefore just a waste of compiler time and can safely be omitted (as the comment suggests). If no value is given with the @{b}ENDPROC@{ub} or @{b}RETURN@{ub} keyword then zero is returned. Therefore, all procedures are actually functions (and the terms @{fg shine}procedure@{fg text} and @{fg shine}function@{fg text} will tend to be used interchangeably). So, what happens to the value when you write a procedure call on a line by itself, not in an expression? Well, as we will see, the value is simply discarded (see @{"Turning an Expression into a Statement" Link "Turning an Expression into a Statement"}). This is what happened in the previous examples when we called the procedures @{b}fred@{ub} and @{b}WriteF@{ub}. @EndNode @Node "One-Line Functions" "beginner.guide/One-Line Functions" @Next "Default Arguments" @Prev "Functions" @Toc "Procedures and Functions" One-Line Functions ================== Just as the @{b}IF@{ub} block and @{b}FOR@{ub} loop have horizontal, single line forms, so does a procedure definition. The general form is: PROC @{fg shine}name@{fg text} (@{fg shine}arg1@{fg text}, @{fg shine}arg2@{fg text}, ...) IS @{fg shine}expression@{fg text} Alternatively, the @{b}RETURN@{ub} keyword can be used: PROC @{fg shine}name@{fg text} (@{fg shine}arg1@{fg text}, @{fg shine}arg2@{fg text}, ...) RETURN @{fg shine}expression@{fg text} At first sight this might seem pretty unusable, but it is useful for very simple functions and our @{b}add@{ub} function in the previous section is a good example. If you look closely at the original definition you'll see that the local variable @{b}s@{ub} wasn't really needed. Here's the one-line definition of @{b}add@{ub}: PROC add(x,y) IS x+y @EndNode @Node "Default Arguments" "beginner.guide/Default Arguments" @Next "Multiple Return Values" @Prev "One-Line Functions" @Toc "Procedures and Functions" Default Arguments ================= Sometimes a procedure (or function) will quite often be called with a particular (constant) value for one of its parameters, and it might be nice if you didn't have to fill this value in all the time. Luckily, E allows you to define @{fg shine}default@{fg text} values for a procedure's parameters when you define the procedure. You can then just leave out that parameter when you call the procedure and it will default to the value you defined for it. Here's a simple example: PROC play(track=1) WriteF('Starting to play track \d\n', track) /* Rest of the code... */ ENDPROC PROC main() play(1) -> Start playing from track 1 play(6) -> Start playing from track 6 play() -> Start playing from track 1 ENDPROC This is an outline of a program to control something like a CD player. The @{b}play@{ub} procedure has one parameter, @{b}track@{ub}, which represents the first track that should be played. Often, though, you just tell the CD player to play, and don't specify a particular track. In this case, play starts from the first track. This is exactly what happens in the example above: the @{b}track@{ub} parameter has a default value of 1 defined for it (the @{b}=1@{ub} in the definition of the @{b}play@{ub} procedure), and the third call to @{b}play@{ub} in @{b}main@{ub} does not specify a value for @{b}track@{ub}, so the default value is used. There are two constraints on the use of default arguments: 1. Any number of the parameters of a procedure may have default values defined for them, although they may only be the right-most parameters. This means that for a three parameter procedure, the second parameter can have a default value only if the last parameter does as well, and the first can have one only if both the others do. This should not be a big problem because you can always reorder the parameters in the procedure definition. The following examples show legal definitions of procedures with default arguments: PROC fred(x, y, z) IS x+y+z -> No defaults PROC fred(x, y, z=1) IS x+y+z -> z defaults to 1 PROC fred(x, y=23, z=1) IS x+y+z -> y and z have defaults PROC fred(x=9, y=23, z=1) IS x+y+z -> All have defaults On the other hand, these definitions are all illegal: PROC fred(x, y=23, z) IS x+y+z -> Illegal: no z default PROC fred(x=9, y, z=1) IS x+y+z -> Illegal: no y default 2. When you call a procedure which has default arguments you can only leave out the right-most parameters. This means that for a three parameter procedure with all three parameters having default values, you can leave out the second parameter in a call to this procedure only if you also leave out the third parameter. The first parameter may be left out only if both the others are, too. The following example shows which parameters are considered defaults: PROC fred(x, y=23, z=1) WriteF('x is \d, y is \d, z is \d\n', x, y, z) ENDPROC PROC main() fred(2, 3, 4) -> No defaults used fred(2, 3) -> z defaults to 1 fred(2) -> y and z default fred() -> Illegal: x has no default ENDPROC In this example, you cannot leave out the @{b}y@{ub} parameter in a call to @{b}fred@{ub} without leaving out the @{b}z@{ub} parameter as well. To make @{b}y@{ub} have its default value and @{b}z@{ub} some value other than its default you need to supply the @{b}y@{ub} value explicitly in the call: fred(2, 23, 9) -> Need to supply 23 for y These constraints are necessary in order to make procedure calls unambiguous. Consider a three-parameter procedure with default values for two of the parameters. If it is called with only two parameters then, without these constraints, it would not be clear which two parameters had been supplied and which had not. If, however, the procedure were defined and called according to these constraints, then it must be the third parameter that needs to be defaulted (and the two parameters with default values must be the last two). @EndNode @Node "Multiple Return Values" "beginner.guide/Multiple Return Values" @Prev "Default Arguments" @Toc "Procedures and Functions" Multiple Return Values ====================== So far we've only seen functions which return only one value, since this is something common to most programming languages. However, E allows you to return up to three values from a function. To do this you list the values separated by commas after the @{b}ENDPROC@{ub}, @{b}RETURN@{ub} or @{b}IS@{ub} keyword, where you would normally have specified only one value. A good example is a function which manipulates a screen coordinate, which is a pair of values: the x- and y-coordinates. PROC movediag(x, y) IS x+8, y+4 All this function does is add 8 to the x-coordinate and 4 to the y-coordinate. To get to the return values other than the first one you must use a multiple-assignment statement: PROC main() DEF a, b a, b:=movediag(10, 3) /* Now a should be 10+8, and b should be 3+4 */ WriteF('a is \d, b is \d\n', a, b) ENDPROC @{b}a@{ub} is assigned the first return value and @{b}b@{ub} is assigned the second. You don't need to use all the return values from a function, so the assignment in the example above could have assigned only to @{b}a@{ub} (in which case it would not be a multiple-assignment anymore). A multiple-assignment makes sense only if the right-hand side is a function call, so don't expect things like the following example to set @{b}b@{ub} properly: a,b:=6+movediag(10,3) -> No obvious value for b If you use a function with more than one return value in any other expression (i.e., something which is not the right-hand side of an assignment), then only the first return value is used. For this reason the return values of a function have special names: the first return value is called the @{fg shine}regular@{fg text} value of the function, and the other values are the @{fg shine}optional@{fg text} values. PROC main() DEF a, b /* The next two lines ignore the second return value */ a:=movediag(10, 3) WriteF('x-coord of movediag(21, 4) is \d\n', movediag(21,4)) ENDPROC @EndNode @Node "Constants" "beginner.guide/Constants" @Next "Types" @Prev "Procedures and Functions" @Toc "Main" Constants ********* A @{fg shine}constant@{fg text} is a value that does not change. A (literal) number like 121 is a good example of a constant--its value is always 121. We've already met another kind of constant: string constants (see @{"Strings" Link "Strings"}). As you can doubtless tell, constants are pretty important things. @{" Numeric Constants " Link "Numeric Constants"} @{" String Constants Special Character Sequences " Link "String Constants Special Character Sequences"} @{" Named Constants " Link "Named Constants"} @{" Enumerations " Link "Enumerations"} @{" Sets " Link "Sets"} @EndNode @Node "Numeric Constants" "beginner.guide/Numeric Constants" @Next "String Constants Special Character Sequences" @Toc "Constants" Numeric Constants ================= We've met a lot of numbers in the previous examples. Technically speaking, these were numeric constants (constant because they don't change value like a variable might). They were all decimal numbers, but you can use hexadecimal and binary numbers as well. There's also a way of specifying a number using characters. To specify a hexadecimal number you use a @{b}$@{ub} before the digits (and after the optional minus sign @{b}-@{ub} to represent a negative value). To specify a binary number you use a @{b}%@{ub} instead. Specifying numbers using characters is more complicated, because the base of this system is 256 (the base of decimal is ten, that of hexadecimal is 16 and that of binary is two). The digits are enclosed in double-quotes (the " character), and there can be at most four digits. Each digit is a character representing its ASCII value. Therefore, the character @{b}A@{ub} represents 65 and the character @{b}0@{ub} (zero) represents 48. This upshot of this is that character @{b}A@{ub} has ASCII value @{b}"A"@{ub} in E, and @{b}"0z"@{ub} represents ("0" * 256) + "z" = (48 * 256) + 122 = 12,410. However, you probably don't need to worry about anything other than the single character case, which gives you the ASCII value of the character. The following table shows the decimal value of several numeric constants. Notice that you can use upper- or lower-case letters for the hexadecimal constants. Obviously the case of characters is significant for character numbers. @{i}Number@{ui} @{i}Decimal value@{ui} ---------------------- 21 21 -143 -143 $1a 26 -$B1 -177 %1110 14 -%1010 -10 "z" 122 "Je" 19,045 -"A" -65 @EndNode @Node "String Constants Special Character Sequences" "beginner.guide/String Constants Special Character Sequences" @Next "Named Constants" @Prev "Numeric Constants" @Toc "Constants" String Constants: Special Character Sequences ============================================= We have seen that in a string the character sequence @{b}\n@{ub} means a linefeed (see @{"Strings" Link "Strings"}). There are several other similar such special character sequences which represent useful characters that can't be typed in a string. The following table shows all these sequences. Note that there are some other similar sequences which are used to control formatting with built-in procedures like @{b}WriteF@{ub}. These are listed where @{b}WriteF@{ub} and similar procedures are described (see @{"Input and output functions" Link "Input and output functions"}). @{i}Sequence@{ui} @{i}Meaning@{ui} -------------------------------------- \0 A null (ASCII zero) \a An apostrophe ' \b A carriage return (ASCII 13) \e An escape (ASCII 27) \n A linefeed (ASCII 10) \q A double quote (ASCII 34) \t A tab (ASCII 9) \\ A backslash \ An apostrophe can also be produced by typing two apostrophes in a row in a string. It's best to use this only in the middle of a string, where it's nice and obvious: WriteF('Here\as an apostrophe.\n') /* Using \a */ WriteF('Here''s another apostrophe.\n') /* Using '' */ @EndNode @Node "Named Constants" "beginner.guide/Named Constants" @Next "Enumerations" @Prev "String Constants Special Character Sequences" @Toc "Constants" Named Constants =============== It is often nice to be able to give names to certain constants. For instance, as we saw earlier, the truth value @{b}TRUE@{ub} actually represents the value -1, and @{b}FALSE@{ub} represents zero (see @{"Logic and comparison" Link "Logic and comparison"}). These are our first examples of named constants. To define your own you use the @{b}CONST@{ub} keyword as follows: CONST ONE=1, LINEFEED=10, BIG_NUM=999999 This has defined the constant @{b}ONE@{ub} to represent one, @{b}LINEFEED@{ub} ten and @{b}BIG_NUM@{ub} 999,999. Named constants must begin with two uppercase letters, as mentioned before (see @{"Identifiers" Link "Identifiers"}). You can use previously defined constants to give the value of a new constant, but in this case the definitions must occur on different @{b}CONST@{ub} lines. CONST ZERO=0 CONST ONE=ZERO+1 CONST TWO=ONE+1 The expression used to define the value of a constant can use only simple operators (no function calls) and constants. @EndNode @Node "Enumerations" "beginner.guide/Enumerations" @Next "Sets" @Prev "Named Constants" @Toc "Constants" Enumerations ============ Often you want to define a whole lot of constants and you just want them all to have a different value so you can tell them apart easily. For instance, if you wanted to define some constants to represent some famous cities and you only needed to know how to distinguish one from another then you could use an @{fg shine}enumeration@{fg text} like this: ENUM LONDON, MOSCOW, NEW_YORK, PARIS, ROME, TOKYO The @{b}ENUM@{ub} keyword begins the definitions (like the @{b}CONST@{ub} keyword does for an ordinary constant definition). The actual values of the constants start at zero and stretch up to five. In fact, this is exactly the same as writing: CONST LONDON=0, MOSCOW=1, NEW_YORK=2, PARIS=3, ROME=4, TOKYO=5 The enumeration does not have to start at zero, though. You can change the starting value at any point by specifying a value for an enumerated constant. For example, the following constant definitions are equivalent: ENUM APPLE, ORANGE, CAT=55, DOG, GOLDFISH, FRED=-2, BARNEY, WILMA, BETTY CONST APPLE=0, ORANGE=1, CAT=55, DOG=56, GOLDFISH=57, FRED=-2, BARNEY=-1, WILMA=0, BETTY=1 @EndNode @Node "Sets" "beginner.guide/Sets" @Prev "Enumerations" @Toc "Constants" Sets ==== Yet another kind of constant definition is the @{fg shine}set@{fg text} definition. This useful for defining flag sets, i.e., a number of options each of which can be on or off. The definition is like a simple enumeration, but using the @{b}SET@{ub} keyword and this time the values start at one and increase as powers of two (so the next value is two, the next is four, the next eight, and so on). Therefore, the following definitions are equivalent: SET ENGLISH, FRENCH, GERMAN, JAPANESE, RUSSIAN CONST ENGLISH=1, FRENCH=2, GERMAN=4, JAPANESE=8, RUSSIAN=16 However, the significance of the values it is best shown by using binary constants: CONST ENGLISH=%00001, FRENCH=%00010, GERMAN=%00100, JAPANESE=%01000, RUSSIAN=%10000 If a person speaks just English then we can use the constant @{b}ENGLISH@{ub}. If they also spoke Japanese then to represent this with a single value we'd normally need a new constant (something like @{b}ENG_JAP@{ub}). In fact, we'd probably need a constant for each combination of languages a person might know. However, with the set definition we can @{b}OR@{ub} the @{b}ENGLISH@{ub} and @{b}JAPANESE@{ub} values together to get a new value, @{b}%01001@{ub}, and this represents a set containing both @{b}ENGLISH@{ub} and @{b}JAPANESE@{ub}. On the other hand, to find out if someone speaks French we would @{b}AND@{ub} the value for the languages they know with @{b}%00010@{ub} (or the constant @{b}FRENCH@{ub}). (As you might have guessed, @{b}AND@{ub} and @{b}OR@{ub} are really bit-wise operators, not simply logical operators. See @{"Bitwise AND and OR" Link "Bitwise AND and OR"}.) Consider this program fragment: speak:=GERMAN OR ENGLISH OR RUSSIAN /* Speak any of these */ IF speak AND JAPANESE WriteF('Can speak in Japanese\n') ELSE WriteF('Unable to speak in Japanese\n') ENDIF IF speak AND (GERMAN OR FRENCH) WriteF('Can speak in German or French\n') ELSE WriteF('Unable to speak in German or French\n') ENDIF The assignment sets @{b}speak@{ub} to show that the person can speak in German, English or Russian. The first @{b}IF@{ub} block tests whether the person can speak in Japanese, and the second tests whether they can speak in German or French. When using sets be careful you don't get tempted to add values instead of @{b}OR@{ub}-ing them. Adding two different constants from the same set is the same as @{b}OR@{ub}-ing them, but adding a constant to itself isn't. This is not the only time addition doesn't give the same answer, but it's the most obvious. If you to stick to using @{b}OR@{ub} you won't have a problem. @EndNode @Node "Types" "beginner.guide/Types" @Next "More About Statements and Expressions" @Prev "Constants" @Toc "Main" Types ***** We've already met the @{b}LONG@{ub} type and found that this was the normal type for variables (see @{"Variable types" Link "Variable types"}). The types @{b}INT@{ub} and @{b}LIST@{ub} were also mentioned. Learning how to use types in an effective and readable way is very important. The type of a variable (as well as its name) can give clues to the reader about how or for what it is used. There are also more fundamental reasons for needing types, e.g., to logically group data using objects (see @{"OBJECT Type" Link "OBJECT Type"}). This is a very large chapter and you might like to take it slowly. One of the most important things to get to grips with is @{fg shine}pointers@{fg text}. Concentrate on trying to understand these as they play a large part in any kind of system programming. @{" LONG Type " Link "LONG Type"} @{" PTR Type " Link "PTR Type"} @{" ARRAY Type " Link "ARRAY Type"} @{" OBJECT Type " Link "OBJECT Type"} @{" LIST and STRING Types " Link "LIST and STRING Types"} @{" Linked Lists " Link "Linked Lists"} @EndNode @Node "LONG Type" "beginner.guide/LONG Type" @Next "PTR Type" @Toc "Types" @{b}LONG@{ub} Type ========= The @{b}LONG@{ub} type is the most important type because it is the default type and by far the most common type. It can be used to store a variety of data, including @{fg shine}memory addresses@{fg text}, as we shall see. @{" Default type " Link "Default type"} @{" Memory addresses " Link "Memory addresses"} @EndNode @Node "Default type" "beginner.guide/Default type" @Next "Memory addresses" @Toc "LONG Type" Default type ------------ @{b}LONG@{ub} is the default type of variables. It is a 32-bit type, meaning that 32-bits of memory (RAM) are used to store the data for each variable of this type and the data can take (integer) values in the range -2,147,483,648 to 2,147,483,647. Variables default to being @{b}LONG@{ub} typed, but they can also be explicitly declared as @{b}LONG@{ub}: DEF x:LONG, y PROC fred(p:LONG, q, r:LONG) DEF zed:LONG @{fg shine}statements@{fg text} ENDPROC The global variable @{b}x@{ub}, procedure parameters @{b}p@{ub} and @{b}r@{ub}, and local variable @{b}zed@{ub} have all been declared to be @{b}LONG@{ub} values. The declarations are very similar to the kinds we've seen before, except that the variables have @{b}:LONG@{ub} after their name in the declaration. This is the way the type of a variable is given. Note that the global variable @{b}y@{ub} and the procedure parameter @{b}q@{ub} are also @{b}LONG@{ub}, since they do not have a type specified and @{b}LONG@{ub} is the default type for variables. @EndNode @Node "Memory addresses" "beginner.guide/Memory addresses" @Prev "Default type" @Toc "LONG Type" Memory addresses ---------------- There's a very good reason why @{b}LONG@{ub} is the normal type. A 32-bit (integer) value can be used as a @{fg shine}memory address@{fg text}. Therefore we can store the address (or location) of data in a variable (the variable is then called a @{fg shine}pointer@{fg text}). The variable would then not contain the value of the data but a way of finding the data. Once the data location is known the data can be read or even altered! The next section covers pointers and addresses in more detail. See @{"PTR Type" Link "PTR Type"}. @EndNode @Node "PTR Type" "beginner.guide/PTR Type" @Next "ARRAY Type" @Prev "LONG Type" @Toc "Types" @{b}PTR@{ub} Type ======== The @{b}PTR@{ub} type is used to hold memory addresses. Variables which have a @{b}PTR@{ub} type are called @{fg shine}pointers@{fg text} (since they store memory addresses, as mentioned in the previous section). This section describes, in detail, addresses, pointers and the @{b}PTR@{ub} type. @{" Addresses " Link "Addresses"} @{" Pointers " Link "Pointers"} @{" Indirect types " Link "Indirect types"} @{" Finding addresses (making pointers) " Link "Finding addresses (making pointers)"} @{" Extracting data (dereferencing pointers) " Link "Extracting data (dereferencing pointers)"} @{" Procedure parameters " Link "Procedure parameters"} @EndNode @Node "Addresses" "beginner.guide/Addresses" @Next "Pointers" @Toc "PTR Type" Addresses --------- To understand memory addresses, a good analogy is to think of memory as a road or street, each memory location as a post-box on a house, and each piece of data as a letter. If you were a postman you would need to know where to put your letters, and this information is given by the address of the post-box. As time goes by, each post-box is filled with different letters. This is like the value in a memory location (or variable) changing. To change the letters stored in your post-box, you tell your friends your address and they can send letters in and fill it. This is like letting some program change your data by giving it the address of the data. The next two diagrams illustrate this analogy. A letter contains an address which points to a particular house (or lot of mail) on a street. +-------+ | Letter| |-------| |Address+----* +-------+ \ \ \ +--------+ +---\----+ +--------+ +--------+ | House | | House | | House | | House | Street: |+------+| |+------+| |+------+| ... |+------+| || Mail || || Mail || || Mail || || Mail || +========+ +========+ +========+ +========+ A pointer contains an address which points to a variable (or data) in memory. +-------+ |Pointer| |-------| |Address+----* +-------+ \ \ \ +--------+ +---\----+ +--------+ +--------+ |Variable| |Variable| |Variable| |Variable| Memory: |+------+| |+------+| |+------+| ... |+------+| || Data || || Data || || Data || || Data || +========+ +========+ +========+ +========+ @EndNode @Node "Pointers" "beginner.guide/Pointers" @Next "Indirect types" @Prev "Addresses" @Toc "PTR Type" Pointers -------- Variables which contain memory addresses are called @{fg shine}pointers@{fg text}. As we saw in the previous section, we can store memory addresses in @{b}LONG@{ub} variables. However, we then don't know the type of the data stored at those addresses. If it is important (or useful) to know this then the @{b}PTR@{ub} type (or, more accurately, one of the many @{b}PTR@{ub} types) should be used. DEF p:PTR TO LONG, i:PTR TO INT, cptr:PTR TO CHAR, gptr:PTR TO gadget The values stored in each of @{b}p@{ub}, @{b}cptr@{ub}, @{b}i@{ub} and @{b}gptr@{ub} are @{b}LONG@{ub} since they are memory addresses. However, the data at the address stored in @{b}p@{ub} is taken to be @{b}LONG@{ub} (a 32-bit value), that at @{b}cptr@{ub} is @{b}CHAR@{ub} (an 8-bit value), that at @{b}i@{ub} is @{b}INT@{ub} (a 16-bit value), and that at @{b}gptr@{ub} is @{b}gadget@{ub}, which is an @{fg shine}object@{fg text} (see @{"OBJECT Type" Link "OBJECT Type"}). @EndNode @Node "Indirect types" "beginner.guide/Indirect types" @Next "Finding addresses (making pointers)" @Prev "Pointers" @Toc "PTR Type" Indirect types -------------- In the previous example we saw @{b}INT@{ub} and @{b}CHAR@{ub} used as the destination types of pointers, and these are the 16- and 8-bit equivalents (respectively) of the @{b}LONG@{ub} type. However, unlike @{b}LONG@{ub} these types cannot be used directly to declare global or local variables, or procedure parameters. They can only be used in constructing types (for instance with @{b}PTR TO@{ub}). The following declarations are therefore @{i}illegal@{ui}, and it might be nice to try compiling a little program with such a declaration, just to see the error message the E compiler gives. /* This program fragment contains illegal declarations */ DEF c:CHAR, i:INT /* This program fragment contains illegal declarations */ PROC fred(a:INT, b:CHAR) DEF x:INT @{fg shine}statements@{fg text} ENDPROC This is not much of a limitation because you can store @{b}INT@{ub} or @{b}CHAR@{ub} values in @{b}LONG@{ub} variables if you really need to. However, it does mean there's a nice, simple rule: every direct value in E is a 32-bit quantity, either a @{b}LONG@{ub} or a pointer. In fact, @{b}LONG@{ub} is actually short-hand for @{b}PTR TO CHAR@{ub}, so you can use @{b}LONG@{ub} values like they were actually @{b}PTR TO CHAR@{ub} values. @EndNode @Node "Finding addresses (making pointers)" "beginner.guide/Finding addresses (making pointers)" @Next "Extracting data (dereferencing pointers)" @Prev "Indirect types" @Toc "PTR Type" Finding addresses (making pointers) ----------------------------------- If a program knows the address of a variable it can directly read or alter the value stored in the variable. To obtain the address of a simple variable you use @{b}{@{ub} and @{b}}@{ub} around the variable name. The address of non-simple variables (e.g., objects and arrays) can be found much more easily (see the appropriate section), and in fact you will very rarely need to use @{b}{@{ub}@{fg shine}var@{fg text} @{b} }@{ub}. However, if you understand how to explicitly make pointers with @{b}{@{ub}@{fg shine}var@{fg text} @{b} }@{ub} and use the pointers to get to data, then you'll understand the way pointers are used for the non-simple types much more quickly. Addresses can be stored in a variable, passed to a procedure or whatever (they're just 32-bit values). Try out the following program: DEF x PROC main() fred(2) ENDPROC PROC fred(y) DEF z WriteF('x is at address \d\n', {x}) WriteF('y is at address \d\n', {y}) WriteF('z is at address \d\n', {z}) WriteF('fred is at address \d\n', {fred}) ENDPROC Notice that you can also find the address of a procedure using @{b}{@{ub} and @{b}}@{ub}. This is is the memory location of the code the procedure represents. Here's the output from one execution of this program (don't expect your output to be exactly the same, though): x is at address 3758280 y is at address 3758264 z is at address 3758252 fred is at address 3732878 This is an interesting program to run several times under different circumstances. You should see that sometimes the numbers for the addresses change. Running the program when another is multi-tasking (and eating memory) should produce the best changes, whereas running it consecutively (in one CLI) should produce the smallest (if any) changes. This gives you a glimpse at the complex memory handling of the Amiga and the E compiler. @EndNode @Node "Extracting data (dereferencing pointers)" "beginner.guide/Extracting data (dereferencing pointers)" @Next "Procedure parameters" @Prev "Finding addresses (making pointers)" @Toc "PTR Type" Extracting data (dereferencing pointers) ---------------------------------------- If you have an address stored in a variable (i.e., a pointer) you can extract the data using the @{b}^@{ub} operator. This act of extracting data via a pointer is called @{fg shine}dereferencing@{fg text} the pointer. This operator should only really be used when @{b}{@{ub}@{fg shine}var@{fg text} @{b} }@{ub} has been used to obtain an address. To this end, @{b}LONG@{ub} values are read and written when dereferencing pointers in this way. For pointers to non-simple types (e.g., objects and arrays), dereferencing is achieved in much more readable ways (see the appropriate section for details), and this operator is not used. In fact, @{b} ^@{ub}@{fg shine}var@{fg text}@{b}@{ub} is seldom used in programs, but is useful for explaining how pointers work, especially in conjunction with @{b}{@{ub}@{fg shine}var@{fg text} @{b} }@{ub}. Using pointers can remove the scope restriction on local variables, i.e., they can be altered from outside the procedure for which they are local. Whilst this kind of use is not generally advised, it makes for a good example which shows the power of pointers. For example, the following program changes the value of the local variable @{b}x@{ub} for the procedure @{b}fred@{ub} from within the procedure @{b}barney@{ub}. PROC main() fred() ENDPROC PROC fred() DEF x, p:PTR TO LONG x:=33 p:={x} barney(p) WriteF('x is now \d\n', x) ENDPROC PROC barney(ptr:PTR TO LONG) DEF val val:=^ptr ^ptr:=val-6 ENDPROC Here's what you can expect it to generate as output: x is now 27 Notice that the @{b}^@{ub} operator (i.e., dereferencing) is quite versatile. In the first assignment of the procedure @{b}barney@{ub} it is used (with the pointer @{b}ptr@{ub}) to get the value stored in the local variable @{b}x@{ub}, and in the second it is used to change this variable's value. In either case, dereferencing makes the pointer behave exactly as if you'd written the variable for which it is a pointer. To emphasise this, we can remove the @{b}barney@{ub} procedure, like we did above (see @{"Style Reuse and Readability" Link "Style Reuse and Readability"}): PROC main() fred() ENDPROC PROC fred() DEF x, p:PTR TO LONG, val x:=33 p:={x} val:=x x:=val-6 WriteF('x is now \d\n', x) ENDPROC Everywhere the @{b}barney@{ub} procedure used @{b}^ptr@{ub} we've written @{b}x@{ub} (because we are now in the procedure for which @{b}x@{ub} is local). We've also eliminated the @{b}ptr@{ub} variable (the parameter to the @{b}barney@{ub} procedure), since it was only used with the @{b}^@{ub} operator. To make things clear the @{b}fred@{ub} and @{b}barney@{ub} example is deliberately `wordy'. The @{b}val@{ub} and @{b}p@{ub} variables are unnecessary, and the pointer types could be abbreviated to @{b}LONG@{ub} or even omitted, for the reasons outlined above (see @{"LONG Type" Link "LONG Type"}). This is the compact form of the example: PROC main() fred() ENDPROC PROC fred() DEF x x:=33 barney({x}) WriteF('x is now \d\n', x) ENDPROC PROC barney(ptr) ^ptr:=^ptr-6 ENDPROC By far the most common use of pointers is to address (or reference) large structures of data. It would be extremely expensive (in terms of CPU time) to pass large amounts of data from procedure to procedure, so addresses to such data are passed instead (and, as we know, these are just 32-bit values). The Amiga system functions (such as ones for creating windows) require a lot of structured data, so if you plan to do any real programming you are going to have to understand and use pointers. @EndNode @Node "Procedure parameters" "beginner.guide/Procedure parameters" @Prev "Extracting data (dereferencing pointers)" @Toc "PTR Type" Procedure parameters -------------------- Only local and global variables have the luxury of a large choice of types. Procedure parameters can only be @{b}LONG@{ub} or @{b}PTR TO @{ub}@{fg shine}type@{fg text}@{b}@{ub}. This is not really a big limitation as we shall see in the later sections. @EndNode @Node "ARRAY Type" "beginner.guide/ARRAY Type" @Next "OBJECT Type" @Prev "PTR Type" @Toc "Types" @{b}ARRAY@{ub} Type ========== Quite often, the data used by a program needs to be ordered in some way, primarily so that it can be accessed easily. E provides a way to achieve such simple ordering: the @{b}ARRAY@{ub} type. This type (in its various forms) is common to most computer languages. @{" Tables of data " Link "Tables of data"} @{" Accessing array data " Link "Accessing array data"} @{" Array pointers " Link "Array pointers"} @{" Point to other elements " Link "Point to other elements"} @{" Array procedure parameters " Link "Array procedure parameters"} @EndNode @Node "Tables of data" "beginner.guide/Tables of data" @Next "Accessing array data" @Toc "ARRAY Type" Tables of data -------------- Data can be grouped together in many different ways, but probably the most common and straight-forward way is to make a table. In a table the data is ordered either vertically or horizontally, but the important thing is the relative positioning of the elements. The E view of this kind of ordered data is the @{b}ARRAY@{ub} type. An @{fg shine}array@{fg text} is just a fixed sized collection of data in order. The size of an array is important and this is fixed when it is declared. The following illustrates array declarations: DEF a[132]:ARRAY, table[21]:ARRAY OF LONG, ints[3]:ARRAY OF INT, objs[54]:ARRAY OF myobject The size of the array is given in the square brackets (@{b}[@{ub} and @{b}]@{ub}). The type of the elements in the array defaults to @{b}CHAR@{ub}, but this can be given explicitly using the @{b}OF@{ub} keyword and the type name. However, only @{b}LONG@{ub}, @{b}INT@{ub}, @{b}CHAR@{ub} and object types are allowed (@{b}LONG@{ub} can hold pointer values so this isn't much of a limitation). Object types are described below (see @{"OBJECT Type" Link "OBJECT Type"}). As mentioned above, procedure parameters cannot be arrays (see @{"Procedure parameters" Link "Procedure parameters"}). We will overcome this limitation soon (see @{"Array procedure parameters" Link "Array procedure parameters"}). @EndNode @Node "Accessing array data" "beginner.guide/Accessing array data" @Next "Array pointers" @Prev "Tables of data" @Toc "ARRAY Type" Accessing array data -------------------- To access a particular element in an array you use square brackets again, this time specifying the @{fg shine}index@{fg text} (or position) of the element you want. Indices start at zero for the first element of the array, one for the second element and, in general, (n-1) for the n-th element. This may seem strange at first, but it's the way most computer languages do it! We will see a reason why this makes sense soon (see @{"Array pointers" Link "Array pointers"}). DEF a[10]:ARRAY PROC main() DEF i FOR i:=0 TO 9 a[i]:=i*i ENDFOR WriteF('The 7th element of the array a is \d\n', a[6]) a[a[2]]:=10 WriteF('The array is now:\n') FOR i:=0 TO 9 WriteF(' a[\d] = \d\n', i, a[i]) ENDFOR ENDPROC This should all seem very straight-forward although one of the lines looks a bit complicated. Try to work out what happens to the array after the assignment immediately following the first @{b}WriteF@{ub}. In this assignment the index comes from a value stored in the array itself! Be careful when doing complicated things like this, though: make sure you don't try to read data from or write data to elements beyond the end of the array. In our example there are only ten elements in the array @{b}a@{ub}, so it wouldn't be sensible to talk about the eleventh element. The program could have checked that the value stored at @{b}a[2]@{ub} was a number between zero and nine before trying to access that array element, but it wasn't necessary in this case. Here's the output this example should generate: The 7th element of the array a is 36 The array is now: a[0] = 0 a[1] = 1 a[2] = 4 a[3] = 9 a[4] = 10 a[5] = 25 a[6] = 36 a[7] = 49 a[8] = 64 a[9] = 81 If you do try to write to a non-existent array element strange things can happen. This may be practically unnoticeable (like corrupting some other data), but if you're really unlucky you might crash your computer. The moral is: stay within the bounds of the array. A short-hand for the first element of an array (i.e., the one with an index of zero) is to omit the index and write only the square brackets. Therefore, @{b}a[]@{ub} is the same as @{b}a[0]@{ub}. @EndNode @Node "Array pointers" "beginner.guide/Array pointers" @Next "Point to other elements" @Prev "Accessing array data" @Toc "ARRAY Type" Array pointers -------------- When you declare an array the address of the (beginning of the) array is given by the variable name without square brackets. Consider the following program: DEF a[10]:ARRAY OF INT PROC main() DEF ptr:PTR TO INT, i FOR i:=0 TO 9 a[i]:=i ENDFOR ptr:=a ptr++ ptr[]:=22 FOR i:=0 TO 9 WriteF('a[\d] is \d\n', i, a[i]) ENDFOR ENDPROC Here's the output from it: a[0] is 0 a[1] is 22 a[2] is 2 a[3] is 3 a[4] is 4 a[5] is 5 a[6] is 6 a[7] is 7 a[8] is 8 a[9] is 9 You should notice that the second element of the array has been changed using the pointer. The @{b}ptr++@{ub} statement increments the pointer @{b}ptr@{ub} to point to the next element of the array. It is important that @{b}ptr@{ub} is declared as @{b}PTR TO INT@{ub} since the array is an @{b}ARRAY OF INT@{ub}. The @{b}[]@{ub} is used to dereference the pointer and therefore 22 is stored in the second element of the array. In fact, the @{b}ptr@{ub} can be used in exactly the same way as an array, so @{b}ptr[1]@{ub} would be the next (or third element) of the array @{b}a@{ub} (after the @{b}ptr++@{ub} statement). Also, since @{b}ptr@{ub} points to the second element of @{b}a@{ub}, negative values may legitimately be used as the index, and @{b}ptr[-1]@{ub} is the first element of @{b}a@{ub}. In fact, the following declarations are identical except the first reserves an appropriate amount of memory for the array whereas the second relies on you having done this somewhere else in the program. DEF a[20]:ARRAY OF INT DEF a:PTR TO INT The following diagram is similar to the diagrams given earlier (see @{"Addresses" Link "Addresses"}). It is an illustration of an array, @{b}a@{ub}, which was declared to be an array of twenty @{b}INT@{ub}s. +--------+ |Variable| | 'a' | |--------| | Address+----* +--------+ \ \ \ +-------+ +--\----+ +-------+ +-------+ +-------+ |Unknown| | a[0] | | a[1] | | a[19] | |Unknown| Memory: |+-----+| |+-----+| |+-----+| ... |+-----+| |+-----+| || XXX || || INT || || INT || || INT || || XXX || +=======+ +=======+ +=======+ +=======+ +=======+ As you can see, the variable @{b}a@{ub} is a pointer to the reserved chunk of memory which contains the array elements. Parts of memory that aren't between @{b}a[0]@{ub} and @{b}a[19]@{ub} are marked as `Unknown' because they are not part of the array. This memory should therefore not be accessed using the array @{b}a@{ub}. @EndNode @Node "Point to other elements" "beginner.guide/Point to other elements" @Next "Array procedure parameters" @Prev "Array pointers" @Toc "ARRAY Type" Point to other elements ----------------------- We saw in the previous section how to increment a pointer so that it points to the next element in the array. Decrementing a pointer @{b}p@{ub} (i.e., making it point to the previous element) is done in a similar way, using the @{b}p--@{ub} statement which works in the same way as the @{b}p++@{ub} statement. In fact, @{b}p++@{ub} and @{b}p--@{ub} are really expressions which denote pointer values. @{b}p++@{ub} denotes the address stored in @{b}p@{ub} @{i}before@{ui} it is incremented, and @{b}p--@{ub} denotes the address @{i}after@{ui} @{b}p@{ub} is decremented. Therefore, addr:=p p++ does the same as addr:=p++ And p-- addr:=p does the same as addr:=p-- The reason why @{b}++@{ub} and @{b}--@{ub} should be used to increment and decrement a pointer is that values from different types occupy different numbers of memory locations. In fact, a single memory location is a @{fg shine}byte@{fg text}, and this is eight bits. Therefore, @{b}CHAR@{ub} values occupy a single byte, whereas @{b}LONG@{ub} values take up four bytes (32 bits). If @{b}p@{ub} were a pointer to @{b}CHAR@{ub} and it was pointing to an array (of @{b}CHAR@{ub}) the @{b}p+1@{ub} memory location would contain the second element of the array (and @{b}p+2@{ub} the third, etc.). But if @{b}p@{ub} were a pointer to an array of @{b}LONG@{ub} the second element in the array would be at @{b}p+4@{ub} (and the third at @{b}p+8@{ub}). The locations @{b}p@{ub}, @{b}p+1@{ub}, @{b}p+2@{ub} and @{b}p+3@{ub} all make up the @{b}LONG@{ub} value at address @{b}p@{ub}. Having to remember things like this is a pain, and it's a lot less readable than using @{b}++@{ub} or @{b}--@{ub}. However, you must remember to declare your pointer with the correct type in order for @{b}++@{ub} and @{b}--@{ub} to work correctly. @EndNode @Node "Array procedure parameters" "beginner.guide/Array procedure parameters" @Prev "Point to other elements" @Toc "ARRAY Type" Array procedure parameters -------------------------- Since we now know how to get the address of an array we can simulate passing an array as a procedure parameter by passing the address of the array. For example, the following program uses a procedure to fill in the first @{b}x@{ub} elements of an array with their index numbers. DEF a[10]:ARRAY OF INT PROC main() DEF i fillin(a, 10) FOR i:=0 TO 9 WriteF('a[\d] is \d\n', i, a[i]) ENDFOR ENDPROC PROC fillin(ptr:PTR TO INT, x) DEF i FOR i:=0 TO x-1 ptr[]:=i ptr++ ENDFOR ENDPROC Here's the output it should generate: a[0] is 0 a[1] is 1 a[2] is 2 a[3] is 3 a[4] is 4 a[5] is 5 a[6] is 6 a[7] is 7 a[8] is 8 a[9] is 9 The array @{b}a@{ub} only has ten elements so we shouldn't fill in any more than the first ten elements. Therefore, in the example, the call to the procedure @{b}fillin@{ub} should not have a bigger number than ten as the second parameter. Also, we could treat @{b}ptr@{ub} more like an array (and not use @{b}++@{ub}), but in this case using @{b}++@{ub} is slightly better since we are assigning to each element in turn. The alternative definition of @{b}fillin@{ub} (without using @{b}++@{ub}) is: PROC fillin2(ptr:PTR TO INT, x) DEF i FOR i:=0 TO x-1 ptr[i]:=i ENDFOR ENDPROC Also, yet another version of @{b}fillin@{ub} uses the expression form of @{b}++@{ub} and the horizontal form of the @{b}FOR@{ub} loop to give a really compact definition. PROC fillin3(ptr:PTR TO INT, x) DEF i FOR i:=0 TO x-1 DO ptr[]++:=i ENDPROC @EndNode @Node "OBJECT Type" "beginner.guide/OBJECT Type" @Next "LIST and STRING Types" @Prev "ARRAY Type" @Toc "Types" @{b}OBJECT@{ub} Type =========== Objects are the E equivalent of C and Assembly structures, or Pascal records. They are like arrays except the elements are named not numbered, and the elements can be of different types. To find a particular element in an object you use a name instead of an index (number). Objects are also the basis of the OOP features of E (see @{"Object Oriented E" Link "Object Oriented E"}). @{" Example object " Link "Example object"} @{" Element selection and element types " Link "Element selection and element types"} @{" Amiga system objects " Link "Amiga system objects"} @EndNode @Node "Example object" "beginner.guide/Example object" @Next "Element selection and element types" @Toc "OBJECT Type" Example object -------------- We'll dive straight in with this first example, and define an object and use it. Object definitions are global and must be made before any procedure definitions. OBJECT rec tag, check table[8]:ARRAY data:LONG ENDOBJECT PROC main() DEF a:rec a.tag:=1 a.check:=a a.data:=a.tag+(10000*a.tag) ENDPROC This program doesn't visibly do anything so there isn't much point in compiling it. What it does do, however, is show how a typical object is defined and elements of an object are selected. The object being defined in the example is @{b}rec@{ub}, and its elements are defined just like variable declarations (but without a @{b}DEF@{ub}). There can be as many lines of element definitions as you like between the @{b}OBJECT@{ub} and @{b}ENDOBJECT@{ub} lines, and each line can contain any number of elements separated by commas. The elements of the @{b}rec@{ub} object are @{b}tag@{ub} and @{b}check@{ub} (which are @{b}LONG@{ub}), @{b}table@{ub} (which is an array of @{b}CHAR@{ub} with eight elements) and @{b}data@{ub} (which is also @{b}LONG@{ub}). Every variable of @{b}rec@{ub} object type will have space reserved for each of these elements. The declaration of the (local) variable @{b}a@{ub} therefore reserves enough memory for one @{b}rec@{ub} object. @EndNode @Node "Element selection and element types" "beginner.guide/Element selection and element types" @Next "Amiga system objects" @Prev "Example object" @Toc "OBJECT Type" Element selection and element types ----------------------------------- To select elements in an object @{b}obj@{ub} you use @{b}obj.name@{ub}, where @{b}name@{ub} is one of the element names. In the example, the @{b}tag@{ub} element of the @{b}rec@{ub} object @{b}a@{ub} is selected by writing @{b}a.tag@{ub}. The other elements are selected in a similar way. Just like an array declaration the address of an object @{b}obj@{ub} is stored in the variable @{b}obj@{ub}, and any pointer of type @{b}PTR TO @{ub}@{fg shine}objectname@{fg text}@{b}@{ub} can be used just like an object of type @{fg shine}objectname@{fg text}. Therefore, in the previous example @{b}a@{ub} is a @{b}PTR TO rec@{ub}. As the example object shows, the elements of an object can have several different types. In fact, the elements can have any type, including object, pointer to object and array of object. The following example shows how to access some different typed elements. OBJECT rec tag, check table[8]:ARRAY data:LONG ENDOBJECT OBJECT bigrec data:PTR TO LONG subrec:PTR TO rec rectable[22]:ARRAY OF rec ENDOBJECT PROC main() DEF r:rec, b:bigrec, rt:PTR TO rec r.table[]:="H" b.subrec:=r b.subrec.tag:=1 b.subrec.data:=r.tag+(10000*b.subrec.tag) b.subrec.table[1]:="i" b.rectable[0].data:=r.tag b.rectable[0].table[0]:="A" rt:=b.rectable rt[].data++:=0 rt[].table[]--:="B" ENDPROC The @{b}++@{ub} and @{b}--@{ub} operators apply to first thing in the selection (i.e., @{b}rt@{ub} in @{i}both@{ui} the last two assignments in the example above), and may only occur after all the selections. Notice that object selection and array indexing can be repeated as much as necessary (but only as the types of the elements allow). As a simple example, consider the third assignment: b.subrec.tag:=1 This selects the @{b}subrec@{ub} element from the @{b}bigrec@{ub} object @{b}b@{ub}, and then sets the @{b}tag@{ub} element of this @{b}rec@{ub} object to 1. Now, consider one of the later assignments: b.rectable[0].table[0]:="A" This selects the @{b}rectable@{ub} element from @{b}b@{ub}, which is an array of @{b}rec@{ub} objects. The first element of this array is selected, and then the @{b}table@{ub} element of the @{b}rec@{ub} object is selected. Finally, the first character of the @{b}table@{ub} is set to the ASCII value of character @{b}A@{ub}. As you can probably tell, it is important to give the elements of objects appropriate types if you want to do multiple selection in this way. However, this is not always possible or the best way of doing some things, so there is a way of giving a different type to pointers (this is called @{fg shine}explicit pointer typing@{fg text}--see the `Reference Manual' for more details). Here's a quite simple example which uses an array of objects: OBJECT rec tag, check table[8]:ARRAY data:LONG ENDOBJECT PROC main() DEF a[10]:ARRAY OF rec, p:PTR TO rec, i p:=a FOR i:=0 TO 9 a[i].tag:=i p.check++:=i ENDFOR FOR i:=0 TO 9 IF a[i].tag<>a[i].check WriteF('Whoops, a[\d] went wrong...\n', i) ENDIF ENDFOR ENDPROC If you think about it for long enough you'll see that @{b}a[0].tag@{ub} is the same as @{b}a.tag@{ub}. That's because @{b}a@{ub} is a pointer to the first element of the array, and the elements of the array are objects. Therefore, @{b}a@{ub} is a pointer to an object (the first object in the array). @EndNode @Node "Amiga system objects" "beginner.guide/Amiga system objects" @Prev "Element selection and element types" @Toc "OBJECT Type" Amiga system objects -------------------- There are many different Amiga system objects. For instance, there's one which contains the information needed to make a gadget (like the `close' gadget on most windows), and one which contains all the information about a process or task. These objects are vitally important and so are supplied with E in the form of `modules'. Each module is specific to a certain area of the Amiga system and contains object and other definitions. Modules are discussed in more detail later (see @{"Modules" Link "Modules"}). @EndNode @Node "LIST and STRING Types" "beginner.guide/LIST and STRING Types" @Next "Linked Lists" @Prev "OBJECT Type" @Toc "Types" @{b}LIST@{ub} and @{b}STRING@{ub} Types ===================== Arrays are common to many computer languages. However, they can be a bit of a pain because you always need to make sure you haven't run off the end of the array when you're writing to it. This is where the @{b}STRING@{ub} and @{b}LIST@{ub} types come in. @{b}STRING@{ub} is very much like @{b}ARRAY OF CHAR@{ub} and @{b}LIST@{ub} is like @{b}ARRAY OF LONG@{ub}. However, each has a set of E (built-in) functions which safely manipulate variables of these types without exceeding their bounds. @{" Normal strings and E-strings " Link "Normal strings and E-strings"} @{" String functions " Link "String functions"} @{" Lists and E-lists " Link "Lists and E-lists"} @{" List functions " Link "List functions"} @{" Complex types " Link "Complex types"} @{" Typed lists " Link "Typed lists"} @{" Static data " Link "Static data"} @EndNode @Node "Normal strings and E-strings" "beginner.guide/Normal strings and E-strings" @Next "String functions" @Toc "LIST and STRING Types" Normal strings and E-strings ---------------------------- @{fg shine}Normal@{fg text} strings are common to most programming languages. They are simply an array of characters, with the end of the string marked by a null character (ASCII zero). We've already met normal strings (see @{"Strings" Link "Strings"}). The ones we used were constant strings contained in ' characters, and they denote pointers to the memory where the string data is stored. Therefore, you can assign a string constant to a pointer (to @{b}CHAR@{ub}), and you've got an array with ready-filled elements, i.e., an initialised array. DEF s:PTR TO CHAR s:='This is a string constant' /* Now s[] is T and s[2] is i */ Remember that @{b}LONG@{ub} is actually @{b}PTR TO CHAR@{ub} so this code is precisely the same as: DEF s s:='This is a string constant' The following diagram illustrates the above assignment to @{b}s@{ub}. The first two characters @{b}s[0]@{ub} and @{b}s[1]@{ub}) are @{b}T@{ub} and @{b}h@{ub}, and the last character (before the terminating null, or zero) is @{b}t@{ub}. Memory marked as `Unknown' is not part of the string constant. +--------+ |Variable| | 's' | |--------| |Address +----* +--------+ \ \ \ +-------+ +--\----+ +-------+ +-------+ +-------+ +-------+ |Unknown| | s[0] | | s[1] | | s[24] | | s[25] | |Unknown| Memory: |+-----+| |+-----+| |+-----+|...|+-----+| |+-----+| |+-----+| || XXX || || "T" || || "h" || || "t" || || 0 || || XXX || +=======+ +=======+ +=======+ +=======+ +=======+ +=======+ @{fg shine}E-strings@{fg text} are very similar to normal strings and, in fact, an E-string can be used wherever a normal string can. However, the reverse is not true, so if something requires an E-string you cannot use a normal string instead. The difference between a normal string and an E-string was hinted at in the introduction to this section: E-strings can be safely altered without exceeding their bounds. A normal string is just an array so you need to be careful not to exceed its bounds. However, an E-string knows what its bounds are, and so any of the string manipulation functions can alter them safely. An E-string (@{b}STRING@{ub} type) variable is declared as in the following example, with the maximum size of the E-string given just like an array declaration. DEF s[30]:STRING As with an array declaration, the variable @{b}s@{ub} is actually a pointer to the string data. To initialise an E-string you need to use the function @{b}StrCopy@{ub} as we shall see. There are some worked examples in Part Three (see @{"String Handling and I-O" Link "String Handling and I-O"}) which show how to use normal strings and E-strings. @EndNode @Node "String functions" "beginner.guide/String functions" @Next "Lists and E-lists" @Prev "Normal strings and E-strings" @Toc "LIST and STRING Types" String functions ---------------- There are a number of useful built-in functions which manipulate strings. Remember that if an E-string can be used wherever a normal string can, but normal strings cannot be used where an E-string is required. If a parameter is marked as @{fg shine}string@{fg text} then a normal or E-string can be passed as that parameter, but if it is marked as @{fg shine}e-string@{fg text} then only an E-string may be used. Some of these functions have default arguments, which means you don't need to specify some parameters to get the default values (see @{"Default Arguments" Link "Default Arguments"}). (You can, of course, ignore the defaults and always give all parameters.) @{b}String(@{ub}@{fg shine}maxsize@{fg text}@{b})@{ub} Allocates memory for an E-string of maximum size @{fg shine}maxsize@{fg text} and returns a pointer to the string data. It is used to make space for a new E-string, like a @{b}STRING@{ub} declaration does. The following code fragments are practically equivalent: DEF s[37]:STRING DEF s:PTR TO CHAR s:=String(37) The slight difference is that there may not be enough memory left to hold the E-string when the @{b}String@{ub} function is used. In that case the special value @{b}NIL@{ub} (a constant) is returned. Your program @{i}must@{ui} check that the value returned is not @{b}NIL@{ub} before you use it as an E-string (or dereference it). The memory for the declaration version is allocated when the program is run, so your program won't run if there isn't enough memory. The @{b}String@{ub} version is often called @{fg shine}dynamic@{fg text} allocation because it happens only when the program is running; the declaration version has allocation done by the E compiler. The memory allocated using @{b}String@{ub} is deallocated using @{b}DisposeLink@{ub} (see @{"System support functions" Link "System support functions"}). @{b}StrCmp(@{ub}@{fg shine}string1@{fg text}@{b},@{ub}@{fg shine}string2@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b}=ALL)@{ub} Compares @{fg shine}string1@{fg text} with @{fg shine}string2@{fg text} (they can both be normal or E-strings). Returns @{b}TRUE@{ub} if the first @{fg shine}length@{fg text} characters of the strings match, and @{b}FALSE@{ub} otherwise. The @{fg shine}length@{fg text} defaults to the special constant @{b}ALL@{ub} which means that the strings must agree on every character. For example, the following comparisons all return @{b}TRUE@{ub}: StrCmp('ABC', 'ABC') StrCmp('ABC', 'ABC', ALL) StrCmp('ABCd', 'ABC', 3) StrCmp('ABCde','ABCxxjs',3) And the following return @{b}FALSE@{ub} (notice the case of the letters): StrCmp('ABC', 'ABc') StrCmp('ABC', 'ABc', ALL) StrCmp('ABCd', 'ABC', ALL) @{b}StrCopy(@{ub}@{fg shine}e-string@{fg text}@{b},@{ub}@{fg shine}string@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b}=ALL)@{ub} Copies the contents of @{fg shine}string@{fg text} to @{fg shine}e-string@{fg text}, and also returns a pointer to the resulting E-string (for convenience). Only @{fg shine}length@{fg text} characters are copied from the source string, but the special constant @{b}ALL@{ub} can be used to indicate that the whole of the source string is to be copied (and this is the default value for @{fg shine}length@{fg text}). Remember that E-strings are safely manipulated, so the following code fragment results in @{b}s@{ub} becoming @{b}More th@{ub}, since its maximum size is (from its declaration) seven characters. DEF s[7]:STRING StrCopy(s, 'More than seven characters', ALL) A declaration using @{b}STRING@{ub} (or @{b}ARRAY@{ub}) reserves a small part of memory, and stores a pointer to this memory in the variable being declared. So to get data into this memory you need to copy it there, using @{b}StrCopy@{ub}. If you're familiar with very high-level languages like BASIC you should take care, because you might think you can assign a string to an array or an E-string variable. In E (and languages like C and Assembly) you must explicitly copy data into arrays and E-strings. You should not do the following: /* You don't want to do things like this! */ DEF s[80]:STRING s:='This is a string constant' This is fairly disastrous: it throws away the pointer to reserved memory that was stored in @{b}s@{ub} and replaces it by a pointer to the string constant. @{b}s@{ub} is then no longer an E-string, and @{i}cannot@{ui} be repaired using @{b}SetStr@{ub}. If you want @{b}s@{ub} to contain the above string you must use @{b}StrCopy@{ub}: DEF s[80]:STRING StrCopy(s,'This is a string constant') The moral is: remember when you are using pointers to data and when you need to copy data. Also, remember that assignment does not copy large arrays of data, it only copies pointers to data, so if you want to store some data in an @{b}ARRAY@{ub} or @{b}STRING@{ub} type variable you need to copy it there. @{b}StrAdd(@{ub}@{fg shine}e-string@{fg text}@{b},@{ub}@{fg shine}string@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b}=ALL)@{ub} This does the same as @{b}StrCopy@{ub} but the source string is copied onto the end of the destination E-string. The following code fragment results in @{b}s@{ub} becoming @{b}This is a string and a half@{ub}. DEF s[30]:STRING StrCopy(s, 'This is a string', ALL) StrAdd(s, ' and a half') @{b}StrLen(@{ub}@{fg shine}string@{fg text}@{b})@{ub} Returns the length of @{fg shine}string@{fg text}. This assumes that the string is terminated by a null character (i.e., ASCII zero), which is true for any strings made from E-strings and string constants. However, you can make a string constant look short if you use the null character (the special sequence @{b}\0@{ub}) in it. For instance, these calls all return three: StrLen('abc') StrLen('abc\0def') In fact, most of the string functions assume strings are null-terminated, so you shouldn't use null characters in your strings unless you really know what you're doing. For E-strings @{b}StrLen@{ub} is less efficient than the @{b}EstrLen@{ub} function. @{b}EstrLen(@{ub}@{fg shine}e-string@{fg text}@{b})@{ub} Returns the length of @{fg shine}e-string@{fg text} (remember this can only be an E-string). This is much more efficient than @{b}StrLen@{ub} since E-strings know their length and it doesn't need to search the string for a null character. @{b}StrMax(@{ub}@{fg shine}e-string@{fg text}@{b})@{ub} Returns the maximum length of @{fg shine}e-string@{fg text}. This is not necessarily the current length of the E-string, rather it is the size used in the declaration with @{b}STRING@{ub} or the call to @{b}String@{ub}. @{b}RightStr(@{ub}@{fg shine}e-string1@{fg text}@{b},@{ub}@{fg shine}e-string2@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b})@{ub} This is like @{b}StrCopy@{ub} but it copies the right-most characters from @{fg shine}e-string2@{fg text} to @{fg shine}e-string1@{fg text} and both strings must be E-strings. At most @{fg shine}length@{fg text} characters are copied, and the special constant @{b}ALL@{ub} @{i}cannot@{ui} be used (to copy all the string you should, of course, use @{b}StrCopy@{ub}). For instance, a value of one for @{fg shine}length@{fg text} means the last character of @{fg shine}e-string2@{fg text} is copied to @{fg shine}e-string1@{fg text}. @{b}MidStr(@{ub}@{fg shine}e-string@{fg text}@{b},@{ub}@{fg shine}string@{fg text}@{b},@{ub}@{fg shine}index@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b}=ALL)@{ub} Copies the contents of @{fg shine}string@{fg text} starting at @{fg shine}index@{fg text} (which is an index just like an array index) to @{fg shine}e-string@{fg text}. At most @{fg shine}length@{fg text} characters are copied, and the special constant @{b}ALL@{ub} can be used if all the remaining characters in @{fg shine}string@{fg text} should be copied (this is the default value for @{fg shine}length@{fg text}). For example, the following two calls to @{b}MidStr@{ub} result in @{b}s@{ub} becoming @{b}four@{ub}: DEF s[30]:STRING MidStr(s, 'Just four', 5) MidStr(s, 'Just four apples', 5, 4) @{b}InStr(@{ub}@{fg shine}string1@{fg text}@{b},@{ub}@{fg shine}string2@{fg text}@{b},@{ub}@{fg shine}startindex@{fg text}@{b}=0)@{ub} Returns the index of the first occurrence of @{fg shine}string2@{fg text} in @{fg shine}string1@{fg text} starting at @{fg shine}startindex@{fg text} (in @{fg shine}string1@{fg text}). @{fg shine}startindex@{fg text} defaults to zero. If @{fg shine}string2@{fg text} could not be found then -1 is returned. @{b}TrimStr(@{ub}@{fg shine}string@{fg text}@{b})@{ub} Returns the address of (i.e., a pointer to) the first non-whitespace character in @{fg shine}string@{fg text}. For instance, the following code fragment results in @{b}s@{ub} becoming @{b}12345@{ub}. DEF s:PTR TO CHAR s:=TrimStr(' \n \t 12345') @{b}LowerStr(@{ub}@{fg shine}string@{fg text}@{b})@{ub} Converts all uppercase letters in @{fg shine}string@{fg text} to lowercase. This change is made @{fg shine}in-place@{fg text}, i.e., the contents of the string are directly affected. The string is returned for convenience. @{b}UpperStr(@{ub}@{fg shine}string@{fg text}@{b})@{ub} Converts all lowercase letters in @{fg shine}string@{fg text} to uppercase. Again, this change is made in-place and the string is returned for convenience. @{b}SetStr(@{ub}@{fg shine}e-string@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b})@{ub} Sets the length of @{fg shine}e-string@{fg text} to @{fg shine}length@{fg text}. E-strings know how long they are, so if you alter an E-string (without using an E-string function) and change its size you need to set its length using this function before you can use it as an E-string again. For instance, if you've used an E-string like an array (which you can do) and written characters to it directly you must set its length before you can treat it as anything other than an array/string: DEF s[10]:STRING s[0]:="a" /* Remember that "a" is a character value. */ s[1]:="b" s[2]:="c" s[3]:="d" /* At this point s is just an array of CHAR. */ SetStr(s, 4) /* Now, s can be used as an E-string again. */ SetStr(s, 2) /* s is a bit shorter, but still an E-string.*/ Notice that this function can be used to shorten an E-string (but you cannot lengthen it this way). @{b}Val(@{ub}@{fg shine}string@{fg text}@{b},@{ub}@{fg shine}address@{fg text}@{b}=NIL)@{ub} What this function does is straight-forward but how you use it is a bit complicated. Basically, it converts @{fg shine}string@{fg text} to a @{b}LONG@{ub} integer. Leading whitespace is ignored, and a leading @{b}%@{ub} or @{b}$@{ub} means that the string denotes a binary or hexadecimal integer (in the same way they do for numeric constants). The decoded integer is returned as the regular return value (see @{"Multiple Return Values" Link "Multiple Return Values"}). The number of characters of @{fg shine}string@{fg text} that were read to make the integer is stored at @{fg shine}address@{fg text}, which is usually a variable address (from using @{b}{@{ub}@{fg shine}var@{fg text} @{b} }@{ub}), and is returned as the first optional return value. If @{fg shine}address@{fg text} is the special constant @{b}NIL@{ub} (or zero) then this number is not stored (this is the default value for @{fg shine}address@{fg text}). You can use this number to calculate the position in the string which was not part of the integer in the string. If an integer could not be decoded from the string then zero is returned and zero is stored at @{fg shine}address@{fg text}. Follow the comments in this example, and pay special attention to the use of the pointer @{b}p@{ub}. DEF s[30]:STRING, value, chars, p:PTR TO CHAR StrCopy(s, ' \t \n 10 \t $3F -%0101010') value, chars:=Val('abcde 10 20') -> Two return values... /* After the above line, value and chars will both be zero */ value:=Val(s, {chars}) -> Use address of chars /* Now value will be 10, chars will be 7 */ p:=s+chars /* p now points to the space after the 10 in s */ value, chars:=Val(p) /* Now value will be $3F (63), chars will be 6 */ p:=p+chars /* p now points to the space after the $3F in s */ value, chars:=Val(p) /* Now value will be -%0101010 (-42), chars will be 10 */ Notice the two different ways of finding the number of characters read: a multiple-assignment and using the address of a variable. There's a couple of other string functions (@{b}ReadStr@{ub} and @{b}StringF@{ub}) which will be discussed later (see @{"Input and output functions" Link "Input and output functions"}). @EndNode @Node "Lists and E-lists" "beginner.guide/Lists and E-lists" @Next "List functions" @Prev "String functions" @Toc "LIST and STRING Types" Lists and E-lists ----------------- Lists are just like strings with @{b}LONG@{ub} elements rather than @{b}CHAR@{ub} elements (so they are very much like @{b}ARRAY OF LONG@{ub}). The list equivalent of an E-string is something called an @{fg shine}E-list@{fg text}. It has the same properties as an E-string, except the elements are @{b}LONG@{ub} (so could be pointers). Normal lists are most like string constants, except that the elements can be built from variables and so do not have to be constants. Just as strings are not true E-strings, (normal) lists are not true E-lists. Lists are written using @{b}[@{ub} and @{b}]@{ub} to delimit comma separated elements. Like string constants a list returns the address of the memory which contains the elements. For example the following code fragment: DEF list:PTR TO LONG, number number:=22 list:=[1,2,3,number] is equivalent to: DEF list[4]:ARRAY OF LONG, number number:=22 list[0]:=1 list[1]:=2 list[2]:=3 list[3]:=number Now, which of these two versions would you rather write? As you can see, lists are pretty useful for making your program easier to write and much easier to read. E-list variables are like E-string variables and are declared in much the same way. The following code fragment declares @{b}lt@{ub} to be an E-list of maximum size 30. As ever, @{b}lt@{ub} is then a pointer (to @{b}LONG@{ub}), and it points to the memory allocated by the declaration. DEF lt[30]:LIST Lists are most useful for writing @{fg shine}tag lists@{fg text}, which are increasingly used in important Amiga system functions. A tag list is a list where the elements are thought of in pairs. The first element of a pair is the tag, and the second is some data for that tag. See the `Rom Kernel Reference Manual (Libraries)' for more details. @EndNode @Node "List functions" "beginner.guide/List functions" @Next "Complex types" @Prev "Lists and E-lists" @Toc "LIST and STRING Types" List functions -------------- There are a number of list functions which are very similar to the string functions (see @{"String functions" Link "String functions"}). Remember that E-lists are the list equivalents of E-strings, i.e., they can be altered and extended safely without exceeding their bounds. As with E-strings, E-lists are downwardly compatible with lists. Therefore, if a function requires a list as a parameter you can supply a list or an E-list. But if a function requires an E-list you cannot use a list in its place. @{b}List(@{ub}@{fg shine}maxsize@{fg text}@{b})@{ub} Allocates memory for an E-list of maximum size @{fg shine}maxsize@{fg text} and returns a pointer to the list data. It is used to make space for a new E-list, like a @{b}LIST@{ub} declaration does. The following code fragments are (as with @{b}String@{ub}) practically equivalent: DEF lt[46]:LIST DEF lt:PTR TO LONG lt:=List(46) Remember that you need to check that the return value from @{b}List@{ub} is not @{b}NIL@{ub} before you use it as an E-list. Like @{b}String@{ub}, the memory allocated using @{b}List@{ub} is deallocated using @{b}DisposeLink@{ub} (see @{"System support functions" Link "System support functions"}). @{b}ListCmp(@{ub}@{fg shine}list1@{fg text}@{b},@{ub}@{fg shine}list2@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b}=ALL)@{ub} Compares @{fg shine}list1@{fg text} with @{fg shine}list2@{fg text} (they can both be normal or E-lists). Works just like @{b}StrCmp@{ub} does for E-strings, so, for example, the following comparisons all return @{b}TRUE@{ub}: ListCmp([1,2,3,4], [1,2,3,4]) ListCmp([1,2,3,4], [1,2,3,7], 3) ListCmp([1,2,3,4,5], [1,2,3], 3) @{b}ListCopy(@{ub}@{fg shine}e-list@{fg text}@{b},@{ub}@{fg shine}list@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b}=ALL)@{ub} Works just like @{b}StrCopy@{ub}, and the following example shows how to initialise an E-list: DEF lt[7]:LIST, x x:=4 ListCopy(lt, [1,2,3,x]) As with @{b}StrCopy@{ub}, an E-list cannot be over-filled using @{b}ListCopy@{ub}. @{b}ListAdd(@{ub}@{fg shine}e-list@{fg text}@{b},@{ub}@{fg shine}list@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b}=ALL)@{ub} Works just like @{b}StrAdd@{ub}, so this next code fragment results in the E-list @{b}lt@{ub} becoming the E-list version of @{b}[1,2,3,4,5,6,7,8]@{ub}. DEF lt[30]:LIST ListCopy(lt, [1,2,3,4]) ListAdd(lt, [5,6,7,8]) @{b}ListLen(@{ub}@{fg shine}list@{fg text}@{b})@{ub} Works just like @{b}StrLen@{ub}, returning the length of @{fg shine}list@{fg text}. There is no E-list specific length function. @{b}ListMax(@{ub}@{fg shine}e-list@{fg text}@{b})@{ub} Works just like @{b}StrMax@{ub}, returning the maximum length of the @{fg shine}e-list@{fg text}. @{b}SetList(@{ub}@{fg shine}e-list@{fg text}@{b},@{ub}@{fg shine}length@{fg text}@{b})@{ub} Works just like @{b}SetStr@{ub}, setting the length of @{fg shine}e-list@{fg text} to @{fg shine}length@{fg text}. @{b}ListItem(@{ub}@{fg shine}list@{fg text}@{b},@{ub}@{fg shine}index@{fg text}@{b})@{ub} Returns the element of @{fg shine}list@{fg text} at @{fg shine}index@{fg text}. For example, if @{b}lt@{ub} is an E-list then @{b}ListItem(lt,n)@{ub} is the same as @{b}lt[n]@{ub}. This function is most useful when the list is not an E-list. For example, the following two code fragments are equivalent: WriteF(ListItem(['Fred','Barney','Wilma','Betty'], name)) DEF lt:PTR TO LONG lt:=['Fred','Barney','Wilma','Betty'] WriteF(lt[name]) @EndNode @Node "Complex types" "beginner.guide/Complex types" @Next "Typed lists" @Prev "List functions" @Toc "LIST and STRING Types" Complex types ------------- In E the @{b}STRING@{ub} and @{b}LIST@{ub} types are called @{fg shine}complex@{fg text} types. Complex typed variables can also be created using the @{b}String@{ub} and @{b}List@{ub} functions as we've seen in the previous sections. @EndNode @Node "Typed lists" "beginner.guide/Typed lists" @Next "Static data" @Prev "Complex types" @Toc "LIST and STRING Types" Typed lists ----------- Normal lists contain @{b}LONG@{ub} elements, so you can write initialised arrays of @{b}LONG@{ub} elements. What about other kinds of array? Well, that's what @{fg shine}typed@{fg text} lists are for. You specify the type of the elements of a list using @{b} :@{ub}@{fg shine}type@{fg text}@{b}@{ub} after the closing @{b}]@{ub}. The allowable types are @{b}CHAR@{ub}, @{b}INT@{ub}, @{b}LONG@{ub} and any object type. There is a subtle difference between a normal, @{b}LONG@{ub} list and a typed list (even a @{b}LONG@{ub} typed list): only normal lists can be used with the list functions (see @{"List functions" Link "List functions"}). For this reason, the term `list' tends to refer only to normal lists. The following code fragment uses the object @{b}rec@{ub} defined earlier (see @{"Example object" Link "Example object"}) and gives a couple of examples of typed lists: DEF ints:PTR TO INT, objects:PTR TO rec, p:PTR TO CHAR ints:=[1,2,3,4]:INT p:='fred' objects:=[1,2,p,4, 300,301,'barney',303]:rec It is equivalent to: DEF ints[4]:ARRAY OF INT, objects[2]:ARRAY OF rec, p:PTR TO CHAR ints[0]:=1 ints[1]:=2 ints[2]:=3 ints[3]:=4 p:='fred' objects[0].tag:=1 objects[0].check:=2 objects[0].table:=p objects[0].data:=4 objects[1].table:='barney' objects[1].tag:=300 objects[1].data:=303 objects[1].check:=301 The last group of assignments to @{b}objects[1]@{ub} have deliberately been shuffled in order to emphasise that the order of the elements in the @{i}definition@{ui} of the object @{b}rec@{ub} is significant. Each of the elements of the list corresponds to an element in the object, and the order of elements in the list corresponds to the order in the object definition. In the example, the (object) list assignment line was broken after the end of the first object (the fourth element) to make it a bit more readable. The last object in the list need not be completely defined, so, for instance, the second line of the assignment could have contained only three elements. This makes an object-typed list slightly different from the corresponding array of objects, since an array always defines a whole number of objects. With an object-typed list you must be careful not to access the undefined elements of a partially defined trailing object. @EndNode @Node "Static data" "beginner.guide/Static data" @Prev "Typed lists" @Toc "LIST and STRING Types" Static data ----------- String constants (e.g., @{b}fred@{ub}), lists (e.g., @{b}[1,2,3]@{ub}) and typed lists (e.g., @{b}[1,2,3]:INT@{ub}) are @{fg shine}static@{fg text} data. This means that the address of the (initialised) data is fixed when the program is run. Normally you don't need to worry about this, but, for instance, if you want to have a series of lists as initialised arrays you might be tempted to use some kind of loop: PROC main() DEF i, a[10]:ARRAY OF LONG, p:PTR TO LONG FOR i:=0 TO 9 a[i]:=[1, i, i*i] /* This assignment is probably not what you want! */ ENDFOR FOR i:=0 TO 9 p:=a[i] WriteF('a[\d] is an array at address \d\n', i, p) WriteF(' and the second element is \d\n', p[1]) ENDFOR ENDPROC The array @{b}a@{ub} is an array of pointers to initialised arrays (which are all three elements long). But, as the comment suggests and the program shows, this probably doesn't do what was intended, since the list is static. That means the address of the list is fixed, so each element of @{b}a@{ub} gets the same address (i.e., the same array). Since @{b}i@{ub} is used in the list the contents of that part of memory varies slightly as the first @{b}FOR@{ub} loop is processed. But after this loop the contents remain fixed, and the second element of each of the ten arrays is always nine. This is an example of the output that will be generated (the @{b}...@{ub} represents a number of similar lines): a[0] is an array at address 4021144 and the second element is 9 a[1] is an array at address 4021144 and the second element is 9 ... a[9] is an array at address 4021144 and the second element is 9 One solution is to use the dynamic typed-allocation operator @{b}NEW@{ub} (see @{"NEW and END Operators" Link "NEW and END Operators"}). Another solution is to use the function @{b}List@{ub} and copy the normal list into the new E-list using @{b}ListCopy@{ub}: PROC main() DEF i, a[10]:ARRAY OF LONG, p:PTR TO LONG FOR i:=0 TO 9 a[i]:=List(3) /* Must check that the allocation succeeded before copying */ IF a[i]<>NIL THEN ListCopy(a[i], [1, i, i*i], ALL) ENDFOR FOR i:=0 TO 9 p:=a[i] IF p=NIL WriteF('Could not allocate memory for a[\d]\n', i) ELSE WriteF('a[\d] is an array at address \d\n', i, p) WriteF(' and the second element is \d\n', p[1]) ENDIF ENDFOR ENDPROC The problem is not so bad with string constants, since the contents are fixed. However, if you alter the contents explicitly, you will need to take care not to run into the same problem, as this next example shows. PROC main() DEF i, strings[10]:ARRAY OF LONG, s:PTR TO CHAR FOR i:=0 TO 9 strings[i]:='Hello World\n' /* This assignment is probably not what you want! */ ENDFOR s:=strings[4] s[5]:="X" FOR i:=0 TO 9 WriteF('strings[\d] is ', i) WriteF(strings[i]) ENDFOR ENDPROC This is an example of the output that will be generated (again, the @{b}...@{ub} represents a number of similar lines):: strings[0] is HelloXWorld strings[1] is HelloXWorld ... strings[9] is HelloXWorld Again, the solution is to use dynamic allocation. The functions @{b}String@{ub} and @{b}StrCopy@{ub} should be used in the same way that @{b}List@{ub} and @{b}ListCopy@{ub} were used above. @EndNode @Node "Linked Lists" "beginner.guide/Linked Lists" @Prev "LIST and STRING Types" @Toc "Types" Linked Lists ============ E-lists and E-strings have a useful extension: they can be used to make @{fg shine}linked lists@{fg text}. These are like the lists we've seen already, except the list elements do not occupy a contiguous block of memory. Instead, each element has an extra piece of data: a pointer to the next element in the list. This means that each element can be anywhere in memory. (Normally, the next element of a list is in the next position in memory.) The end of a linked list has been reached when the pointer to the next element is the special value @{b}NIL@{ub} (a constant). You need to be very careful to check that the pointer is not @{b}NIL@{ub} because if you dereference a @{b}NIL@{ub} pointer the program will most definitely crash. The elements of a linked list are E-lists or E-strings (i.e., the elements are complex typed). So, you can link E-lists to get a `linked list of E-lists' (or, more simply, a `list of lists'). Similarly, linking E-strings gives `linked list of E-strings', or a `list of strings'. You don't have to stick to these two kinds of linked lists, though: you can use a mixture of E-lists and E-strings in the same linked list. To link one complex typed element to another you use the @{b}Link@{ub} function and to find subsequent elements in a linked list you use the @{b}Next@{ub} or @{b}Forward@{ub} functions. @{b}Link(@{ub}@{fg shine}complex1@{fg text}@{b},@{ub}@{fg shine}complex2@{fg text}@{b})@{ub} Links @{fg shine}complex1@{fg text} to @{fg shine}complex2@{fg text}. Both must be an E-list or an E-string, with the exception that @{fg shine}complex2@{fg text} can be the special constant @{b}NIL@{ub} to indicate that @{fg shine}complex1@{fg text} is the end of the linked list. The value @{fg shine}complex1@{fg text} is returned by the function, which isn't always useful so, usually, calls to @{b}Link@{ub} will be used as statements rather than functions. The effect of @{b}Link@{ub} is that @{fg shine}complex1@{fg text} will point to @{fg shine}complex2@{fg text} as the next element in the linked list (so @{fg shine}complex1@{fg text} is the @{fg shine}head@{fg text} of the list, and @{fg shine}complex2@{fg text} is the @{fg shine}tail@{fg text}). For both E-lists and E-strings the pointer to the next element is initially @{b}NIL@{ub}, so you will only need to use @{b}Link@{ub} with a @{b}NIL@{ub} parameter when you want to make a linked list shorter (by losing the tail). @{b}Next(@{ub}@{fg shine}complex@{fg text}@{b})@{ub} Returns the pointer to the next element in the linked list. This may be the special constant @{b}NIL@{ub} if @{fg shine}complex@{fg text} is the last element in the linked list. Be careful to check that the value isn't @{b}NIL@{ub} before you dereference it! Follow the comments in the example below: DEF s[23]:STRING, t[7]:STRING, lt[41]:LIST, lnk /* The next two lines set up the linked list "lnk" */ lnk:=Link(lt,t) /* lnk list starts at lt and is lt->t */ lnk:=Link(s,lt) /* Now it starts at s and is s->lt->t */ /* The next three lines follow the links in "lnk" */ lnk:=Next(lnk) /* Now it starts at lt and is lt->t */ lnk:=Next(lnk) /* Now it starts at t and is t */ lnk:=Next(lnk) /* Now lnk is NIL so the list has ended */ You may safely call @{b}Next@{ub} with a @{b}NIL@{ub} parameter, and in this case it will return @{b}NIL@{ub}. @{b}Forward(@{ub}@{fg shine}complex@{fg text}@{b},@{ub}@{fg shine}expression@{fg text}@{b})@{ub} Returns a pointer to the element which is @{fg shine}expression@{fg text} number of links down the linked list @{fg shine}complex@{fg text}. If @{fg shine}expression@{fg text} represents the value one a pointer to the next element is returned (just like using @{b}Next@{ub}). If it's two a pointer to the element after that is returned. If @{fg shine}expression@{fg text} represents a number which is greater than the number of links in the list the special value @{b}NIL@{ub} is returned. Since the link in a linked list is a pointer to the next element you can only look through the list from beginning to end. Technically this is a @{fg shine}singly@{fg text} linked list (a @{fg shine}doubly@{fg text} linked list would also have a pointer to the previous element in the list, enabling backwards searching through the list). Linked lists are useful for building lists that can grow quite large. This is because it's much better to have lots of small bits of memory than a large lump. However, you only need to worry about these things when you're playing with quite big lists (as a rough guide, ones with over 100,000 elements are big!). @EndNode @Node "More About Statements and Expressions" "beginner.guide/More About Statements and Expressions" @Next "E Built-In Constants Variables and Functions" @Prev "Types" @Toc "Main" More About Statements and Expressions ************************************* This chapter details various E statements and expressions that were not covered in Part One. It also completes some of the partial descriptions given in Part One. @{" Turning an Expression into a Statement " Link "Turning an Expression into a Statement"} @{" Initialised Declarations " Link "Initialised Declarations"} @{" Assignments " Link "Assignments"} @{" More Expressions " Link "More Expressions"} @{" More Statements " Link "More Statements"} @{" Unification " Link "Unification"} @{" Quoted Expressions " Link "Quoted Expressions"} @{" Assembly Statements " Link "Assembly Statements"} @EndNode @Node "Turning an Expression into a Statement" "beginner.guide/Turning an Expression into a Statement" @Next "Initialised Declarations" @Toc "More About Statements and Expressions" Turning an Expression into a Statement ====================================== The @{b}VOID@{ub} operator converts an expression to a statement. It does this by evaluating the expression and then throwing the result away. This may not seem very useful, but in fact we've done it a lot already. We didn't use @{b}VOID@{ub} explicitly because E does this automatically if it finds an expression where it was expecting a statement (normally when it is on a line by itself). Some of the expressions we've turned into statements were the procedure calls (to @{b}WriteF@{ub} and @{b}fred@{ub}) and the use of @{b}++@{ub}. Remember that all procedure calls denote values because they're really functions that, by default, return zero (see @{"Functions" Link "Functions"}). For example, the following code fragments are equivalent: VOID WriteF('Hello world\n') VOID x++ WriteF('Hello world\n') x++ Since E automatically uses @{b}VOID@{ub} it's a bit of a waste of time writing it in, although there may be occasions where you want to use it to make this voiding process more explicit (to the reader). The important thing is the fact that expressions can validly be used as statements in E. @EndNode @Node "Initialised Declarations" "beginner.guide/Initialised Declarations" @Next "Assignments" @Prev "Turning an Expression into a Statement" @Toc "More About Statements and Expressions" Initialised Declarations ======================== Some variables can be initialised using constants in their declarations. The variables you cannot initialise in this way are array and complex type variables (and procedure parameters, obviously). All the other kinds can be initialised, whether they are local or global. An @{fg shine}initialised declaration@{fg text} looks very much like a constant definition, with the value following the variable name and a @{b}=@{ub} character joining them. The following example illustrates initialised declarations: SET ENGLISH, FRENCH, GERMAN, JAPANESE, RUSSIAN CONST FREDLANGS=ENGLISH OR FRENCH OR GERMAN DEF fredspeak=FREDLANGS, p=NIL:PTR TO LONG, q=0:PTR TO rec PROC fred() DEF x=1, y=88 /* Rest of procedure */ ENDPROC Notice how the constant @{b}FREDLANGS@{ub} needs to be defined in order to initialise the declaration of @{b}fredspeak@{ub} to something mildly complicated. Also, notice the initialisation of the pointers @{b}p@{ub} and @{b}q@{ub}, and the position of the type information. Of course, if you want to initialise variables with anything more complicated than a constant you can use assignments at the start of the code. Generally, you should always initialise your variables (using either method) so that they are guaranteed to have a sensible value when you use them. Using the value of a variable that you haven't initialised in some way will probably get you in to a lot of trouble, because the value will just be some random value that happened to be in the memory used by the variable. There are rules for how E initialises some kinds of variables (see the `Reference Manual', but it's wise to explicitly initialise even those, as (strangely enough!) this will make your program more readable. @EndNode @Node "Assignments" "beginner.guide/Assignments" @Next "More Expressions" @Prev "Initialised Declarations" @Toc "More About Statements and Expressions" Assignments =========== We've already seen some assignments--these were assignment statements. Assignment expressions are similar except (as you've guessed) they can be used in expressions. This is because they return the value on the right-hand side of the assignment as well as performing the assignment. This is useful for efficiently checking that the value that's been assigned is sensible. For instance, the following code fragments are equivalent, but the first uses an assignment expression instead of a normal assignment statement. IF (x:=y*z)=0 WriteF('Error: y*z is zero (and x is zero)\n') ELSE WriteF('OK: y*z is not zero (and x is y*z)\n') ENDIF x:=y*z IF x=0 WriteF('Error: y*z is zero (and x is zero)\n') ELSE WriteF('OK: y*z is not zero (and x is y*z)\n') ENDIF You can easily tell the assignment expression: it's in parentheses and not on a line by itself. Notice the use of parentheses to group the assignment expression. Technically, the assignment operator has a very low precedence. Less technically, it will take as much as it can of the right-hand side to form the value to be assigned, so you need to use parentheses to stop @{b}x@{ub} getting the value @{b}((y*z)=0)@{ub} (which will be @{b}TRUE@{ub} or @{b}FALSE@{ub}, i.e., -1 or zero). Assignment expressions, however, don't allow as rich a left-hand side as assignment statements. The only thing allowed on the left-hand side of an assignment expression is a variable name, whereas the statement form allows: @{fg shine}var@{fg text} @{fg shine}var@{fg text} [ @{fg shine}expression@{fg text} ] @{fg shine}var@{fg text} . @{fg shine}obj_element_name@{fg text} ^ @{fg shine}var@{fg text} (With as many repetitions of object element selection and/or array indexing as the elements' types allow.) Each of these may end with @{b}++@{ub} or @{b}--@{ub}. Therefore, the following are all valid assignments (the last three use assignment expressions): x:=2 x--:=1 x[a*b]:=rubble x.apple++:=3 x[22].apple:=y*z x[].banana.basket[6]:=3+full(9) x[].pear--:=fred(2,4) x.pear:=(y:=2) x[y*z].table[1].orange:=(IF (y:=z)=2 THEN 77 ELSE 33) WriteF('x is now \d\n', x:=1+(y:=(z:=fred(3,5)/2)*8)) You may be wondering what the @{b}++@{ub} or @{b}--@{ub} affect. Well, it's very simple: they only affect the @{fg shine}var@{fg text}, which is @{b}x@{ub} in all of the examples above. Notice that @{b}x[].pear--@{ub} is the same as @{b}x.pear--@{ub}, for the same reasons mentioned earlier (see @{"Element selection and element types" Link "Element selection and element types"}). @EndNode @Node "More Expressions" "beginner.guide/More Expressions" @Next "More Statements" @Prev "Assignments" @Toc "More About Statements and Expressions" More Expressions ================ This section discusses side-effects, details two new operators (@{b}BUT@{ub} and @{b}SIZEOF@{ub}) and completes the description of the @{b}AND@{ub} and @{b}OR@{ub} operators. @{" Side-effects " Link "Side-effects"} @{" BUT expression " Link "BUT expression"} @{" Bitwise AND and OR " Link "Bitwise AND and OR"} @{" SIZEOF expression " Link "SIZEOF expression"} @EndNode @Node "Side-effects" "beginner.guide/Side-effects" @Next "BUT expression" @Toc "More Expressions" Side-effects ------------ If evaluating an expression causes the contents of variables to change then that expression is said to have @{fg shine}side-effects@{fg text}. An assignment expression is a simple example of an expression with side-effects. Less obvious ones involve function calls with pointers to variables. Generally, expressions with side-effects should be avoided unless it is really obvious what is happening. This is because it can be difficult to find problems with your program's code if subtleties are buried in complicated expressions. On the other hand, side-effecting expressions are concise and often very elegant. They are also useful for @{i}obfuscating@{ui} your code (i.e., making it difficult to understand--a form of copy protection!). @EndNode @Node "BUT expression" "beginner.guide/BUT expression" @Next "Bitwise AND and OR" @Prev "Side-effects" @Toc "More Expressions" @{b}BUT@{ub} expression -------------- @{b}BUT@{ub} is used to sequence two expressions. @{b}@{ub}@{fg shine}exp1@{fg text}@{b} BUT @{ub}@{fg shine}exp2@{fg text}@{b}@{ub} evaluates @{fg shine}exp1@{fg text}, and then evaluates and returns the value of @{fg shine}exp2@{fg text}. This may not seem very useful at first sight, but if the first expression is an assignment it allows for a more general assignment expression. For example, the following code fragments are equivalent: fred((x:=12*3) BUT x+y) x:=12*3 fred(x+y) Notice that parentheses need to be used around the assignment expression (in the first fragment) for the reasons given earlier (see @{"Assignments" Link "Assignments"}). @EndNode @Node "Bitwise AND and OR" "beginner.guide/Bitwise AND and OR" @Next "SIZEOF expression" @Prev "BUT expression" @Toc "More Expressions" Bitwise @{b}AND@{ub} and @{b}OR@{ub} ------------------ As hinted in the earlier chapters, the operators @{b}AND@{ub} and @{b}OR@{ub} are not simply logical operators. In fact, they are both bit-wise operators, where a @{fg shine}bit@{fg text} is a binary digit (i.e., the zeroes or ones in the binary form of a number). So, to see how they work we should look at what happens to zeroes and ones: x y x OR y x AND y ------------------------ 1 1 1 1 1 0 1 0 0 1 1 0 0 0 0 0 Now, when you @{b}AND@{ub} or @{b}OR@{ub} two numbers the corresponding bits (binary digits) of the numbers are compared individually, according to the above table. So if @{b}x@{ub} were @{b}%0111010@{ub} and @{b}y@{ub} were @{b}%1010010@{ub} then @{b}x AND y@{ub} would be @{b}%0010010@{ub} and @{b}x OR y@{ub} would be @{b}%1111010@{ub}: %0111010 %0111010 AND OR %1010010 %1010010 ------- ------- %0010010 %1111010 The numbers (in binary form) are lined up above each other, just like you do additions with normal numbers (i.e., starting with the right-hand digits, and maybe padding with zeroes on the left-hand side). The two bits in each column are @{b}AND@{ub}-ed or @{b}OR@{ub}-ed to give the result below the line. So, how does this work for @{b}TRUE@{ub} and @{b}FALSE@{ub} and logic operations? Well, @{b}FALSE@{ub} is the number zero, so all the bits of @{b}FALSE@{ub} are zeroes, and @{b}TRUE@{ub} is -1, which is has all 32 bits as ones (these numbers are @{b}LONG@{ub} so they are 32-bit quantities). So @{b}AND@{ub}-ing and @{b}OR@{ub}-ing these values always gives numbers which have all zero bits (i.e., @{b}FALSE@{ub}) or all one bits (i.e., @{b}TRUE@{ub}), as appropriate. It's only when you start mixing numbers that aren't zero or -1 that you can muck up the logic. The non-zero numbers one and four are (by themselves) considered to be @{b}TRUE@{ub}, but @{b}4 AND 1@{ub} is @{b}%100 AND %001@{ub} which is zero (i.e., @{b}FALSE@{ub}). So when you use @{b}AND@{ub} as the logical operator it's not strictly true that all non-zero numbers represent @{b}TRUE@{ub}. @{b}OR@{ub} does not give such problems so all non-zero numbers are treated as @{b}TRUE@{ub}. Run this example to see why you should be careful: PROC main() test(TRUE, 'TRUE\t\t') test(FALSE, 'FALSE\t\t') test(1, '1\t\t') test(4, '4\t\t') test(TRUE OR TRUE, 'TRUE OR TRUE\t') test(TRUE AND TRUE, 'TRUE AND TRUE\t') test(1 OR 4, '1 OR 4\t\t') test(1 AND 4, '1 AND 4\t\t') ENDPROC PROC test(x, title) WriteF(title) WriteF(IF x THEN ' is TRUE\n' ELSE ' is FALSE\n') ENDPROC Here's the output that should be generated: TRUE is TRUE FALSE is FALSE 1 is TRUE 4 is TRUE TRUE OR TRUE is TRUE TRUE AND TRUE is TRUE 1 OR 4 is TRUE 1 AND 4 is FALSE So, @{b}AND@{ub} and @{b}OR@{ub} are primarily bit-wise operators, and they can be used as logical operators under most circumstances, with zero representing false and all other numbers representing true. Care must be taken when using @{b}AND@{ub} with some pairs of non-zero numbers, since the bit-wise @{b}AND@{ub} of such numbers does not always give a non-zero (or true) result. @EndNode @Node "SIZEOF expression" "beginner.guide/SIZEOF expression" @Prev "Bitwise AND and OR" @Toc "More Expressions" @{b}SIZEOF@{ub} expression ----------------- @{b}SIZEOF@{ub} returns the size, in bytes, of an object or a built-in type (like @{b}LONG@{ub}). This can be useful for determining storage requirements. For instance, the following code fragment prints the size of the object @{b}rec@{ub}: OBJECT rec tag, check table[8]:ARRAY data:LONG ENDOBJECT PROC main() WriteF('Size of rec object is \d bytes\n', SIZEOF rec) ENDPROC You may think that @{b}SIZEOF@{ub} is unnecessary because you can easily calculate the size of an object just by looking at the sizes of the elements. Whilst this is generally true (it was for the @{b}rec@{ub} object), there is one thing to be careful about: alignment. This means that @{b}ARRAY@{ub}, @{b}INT@{ub}, @{b}LONG@{ub} and object typed elements must start at an even memory address. Normally this isn't a problem, but if you have an odd number of consecutive @{b}CHAR@{ub} typed elements or an odd sized @{b}ARRAY OF CHAR@{ub}, an extra, @{fg shine}pad@{fg text} byte is introduced into the object so that the following element is aligned properly. This pad byte can be considered part of an @{b}ARRAY OF CHAR@{ub}, so in effect this means array sizes are rounded up to the nearest even number. Otherwise, pad bytes are just an unusable part of an object, and their presence means the object size is not quite what you'd expect. Try the following program: OBJECT rec2 tag, check table[7]:ARRAY data:LONG ENDOBJECT PROC main() WriteF('Size of rec2 object is \d bytes\n', SIZEOF rec2) ENDPROC The only difference between the @{b}rec@{ub} and @{b}rec2@{ub} objects is that the array size is seven in @{b}rec2@{ub}. If you run the program you'll see that the size of the object has not changed. We might just as well have declared the @{b}table@{ub} element to be a slightly bigger array (i.e., have eight elements). @EndNode @Node "More Statements" "beginner.guide/More Statements" @Next "Unification" @Prev "More Expressions" @Toc "More About Statements and Expressions" More Statements =============== This section details five new statements (@{b}INC@{ub}, @{b}DEC@{ub}, @{b}JUMP@{ub}, @{b}EXIT@{ub} and @{b}LOOP@{ub}) and describes the use of labelling. @{" INC and DEC statements " Link "INC and DEC statements"} @{" Labelling and the JUMP statement " Link "Labelling and the JUMP statement"} @{" EXIT statement " Link "EXIT statement"} @{" LOOP block " Link "LOOP block"} @EndNode @Node "INC and DEC statements" "beginner.guide/INC and DEC statements" @Next "Labelling and the JUMP statement" @Toc "More Statements" @{b}INC@{ub} and @{b}DEC@{ub} statements ---------------------- @{b}INC x@{ub} is the same as the statement @{b}x:=x+1@{ub}. However, because it doesn't do an addition it's a bit more efficient. Similarly, @{b}DEC x@{ub} is the same as @{b}x:=x-1@{ub}. The observant reader may think that @{b}INC@{ub} and @{b}DEC@{ub} are the same as @{b}++@{ub} and @{b}--@{ub}. But there's one important difference: @{b}INC x@{ub} always increases @{b}x@{ub} by one, whereas @{b}x++@{ub} may increase @{b}x@{ub} by more than one depending on the type to which @{b}x@{ub} points. For example, if @{b}x@{ub} were a pointer to @{b}INT@{ub} then @{b}x++@{ub} would increase @{b}x@{ub} by two (@{b}INT@{ub} is 16-bit, which is two bytes). @EndNode @Node "Labelling and the JUMP statement" "beginner.guide/Labelling and the JUMP statement" @Next "EXIT statement" @Prev "INC and DEC statements" @Toc "More Statements" Labelling and the @{b}JUMP@{ub} statement -------------------------------- A @{fg shine}label@{fg text} names a position in a program, and these names are global (they can be used in any procedure). The most common use of label is with the @{b}JUMP@{ub} statement, but you can also use labels to mark the position of some data (see @{"Assembly Statements" Link "Assembly Statements"}). To define a label you write a name followed by a colon immediately before the position you want to mark. This must be just before the beginning of a statement, either on the previous line (by itself) or the start of the same line. The @{b}JUMP@{ub} statement makes execution continue from the position marked by a label. This position must be in the same procedure, but it can be, for instance, outside of a loop (and the @{b}JUMP@{ub} will then have terminated that loop). For example, the following code fragments are equivalent: x:=1 y:=2 JUMP rubble x:=9999 y:=1234 rubble: z:=88 x:=1 y:=2 z:=88 As you can see the @{b}JUMP@{ub} statement has caused the second group of assignments to @{b}x@{ub} and @{b}y@{ub} to be skipped. A more useful example uses @{b}JUMP@{ub} to help terminate a loop: x:=1 y:=2 WHILE x<10 IF y<10 WriteF('x is \d, y is \d\n', x, y) ELSE JUMP end ENDIF x:=x+2 y:=y+2 ENDWHILE end: WriteF('Finished!\n') This loop terminates if @{b}x@{ub} is not less than ten (the @{b}WHILE@{ub} check), or if @{b}y@{ub} is not less than ten (the @{b}JUMP@{ub} in the @{b}IF@{ub} block). This may seem pretty familiar, because it's practically the same as an example earlier (see @{"WHILE loop" Link "WHILE loop"}). In fact, it's equivalent to: x:=1 y:=2 WHILE (x<10) AND (y<10) WriteF('x is \d, y is \d\n', x, y) x:=x+2 y:=y+2 ENDWHILE WriteF('Finished!\n') @EndNode @Node "EXIT statement" "beginner.guide/EXIT statement" @Next "LOOP block" @Prev "Labelling and the JUMP statement" @Toc "More Statements" @{b}EXIT@{ub} statement -------------- As noted above, you can use the @{b}JUMP@{ub} statement and labelling to break out of a loop prematurely. However, a much nicer mechanism exists for @{b}WHILE@{ub} and @{b}FOR@{ub} loops: the @{b}EXIT@{ub} statement. This statement will terminate the closest one of these loops (of which it is part) if the supplied expression evaluates to true (i.e., a non-zero value). Any loop using @{b}EXIT@{ub} can be re-written without it, but sometimes at the expense of readability. The following fragments of code are equivalent: FOR x:=1 TO 10 y:=f(x) EXIT y=-1 WriteF('x=\d, f(x)=\d\n', x, y) ENDFOR FOR x:=1 TO 10 y:=f(x) IF y=-1 THEN JUMP end WriteF('x=\d, f(x)=\d\n', x, y) ENDFOR end: This example shows a situation which is arguably more readable using something like @{b}EXIT@{ub}. It can be rewritten using a @{b}WHILE@{ub} loop, as below, but the code is a bit less clear. going:=TRUE x:=1 WHILE going AND (x<=10) y:=f(x) IF y=-1 going:=FALSE ELSE WriteF('x=\d, f(x)=\d\n', x, y) INC x ENDIF ENDWHILE @EndNode @Node "LOOP block" "beginner.guide/LOOP block" @Prev "EXIT statement" @Toc "More Statements" @{b}LOOP@{ub} block ---------- A @{b}LOOP@{ub} block is a multi-line statement. It's the general form of loops like the @{b}WHILE@{ub} loop, and it builds a loop with no check. So, this kind of loop would normally never end. However, as we now know, you can terminate a @{b}LOOP@{ub} block using the @{b}JUMP@{ub} statement. As an example, the following two code fragments are equivalent: x:=0 LOOP IF x<100 WriteF('x is \d\n', x++) ELSE JUMP end ENDIF ENDLOOP end: WriteF('Finished\n') x:=0 WHILE x<100 WriteF('x is \d\n', x++) ENDWHILE WriteF('Finished\n') @EndNode @Node "Unification" "beginner.guide/Unification" @Next "Quoted Expressions" @Prev "More Statements" @Toc "More About Statements and Expressions" Unification =========== In E, @{fg shine}unification@{fg text} is a way of doing complicated, conditional assignments. It may also be referred to as @{fg shine}pattern matching@{fg text} because that is what it does: it matches patterns and tries to fits values to the variables mentioned in those patterns. The result of a unification is true or false, depending on whether the pattern was successfully matched. The basic form of a unification expression is: @{fg shine}expression@{fg text} <=> @{fg shine}pattern@{fg text} The only things that can be used in a pattern are constants and variable names, and lists of patterns. (Strictly speaking, lisp-cells are also allowed, but this variant of unification is beyond the scope of this Guide.) The @{fg shine}pattern@{fg text} is matched against the @{fg shine}expression@{fg text} as follows: @{b}*@{ub} If @{fg shine}pattern@{fg text} is a constant then the match succeeds only if @{fg shine}expression@{fg text} evaluates to the same value. So, the simple unification expression @{b}x<=>1@{ub} is similar to an equality check @{b}x=1@{ub}. @{b}*@{ub} If @{fg shine}pattern@{fg text} is a variable name then the match is successful and the variable is assigned the value of @{fg shine}expression@{fg text}. So, the simple unification expression @{b}1<=>x@{ub} is similar to an assignment @{b}x:=1@{ub}. @{b}*@{ub} If @{fg shine}pattern@{fg text} is a list then @{fg shine}expression@{fg text} is assumed to be a list, and each element of @{fg shine}pattern@{fg text} is taken to be a pattern to be (recursively) matched against the corresponding element (by index) of the @{fg shine}expression@{fg text} list. The match succeeds only if the @{fg shine}pattern@{fg text} list and the @{fg shine}expression@{fg text} list are the same length and all the elements match. (It is a serious programming error if @{fg shine}pattern@{fg text} is a list but @{fg shine}expression@{fg text} does not represent a list. In this case, strange things may happen and the program may crash.) So, the things in @{fg shine}pattern@{fg text} that control whether a match succeeds are the constants and the lists. If a match succeeds then all variables mentioned in the @{fg shine}pattern@{fg text} will be assigned the appropriate values. However, if a match fails you should consider all variables involved in the pattern to have undefined values (so you may need to initialise them to safely their values again). This is because the actual way that unification is implemented may not follow the rules above in the obvious way, but will have the same effect in the successful case and will affect only the variables mentioned in the pattern if the match fails. For example, the following program shows a couple of simple unification expressions in use: PROC main() DEF x, lt x:=0 WriteF('x is \d\n', x) lt:=[9,-1,7,4] /* The next line uses unification */ IF lt <=> [9,-1,x,4] WriteF('First match succeeded\n') WriteF('1) x is now \d\n', x) ELSE WriteF('First match failed\n') /* To be safe, reset x */ x:=0 ENDIF /* The next line uses unification */ IF lt <=> [1,x,6,4] WriteF('Second match succeeded\n') WriteF('2) x is now \d\n', x) ELSE WriteF('Second match failed\n') /* To be safe, reset x */ x:=0 ENDIF ENDPROC The first match will succeed in this example, and there will be a side-effect of assigning seven to @{b}x@{ub}. The second match will not succeed because, for instance, the first element of @{b}lt@{ub} is not one. We can rewrite the above example without using the unification operator (to show why unification is so useful). This code follows the rules in one particular way, so is not guaranteed to have the same effect as the unification version if any of the matches fail. PROC main() DEF x, lt, match x:=0 WriteF('x is \d\n', x) lt:=[9,-1,7,4] /* The next lines mimic: lt <=> [9,-1,x,4] */ match:=FALSE IF ListLen(lt)=4 IF ListItem(lt, 0)=9 IF ListItem(lt, 1)=-1 x:=ListItem(lt,2) IF ListItem(lt, 3)=4 match:=TRUE ENDIF ENDIF ENDIF ENDIF IF match WriteF('First match succeeded\n') WriteF('1) x is now \d\n', x) ELSE WriteF('First match failed\n') /* To be safe, reset x */ x:=0 ENDIF /* The next lines mimic: lt <=> [1,x,6,4] */ match:=FALSE IF ListLen(lt)=4 IF ListItem(lt, 0)=1 x:=ListItem(lt, 1) IF ListItem(lt, 2)=6 IF ListItem(lt, 3)=4 match:=TRUE ENDIF ENDIF ENDIF ENDIF IF match WriteF('Second match succeeded\n') WriteF('2) x is now \d\n', x) ELSE WriteF('Second match failed\n') /* To be safe, reset x */ x:=0 ENDIF ENDPROC Here's a slightly more complicated example, which shows how you might use patterns made up of nested lists. Remember that if the pattern is a list then the expression to be matched must be a list. If this is not the case (e.g., if the expression represents @{b}NIL@{ub}) then your program could behave strangely or even crash your computer. A similar, but less disastrous, problem is if the converse happens: the pattern is not a list but the expression to be matched is a list. In this case the pointer (to the list) is matched against the pattern constant or assigned to the pattern variable. PROC main() DEF x=10, y=-3, p=NIL:PTR TO LONG, lt, i WriteF('x is \d, y is \d\n', x, y) lt:=[[23,x],y] /* This basically swaps x and y */ IF lt <=> [[23,y],x] WriteF('First match succeeded\n') WriteF('1) Now x is \d, y is \d\n', x, y) ELSE WriteF('First match failed\n') /* To be safe, reset x and y */ x:=10; y:=-3 ENDIF /* This will make p point to the sub-list of lt */ IF lt <=> [p,-3] WriteF('Second match succeeded\n') WriteF('2) p is now $\h (a pointer to a list)\n', p) FOR i:=0 TO ListLen(p)-1 WriteF(' Element \d of the list p is \d\n', i, p[i]) ENDFOR ELSE WriteF('First match failed\n') /* To be safe, reset p */ p:=NIL ENDIF ENDPROC @EndNode @Node "Quoted Expressions" "beginner.guide/Quoted Expressions" @Next "Assembly Statements" @Prev "Unification" @Toc "More About Statements and Expressions" Quoted Expressions ================== @{fg shine}Quoted expressions@{fg text} are a powerful feature of the E language, and they require quite a bit of advanced knowledge. Basically, you can @{fg shine}quote@{fg text} any expression by starting it with the back-quote character ` (be careful not to get it mixed up with the quote character ' which is used for strings). This quoting action does not evaluate the expression, instead the address of the code for the expression is returned. This address can be used just like any other address, so you can, for instance, store it in a variable and pass it to procedures. Of course, at some point you will use the address to execute the code and get the value of the expression. The idea of quoted expressions was borrowed from the functional programming language Lisp. Also borrowed were some powerful functions which combine lists with quoted expressions to give very concise and readable statements. @{" Evaluation " Link "Evaluation"} @{" Quotable expressions " Link "Quotable expressions"} @{" Lists and quoted expressions " Link "Lists and quoted expressions"} @EndNode @Node "Evaluation" "beginner.guide/Evaluation" @Next "Quotable expressions" @Toc "Quoted Expressions" Evaluation ---------- When you've quoted an expression you have the address of the code which calculates the value of the expression. To evaluate the expression you pass this address to the @{b}Eval@{ub} function. So now we have a round-about way of calculating the value of an expression. (If you have a GB keyboard you can get the ` character by holding down the ALT key and pressing the ' key, which is in the corner just below the ESC key. On a US and most European keyboards it's on the same key but you don't have to press the ALT key at the same time.) PROC main() DEF adr, x, y x:=0; y:=0 adr:=`1+(fred(x,1)*8)-y x:=2; y:=7 WriteF('The value is \d\n', Eval(adr)) x:=1; y:=100 WriteF('The value is now \d\n', Eval(adr)) ENDPROC PROC fred(a,b) RETURN (a+b)*a+20 This is the output that should be generated: The value is 202 The value is now 77 This example shows a quite complicated expression being quoted. The address of the expression is stored in the variable @{b}adr@{ub}, and the expression is evaluated using @{b}Eval@{ub} in the calls to @{b}WriteF@{ub}. The values of the variables @{b}x@{ub} and @{b}y@{ub} when the expression is quoted are irrelevant--only their values each time @{b}Eval@{ub} is used are significant. Therefore, when @{b}Eval@{ub} is used in the second call to @{b}WriteF@{ub} the values of @{b}x@{ub} and @{b}y@{ub} have changed so the resulting value is different. Repeatedly evaluating the same expression is the most obvious use of quoted expressions. Another common use is when you want to do the same thing for a variety of different expressions. For example, if you wanted to discover the amount of time it takes to calculate the results of various expressions it would be best to use quoted expressions, something like this: DEF x,y PROC main() x:=999; y:=173 time(`x+y, 'Addition') time(`x*y, 'Multiplication') time(`fred(x), 'Procedure call') ENDPROC PROC time(exp, message) WriteF(message) /* Find current time */ Eval(exp) /* Find new time and calculate difference, t */ WriteF(': time taken \d\n', t) ENDPROC This is just the outline of a program--it's not complete so don't bother running it. The complete version is given as a worked example later (see @{"Timing Expressions" Link "Timing Expressions"}). @EndNode @Node "Quotable expressions" "beginner.guide/Quotable expressions" @Next "Lists and quoted expressions" @Prev "Evaluation" @Toc "Quoted Expressions" Quotable expressions -------------------- There is no restriction on the kinds of expression you can quote, except that you need to be careful about variable scoping. If you use local variables in a quoted expression you can only @{b}Eval@{ub} it within the same procedure (so the variables are in scope). However, if you use only global variables you can @{b}Eval@{ub} it in any procedure. Therefore, if you are going to pass a quoted expression to a procedure and do something with it, you should use only global variables. A word of warning: @{b}Eval@{ub} does not check to see if the address it's been given is really the address of an expression. You can therefore get in a real mess if you pass it, say, the address of a variable using @{b}{@{ub}@{fg shine}var@{fg text} @{b} }@{ub}. You need to check all uses of things like @{b}Eval@{ub} yourself, because the E compiler lets you write things like @{b}Eval(x+9)@{ub}, where you probably meant to write @{b}Eval(`x+9)@{ub}. That's because you might want the address you pass to @{b}Eval@{ub} to be the result of complicated expressions. So you may have meant to pass @{b}x+9@{ub} as the parameter! @EndNode @Node "Lists and quoted expressions" "beginner.guide/Lists and quoted expressions" @Prev "Quotable expressions" @Toc "Quoted Expressions" Lists and quoted expressions ---------------------------- There are several E built-in functions which use lists and quoted expressions in powerful ways. These functions are similar to functional programming constructs and, basically, they allow for very readable code, which otherwise would require iterative algorithms (i.e., loops). @{b}MapList(@{ub}@{fg shine}address@{fg text}@{b},@{ub}@{fg shine}list@{fg text}@{b},@{ub}@{fg shine}e-list@{fg text}@{b},@{ub}@{fg shine}quoted-exp@{fg text}@{b})@{ub} The @{fg shine}address@{fg text} is the address of a variable (e.g., @{b}{x}@{ub}), @{fg shine}list@{fg text} is a list or E-list (the source), @{fg shine}e-list@{fg text} is an E-list variable (the destination), and @{fg shine}quoted-exp@{fg text} is the address of an expression which involves the addressed variable (e.g., @{b}`x+2@{ub}). The effect of the function is to take, in turn, a value from @{fg shine}list@{fg text}, store it at @{fg shine}address@{fg text}, evaluate the quoted expression and store the result in the destination list. The resulting list is also returned (for convenience). For example: MapList({y}, [1,2,3,a,99,1+c], lt, `y*y) results in @{b}lt@{ub} taking the value: [1,4,9,a*a,9801,(1+c)*(1+c)] Functional programmers would say that @{b}MapList@{ub} @{fg shine}mapped@{fg text} the function (the quoted expression) across the (source) list. @{b}ForAll(@{ub}@{fg shine}address@{fg text}@{b},@{ub}@{fg shine}list@{fg text}@{b},@{ub}@{fg shine}quoted-exp@{fg text}@{b})@{ub} Works just like @{b}MapList@{ub} except that the resulting list is not stored. Instead, @{b}ForAll@{ub} returns @{b}TRUE@{ub} if every element of the resulting list is @{b}TRUE@{ub} (i.e., non-zero), and @{b}FALSE@{ub} otherwise. In this way it decides whether the quoted expression is @{b}TRUE@{ub} @{fg shine}for all@{fg text} elements of the source list. For example, the following are @{b}TRUE@{ub}: ForAll({x}, [1,2,-13,8,0], `x<10) ForAll({x}, [1,2,-13,8,0], `x<=8) ForAll({x}, [1,2,-13,8,0], `x>-20) and these are @{b}FALSE@{ub}: ForAll({x}, [1,2,-13,8,0], `x OR x) ForAll({x}, [1,2,-13,8,0], `x=2) ForAll({x}, [1,2,-13,8,0], `x<>2) @{b}Exists(@{ub}@{fg shine}address@{fg text}@{b},@{ub}@{fg shine}list@{fg text}@{b},@{ub}@{fg shine}quoted-exp@{fg text}@{b})@{ub} Works just like @{b}ForAll@{ub} except it returns @{b}TRUE@{ub} if the quoted expression is @{b}TRUE@{ub} (i.e., non-zero) for at least one of the source list elements and @{b}FALSE@{ub} otherwise. For example, the following are @{b}TRUE@{ub}: Exists({x}, [1,2,-13,8,0], `x<10) Exists({x}, [1,2,-13,8,0], `x=2) Exists({x}, [1,2,-13,8,0], `x>0) and these are @{b}FALSE@{ub}: Exists({x}, [1,2,-13,8,0], `x<-20) Exists({x}, [1,2,-13,8,0], `x=4) Exists({x}, [1,2,-13,8,0], `x>8) @{b}SelectList(@{ub}@{fg shine}address@{fg text}@{b},@{ub}@{fg shine}list@{fg text}@{b},@{ub}@{fg shine}e-list@{fg text}@{b},@{ub}@{fg shine}quoted-exp@{fg text}@{b})@{ub} Works just like @{b}MapList@{ub} except the @{fg shine}quoted-exp@{fg text} is used to decide which elements from @{fg shine}list@{fg text} are copied to @{b}e-list@{ub}. Only the elements for which @{fg shine}quoted-exp@{fg text} evaluates to a non-zero (i.e., true) value are copied. The resulting list is also returned (for convenience). For example: SelectList({y}, [99,6,1,2,7,1,1,6,6], lt, `y>5) results in @{b}lt@{ub} taking the value: [99,6,7,6,6] @EndNode @Node "Assembly Statements" "beginner.guide/Assembly Statements" @Prev "Quoted Expressions" @Toc "More About Statements and Expressions" Assembly Statements =================== The E language incorporates an assembler so you can write Assembly mnemonics as E statements. You can even write complete Assembly programs and compile them using the E compiler. More powerfully, you can use E variables as part of the mnemonics, so you can really mix Assembly statements with normal E statements. This is not really the place to discuss Assembly programming, so if you plan to use this feature of E you should get yourself a good book, preferably on Amiga Assembly. Remember that the Amiga uses the Motorola 68000 CPU, so you need to learn the Assembly language for that CPU. More powerful and newer Amigas use more advanced CPUs (such as the 68020) which have extra mnemonics. Programs written using just 68000 CPU mnemonics will work on all Amigas. If you don't know 68000 Assembly language you ought to skip this section and just bear in mind that E statements you don't recognise are probably Assembly mnemonics. @{" Assembly and the E language " Link "Assembly and the E language"} @{" Static memory " Link "Static memory"} @{" Things to watch out for " Link "Things to watch out for"} @EndNode @Node "Assembly and the E language" "beginner.guide/Assembly and the E language" @Next "Static memory" @Toc "Assembly Statements" Assembly and the E language --------------------------- You can reference E variables simply by using them in an operand. Follow the comments in the next example (the comments are on the same lines as the Assembly mnemonics, the other lines are normal E statements): PROC main() DEF x x:=1 MOVE.L x, D0 /* Copy the value in x to register D0 */ ADD.L D0, D0 /* Double the value in D0 */ MOVE.L D0, x /* Copy the value in D0 back to variable x */ WriteF('x is now \d\n', x) ENDPROC Constants can also be referenced but you need to precede the constant with a @{b}#@{ub}. CONST APPLE=2 PROC main() DEF x MOVE.L #APPLE, D0 /* Copy the constant APPLE to register D0 */ ADD.L D0, D0 /* Double the value in D0 */ MOVE.L D0, x /* Copy the value in D0 to variable x */ WriteF('x is now \d\n', x) ENDPROC Labels and procedures can similarly be referenced, but these are PC-relative so you can only address them in this way. The following example illustrates this, but doesn't do anything useful: PROC main() DEF x LEA main(PC), A0 /* Copy the address of main to register A0 */ MOVE.L A0, x /* Copy the value in A0 to variable x */ WriteF('x is now \d\n', x) ENDPROC You can call Amiga system functions in the same way as you would normally in Assembly. You need to load the A6 register with the appropriate library base, load the other registers with appropriate data and then @{b}JSR@{ub} to the system routine. This next example uses the E built-in variable @{b}intuitionbase@{ub} and the Intuition library routine @{b}DisplayBeep@{ub}. When you run it the screen flashes (or, with Workbench 2.1 and above, you might get a beep or a sampled sound, depending on your Workbench setup). PROC main() MOVE.L #NIL, A0 MOVE.L intuitionbase, A6 JSR DisplayBeep(A6) ENDPROC @EndNode @Node "Static memory" "beginner.guide/Static memory" @Next "Things to watch out for" @Prev "Assembly and the E language" @Toc "Assembly Statements" Static memory ------------- Assembly programs reserve static memory for things like strings using @{b}DC@{ub} mnemonics. However, these aren't real mnemonics. They are, in fact, compiler directives and they can vary from compiler to compiler. The E versions are @{b}LONG@{ub}, @{b}INT@{ub} and @{b}CHAR@{ub} (the type names), which take a list of values, reserve the appropriate amount of static memory and fill in this memory with the supplied values. The @{b}CHAR@{ub} form also allows a list of characters to be supplied more easily as a string. In this case, the string will automatically be aligned to an even memory location, although you are responsible for null-terminating it. You can also include a whole file as static data using @{b}INCBIN@{ub} (and the file named using this statement must exist when the program is compiled). To get at the data you mark it with a label. This next example is a bit contrived, but illustrates some static data: PROC main() DEF x:PTR TO CHAR LEA datatable(PC), A0 MOVE.L A0, x WriteF(x) ENDPROC datatable: CHAR 'Hello world\n', 0 moredata: LONG 1,5,-999,0; INT -1,222 INCBIN 'file.data'; CHAR 0,7,-8 The Assembly stuff to get the label address is not really necessary, so the example could have been just: PROC main() WriteF({datatable}) ENDPROC datatable: CHAR 'Hello world\n', 0 @EndNode @Node "Things to watch out for" "beginner.guide/Things to watch out for" @Prev "Static memory" @Toc "Assembly Statements" Things to watch out for ----------------------- There are a few things to be aware of when using Assembly with E: @{b}*@{ub} All mnemonics and registers must be in uppercase, whilst, of course, E variables etc., follow the normal E rules. @{b}*@{ub} Most standard Assemblers use @{b};@{ub} to mark the rest of the line as a comment. In E you can use @{b}->@{ub} for the same effect, or you can use the @{b}/*@{ub} and @{b}*/@{ub} delimiters. @{b}*@{ub} Registers A4 and A5 are used internally by E, so should not be messed with if you are mixing E and Assembly code. Other registers might also be used, especially if you've used the @{b}REG@{ub} keyword. Refer to the `Reference Manual' for more details. @{b}*@{ub} E function calls like @{b}WriteF@{ub} can affect registers. Refer to the `Reference Manual' for more details. @EndNode @Node "E Built-In Constants Variables and Functions" "beginner.guide/E Built-In Constants Variables and Functions" @Next "Modules" @Prev "More About Statements and Expressions" @Toc "Main" E Built-In Constants, Variables and Functions ********************************************* This chapter describes the constants, variables and functions which are built-in to the E language. You can add more by using modules, but that's a more advanced topic (see @{"Modules" Link "Modules"}). @{" Built-In Constants " Link "Built-In Constants"} @{" Built-In Variables " Link "Built-In Variables"} @{" Built-In Functions " Link "Built-In Functions"} @EndNode @Node "Built-In Constants" "beginner.guide/Built-In Constants" @Next "Built-In Variables" @Toc "E Built-In Constants Variables and Functions" Built-In Constants ================== We've already met several built-in constants. Here's the complete list: @{b}TRUE@{ub}, @{b}FALSE@{ub} The boolean constants. As numbers, @{b}TRUE@{ub} is -1 and @{b}FALSE@{ub} is zero. @{b}NIL@{ub} The bad pointer value. Several functions produce this value for a pointer if an error occurred. As a number, @{b}NIL@{ub} is zero. @{b}ALL@{ub} Used with string and list functions to indicate that all the string or list is to be used. As a number, @{b}ALL@{ub} is -1. @{b}GADGETSIZE@{ub} The minimum number of bytes required to hold all the data for one gadget. See @{"Intuition support functions" Link "Intuition support functions"}. @{b}OLDFILE@{ub}, @{b}NEWFILE@{ub} Used with @{b}Open@{ub} to open an old or new file. See the `AmigaDOS Manual' for more details. @{b}STRLEN@{ub} The length of the last string constant used. Remember that a string constant is something between @{b}'@{ub} characters, so, for example, the following program prints the string @{b}s@{ub} and then its length: PROC main() DEF s:PTR TO CHAR, len s:='12345678' len:=STRLEN WriteF(s) WriteF('\nis \d characters long\n', len) ENDPROC @EndNode @Node "Built-In Variables" "beginner.guide/Built-In Variables" @Next "Built-In Functions" @Prev "Built-In Constants" @Toc "E Built-In Constants Variables and Functions" Built-In Variables ================== The following variables are built-in to E and are called @{fg shine}system variables@{fg text}. They are global so can be accessed from any procedure. @{b}arg@{ub} This is a string which contains the @{fg shine}command line@{fg text} arguments passed your program when it was run (from the Shell or CLI). For instance, if your program were called @{b}fred@{ub} and you ran it like this: fred file.txt "a big file" another then @{b}arg@{ub} would the string: file.txt "a big file" another If you have AmigaDOS 2.0 (or greater) you can use the system routine @{b}ReadArgs@{ub} to parse the command line in a much more versatile way. There is a worked example on argument parsing in Part Three (see @{"Argument Parsing" Link "Argument Parsing"}). @{b}wbmessage@{ub} This contains @{b}NIL@{ub} if your program was started from the Shell/CLI, otherwise it's a pointer to the Workbench message which contains information about the icons selected when you started the program from Workbench. So, if you started the program from Workbench @{b}wbmessage@{ub} will not be @{b}NIL@{ub} and it will contain the Workbench arguments, but if you started the program from the Shell/CLI @{b}wbmessage@{ub} will be @{b}NIL@{ub} and the argments will be in @{b}arg@{ub} (or via @{b}ReadArgs@{ub}). There is a worked example on argument parsing in Part Three (see @{"Argument Parsing" Link "Argument Parsing"}). @{b}stdin@{ub}, @{b}stdout@{ub}, @{b}conout@{ub} The @{b}stdin@{ub} and @{b}stdout@{ub} variables contain the standard input and output filehandles. If your program was started from the Shell/CLI they will be filehandles on the Shell/CLI window (and @{b}conout@{ub} will be @{b}NIL@{ub}). However, if your program was started from Workbench these will both be @{b}NIL@{ub}, and in this case the first call to @{b}WriteF@{ub} will open an output @{b}CON:@{ub} window and store the file handle for the window in @{b}stdout@{ub} and @{b}conout@{ub}. The file handle stored in @{b}conout@{ub} when the program terminates will be closed using @{b}Close@{ub}, so you can set up your own @{b}CON:@{ub} window or file for use by the output functions and have it automatically closed. See @{"Input and output functions" Link "Input and output functions"}. @{b}stdrast@{ub} The raster port used by E built-in graphics functions such as @{b}Box@{ub} and @{b}Plot@{ub}. This can be changed so that these functions draw on different screens etc. See @{"Graphics functions" Link "Graphics functions"}. @{b}dosbase@{ub}, @{b}execbase@{ub}, @{b}gfxbase@{ub}, @{b}intuitionbase@{ub} These are pointers to the appropriate library base, and are initialised by the E startup code, i.e., the Dos, Exec, Graphics and Intuition libraries are all opened by E so you don't need to do it yourself. These libraries are also automatically closed by E, so you shouldn't close them yourself. However, you must explicitly open and close all other Amiga system libraries that you want to use. The other library base variables are defined in the accompanying module (see @{"Modules" Link "Modules"}). Consult the `Reference Manual' for details about the library base variable @{b}mathbase@{ub}. @EndNode @Node "Built-In Functions" "beginner.guide/Built-In Functions" @Prev "Built-In Variables" @Toc "E Built-In Constants Variables and Functions" Built-In Functions ================== There are many built-in functions in E. We've already seen a lot of string and list functions, and we've used @{b}WriteF@{ub} for printing. The remaining functions are, generally, simplifications of complex Amiga system functions, or E versions of support functions found in languages like C and Pascal. To understand the graphics and Intuition support functions completely you really need to get something like the `Rom Kernel Reference Manual (Libraries)'. However, if you don't want to do anything too complicated you can just about get by. @{" Input and output functions " Link "Input and output functions"} @{" Intuition support functions " Link "Intuition support functions"} @{" Graphics functions " Link "Graphics functions"} @{" Maths and logic functions " Link "Maths and logic functions"} @{" System support functions " Link "System support functions"} @EndNode @Node "Input and output functions" "beginner.guide/Input and output functions" @Next "Intuition support functions" @Toc "Built-In Functions" Input and output functions -------------------------- @{b}WriteF(@{ub}@{fg shine}string@{fg text}@{b},@{ub}@{fg shine}param1@{fg text}@{b},@{ub}@{fg shine}param2@{fg text}@{b},...)@{ub} Writes a string to the standard output and returns the number of characters written. If place-holders are used in the string then the appropriate number of parameters must be supplied after the string in the order they are to be printed as part of the string. So far we've only met the @{b}\d@{ub} place-holder for decimal numbers. The complete list is: @{i}Place-Holder@{ui} @{i}Parameter Type@{ui} @{i}Prints@{ui} ------------------------------------------------- \c Number Character \d Number Decimal number \h Number Hexadecimal number \s String String So to print a string you use the @{b}\s@{ub} place-holder in the string and supply the string (e.g., a @{b}PTR TO CHAR@{ub}) as a parameter. Try the following program (remember @{b}\a@{ub} prints an apostrophe character): PROC main() DEF s[30]:STRING StrCopy(s, 'Hello world', ALL) WriteF('The third element of s is "\c"\n', s[2]) WriteF('or \d (decimal)\n', s[2]) WriteF('or \h (hexadecimal)\n', s[2]) WriteF('and s itself is \a\s\a\n', s) ENDPROC This is the output it generates: The third element of s is "l" or 108 (decimal) or 6C (hexadecimal) and s itself is 'Hello world' You can control how the parameter is formatted in the @{b}\d@{ub}, @{b}\h@{ub} and @{b}\s@{ub} fields using another collection of special character sequences before the place-holder and size specifiers after it. If no size is specified the field will be as big as the data requires. A fixed field size can be specified using @{b} [@{ub}@{fg shine}number@{fg text}@{b}]@{ub} after the place-holder. For strings you can also use the size specifier @{b} (@{ub}@{fg shine}min@{fg text}@{b},@{ub}@{fg shine}max@{fg text}@{b})@{ub} which specifies the minimum and maximum sizes of the field. By default the data is right justified in the field and the left part of the field is filled, if necessary, with spaces. The following sequences before the place-holder can change this: @{i}Sequence@{ui} @{i}Meaning@{ui} ----------------------------------- \l Left justify in field \r Right justify in field \z Set fill character to "0" See how these formatting controls affect this example: PROC main() DEF s[30]:STRING StrCopy(s, 'Hello world', ALL) WriteF('The third element of s is "\c"\n', s[2]) WriteF('or \d[4] (decimal)\n', s[2]) WriteF('or \z\h[4] (hexadecimal)\n', s[2]) WriteF('\a\s[5]\a are the first five elements of s \n', s) WriteF('and s in a very big field \a\s[20]\a\n', s) WriteF('and s left justified in it \a\l\s[20]\a\n', s) ENDPROC Here's the output it should generate: The third element of s is "l" or 108 (decimal) or 006C (hexadecimal) 'Hello' are the first five elements of s and s in a very big field ' Hello world' and s left justified in it 'Hello world ' @{b}WriteF@{ub} uses the standard output, and this file handle is stored in the @{b}stdout@{ub} variable. If your program is started from Workbench this variable will contain @{b}NIL@{ub}. In this case, the first call to @{b}WriteF@{ub} will open a special output window and put the file handle in the variables @{b}stdout@{ub} and @{b}conout@{ub}, as outlined above. @{b}PrintF(@{ub}@{fg shine}string@{fg text}@{b},@{ub}@{fg shine}param1@{fg text}@{b},@{ub}@{fg shine}param2@{fg text}@{b},...)@{ub} @{b}PrintF@{ub} works just like @{b}WriteF@{ub} except it uses the more efficient, buffered output routines only available if your Amiga is using Kickstart version 37 or greater (i.e., AmigaDOS 2.04 and above). @{b}StringF(@{ub}@{fg shine}e-string@{fg text}@{b},@{ub}@{fg shine}string@{fg text}@{b},@{ub}@{fg shine}arg1@{fg text}@{b},@{ub}@{fg shine}arg2@{fg text}@{b},...)@{ub} The same as @{b}WriteF@{ub} except that the result is written to @{fg shine}e-string@{fg text} instead of being printed. For example, the following code fragment sets @{b}s@{ub} to @{b}00123 is a@{ub} (since the E-string is not long enough for the whole string): DEF s[10]:STRING StringF(s, '\z\d[5] is a number', 123) @{b}Out(@{ub}@{fg shine}filehandle@{fg text}@{b},@{ub}@{fg shine}char@{fg text}@{b})@{ub} Outputs a single character, @{fg shine}char@{fg text}, to the file or console window denoted by @{fg shine}filehandle@{fg text}, and returns -1 to indicate success (so any other return value means an error occurred). For instance, @{fg shine}filehandle@{fg text} could be @{b}stdout@{ub}, in which case the character is written to the standard output. (You need to make sure @{b}stdout@{ub} is not @{b}NIL@{ub}, and you can do this by using a @{b}WriteF('')@{ub} call.) @{b}Inp(@{ub}@{fg shine}filehandle@{fg text}@{b})@{ub} Reads and returns a single character from @{fg shine}filehandle@{fg text}. If -1 is returned then the end of the file (EOF) was reached, or there was an error. @{b}ReadStr(@{ub}@{fg shine}filehandle@{fg text}@{b},@{ub}@{fg shine}e-string@{fg text}@{b})@{ub} Reads a whole string from @{fg shine}filehandle@{fg text} and returns -1 if EOF was reached or an error occurred. Characters are read up to a linefeed or the size of the string, which ever is sooner. Therefore, the resulting string may be only a partial line. If -1 is returned then EOF was reached or an error occurred, and in either case the string so far is still valid. So, you still need to check the string even if -1 is returned. (This will most commonly happen with files that do not end with a linefeed.) The string will be empty (i.e., of zero length) if nothing more had been read from the file when the error or EOF happened. This next little program reads continually from its input until an error occurs or the user types @{b}quit@{ub}. It echoes the lines that it reads in uppercase. If you type a line longer than ten characters you'll see it reads it in more than one go. Because of the way normal console windows work, you need to type a return before a line gets read by the program (but this allows you to edit the line before the program sees it). If the program is started from Workbench then @{b}stdin@{ub} would be @{b}NIL@{ub}, so @{b}WriteF('')@{ub} is used to force @{b}stdout@{ub} to be valid, and in this case it will be a new console window which can be used to accept input! (To make the compiled program into a Workbench program you simply need to create a tool icon for it. A quick way of doing this is to copy an existing tool's icon.) PROC main() DEF s[10]:STRING, fh WriteF('') fh:=IF stdin THEN stdin ELSE stdout WHILE ReadStr(fh, s)<>-1 UpperStr(s) EXIT StrCmp(s, 'QUIT', ALL) WriteF('Read: \a\s\a\n', s) ENDWHILE WriteF('Finished\n') ENDPROC There are some worked examples in Part Three (see @{"String Handling and I-O" Link "String Handling and I-O"}) which also show how to use @{b}ReadStr@{ub}. @{b}FileLength(@{ub}@{fg shine}string@{fg text}@{b})@{ub} Returns the length of the file named in @{fg shine}string@{fg text}, or -1 if the file doesn't exist or an error occurred. Notice that you don't need to @{b}Open@{ub} the file or have a filehandle, you just supply the filename. There is a worked example in Part Three (see @{"String Handling and I-O" Link "String Handling and I-O"}) which shows how to use this function. @{b}SetStdIn(@{ub}@{fg shine}filehandle@{fg text}@{b})@{ub} Returns the value of @{b}stdin@{ub} before setting it to @{fg shine}filehandle@{fg text}. Therefore, the following code fragments are equivalent: oldstdin:=SetStdIn(newstdin) oldstdin:=stdin stdin:=newstdin @{b}SetStdOut(@{ub}@{fg shine}filehandle@{fg text}@{b})@{ub} Returns the value of @{b}stdout@{ub} before setting it to @{fg shine}filehandle@{fg text}, and is otherwise just like @{b}SetStdIn@{ub}. @EndNode @Node "Intuition support functions" "beginner.guide/Intuition support functions" @Next "Graphics functions" @Prev "Input and output functions" @Toc "Built-In Functions" Intuition support functions --------------------------- The functions in this section are simplified versions of Amiga system functions (in the Intuition library, as the title suggests). To make best use of them you are probably going to need something like the `Rom Kernel Reference Manual (Libraries)', especially if you want to understand the Amiga specific things like IDCMP and raster ports. The descriptions given here vary slightly in style from the previous descriptions. All function parameters can be expressions which represent numbers or addresses, as appropriate. Because many of the functions take several parameters they have been named (fairly descriptively) so they can be more easily referenced. @{b}OpenW(@{ub}@{fg shine}x@{fg text}@{b},@{ub}@{fg shine}y@{fg text}@{b},@{ub}@{fg shine}wid@{fg text}@{b},@{ub}@{fg shine}hgt@{fg text}@{b},@{ub}@{fg shine}idcmp@{fg text}@{b},@{ub}@{fg shine}wflgs@{fg text}@{b},@{ub}@{fg shine}title@{fg text}@{b},@{ub}@{fg shine}scrn@{fg text}@{b},@{ub}@{fg shine}sflgs@{fg text}@{b},@{ub}@{fg shine}gads@{fg text}@{b},@{ub}@{fg shine}tags@{fg text}@{b}=NIL)@{ub} Opens and returns a pointer to a window with the supplied properties. If for some reason the window could not be opened @{b}NIL@{ub} is returned. @{fg shine}x@{fg text}, @{fg shine}y@{fg text} The position on the screen where the window will appear. @{fg shine}wid@{fg text}, @{fg shine}hgt@{fg text} The width and height of the window. @{fg shine}idcmp@{fg text}, @{fg shine}wflgs@{fg text} The IDCMP and window specific flags. @{fg shine}title@{fg text} The window title (a string) which appears on the title bar of the window. @{fg shine}scrn@{fg text}, @{fg shine}sflgs@{fg text} The screen on which the window should open. If @{fg shine}sflgs@{fg text} is 1 the window will be opened on Workbench, and @{fg shine}scrn@{fg text} is ignored (so it can be @{b}NIL@{ub}). If @{fg shine}sflgs@{fg text} is @{b}$F@{ub} (i.e., 15) the window will open on the custom screen pointed to by @{fg shine}scrn@{fg text} (which must then be valid). See @{b}OpenS@{ub} to see how to open a custom screen and get a screen pointer. @{fg shine}gads@{fg text} A pointer to a gadget list, or @{b}NIL@{ub} if you don't want any gadgets. These are not the standard window gadgets, since they are specified using the window flags. A gadget list can be created using the @{b}Gadget@{ub} function. @{fg shine}tags@{fg text} A tag-list of other options available under Kickstart version 37 or greater. This can normally be omitted since it defaults to @{b}NIL@{ub}. See the `Rom Kernel Reference Manual (Libraries)' for details about the available tags and their meanings. There's not enough space to describe all the fine details about windows and IDCMP (see the `Rom Kernel Reference Manual (Libraries)' for complete details), but a brief description in terms of flags might be useful. Here's a small table of common IDCMP flags: @{i}IDCMP Flag@{ui} @{i}Value@{ui} -------------------------- IDCMP_NEWSIZE $2 IDCMP_REFRESHWINDOW $4 IDCMP_MOUSEBUTTONS $8 IDCMP_MOUSEMOVE $10 IDCMP_GADGETDOWN $20 IDCMP_GADGETUP $40 IDCMP_MENUPICK $100 IDCMP_CLOSEWINDOW $200 IDCMP_RAWKEY $400 IDCMP_DISKINSERTED $8000 IDCMP_DISKREMOVED $10000 Here's a table of useful window flags: @{i}Window Flag@{ui} @{i}Value@{ui} -------------------------- WFLG_SIZEGADGET $1 WFLG_DRAGBAR $2 WFLG_DEPTHGADGET $4 WFLG_CLOSEGADGET $8 WFLG_SIZEBRIGHT $10 WFLG_SIZEBBOTTOM $20 WFLG_SMART_REFRESH 0 WFLG_SIMPLE_REFRESH $40 WFLG_SUPER_BITMAP $80 WFLG_BACKDROP $100 WFLG_REPORTMOUSE $200 WFLG_GIMMEZEROZERO $400 WFLG_BORDERLESS $800 WFLG_ACTIVATE $1000 All these flags are defined in the module @{b}intuition/intuition@{ub}, so if you use that module you can use the constants rather than having to write the less descriptive value (see @{"Modules" Link "Modules"}). Of course, you can always define your own constants for the values that you use. You use the flags by @{b}OR@{ub}-ing the ones you want together, in similar way to using sets (see @{"Sets" Link "Sets"}). However, you should supply only IDCMP flags as part of the @{fg shine}idcmp@{fg text} parameter, and you should supply only window flags as part of the @{fg shine}wflgs@{fg text} parameter. So, to get IDCMP messages when a disk is inserted and when the close gadget is clicked you specify both of the flags @{b}IDCMP_DISKINSERTED@{ub} and @{b}IDCMP_CLOSEWINDOW@{ub} for the @{fg shine}idcmp@{fg text} parameter, either by @{b}OR@{ub}-ing the constants or (less readably) by using the calculated value @{b}$8200@{ub}. Some of the window flags require some of IDCMP flags to be used as well, if an effect is to be complete. For example, if you want your window to have a close gadget (a standard window gadget) you need to use @{b}WFLG_CLOSEGADGET@{ub} as one of the window flags. If you want that gadget to be useful then you need to get an IDCMP message when the gadget is clicked. You therefore need to use @{b}IDCMP_CLOSEWINDOW@{ub} as one of the IDCMP flags. So the full effect requires both a window and an IDCMP flag (a gadget is pretty useless if you can't tell when it's been clicked). The worked example in Part Three illustrates how to use these flags in this way (see @{"Gadgets" Link "Gadgets"}). If you only want to output text to a window (and maybe do some input from a window), it may be better to use a @{fg shine}console@{fg text} window. These provide a text based input and output window, and are opened using the Dos library function @{b}Open@{ub} with the appropriate @{b}CON:@{ub} file name. See the `AmigaDOS Manual' for more details about console windows. @{b}CloseW(@{ub}@{fg shine}winptr@{fg text}@{b})@{ub} Closes the window which is pointed to by @{fg shine}winptr@{fg text}. It's safe to give @{b}NIL@{ub} for @{fg shine}winptr@{fg text}, but in this case, of course, no window will be closed! The window pointer is usually a pointer returned by a matching call to @{b}OpenW@{ub}. You @{i}must@{ui} remember to close any windows you may have opened before terminating your program. @{b}OpenS(@{ub}@{fg shine}wid@{fg text}@{b},@{ub}@{fg shine}hgt@{fg text}@{b},@{ub}@{fg shine}depth@{fg text}@{b},@{ub}@{fg shine}scrnres@{fg text}@{b},@{ub}@{fg shine}title@{fg text}@{b},@{ub}@{fg shine}tags@{fg text}@{b}=NIL)@{ub} Opens and returns a pointer to a custom screen with the supplied properties. If for some reason the screen could not be opened @{b}NIL@{ub} is returned. @{fg shine}wid@{fg text}, @{fg shine}hgt@{fg text} The width and height of the screen. @{fg shine}depth@{fg text} The depth of the screen, i.e., the number of bit-planes. This can be a number in the range 1-8 for AGA machines, or 1-6 for pre-AGA machines. A screen with depth 3 will be able to show 2 to the power 3 (i.e., 8) different colours, since it will have 2 to the power 3 different pens (or colour registers) available. You can set the colours of pens using the @{b}SetColour@{ub} function. @{fg shine}scrnres@{fg text} The screen resolution flags. @{fg shine}title@{fg text} The screen title (a string) which appears on the title bar of the screen. @{fg shine}tags@{fg text} A tag-list of other options available under Kickstart version 37 or greater. See the `Rom Kernel Reference Manual (Libraries)' for more details. The screen resolution flags control the screen mode. The following (common) values are taken from the module @{b}graphics/view@{ub} (see @{"Modules" Link "Modules"}). You can, if you want, define your own constants for the values that you use. Either way it's best to use descriptive constants rather than directly using the values. @{i}Mode Flag@{ui} @{i}Value@{ui} ------------------------ V_LACE $4 V_SUPERHIRES $20 V_PFBA $40 V_EXTRA_HALFBRITE $80 V_DUALPF $400 V_HAM $800 V_HIRES $8000 So, to get a hires, interlaced screen you specify both of the flags @{b}V_HIRES@{ub} and @{b}V_LACE@{ub}, either by @{b}OR@{ub}-ing the constants or (less readably) by using calculated value @{b}$8004@{ub}. There is a worked example using this function in Part Three (see @{"Screens" Link "Screens"}). @{b}CloseS(@{ub}@{fg shine}scrnptr@{fg text}@{b})@{ub} Closes the screen which is pointed to by @{fg shine}scrnptr@{fg text}. It's safe to give @{b}NIL@{ub} for @{fg shine}scrnptr@{fg text}, but in this case, of course, no screen will be closed! The screen pointer is usually a pointer returned by a matching call to @{b}OpenS@{ub}. You @{i}must@{ui} remember to close any screens you may have opened before terminating your program. Also, you @{i}must@{ui} close all windows that you opened on your screen before you can close the screen. @{b}Gadget(@{ub}@{fg shine}buf@{fg text}@{b},@{ub}@{fg shine}glist@{fg text}@{b},@{ub}@{fg shine}id@{fg text}@{b},@{ub}@{fg shine}flags@{fg text}@{b},@{ub}@{fg shine}x@{fg text}@{b},@{ub}@{fg shine}y@{fg text}@{b},@{ub}@{fg shine}width@{fg text}@{b},@{ub}@{fg shine}text@{fg text}@{b})@{ub} Creates a new gadget with the supplied properties and returns a pointer to the next position in the (memory) buffer which can be used for a gadget. @{fg shine}buf@{fg text} This is the memory buffer, i.e., a chunk of allocated memory. The best way of allocating this memory is to declare an array of size @{b}@{ub}@{fg shine}n@{fg text}@{b}*GADGETSIZE@{ub}, where @{fg shine}n@{fg text} is the number of gadgets which are going to be created. The first call to @{b}Gadget@{ub} will use the array as the buffer, and subsequent calls use the result of the previous call as the buffer (since this function returns the next free position in the buffer). @{fg shine}glist@{fg text} This is a pointer to the gadget list that is being created, i.e., the array used as the buffer. When you create the first gadget in the list using an array @{b}a@{ub}, this parameter should be @{b}NIL@{ub}. For all other gadgets in the list this parameter should be the array @{b}a@{ub}. @{fg shine}id@{fg text} A number which identifies the gadget. It is best to give a unique number for each gadget, that way you can easily identify them. This number is the only way you can identify which gadget has been clicked. @{fg shine}flags@{fg text} The type of gadget to be created. Zero represents a normal gadget, one a boolean gadget (a toggle) and three a boolean that starts selected. @{fg shine}x@{fg text}, @{fg shine}y@{fg text} The position of the gadget, relative to the top, left-hand corner of the window. @{fg shine}width@{fg text} The width of the gadget (in pixels, not characters). @{fg shine}text@{fg text} The text (a string) which will centred in the gadget, so the @{fg shine}width@{fg text} must be big enough to hold this text. Once a gadget list has been created by possibly several calls to this function the list can be passed as the @{fg shine}gads@{fg text} parameter to @{b}OpenW@{ub}. There is a worked example using this function in Part Three (see @{"Gadgets" Link "Gadgets"}). @{b}Mouse()@{ub} Returns the state of the mouse buttons (including the middle mouse button if you have a three-button mouse). This is a set of flags, and the individual flag values are: @{i}Button Pressed@{ui} @{i}Value@{ui} ---------------------- Left %001 Right %010 Middle %100 So, if this function returns @{b}%001@{ub} you know the left button is being pressed, and if it returns @{b}%110@{ub} you know the middle and right buttons are both being pressed. This mouse function is not strictly the proper way to do things. It is suggested you use this function only for small tests or demo-like programs. The proper way of getting mouse details is to use the appropriate IDCMP flags for your window, wait for events and decode the information. @{b}MouseX(@{ub}@{fg shine}winptr@{fg text}@{b})@{ub} Returns the @{fg shine}x@{fg text} coordinate of the mouse pointer, relative to the window pointed to by @{fg shine}winptr@{fg text}. This mouse function is not strictly the proper way to do things. It is suggested you use this function only for small tests or demo-like programs. The proper way of getting mouse details is to use the appropriate IDCMP flags for your window, wait for events and decode the information. @{b}MouseY(@{ub}@{fg shine}winptr@{fg text}@{b})@{ub} Returns the @{fg shine}y@{fg text} coordinate of the mouse pointer, relative to the window pointed to by @{fg shine}winptr@{fg text}. This mouse function is not strictly the proper way to do things. It is suggested you use this function only for small tests or demo-like programs. The proper way of getting mouse details is to use the appropriate IDCMP flags for your window, wait for events and decode the information. @{b}LeftMouse(@{ub}@{fg shine}winptr@{fg text}@{b})@{ub} Returns @{b}TRUE@{ub} if left mouse button has been clicked in the window pointed to by @{fg shine}winptr@{fg text}, and @{b}FALSE@{ub} otherwise. In order for this to work sensibly the window must have the IDCMP flag @{b}IDCMP_MOUSEBUTTONS@{ub} set (see above). This function does things in a proper, Intuition-friendly manner and so is a good alternative to the @{b}Mouse@{ub} function. @{b}WaitIMessage(@{ub}@{fg shine}winptr@{fg text}@{b})@{ub} This function waits for a message from Intuition for the window pointed to by @{fg shine}winptr@{fg text} and returns the class of the message (which is an IDCMP flag). If you did not specify any IDCMP flags when the window was opened, or the specified messages could never happen (e.g., you asked only for gadget messages and you have no gadgets), then this function may wait forever. When you've got a message you can use the @{b}MsgXXX@{ub} functions to get some more information about the message. See the `Rom Kernel Reference Manual (Libraries)' for more details on Intuition and IDCMP. There is a worked example using this function in Part Three (see @{"IDCMP Messages" Link "IDCMP Messages"}). This function is basically equivalent to the following function, except that the @{b}MsgXXX@{ub} functions can also access the message data held in the variables @{b}code@{ub}, @{b}qual@{ub} and @{b}iaddr@{ub}. PROC waitimessage(win:PTR TO window) DEF port,msg:PTR TO intuimessage,class,code,qual,iaddr port:=win.userport IF (msg:=GetMsg(port))=NIL REPEAT WaitPort(port) UNTIL (msg:=GetMsg(port))<>NIL ENDIF class:=msg.class code:=msg.code qual:=msg.qualifier iaddr:=msg.iaddress ReplyMsg(msg) ENDPROC class @{b}MsgCode()@{ub} Returns the @{b}code@{ub} part of the message returned by @{b}WaitIMessage@{ub}. @{b}MsgIaddr()@{ub} Returns the @{b}iaddr@{ub} part of the message returned by @{b}WaitIMessage@{ub}. There is a worked example using this function in Part Three (see @{"IDCMP Messages" Link "IDCMP Messages"}). @{b}MsgQualifier()@{ub} Returns the @{b}qual@{ub} part of the message returned by @{b}WaitIMessage@{ub}. @{b}WaitLeftMouse(@{ub}@{fg shine}winptr@{fg text}@{b})@{ub} This function waits for the left mouse button to be clicked in the window pointed to by @{fg shine}winptr@{fg text}. It is advisable to have the IDCMP flag @{b}IDCMP_MOUSEBUTTONS@{ub} set for the window (see above). This function does things in a proper, Intuition-friendly manner and so is a good alternative to the @{b}Mouse@{ub} function. @EndNode @Node "Graphics functions" "beginner.guide/Graphics functions" @Next "Maths and logic functions" @Prev "Intuition support functions" @Toc "Built-In Functions" Graphics functions ------------------ The functions in this section use the standard raster port, the address of which is held in the variable @{b}stdrast@{ub}. Most of the time you don't need to worry about this because the E functions which open windows and screens set up this variable (see @{"Intuition support functions" Link "Intuition support functions"}). So, by default, these functions affect the last window or screen opened. When you close a window or screen, @{b}stdrast@{ub} becomes @{b}NIL@{ub} and calls to these functions have no effect. There is a worked example using these functions in Part Three (see @{"Graphics" Link "Graphics"}). The descriptions in this section follow the same style as the previous section. @{b}Plot(@{ub}@{fg shine}x@{fg text}@{b},@{ub}@{fg shine}y@{fg text}@{b},@{ub}@{fg shine}pen@{fg text}@{b}=1)@{ub} Plots a single point (@{fg shine}x@{fg text},@{fg shine}y@{fg text}) in the specified pen colour. The position is relative to the top, left-hand corner of the window or screen that is the current raster port (normally the last screen or window to be opened). The range of pen values available depend on the screen setup, but are at best 0-255 on AGA machines and 0-31 on pre-AGA machines. As a guide, the background colour is usually pen zero, and the main foreground colour is pen one (and this is the default pen). You can set the colours of pens using the @{b}SetColour@{ub} function. @{b}Line(@{ub}@{fg shine}x1@{fg text}@{b},@{ub}@{fg shine}y1@{fg text}@{b},@{ub}@{fg shine}x2@{fg text}@{b},@{ub}@{fg shine}y2@{fg text}@{b},@{ub}@{fg shine}pen@{fg text}@{b}=1)@{ub} Draws the line (@{fg shine}x1@{fg text},@{fg shine}y1@{fg text}) to (@{fg shine}x2@{fg text},@{fg shine}y2@{fg text}) in the specified pen colour. @{b}Box(@{ub}@{fg shine}x1@{fg text}@{b},@{ub}@{fg shine}y1@{fg text}@{b},@{ub}@{fg shine}x2@{fg text}@{b},@{ub}@{fg shine}y2@{fg text}@{b},@{ub}@{fg shine}pen@{fg text}@{b}=1)@{ub} Draws the (filled) box with vertices (@{fg shine}x1@{fg text},@{fg shine}y1@{fg text}), (@{fg shine}x2@{fg text},@{fg shine}y1@{fg text}), (@{fg shine}x1@{fg text},@{fg shine}y2@{fg text}) and (@{fg shine}x2@{fg text},@{fg shine}y2@{fg text}) in the specified pen colour. @{b}Colour(@{ub}@{fg shine}fore-pen@{fg text}@{b},@{ub}@{fg shine}back-pen@{fg text}@{b}=0)@{ub} Sets the foreground and background pen colours. As mentioned above, the background colour is normally pen zero and the main foreground is pen one. You can change these defaults with this function, and if you stick to having the background pen as pen zero then calling this function with one argument changes just the foreground pen. @{b}TextF(@{ub}@{fg shine}x@{fg text}@{b},@{ub}@{fg shine}y@{fg text}@{b},@{ub}@{fg shine}format-string@{fg text}@{b},@{ub}@{fg shine}arg1@{fg text}@{b},@{ub}@{fg shine}arg2@{fg text}@{b},...)@{ub} This works just like @{b}WriteF@{ub} except the resulting string is written starting at point (@{fg shine}x@{fg text},@{fg shine}y@{fg text}). Also, don't use any line-feed, carriage return, tab or escape characters in the string--they don't behave like they do in @{b}WriteF@{ub}. @{b}SetColour(@{ub}@{fg shine}scrnptr@{fg text}@{b},@{ub}@{fg shine}pen@{fg text}@{b},@{ub}@{fg shine}r@{fg text}@{b},@{ub}@{fg shine}g@{fg text}@{b},@{ub}@{fg shine}b@{fg text}@{b})@{ub} Sets the colour of colour register @{fg shine}pen@{fg text} for the screen pointed to by @{fg shine}scrnptr@{fg text} to be the appropriate RGB value (i.e., red value @{fg shine}r@{fg text}, green value @{fg shine}g@{fg text} and blue value @{fg shine}b@{fg text}). The @{b}pen@{ub} can be anything up to 255, depending on the screen depth. Regardless of the chipset being used, @{fg shine}r@{fg text}, @{fg shine}g@{fg text} and @{fg shine}b@{fg text} are taken from the range zero to 255, so 24-bit colours are always specified. In operation, though, the values are scaled to 12-bit colour for non-AGA machines. @{b}SetStdRast(@{ub}@{fg shine}newrast@{fg text}@{b})@{ub} Returns the value of @{b}stdrast@{ub} before setting it to the new value. The following code fragments are equivalent: oldstdrast:=SetStdRast(newstdrast) oldstdrast:=stdrast stdrast:=newstdrast @{b}SetTopaz(@{ub}@{fg shine}size@{fg text}@{b}=8)@{ub} Sets the text font for the current raster port to Topaz at the specified size, which defaults to the standard size eight. @EndNode @Node "Maths and logic functions" "beginner.guide/Maths and logic functions" @Next "System support functions" @Prev "Graphics functions" @Toc "Built-In Functions" Maths and logic functions ------------------------- We've already seen the standard arithmetic operators. The addition, @{b}+@{ub}, and subtraction, @{b}-@{ub}, operators use full 32-bit integers, but, for efficiency, multiplication, @{b}*@{ub}, and division, @{b}/@{ub}, use restricted values. You can only use @{b}*@{ub} to multiply 16-bit integers, and the result will be a 32-bit integer. Similarly, you can only use @{b}/@{ub} to divide a 32-bit integer by a 16-bit integer, and the result will be a 16-bit integer. The restrictions do not affect most calculations, but if you really need to use all 32-bit integers (and you can cope with overflows etc.) you can use the @{b}Mul@{ub} and @{b}Div@{ub} functions. @{b}Mul(a,b)@{ub} corresponds to @{b}a*b@{ub}, and @{b}Div(a,b)@{ub} corresponds to @{b}a/b@{ub}. We've also met the logic operators @{b}AND@{ub} and @{b}OR@{ub}, which we know are really bit-wise operators. You can also use the functions @{b}And@{ub} and @{b}Or@{ub} to do exactly the same as @{b}AND@{ub} and @{b}OR@{ub} (respectively). So, for instance, @{b}And(a,b)@{ub} is the same as @{b}a AND b@{ub}. The reason for these functions is because there are @{b}Not@{ub} and @{b}Eor@{ub} (bit-wise) functions, too (and there aren't operators for these). @{b}Not(a)@{ub} swaps one and zero bits, so, for instance, @{b}Not(TRUE)@{ub} is @{b}FALSE@{ub} and @{b}Not(FALSE)@{ub} is @{b}TRUE@{ub}. @{b}Eor(a,b)@{ub} is the exclusive version of @{b}Or@{ub} and does almost the same, except that @{b}Eor(1,1)@{ub} is 0 whereas @{b}Or(1,1)@{ub} is 1 (and this extends to all the bits). So, basically, @{b}Eor@{ub} tells you which bits are different, or, logically, if the truth values are different. Therefore, @{b}Eor(TRUE,TRUE)@{ub} is @{b}FALSE@{ub} and @{b}Eor(TRUE,FALSE)@{ub} is @{b}TRUE@{ub}. There's a collection of other functions related to maths, logic or numbers in general: @{b}Abs(@{ub}@{fg shine}expression@{fg text}@{b})@{ub} Returns the absolute value of @{fg shine}expression@{fg text}. The absolute value of a number is that number made positive if necessary. So, @{b}Abs(9)@{ub} is 9, and @{b}Abs(-9)@{ub} is also 9. @{b}Sign(@{ub}@{fg shine}expression@{fg text}@{b})@{ub} Returns the sign of @{fg shine}expression@{fg text}, which is the value one if it is (strictly) positive, -1 if it is (strictly) negative and zero if it is zero. @{b}Even(@{ub}@{fg shine}expression@{fg text}@{b})@{ub} Returns @{b}TRUE@{ub} if @{fg shine}expression@{fg text} represents an even number, and @{b}FALSE@{ub} otherwise. Obviously, a number is either odd or even! @{b}Odd(@{ub}@{fg shine}expression@{fg text}@{b})@{ub} Returns @{b}TRUE@{ub} if @{fg shine}expression@{fg text} represents an odd number, and @{b}FALSE@{ub} otherwise. @{b}Max(@{ub}@{fg shine}exp1@{fg text}@{b}, @{ub}@{fg shine}exp2@{fg text}@{b})@{ub} Returns the maximum of @{fg shine}exp1@{fg text} and @{fg shine}exp2@{fg text}. @{b}Min(@{ub}@{fg shine}exp1@{fg text}@{b}, @{ub}@{fg shine}exp2@{fg text}@{b})@{ub} Returns the minimum of @{fg shine}exp1@{fg text} and @{fg shine}exp2@{fg text}. @{b}Bounds(@{ub}@{fg shine}exp@{fg text}@{b}, @{ub}@{fg shine}minexp@{fg text}@{b}, @{ub}@{fg shine}maxexp@{fg text}@{b})@{ub} Returns the value of @{fg shine}exp@{fg text} bounded to the limits @{fg shine}minexp@{fg text} (minimum bound) and @{fg shine}maxexp@{fg text} (maximum bound). That is, if @{fg shine}exp@{fg text} lies between the bounds then @{fg shine}exp@{fg text} is returned, but if it is less than @{fg shine}minexp@{fg text} then @{fg shine}minexp@{fg text} is returned or if it is greater than @{fg shine}maxexp@{fg text} then @{fg shine}maxexp@{fg text} is returned. This is useful for, say, constraining a calculated value to be a valid (integer) percentage (i.e., a value between zero and one hundred). The following code fragments are equivalent: y:=Bounds(x, min, max) y:=IF xmax THEN max ELSE x @{b}Mod(@{ub}@{fg shine}exp1@{fg text}@{b},@{ub}@{fg shine}exp2@{fg text}@{b})@{ub} Returns the 16-bit remainder (or modulus) of the division of the 32-bit @{fg shine}exp1@{fg text} by the 16-bit @{fg shine}exp2@{fg text} as the regular return value (see @{"Multiple Return Values" Link "Multiple Return Values"}), and the 16-bit result of the division as the first optional return value. For example, the first assignment in the following code sets @{b}a@{ub} to 5 (since 26=(7*3)+5), @{b}b@{ub} to 3, @{b}c@{ub} to -5 and @{b}d@{ub} to -3. It is important to notice that if @{fg shine}exp1@{fg text} is negative then the modulus will also be negative. This is because of the way integer division works: it simply discards fractional parts rather rounding. a,b:=Mod(26,7) c,d:=Mod(-26,7) @{b}Rnd(@{ub}@{fg shine}expression@{fg text}@{b})@{ub} Returns a random number in the range 0 to (n-1), where @{fg shine}expression@{fg text} represents the value n. These numbers are pseudo-random, so although you appear to get a random value from each call, the sequence of numbers you get will probably be the same each time you run your program. Before you use @{b}Rnd@{ub} for the first time in your program you should call it with a negative number. This decides the starting point for the pseudo-random numbers. @{b}RndQ(@{ub}@{fg shine}expression@{fg text}@{b})@{ub} Returns a random 32-bit value, based on the seed @{fg shine}expression@{fg text}. This function is quicker than @{b}Rnd@{ub}, but returns values in the 32-bit range, not a specified range. The seed value is used to select different sequences of pseudo-random numbers, and the first call to @{b}RndQ@{ub} should use a large value for the seed. @{b}Shl(@{ub}@{fg shine}exp1@{fg text}@{b},@{ub}@{fg shine}exp2@{fg text}@{b})@{ub} Returns the value represented by @{fg shine}exp1@{fg text} shifted @{fg shine}exp2@{fg text} bits to the left. For example, @{b}Shl(%0001110,2)@{ub} is @{b}%0111000@{ub} and @{b}Shl(%0001011,3)@{ub} is @{b}%1011000@{ub}. Shifting a number one bit to the left is generally the same as multiplying it by two (although this isn't true when you shift large positive or large negative values). (The new bits shifted in at the right are always zeroes.) @{b}Shr(@{ub}@{fg shine}exp1@{fg text}@{b},@{ub}@{fg shine}exp2@{fg text}@{b})@{ub} Returns the value represented by @{fg shine}exp1@{fg text} shifted @{fg shine}exp2@{fg text} bits to the right. For example, @{b}Shr(%0001110,2)@{ub} is @{b}%0000011@{ub} and @{b}Shr(%1011010,3)@{ub} is @{b}%0001011@{ub}. Shifting a number one bit to the right is generally the same as dividing it by two. (The new bits shifted in at the left are always zeroes.) @{b}Long(@{ub}@{fg shine}addr@{fg text}@{b}), Int(@{ub}@{fg shine}addr@{fg text}@{b}), Char(@{ub}@{fg shine}addr@{fg text}@{b})@{ub} Returns the @{b}LONG@{ub}, @{b}INT@{ub} or @{b}CHAR@{ub} value at the address @{fg shine}addr@{fg text}. These functions should be used only when setting up a pointer and dereferencing it in the normal way would make your program cluttered and less readable. Use of functions like these is often called @{fg shine}peeking@{fg text} memory (especially in dialects of the BASIC language). @{b}PutLong(@{ub}@{fg shine}addr@{fg text}@{b},@{ub}@{fg shine}exp@{fg text}@{b}), PutInt(@{ub}@{fg shine}addr@{fg text}@{b},@{ub}@{fg shine}exp@{fg text}@{b}), PutChar(@{ub}@{fg shine}addr@{fg text}@{b},@{ub}@{fg shine}exp@{fg text}@{b})@{ub} Writes the @{b}LONG@{ub}, @{b}INT@{ub} or @{b}CHAR@{ub} value represented by @{fg shine}exp@{fg text} to the address @{fg shine}addr@{fg text}. Again, these functions should be used only when really necessary. Use of functions like these is often called @{fg shine}poking@{fg text} memory. @EndNode @Node "System support functions" "beginner.guide/System support functions" @Prev "Maths and logic functions" @Toc "Built-In Functions" System support functions ------------------------ @{b}New(@{ub}@{fg shine}bytes@{fg text}@{b})@{ub} Returns a pointer to a newly allocated chunk of memory, which is @{fg shine}bytes@{fg text} number of bytes. If the memory could not be allocated @{b}NIL@{ub} is returned. The memory is initialised to zero in each byte, and taken from any available store (Fast or Chip memory, in that order of preference). When you've finished with this memory you can use @{b}Dispose@{ub} to free it for use elsewhere in your program. You don't have to @{b}Dispose@{ub} with memory you allocated with @{b}New@{ub} because your program will automatically free it when it terminates. This is @{i}not@{ui} true for memory allocated using the normal Amiga system routines. @{b}NewR(@{ub}@{fg shine}bytes@{fg text}@{b})@{ub} The same as @{b}New@{ub} except that if the memory could not be allocated then the exception @{b}"MEM"@{ub} is raised (and so, in this case, the function does not return). See @{"Exception Handling" Link "Exception Handling"}. @{b}NewM(@{ub}@{fg shine}bytes@{fg text}@{b},@{ub}@{fg shine}type@{fg text}@{b})@{ub} The same as @{b}NewR@{ub} except that the @{fg shine}type@{fg text} of memory (Fast or Chip) to be allocated can be specified using flags. The flags are defined in the module @{b}exec/memory@{ub} (see @{"Amiga System Modules" Link "Amiga System Modules"}). See the `Rom Kernel Reference Manual (Libraries)' for details about the system function @{b}AllocMem@{ub} which uses these flags in the same way. As useful example, here's a small program which allocates some cleared (i.e., zeroed) Chip memory. MODULE 'exec/memory' PROC main() DEF m m:=NewM(20, MEMF_CHIP OR MEMF_CLEAR) WriteF('Allocation succeeded, m = $\h\n', m) EXCEPT IF exception="NEW" THEN WriteF('Failed\n') ENDPROC @{b}Dispose(@{ub}@{fg shine}address@{fg text}@{b})@{ub} Used to free memory allocated with @{b}New@{ub}, @{b}NewR@{ub} or @{b}NewM@{ub}. You should rarely need to use this function because the memory is automatically freed when the program terminates. @{b}DisposeLink(@{ub}@{fg shine}complex@{fg text}@{b})@{ub} Used to free the memory allocated @{b}String@{ub} (see @{"String functions" Link "String functions"}) and @{b}List@{ub} (see @{"List functions" Link "List functions"}). Again, you should rarely need to use this function because the memory is automatically freed when the program terminates. @{b}FastNew(@{ub}@{fg shine}bytes@{fg text}@{b})@{ub} The same as @{b}NewR@{ub} except it uses a very fast, recycling method of allocating memory. The memory allocated using @{b}FastNew@{ub} is, as ever, deallocated automatically at the end of a program, and can be deallocated before then using @{b}FastDispose@{ub}. Note that only @{b}FastDispose@{ub} can be used and that it differs slightly from the @{b}Dispose@{ub} and @{b}DisposeLink@{ub} functions (you have to specify the number of bytes originally allocated when deallocating). @{b}FastDispose(@{ub}@{fg shine}address@{fg text}@{b},@{ub}@{fg shine}bytes@{fg text}@{b})@{ub} Used to free the memory allocated using @{b}FastNew@{ub}. The @{fg shine}bytes@{fg text} parameter must be the same as the @{fg shine}bytes@{fg text} used when allocating with @{b}FastNew@{ub}, but the benefit is much faster allocation and deallocation and generally more efficient use of memory. @{b}CleanUp(@{ub}@{fg shine}expression@{fg text}@{b}=0)@{ub} Terminates the program at this point, and does the normal things an E program does when it finishes. The value denoted by @{fg shine}expression@{fg text} is returned as the error code for the program. It is the replacement for the AmigaDOS @{b}Exit@{ub} routine which should @{i}never@{ui} be used in an E program. This is the only safe way of terminating a program, other than reaching the (logical) end of the @{b}main@{ub} procedure (which is by far the most common way!). @{b}CtrlC()@{ub} Returns @{b}TRUE@{ub} if control-C has been pressed since the last call, and @{b}FALSE@{ub} otherwise. This is only sensible for programs started from the Shell/CLI. @{b}FreeStack()@{ub} Returns the current amount of free stack space for the program. Only complicated programs need worry about things like stack. Recursion is the main thing that eats a lot of stack space. @{b}KickVersion(@{ub}@{fg shine}expression@{fg text}@{b})@{ub} Returns @{b}TRUE@{ub} if your Kickstart revision is at least that given by @{fg shine}expression@{fg text}, and @{b}FALSE@{ub} otherwise. For instance, @{b}KickVersion(37)@{ub} checks whether you're running with Kickstart version 37 or greater (i.e., AmigaDOS 2.04 and above). @EndNode @Node "Modules" "beginner.guide/Modules" @Next "Exception Handling" @Prev "E Built-In Constants Variables and Functions" @Toc "Main" Modules ******* A @{fg shine}module@{fg text} is the E equivalent of a C header file and an Assembly include file. It can contain various object and constant definitions, and also library function offsets and library base variables. This information is necessary for the correct use of a library. @{" Using Modules " Link "Using Modules"} @{" Amiga System Modules " Link "Amiga System Modules"} @{" Non-Standard Modules " Link "Non-Standard Modules"} @{" Example Module Use " Link "Example Module Use"} @{" Code Modules " Link "Code Modules"} @EndNode @Node "Using Modules" "beginner.guide/Using Modules" @Next "Amiga System Modules" @Toc "Modules" Using Modules ============= To use the definitions in a particular module you use the @{b}MODULE@{ub} statement at the beginning of your program (before the first procedure definition). You follow the @{b}MODULE@{ub} keyword by a comma-separated list of strings, each of which is the filename (or path if necessary) of a module without the @{b}.m@{ub} extension (every module file ends with @{b}.m@{ub}). The filenames (and paths) are all relative to the logical volume @{b}Emodules:@{ub}, which is set-up using an @{b}assign@{ub} as described in the `Reference Manual', unless the first character of the string is @{b}*@{ub}. In this case the files are relative to the directory of the current source file. For instance, the statement: MODULE 'fred', 'dir/barney', '*mymod' will try to load the files @{b}Emodules:fred.m@{ub}, @{b}Emodules:dir/barney.m@{ub} and @{b}mymod.m@{ub}. If it can't find these files or they aren't proper modules the E compiler will complain. All the definitions in the modules included in this way are available to every procedure in the program. To see what a module contains you can use the @{b}showmodule@{ub} program that comes with the Amiga E distribution. @EndNode @Node "Amiga System Modules" "beginner.guide/Amiga System Modules" @Next "Non-Standard Modules" @Prev "Using Modules" @Toc "Modules" Amiga System Modules ==================== Amiga E comes with the standard Amiga system include files as E modules. The AmigaDOS 2.04 modules are supplied with E version 2.1, and the AmigaDOS 3.0 modules are supplied with E version 3.0. However, modules are much more useful in E version 3.0 (see @{"Code Modules" Link "Code Modules"}). If you want to use any of the standard Amiga libraries properly you will need to investigate the modules for that library. The top-level @{b}.m@{ub} files in @{b}Emodules:@{ub} contain the library function offsets, and those in directories in @{b}Emodules:@{ub} contain constant and object definitions for the appropriate library. For instance, the module @{b}asl@{ub} (i.e., the file @{b}Emodules:asl.m@{ub}) contains the ASL library function offsets and @{b}libraries/asl@{ub} contains the ASL library constants and objects. If you are going to use, say, the ASL library then you need to open the library using the @{b}OpenLibrary@{ub} function (an Amiga system function) before you can use any of the library functions. You also need to define the library function offsets by using the @{b}MODULE@{ub} statement. However, the DOS, Exec, Graphics and Intuition libraries don't need to be opened and their function offsets are built in to E. That's why you won't find, for example, a @{b}dos.m@{ub} file in @{b}Emodules:@{ub}. The constants and objects for these libraries still need to be included via modules (they are not built in to E). @EndNode @Node "Non-Standard Modules" "beginner.guide/Non-Standard Modules" @Next "Example Module Use" @Prev "Amiga System Modules" @Toc "Modules" Non-Standard Modules ==================== Several non-standard library modules are also supplied with Amiga E. To make your own modules you need the @{b}pragma2module@{ub} and @{b}iconvert@{ub} programs. These convert standard format C header files and Assembly include files to modules. The C header file should contain pragmas for function offsets, and the Assembly include file should contain constant and structure definitions (the Assembly structures will be converted to objects). However, unless you're trying to do really advanced things you probably don't need to worry about any of this! @EndNode @Node "Example Module Use" "beginner.guide/Example Module Use" @Next "Code Modules" @Prev "Non-Standard Modules" @Toc "Modules" Example Module Use ================== The gadget example program in Part Three shows how to use constants from the module @{b}intuition/intuition@{ub} (see @{"Gadgets" Link "Gadgets"}), and the IDCMP example program shows the object @{b}gadget@{ub} from that module being used (see @{"IDCMP Messages" Link "IDCMP Messages"}). The following program uses the modules for the Reqtools library, which is not a standard Amiga system library but a commonly used one, and the appropriate modules are supplied with Amiga E. To run this program, you will, of course, need the @{b}reqtools.library@{ub} in @{b}Libs:@{ub}. MODULE 'reqtools' PROC main() DEF col IF (reqtoolsbase:=OpenLibrary('reqtools.library',37))<>NIL IF (col:=RtPaletteRequestA('Select a colour', 0,0))<>-1 RtEZRequestA('You picked colour \d', 'I did|I can\at remember',0,[col],0) ENDIF CloseLibrary(reqtoolsbase) ELSE WriteF('Could not open reqtools.library, version 37+\n') ENDIF ENDPROC The @{b}reqtoolsbase@{ub} variable is the library base variable for the Reqtools library. This is defined in the module @{b}reqtools@{ub} and you @{i}must@{ui} store the result of the @{b}OpenLibrary@{ub} call in this variable if you are going to use any of the functions from the Reqtools library. (You can find out which variable to use for other libraries by running the @{b}showmodule@{ub} program on the library module for the library.) The two functions the program uses are @{b}RtPaletteRequestA@{ub} and @{b}RtEZRequestA@{ub}. Without the inclusion of the @{b}reqtools@{ub} module and the setting up of the @{b}reqtoolsbase@{ub} variable you would not be able to use these functions. In fact, if you didn't have the @{b}MODULE@{ub} line you wouldn't even be able to compile the program because the compiler wouldn't know where the functions came from and would complain bitterly. Notice that the Reqtools library is closed before the program terminates (if it had been successfully opened). This is always necessary: if you succeed in opening a library you @{i}must@{ui} close it when you're finished with it. @EndNode @Node "Code Modules" "beginner.guide/Code Modules" @Prev "Example Module Use" @Toc "Modules" Code Modules ============ You can also make modules containing procedure definitions and some global variables. These are called @{fg shine}code modules@{fg text} and can be extremely useful. This section briefly outlines their construction and use. For in-depth details see the `Reference Manual'. Code modules can be made by using the E compiler as you would to make an executable, except you put the statement @{b}OPT MODULE@{ub} at the start of the code. Also, all definitions that are to be accessed from outside the module need to be marked with the @{b}EXPORT@{ub} keyword. Alternatively, all definitions can be exported using @{b}OPT EXPORT@{ub} at the start of the code. You include the definitions from this module (and use the exported ones) in your program using @{b}MODULE@{ub} in the normal way. The following code is an example of a small module: OPT MODULE EXPORT CONST MAX_LEN=20 EXPORT OBJECT fullname firstname, surname ENDOBJECT EXPORT PROC printname(p:PTR TO fullname) IF short(p.surname) WriteF('Hello, \s \s\n', p.firstname, p.surname) ELSE WriteF('Gosh, you have a long name\n') ENDIF ENDPROC PROC short(s) RETURN StrLen(s)