Part I - Core Language

1. Introduction

 
Euphoria is a new programming language with the following advantages over conventional languages:

  • a remarkably simple, flexible, powerful language definition that is easy to learn and use.

  • dynamic storage allocation. Variables grow or shrink without the programmer having to worry about allocating and freeing chunks of memory. Objects of any size can be assigned to an element of a Euphoria sequence (array).

  • a high-performance, state-of-the-art interpreter that's at least 10 to 30 times faster than conventional interpreters such as Microsoft QBasic, Perl and Python.

  • lightning-fast pre-compilation. Your program is checked for syntax and converted into an efficient internal form at over 35,000 lines per second on a Pentium-150.

  • extensive run-time checking for: out-of-bounds subscripts, uninitialized variables, bad parameter values for library routines, illegal value assigned to a variable and many more. There are no mysterious machine exceptions -- you will always get a full English description of any problem that occurs with your program at run-time, along with a call-stack trace-back and a dump of all of your variable values. Programs can be debugged quickly, easily and more thoroughly.

  • features of the underlying hardware are completely hidden. Programs are not aware of word-lengths, underlying bit-level representation of values, byte-order etc.

  • a full-screen source debugger and an execution profiler are included, along with a full-screen, multi-file editor. On a color monitor, the editor displays Euphoria programs in multiple colors, to highlight comments, reserved words, built-in functions, strings, and level of nesting of brackets. It optionally performs auto-completion of statements, saving you typing effort and reducing syntax errors. This editor is written in Euphoria, and the source code is provided to you without restrictions. You are free to modify it, add features, and redistribute it as you wish.

  • Euphoria programs run under Linux, 32-bit Windows, and any DOS environment, and are not subject to any 64K or 640K memory limitations. You can create programs that use the full multi-megabyte memory of your computer, and a swap file is automatically used when a program needs more memory than exists on your machine.

  • You can make a single, stand-alone .exe file from your program.

  • Euphoria routines are naturally generic. The example program below shows a single routine that will sort any type of data -- integers, floating-point numbers, strings etc. Euphoria is not an "object-oriented" language, yet it achieves many of the benefits of these languages in a much simpler way.



1.1 Example Program

The following is an example of a complete Euphoria program.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 sequence list, sorted_list

 function merge_sort(sequence x)
 -- put x into ascending order using a recursive merge sort
     integer n, mid
     sequence merged, a, b

     n = length(x)
     if n = 0 or n = 1 then
         return x  -- trivial case
     end if

     mid = floor(n/2)
     a = merge_sort(x[1..mid])       -- sort first half of x
     b = merge_sort(x[mid+1..n])     -- sort second half of x

     -- merge the two sorted halves into one
     merged = {}
     while length(a) > 0 and length(b) > 0 do
         if compare(a[1], b[1]) < 0 then
             merged = append(merged, a[1])
             a = a[2..length(a)]
         else
             merged = append(merged, b[1])
             b = b[2..length(b)]
         end if
     end while
     return merged & a & b  -- merged data plus leftovers
 end function

 procedure print_sorted_list()
 -- generate sorted_list from list
     list = {9, 10, 3, 1, 4, 5, 8, 7, 6, 2}
     sorted_list = merge_sort(list)
     ? sorted_list
 end procedure

 print_sorted_list()     -- this command starts the program


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The above example contains 4 separate commands that are processed in order. The first declares two variables: list and sorted_list to be sequences (flexible arrays). The second defines a function merge_sort(). The third defines a procedure print_sorted_list(). The final command calls procedure print_sorted_list().

The output from the program will be:
    {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}.

merge_sort() will just as easily sort {1.5, -9, 1e6, 100} or {"oranges", "apples", "bananas"} .

This example is stored as euphoria\tutorial\example.ex. This is not the fastest way to sort in Euphoria. Go to the euphoria\demo directory and type "ex allsorts" to see timings on several different sorting algorithms for increasing numbers of objects. For a quick tutorial example of Euphoria programming see euphoria\demo\bench\filesort.ex.



1.2 Installation

To install Euphoria on your machine, first read the file install.doc. Installation simply involves copying the euphoria files to your hard disk under a directory named "euphoria", and then modifying your autoexec.bat file so that euphoria\bin is on your search path, and the environment variable EUDIR is set to the euphoria directory. On DOS/Windows an automatic install program, install.bat is provided for this purpose. For the latest details, please read the instructions in install.doc before you run install.bat.

When installed, the euphoria directory will look something like this:

