|
Part I - Core Language 1. Introduction
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: 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. When installed, the euphoria directory will look something like this:
The Linux subdirectory is not included in the DOS/Windows distribution, and the dos32 and win32 subdirectories are not included in the Linux/FreeBSD distribution. In this manual, directory names are shown using backslash (\). Linux/FreeBSD 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/FreeBSD 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/FreeBSD, 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 when it starts with #!.
Be careful though that your first line ends with the Linux/FreeBSD-style \n,
and not the DOS/Windows-style \r\n, or the Linux/FreeBSD shell might get confused.
If your file is shrouded, you must give the path to backendu, not exu.
You can also run bind.bat (DOS32), or bindw.bat (WIN32) or bindu (Linux/FreeBSD) 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. Using the Euphoria to C Translator, you can also make a stand-alone .exe file, and it will normally run much faster than a bound program. exu or ex.exe and exw.exe will be 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. 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 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. If you run a Euphoria program under Linux/FreeBSD 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/FreeBSD 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 text-mode editor that runs on DOS, Linux, FreeBSD and the Windows console. See also David Cuny's excellent ee.ex editor for DOS and Linux/FreeBSD. You can download ee.ex 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 4 distinct ways of distributing a program. In the first method you simply ship your users 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 Binder 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 .il file. Binding combines your shrouded program with backend.exe, backendw.exe or backendu 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. For more information about shrouding and binding, see bind.doc. Finally, with the Euphoria To C Translator, you can translate your Euphoria program into C and then compile it with a C compiler to get an executable (.exe) file. This product is free and open source, and has benefited from the contributions of many people. You have complete royalty-free rights to distribute any Euphoria programs that you develop. You are also free to distribute ex.exe, exw.exe and exu files so anyone can run your program. You can also distribute the interpreter backend: backend.exe, backendw.exe and backendu. You can can shroud or bind your program 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 euphoria\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. Icon files, such as euphoria.ico in euphoria\bin, may be distributed with or without your changes. The high-speed version of the Euphoria Interpreter back-end is written in ANSI C, and can be compiled with many different C compilers. The complete source code is in euphoria\source, along with execute.e, the alternate, Euphoria-coded back-end. The generous open source License allows both personal and commercial use, and unlike many other open source licenses, your changes do not have to be made open source. Some additional 3rd-party legal restrictions might apply when you use the Euphoria To C Translator.
|