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. 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:
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.txtor 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 %3The 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: myproginstead of: ex myprogUnfortunately 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.exuYou can just type: foo.exuto 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. 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. 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. 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.
|