\euphoria
readme.doc
readme.htm
\bin
ex.exe and exw.exe, or exu (Linux), ed.bat, guru.bat, other utilities
\include
standard include files, e.g. graphics.e
\doc
refman.doc, library.doc, and several other plain-text documentation files
\html
HTML files corresponding to each of the .doc files in the doc directory
\tutorial
small tutorial programs to help you learn Euphoria
\demo
generic demo programs that run on all platforms
\dos32
DOS32-specific demo programs (optional)
\win32
WIN32-specific demo programs (optional)
\linux
Linux-specific demo programs (optional)
\langwar
language war game (pixel-graphics version for DOS, or text version for Linux)
\bench
benchmark programs
\register
information on ordering the Complete Edition

The linux subdirectory is not included in the DOS/Windows distribution, and the dos32 and win32 subdirectories are not included in the Linux distribution. In this manual, directory names are shown using backslash (\). Linux users should substitute forward slash (/).



1.3 Running a Program

Euphoria programs are executed by typing ex, exw or exu followed by the name of the main Euphoria file. You can type additional words (known as arguments) on this line, known as the command-line. Your program can call the built-in function command_line() to read the command-line. The DOS32 version of the Euphoria interpreter is called ex.exe. The WIN32 version is called exw.exe. The Linux version is called exu. By convention, main Euphoria files have an extension of .ex, .exw or .exu. Other Euphoria files, that are meant to be included in a larger program, end in .e or sometimes .ew or .eu. To save typing, you can leave off the ".ex", and the ex command will supply it for you automatically. exw.exe will supply ".exw", and exu will supply ".exu". If the file can't be found in the current directory, your PATH will be searched. You can redirect standard input and standard output when you run a Euphoria program, for example:

        ex filesort.ex < raw.txt > sorted.txt
or simply,
        ex filesort < raw.txt > sorted.txt

Unlike many other compilers and interpreters, there are no special command-line options for ex, exw or exu. Only the name of your Euphoria file is expected, and if you don't supply it, you will be prompted for it.

For frequently-used programs under DOS/Windows you might want to make a small .bat (batch) file, perhaps called myprog.bat, containing two statements like:

        @echo off
        ex myprog.ex %1 %2 %3
The first statement turns off echoing of commands to the screen. The second runs ex myprog.ex with up to 3 command-line arguments. See command_line() for an example of how to read these arguments. If your program takes more arguments, you should add %4 %5 etc. Having a .bat file will save you the minor inconvenience of typing ex (or exw) all the time, i.e. you can just type:
        myprog
instead of:
        ex myprog
Unfortunately DOS will not allow redirection of standard input and output when you use a .bat file

Under Linux, you can type the path to the Euphoria interpreter on the first line of your main file, e.g. if your program is called foo.exu:

        #!/home/rob/euphoria/bin/exu
        
        procedure foo()
            ? 2+2
        end procedure

        foo()
Then if you make your file executable:
        chmod +x foo.exu
You can just type:
        foo.exu 
to run your program. You could even shorten the name to simply "foo". Euphoria ignores the first line of your program if it starts with #!.

You can also run bind.bat (DOS32 or Linux) or bindw.bat (WIN32) to combine your Euphoria program with ex.exe, exw.exe or exu, to make a stand-alone executable file (.exe file on DOS/Windows). With a stand-alone .exe file you can redirect standard input and output. Binding is discussed further in 1.5 Distributing a Program.

Either exu or ex.exe and exw.exe are in the euphoria\bin directory which must be on your search path. The environment variable EUDIR should be set to the main Euphoria directory, e.g. c:\euphoria.


1.3.1 Running under Windows

You can run Euphoria programs directly from the Windows environment, or from a DOS shell that you have opened from Windows. By "associating" .ex files with ex.exe, and .exw files with exw.exe you can simply double-click on a .ex or .exw file to run it. Under Windows 95/98/NT you would define a new file type for .ex, by clicking on My Computer / view / options / file types. It is possible to have several Euphoria programs active in different windows. If you turn your program into a .exe file, you can simply double-click on it to run it.


1.3.2 Use of a Swap File

If you run a Euphoria program under Linux or Windows (or in a DOS shell under Windows), and the program runs out of physical memory, it will start using "virtual memory". The operating system provides this virtual memory automatically by swapping out the least-recently-used code and data to a system swap file. To change the size of the Windows swap file, click on Control Panel / 386 Enhanced / "virtual memory...". Under OS/2 you can adjust the "DPMI_MEMORY_LIMIT" by clicking the Virtual DOS machine icon / "DOS Settings" to allocate more extended memory for your program.

Under pure DOS, outside of Windows, there is no system swap file so the DOS-extender built in to ex.exe (DOS32) will create one for possible use by your program. See platform.doc.



1.4 Editing a Program

You can use any text editor to edit a Euphoria program. However, Euphoria comes with its own special editor that is written entirely in Euphoria. Type: ed followed by the complete name of the file you wish to edit (the .ex/.exw/.exu extension is not assumed). You can use this editor to edit any kind of text file. When you edit a Euphoria file, some extra features such as color syntax highlighting and auto-completion of certain statements, are available to make your job easier.

Whenever you run a Euphoria program and get an error message, during compilation or execution, you can simply type ed with no file name and you will be automatically positioned in the file containing the error, at the correct line and column, and with the error message displayed at the top of the screen.

Under Windows you can associate ed.bat with various kinds of text files that you want to edit. Color syntax highlighting is provided for .ex, .exw, .exu, .e, .ew, .eu, and .pro (profile) files.

Most keys that you type are inserted into the file at the cursor position. Hit the Esc key once to get a menu bar of special commands. The arrow keys, and the Insert/Delete/Home/End/PageUp/PageDown keys are also active. Under Linux some keys may not be available, and alternate keys are provided. See the file euphoria\doc\ed.doc (euphoria\html\ed.htm) for a complete description of the editing commands. Esc h (help) will let you view ed.doc from your editing session.

If you need to understand or modify any detail of the editor's operation, you can edit the file ed.ex in euphoria\bin (be sure to make a backup copy so you don't lose your ability to edit). If the name ed conflicts with some other command on your system, simply rename the file euphoria\bin\ed.bat to something else. Because this editor is written in Euphoria, it is remarkably concise and easy to understand. The same functionality implemented in a language like C, would take far more lines of code.

ed is a simple DOS editor. See also David Cuny's excellent ee.ex editor for DOS32 and Linux. You can download it from the Euphoria Web site. There are also some Windows editors oriented to Euphoria. These are also on the Web site.



1.5 Distributing a Program

Euphoria provides you with 3 distinct ways of distributing a program.

In the first method you simply ship your users the Public Domain ex.exe or exw.exe or exu file, along with your main Euphoria .ex, .exw, or .exu file and any .e include files that are needed (including any of the standard ones from euphoria\include). If the Euphoria source files are placed together in one directory and ex.exe, exw.exe or exu is placed in the same directory or somewhere on the search path, then your user can run your program by typing ex (exw) or (exu) followed by the path of your main .ex, .exw, or .exu file. You might also provide a small .bat file so people won't actually have to type ex (exw). This method assumes that you are willing to share your Euphoria source code with your users.

The Complete Edition gives you two more methods of distribution. You can shroud your program, or you can bind your program. Shrouding combines all of the .e files that your program needs, along with your main file to create a single .ex, .exw, or .exu file. Comments are stripped out and variable and routine names are converted into short meaningless names. You can also apply a "scrambling" algorithm to further improve security and make your program tamper-proof. Binding combines your shrouded/scrambled program with ex.exe, exw.exe, or exu to create a single, stand-alone executable (.exe) file. For example, if your program is called "myprog.ex" you can create "myprog.exe" which will run identically.

If you have just one program to distribute, and you want to conceal the source, you should make it into a .exe file. If you have several small programs, you might want to shroud each of them and ship just one copy of the Public Domain ex.exe, exw.exe or exu to run them. This will save disk space and give you a smaller .zip file for distribution.

For more information about shrouding and binding, see bind.doc.


1.5.1 Licensing

You have complete royalty-free rights to distribute any Euphoria programs that you develop. You are free to distribute the Public Domain Edition ex.exe, exw.exe and exu files so anyone can run your program. With the Complete Edition, you can shroud or bind your programs and distribute the resulting files royalty-free.

You may incorporate any Euphoria source files from this package into your program, either "as is" or with your modifications. (You will probably need at least a few of the standard include files in any large program).

We would appreciate it if you told people that your program was developed using Euphoria, and gave them the address: http://www.RapidEuphoria.com of our Web page, but we do not require any such acknowledgment.

The only files that you may not distribute are the ex.exe, exw.exe, bind.ex, bind.bat, bindw.bat, and shroud.bat files that come with the Complete Edition for DOS32 + WIN32, and exu, bind.ex, bind and shroud that come with the Complete Edition for Linux.

 

... continue 2. Language Definition