Part II - Library Routines 1. Introduction A large number of library routines are provided. Some are built right into the interpreter, ex.exe. Others are written in Euphoria and you must include one of the .e files in euphoria\include to use them. Where this is the case, the appropriate include file is noted in the "Syntax" part of the description. Of course an include file need only be included once in your program. The editor displays in magenta those routines that are built into the interpreter, ex.exe, and require no include file. You can override the definition of these built-in routines by defining your own routine with the same name. You will get a suppressible warning if you do this. To indicate what kind of object may be passed in and returned, the following prefixes are used: x - a general object (atom or sequence) s - a sequence a - an atom i - an integer fn - an integer used as a file number st - a string sequence, or single-character atom An error will result if an illegal argument value is passed to any of these routines. 2. Routines by Application Area 2.1 Predefined Types As well as declaring variables with these types, you can also call them just like ordinary functions, in order to test if a value is a certain type. integer - test if an object is an integer atom - test if an object is an atom sequence - test if an object is a sequence 2.2 Sequence Manipulation length - return the length of a sequence repeat - repeat an object n times to form a sequence of length n append - add a new element to the end of a sequence prepend - add a new element to the beginning of a sequence 2.3 Searching and Sorting compare - compare two objects find - find an object in a sequence match - find a sequence as a slice of another sequence sort - sort the elements of a sequence into ascending order 2.4 Pattern Matching lower - convert an atom or sequence to lower case upper - convert an atom or sequence to upper case wildcard_match - match a pattern containing ? and * wildcards wildcard_file - match a file name against a wild card specification 2.5 Math These routines can be applied to individual atoms or to sequences of values. See "Operations on Sequences" in chapter 2 of REFMAN.DOC. sqrt - calculate the square root of an object rand - generate random numbers sin - calculate the sine of an angle cos - calculate the cosine of an angle tan - calculate the tangent of an angle arctan - calculate the arc tangent of a number log - calculate the natural logarithm floor - round down to the nearest integer remainder - calculate the remainder when a number is divided by another power - calculate a number raised to a power 2.6 Bitwise Logical Operations These routines treat numbers as collections of binary bits, and logical operations are performed on corresponding bits in the binary representation of the numbers. There are no routines for shifting bits left or right, but you can achieve the same effect by multiplying or dividing by powers of 2. and_bits - perform logical AND on corresponding bits or_bits - perform logical OR on corresponding bits xor_bits - perform logical XOR on corresponding bits not_bits - perform logical NOT on all bits 2.7 File and Device I/O To do input or output on a file or device you must first open the file or device, then use the routines below to read or write to it, then close the file or device. open() will give you a file number to use as the first argument of the other I/O routines. Certain files/devices are opened for you automatically (as text files): 0 - standard input 1 - standard output 2 - standard error Unless you redirect them on the command line, standard input comes from the keyboard, standard output and standard error go to the screen. When you write something to the screen it is written immediately without buffering. If you write to a file, your characters are put into a buffer until there are enough of them to write out efficiently. When you close the file or device, any remaining characters are written out. Input from files is also buffered. When your program terminates, any files that are still open will be closed for you automatically. Note: If a program (written in Euphoria or any other language) has a file open for writing, and you are forced to reboot your computer for any reason, you should immediately run CHKDSK or SCANDISK to repair any damage to the file system that may have occurred. open - open a file or device close - close a file or device print - print a Euphoria object with {,,} to show the structure ? x - shorthand for print(1, x) printf - formatted print to a file or device sprintf - formatted print returned as a string sequence puts - output a string sequence to a file or device getc - read the next character from a file or device gets - read the next line from a file or device get_key - check for key pressed by the user, don't wait wait_key - wait for user to press a key get - read the representation of any Euphoria object from a file value - read the representation of any Euphoria object from a string seek - move to any character position within an open file where - report the current character position in an open file current_dir - return the name of the current directory dir - return complete info on all files in a directory allow_break - allow control-C/control-Break to terminate your program or not check_break - check if user has pressed control-C or control-Break 2.8 Mouse Support get_mouse - return mouse "events" (clicks, movements) mouse_events - select mouse events to watch for mouse_pointer - display or hide the mouse pointer 2.9 Operating System time - number of seconds since a fixed point in the past tick_rate - set the number of clock ticks per second date - current year, month, day, hour, minute, second etc. command_line - DOS command-line used to run this program getenv - get value of an environment variable system - execute a DOS command line abort - terminate execution 2.10 Special Machine-dependent routines machine_func - specialized operations in ex.exe with return value machine_proc - specialized operations in ex.exe - no return value 2.11 Debugging trace - dynamically turns tracing on or off 2.12 Graphics & Sound The following routines let you display information on the screen. The PC screen can be placed into one of many graphics modes. See the top of include\graphics.e for a description of the modes. There are two basic types of graphics mode available. "Text" modes divide the screen up into lines, where each line has a certain number of characters. "Pixel-graphics" modes divide the screen up into many rows of dots, or "pixels". Each pixel can be a different color. In text modes you can display text only, with the choice of a foreground and a background color for each character. In pixel-graphics modes you can display lines, circles, dots, and also text. We've also included a routine for making sound on your PC speaker. To make more sophisticated sounds, get the Sound Blaster library developed by Jacques Deschenes. It's available on the Euphoria Web page. The following routines work in all text and pixel-graphics modes: clear_screen - clear the screen position - set cursor line and column get_position - return cursor line and column graphics_mode - select a new pixel-graphics or text mode video_config - return parameters of current mode scroll - scroll text up or down wrap - control line wrap at right edge of screen text_color - set foreground text color bk_color - set background color palette - change color for one color number all_palette - change color for all color numbers get_all_palette - get the palette values for all colors read_bitmap - read a bitmap (.BMP) file and return a palette and a 2-d sequence of pixels get_active_page - return the page currently being written to set_active_page - change the page currently being written to get_display_page - return the page currently being displayed set_display_page - change the page currently being displayed sound - make a sound on the PC speaker The following routines work in text modes only: cursor - select cursor shape text_rows - set number of lines on text screen save_text_image - save a rectangular region from a text screen display_text_image - display an image on the text screen The following routines work in pixel-graphics modes only. pixel - set color of a pixel or set of pixels get_pixel - read color of a pixel or set of pixels draw_line - connect a series of graphics points with a line polygon - draw an n-sided figure ellipse - draw an ellipse or circle save_screen - save the screen to a bitmap (.BMP) file save_image - save a rectangular region from a pixel-graphics screen save_bitmap - create a bitmap (.BMP) file, given a palette and a 2-d sequence of pixels display_image - display an image on the pixel-graphics screen 2.13 Machine Level Interface We've grouped here a number of routines that you can use to access your machine at a low-level. With this low-level machine interface you can read and write to memory. You can also set up your own 386+ machine language routines and call them. Some of the routines listed below are unsafe, in the sense that Euphoria can't protect you if you use them incorrectly. You could crash your program or even your system. If you reference a bad memory address it will often be safely caught by the Causeway DOS extender, and you'll get an error message on the screen plus a dump of machine-level information in the file CW.ERR. These routines are important because they allow Euphoria programmers to access low-level features of the hardware and operating system. For those with specialized applications this could be crucial. Machine code routines can be written by hand, or taken from the disassembled output of a compiler for C or some other language. Remember that your machine code will be running in 32-bit protected mode. See demo\callmach.ex for an example. peek - read one or more bytes from memory poke - write one or more bytes to memory mem_copy - copy a block of memory mem_set - set a block of memory to a value call - call a machine language routine dos_interrupt - call a DOS software interrupt routine allocate - allocate a block of memory free - deallocate a block of memory allocate_low - allocate a block of low memory (address less than 1Mb) free_low - free a block allocated with allocate_low get_vector - return address of interrupt handler set_vector - set address of interrupt handler lock_memory - ensure that a region of memory will never be swapped out int_to_bytes - convert an integer to 4 bytes bytes_to_int - convert 4 bytes to an integer int_to_bits - convert an integer to a sequence of bits bits_to_int - convert a sequence of bits to an integer atom_to_float64 - convert an atom, to a sequence of 8 bytes in IEEE 64-bit floating-point format atom_to_float32 - convert an atom, to a sequence of 4 bytes in IEEE 32-bit floating-point format float64_to_atom - convert a sequence of 8 bytes in IEEE 64-bit floating- point format, to an atom float32_to_atom - convert a sequence of 4 bytes in IEEE 32-bit floating- point format, to an atom set_rand - set the random number generator so it will generate a repeatable series of random numbers use_vesa - force the use of the VESA graphics standard crash_message - specify a message to be printed if Euphoria detects an error in your program 3. Alphabetical Listing of all Routines ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: ? x Description: This is just a shorthand way of saying: print(1, x) i.e. printing the value of an expression to the standard output. Example: ? {1, 2} + {3, 4} would display {4, 6}. Comments: ? differs slightly from print() since it will add new-lines to make the output more readable on your screen or wherever you have directed standard output. See Also: print ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: abort(i) Description: Abort execution of the program. The argument i is an integer status value to be returned to the operating system. A value of 0 generally indicates successful completion of the program. Other values can indicate various kinds of errors. DOS batch (.bat) programs can read this value using the errorlevel feature. Comments: abort() is useful when a program is many levels deep in subroutine calls, and execution must end immediately, perhaps due to a severe error that has been detected. Normally ex.exe returns an exit status code of 0. If your program fails with a Euphoria-detected compile-time or run-time error then a code of 1 is returned. Example: if x = 0 then puts(ERR, "can't divide by 0 !!!\n") abort(1) else z = y / x end if See Also: crash_message ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e all_palette(s) Description: Specify new color intensities for the entire set of colors in the current graphics mode. s is a sequence of the form: {{r,g,b}, {r,g,b}, ..., {r,g,b}} Each element specifies a new color intensity {red, green, blue} for the corresponding color number, starting with color number 0. The values for red, green and blue must be in the range 0 to 63. Comments: This executes much faster than if you were to use palette() to set the new color intensities one by one. This procedure can be used with read_bitmap() to quickly display a picture on the screen. Example Program: demo\bitmap.ex See Also: palette, read_bitmap, video_config, graphics_mode ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e a = allocate(i) Description: Allocate i contiguous bytes of memory. Return the address of the block of memory, or return 0 if the memory can't be allocated. Example: buffer = allocate(100) for i = 0 to 99 do poke(buffer+i, 0) end for See Also: free, allocate_low, peek, poke, call ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e i2 = allocate_low(i1) Description: Allocate i1 contiguous bytes of low memory, i.e. conventional memory with an address below 1 megabyte. Return the address of the block of memory, or return 0 if the memory can't be allocated. Comment: Some DOS software interrupts require that you pass one or more addresses in registers. These addresses must be conventional memory addresses for DOS to be able to read or write to them. Example Program: demo\dosint.ex See Also: dos_interrupt, free_low, allocate, peek, poke ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include file.e allow_break(i) Description: When i is 1 (TRUE) control-c and control-break can terminate your program when it tries to read input from the keyboard. When i is 0 (FALSE) your program will not be terminated by control-c or control-break. Comments: The operating system will still display ^C on the screen, even when your program cannot be terminated. Initially your program can be terminated at any point where it tries to read from the keyboard. It could also be terminated by other input/output operations depending on options the user has set in his CONFIG.SYS file. (See the MS-DOS BREAK command) For some types of program this sudden termination could leave things in a messy state and might result in loss of data. allow_break(0) lets you avoid this situation. You can find out if the user has pressed control-c or control-break by calling check_break(). Example: allow_break(0) -- don't let the user kill me! See Also: check_break ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x3 = and_bits(x1, x2) Description: Perform the logical AND operation on corresponding bits in x1 and x2. A bit in x3 will be 1 only if the corresponding bits in x1 and x2 are both 1. Comments: The arguments to this function may be atoms or sequences. The rules for arithmetic operations on sequences apply. The arguments must be representable as 32-bit numbers, either signed or unsigned. If you intend to manipulate full 32-bit values, you should declare your variables as atom, rather than integer. Euphoria's integer type is limited to 31-bits. Results are treated as signed numbers. They will be negative when the highest-order bit is 1. To understand the binary representation of a number you should display it in hexadecimal notation. Use the %x format of printf(). Example 1: a = and_bits(#0F0F0000, #12345678) -- a is #02040000 Example 2: a = and_bits(#FF, {#123456, #876543, #2211}) -- a is {#56, #43, #11} Example 3: a = and_bits(#FFFFFFFF, #FFFFFFFF) -- a is -1 -- Note that #FFFFFFFF is a positive number, -- but the result of a bitwise logical operation is interpreted -- as a signed 32-bit number, so it's negative. See Also: or_bits, xor_bits, not_bits, int_to_bits ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: s2 = append(s1, x) Description: Create a new sequence identical to s1 but with x added on the end as the last element. The length of s2 will be length(s1) + 1. Comments: If x is an atom this is equivalent to s2 = s1 & x. If x is a sequence it is not equivalent. The extra storage is allocated automatically and very efficiently with Euphoria's dynamic storage allocation. The case where s1 and s2 are actually the same variable (as in Example 1 below) is highly optimized. Example 1: You can use append to dynamically grow a sequence, e.g. sequence x x = {} for i = 1 to 10 do x = append(x, i) end for -- x is now {1,2,3,4,5,6,7,8,9,10} Example 2: Any kind of Euphoria object can be appended to a sequence, e.g. sequence x, y, z x = {"fred", "barney"} y = append(x, "wilma") -- y is now {"fred", "barney", "wilma"} z = append(append(y, "betty"), {"bam", "bam"}) -- z is now {"fred", "barney", "wilma", "betty", {"bam", "bam"}} See Also: prepend, concatenation (&) and sequence-formation {,,} operators in refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = arctan(x1) Description: Return the arctangent of x1. Comments: The result will always be in the range -pi/2 to +pi/2 radians. This function may be applied to an atom or to all elements of a sequence. Example: s = arctan({1,2,3}) -- s is {0.785398, 1.10715, 1.24905} See Also: tan, sin, cos ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = atom(x) Description: Return 1 if x is an atom else return 0. Comments: This serves to define the atom type. You can also call it like an ordinary function to determine if an object is an atom. Example 1: atom a a = 5.99 Example 2: line = gets(0) if atom(line) then puts(SCREEN, "end of file\n") end if See Also: sequence ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e s = atom_to_float32(a1) Description: Convert a Euphoria atom to a sequence of 4 single-byte values. These 4 bytes contain the representation of an IEEE floating- point number in 32-bit format. Comments: Euphoria atoms can have values which are 64-bit IEEE floating- point numbers, so you may lose precision when you convert to 32-bits (16 significant digits versus 7). The range of exponents is much larger in 64-bit format (10 to the 308, versus 10 to the 38), so some atoms may be too large or too small to represent in 32-bit format. In this case you will get one of the special 32-bit values: inf or -inf (infinity or -infinity). Integer values will also be converted to 32-bit floating-point format. Example: fn = open("numbers.dat", "wb") puts(fn, atom_to_float32(157.82)) -- write 4 bytes to a file See Also: atom_to_float64, float32_to_atom ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e s = atom_to_float64(a1) Description: Convert a Euphoria atom to a sequence of 8 single-byte values. These 8 bytes contain the representation of an IEEE floating- point number in 64-bit format. Comments: All Euphoria atoms have values which can be represented as 64-bit IEEE floating-point numbers, so you can convert any atom to 64-bit format without losing any precision. Integer values will also be converted to 64-bit floating-point format. Example: fn = open("numbers.dat", "wb") puts(fn, atom_to_float64(157.82)) -- write 8 bytes to a file See Also: atom_to_float32, float64_to_atom ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e a = bits_to_int(s) Description: Convert a sequence of binary 1's and 0's into a positive number. The least-significant bit is s[1]. Comments: If you print s the bits will appear in "reverse" order, but it is convenient to have increasing subscripts access bits of increasing significance. Example: a = bits_to_int({1,1,1,0,1}) -- a is 23 (binary 10111) See Also: int_to_bits, and/or/not of sequences in refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e bk_color(i) Description: Set the background color. In pixel-graphics modes the whole screen is affected immediately. In text modes any new characters that you print will have the new background color. Comments: The various colors are defined as constants in graphics.e In pixel-graphics modes, color 0 which is normally BLACK, will be set to the same {r,g,b} palette value as color number i. In text modes, to restore the original background color when your program finishes, e.g. 0 - BLACK, you must call bk_color(0). If the cursor is at the bottom line of the screen, you may have to actually print something before terminating your program. Printing '\n' may be enough. Example: bk_color(BLACK) See Also: text_color ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e a = bytes_to_int(s) Description: Convert a 4-element sequence of byte values to an atom. The elements of s are in the order expected for a 32-bit integer on the 386, i.e. least significant byte first. Comments: The result could be greater than the integer type allows, so you should assign it to an atom. s would normally contain positive values that have been read using peek() from 4 consecutive memory locations. Example: atom int32 int32 = bytes_to_int({37,1,0,0}) -- int32 is 37 + 256*1 = 293 See Also: int_to_bytes, bits_to_int, peek, poke ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: call(a) Description: Call a machine language routine that starts at address a. This routine must execute a RET instruction #C3 to return control to Euphoria. The routine should save and restore any registers that it uses. Comments: You can allocate a block of memory for the routine and then poke in the bytes of machine code. You might allocate other blocks of memory for data and parameters that the machine code can operate on. The addresses of these blocks could be poked into the machine code. Example Program: see demo\callmach.ex See Also: allocate, free, peek, poke ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include file.e i = check_break() Description: Return the number of times that control-c or control-break have been pressed since the last call to check_break(), or since the beginning of the program if this is the first call. Comments: This is useful after you have called allow_break(0) which prevents control-c or control-break from terminating your program. You can use check_break() to find out if the user has pressed one of these keys. You might then perform some action such as a graceful shutdown of your program. Neither control-c nor control-break will be returned as input characters when you read the keyboard. You can only detect them by calling check_break(). Example: k = get_key() if check_break() then temp = graphics_mode(-1) puts(1, "Shutting down...") save_all_user_data() abort(1) end if See Also: allow_break, get_key ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: clear_screen() Description: Clear the screen using the current background color (may be set by bk_color()). Comments: This works in all text and pixel-graphics modes. See Also: bk_color, graphics_mode ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: close(fn) Description: Close a file or device and flush out any still-buffered characters. Comments: Any still-open files will be closed automatically when your program terminates. See Also: open ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: s = command_line() Description: Return a sequence of strings, where each string is a word from the command line that started your program. The first word will be the path to either the Euphoria executable, ex.exe or to your bound .exe file. The next word is either the name of your Euphoria .ex file, or the path to your bound .exe file. After that will come any extra words typed by the user. You can use these words in your program. Comments: Euphoria (ex.exe) does not use any command line options. You are free to use any options for your own program. If you bind your program you will find that all command line arguments remain the same, except for the first two, even though your user no longer types "ex" (see examples below). Example 1: -- The user types: ex myprog myfile.dat 12345 cmd = command_line() -- cmd will be: {"C:\EUPHORIA\BIN\EX.EXE", "myprog", "myfile.dat", "12345"} Example 2: -- Your program is bound with the name "myprog.exe" -- and is stored in the directory c:\myfiles -- The user types: myprog myfile.dat 12345 cmd = command_line() -- cmd will be: {"C:\MYFILES\MYPROG.EXE", "C:\MYFILES\MYPROG.EXE", -- spacer "myfile.dat", "12345"} -- Note that all arguments remain the same as Example 1 -- except for the first two. The second argument is always -- the same as the first and is inserted to keep the numbering -- of the subsequent arguments the same, whether your program -- is bound as a .exe or not. See Also: getenv ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = compare(x1, x2) Description: Return 0 if objects x1 and x2 are identical, 1 if x1 is greater than x2, -1 if x1 is less than x2. Atoms are considered to be less than sequences. Sequences are compared "alphabetically" starting with the first element until a difference is found. Example 1: x = compare({1,2,{3,{4}},5}, {2-1,1+1,{3,{4}},6-1}) -- identical, x is 0 Example 2: if compare("ABC", "ABCD") < 0 then -- -1 -- will be true: ABC is "less" because it is shorter end if Example 3: x = compare({12345, 99999, -1, 700, 2}, {12345, 99999, -1, 699, 3, 0}) -- x will be 1 because 700 > 699 See Also: equals (=) operator in refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = cos(x1) Description: Return the cosine of x1, where x1 is in radians. Comments: This function may be applied to an atom or to all elements of a sequence. Example: x = cos({.5, .6, .7}) -- x is {0.8775826, 0.8253356, 0.7648422} See Also: sin, tan, log, sqrt ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e crash_message(s) Description: Specify a string, s, to be printed on the screen in the event that Euphoria must stop your program due to a compile-time or run-time error. Comments: Normally Euphoria prints a diagnostic message such as "syntax error" or "divide by zero" on the screen, as well as dumping debugging information into "ex.err". Euphoria's error messages will not be meaningful for your users unless they happen to be Euphoria programmers. By calling crash_message() you can control the message that will appear on the screen. Debugging information will still be stored in ex.err. You won't lose any information by doing this. s may contain '\n', new-line characters so your message can span several lines on the screen. Euphoria will switch to the top of a clear text-mode screen before printing your message. You can call crash_message() as many times as you like from different parts of your program. The message specified by the last call will be the one displayed. Your crash message will always be displayed if a compile-time error (syntax, undeclared variable etc.) occurs. In the case of a run-time error (subscript out of bounds, uninitialized variable, divide by zero etc.) your program must be executed by the Complete Edition EX.EXE, or have been bound using the Complete Edition PDEX.EXE, or be under 300 statements. Example: crash_message("An unexpected error has occurred!\n" & "Please contact john_doe@whoops.com\n" & "Do not delete the file \"ex.err\".\n") See Also: abort Debugging section of refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include file.e s = current_dir() Description: Return the name of the current working directory. Example: sequence s s = current_dir() -- s would have "C:\EUPHORIA\DOC" if you were in that directory See Also: dir, getenv ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e cursor(i) Description: Select a style of cursor. graphics.e contains: global constant NO_CURSOR = #2000, UNDERLINE_CURSOR = #0607, THICK_UNDERLINE_CURSOR = #0507, HALF_BLOCK_CURSOR = #0407, BLOCK_CURSOR = #0007 The second and fourth hex digits (from the left) determine the top and bottom rows of pixels in the cursor. The first digit controls whether the cursor will be visible or not. For example, #0407 turns on the 4th through 7th rows. Comments: In pixel-graphics modes there is no cursor. Example: cursor(BLOCK_CURSOR) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: s = date() Description: Return a sequence with the following information: { year (since 1900), month (January = 1), day (day of month, starting at 1), hour (0 to 23), minute (0 to 59), second (0 to 59), day of the week (Sunday = 1), day of the year (January 1st = 1) } Example: now = date() -- now has: {95,3,24,23,47,38,6,83} -- i.e. Friday March 24, 1995 at 11:47:38pm, day 83 of the year See Also: time ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include file.e x = dir(st) Description: Return directory information for the file or directory named by st. If there is no file or directory with this name then -1 is returned. This information is similar to what you would get from the DOS DIR command. A sequence is returned where each element is a sequence that describes one file or subdirectory. If st names a directory you may have entries for "." and "..", just as with the DOS DIR command. If st names a file then x will have just one entry, i.e. length(x) will be 1. Each entry contains the name, attributes and file size as well as the year, month, day, hour, minute and second of the last modification. You can refer to the elements of an entry with the following constants defined in file.e: global constant D_NAME = 1, D_ATTRIBUTES = 2, D_SIZE = 3, D_YEAR = 4, D_MONTH = 5, D_DAY = 6, D_HOUR = 7, D_MINUTE = 8, D_SECOND = 9 The attributes element is a string sequence containing characters chosen from: d - directory r - read only file h - hidden file s - system file v - volume-id entry a - archive file A normal file without special attributes would just have an empty string, "", in this field. Comments: The top level directory, e.g. c:\ does not have "." or ".." entries. This function is often used just to test if a file or directory exists. Under Windows 95, st can have a long file or directory name anywhere in the path. The file name returned in D_NAME will be a standard DOS 8.3 name, even on Windows 95 or Windows NT. A new long-filename element may be added in a future release of Euphoria. Example: d = dir(current_dir()) -- d might have: { {".", "d", 0 1994, 1, 18, 9, 30, 02}, {"..", "d", 0 1994, 1, 18, 9, 20, 14}, {"fred", "ra", 2350, 1994, 1, 22, 17, 22, 40}, {"sub", "d" , 0, 1993, 9, 20, 8, 50, 12} } d[3][D_NAME] would be "fred" Example Programs: bin\search.ex, install.ex See Also: wildcard_file, current_dir, open ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e display_image(s1, s2) Description: Display at point s1 on a pixel-graphics screen the 2-d sequence of pixels contained in s2. s1 is a two-element sequence {x, y}. s2 is a sequence of sequences, where each sequence is one horizontal line of pixel colors to be displayed. The first pixel of the first sequence is displayed at s1. It is the top-left pixel. All other pixels appear to the right or below of this point. Comments: s2 might be the result of a previous call to save_image(), or read_bitmap(), or it could be something you have created. You could use save_image/display_image in a graphical user interface, to allow "pop-up" dialog boxes, and drop-down menus to appear and disappear without losing what was previously on the screen. The sequences (rows) of the image do not have to all be the same length. Example: display_image({20,30}, {{1,5,9}, {2,4}, {1,0,1,0,4}, {5,5,5}}) -- displays a small 4-line image at {20,30}, with the pixels appearing in the same relative positions as the layout above would indicate Example Program: see demo\bitmap.ex See Also: save_image, read_bitmap, display_text_image ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e display_text_image(s1, s2) Description: Display the 2-d sequence of characters and attributes contained in s2 at line s1[1], column s1[2]. s2 is a sequence of sequences, where each sequence is a string of characters and attributes to be displayed. The top-left character is displayed at s1. Other characters appear to the right or below of this position. The attributes indicate the foreground and background color of the preceding character. Comments: s2 would normally be the result of a previous call to save_text_image(), although you could construct it yourself. This routine only works in text modes. You might use save_text_image/display_text_image in a text-mode graphical user interface, to allow "pop-up" dialog boxes, and drop-down menus to appear and disappear without losing what was previously on the screen. The sequences of the text image do not have to all be the same length. Example: clear_screen() display_text_image({1,1}, {{'A', WHITE, 'B', GREEN}, {'C', RED+16*WHITE}, {'D', BLUE}}) -- displays: AB C D in the appropriate colors at the top left corner of the screen See Also: save_text_image, display_image ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e s2 = dos_interrupt(i, s1) Description: Call DOS software interrupt number i. s1 is a 10-element sequence of 16-bit register values to be used as input to the routine. s2 is a similar 10-element sequence containing output register values after the call returns. machine.e has the following declaration which shows the order of the register values in the input and output sequences. global constant REG_DI = 1, REG_SI = 2, REG_BP = 3, REG_BX = 4, REG_DX = 5, REG_CX = 6, REG_AX = 7, REG_FLAGS = 8, REG_ES = 9, REG_DS = 10 Comments: The register values returned in s2 are always positive values between 0 and #FFFF (65535). The flags value in s1[REG_FLAGS] is ignored on input. On output the least significant bit of s2[REG_FLAGS] has the carry flag, which usually indicates failure if it is set to 1. Certain interrupts require that you supply addresses of blocks of memory. These addresses must be conventional, low-memory addresses. You can allocate/deallocate low-memory using allocate_low() and free_low(). With DOS software interrupts you can perform a wide variety of specialized operations, anything from formatting your floppy drive to rebooting your computer. For documentation on these interrupts consult a technical manual such as Peter Norton's "PC Programmer's Bible", or download Ralf Brown's Interrupt List from the WEB: http://www.cs.cmu.edu/afs/cs.cmu.edu/user/ralf/pub/WWW/files.html Example Program: demo\dosint.ex See Also: allocate_low, free_low ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e draw_line(i, s) Description: Draw a line on a pixel-graphics screen connecting two or more points in s, using color i. Example: draw_line(WHITE, {{100, 100}, {200, 200}, {900, 700}}) This would connect the three points in the sequence using a white line, i.e. a line would be drawn from {100, 100} to {200, 200} and another line would be drawn from {200, 200} to {900, 700}. See Also: polygon, ellipse, pixel ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e ellipse(i1, i2, s1, s2) Description: Draw an ellipse with color i1 on a pixel-graphics screen. The ellipse will neatly fit inside the rectangle defined by diagonal points s1 {x1, y1} and s2 {x2, y2}. If the rectangle is a square then the ellipse will be a circle. Fill the ellipse when i2 is 1. Don't fill when i2 is 0. Example: ellipse(MAGENTA, 0, {10, 10}, {20, 20}) This would make a magenta colored circle just fitting inside the square: {10, 10}, {10, 20}, {20, 20}, {20, 10}. Example Program: demo\sb.ex See Also: polygon, draw_line ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = find(x, s) Description: Find x as an element of s. If successful, return the index of the first element of s that matches. If unsuccessful return 0. Example 1: location = find(11, {5, 8, 11, 2, 3}) -- location is set to 3 Example 2: names = {"fred", "rob", "george", "mary", ""} location = find("mary", names) -- location is set to 4 See Also: match, compare ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e a1 = float32_to_atom(s) Description: Convert a sequence of 4 bytes to an atom. These 4 bytes must contain an IEEE floating-point number in 32-bit format. Comments: Any 32-bit IEEE floating-point number can be converted to an atom. Example: f = repeat(0, 4) fn = open("numbers.dat", "rb") -- read binary f[1] = getc(fn) f[2] = getc(fn) f[3] = getc(fn) f[4] = getc(fn) a = float32_to_atom(f) See Also: float64_to_atom, atom_to_float32 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e a1 = float64_to_atom(s) Description: Convert a sequence of 8 bytes to an atom. These 8 bytes must contain an IEEE floating-point number in 64-bit format. Comments: Any 64-bit IEEE floating-point number can be converted to an atom. Example: f = repeat(0, 8) fn = open("numbers.dat", "rb") -- read binary for i = 1 to 8 do f[i] = getc(fn) end for a = float64_to_atom(f) See Also: float32_to_atom, atom_to_float64 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = floor(x1) Description: Return the greatest integer less than or equal to x1. (Round down to an integer.) Comments: This function may be applied to an atom or to all elements of a sequence. Example: y = floor({0.5, -1.6, 9.99, 100}) -- y is {0, -2, 9, 100} See Also: remainder ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e free(a) Description: Free up a previously allocated block of memory by specifying the address of the start of the block, i.e. the address that was returned by allocate(). Comments: Use free() to recycle blocks of memory during execution. This will reduce the chance of running out of memory or getting into excessive virtual memory swapping to disk. Do not reference a block of memory that has been freed. When your program terminates, all allocated memory will be returned to the system. Do not use free() to deallocate memory that was allocated using allocate_low(). Use free_low() for this purpose. Example Program: demo\callmach.ex See Also: allocate, free_low ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e free_low(i) Description: Free up a previously allocated block of conventional memory by specifying the address of the start of the block, i.e. the address that was returned by allocate_low(). Comments: Use free_low() to recycle blocks of conventional memory during execution. This will reduce the chance of running out of conventional memory. Do not reference a block of memory that has been freed. When your program terminates, all allocated memory will be returned to the system. Do not use free_low() to deallocate memory that was allocated using allocate(). Use free() for this purpose. Example Program: demo\dosint.ex See Also: allocate_low, dos_interrupt, free ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include get.e s = get(fn) Description: Input, from file fn, a human-readable string of characters representing a Euphoria object. Convert the string into the numeric value of that object. s will be a 2-element sequence: {error status, value}. Error status values are: GET_SUCCESS -- object was read successfully GET_EOF -- end of file before object was read GET_FAIL -- object is not syntactically correct get() can read arbitrarily complicated Euphoria objects. You could have a long sequence of values in braces and separated by commas, e.g. {23, {49, 57}, 0.5, -1, 99, 'A', "john"}. A single call to get() will read in this entire sequence and return it's value as a result. Each call to get() picks up where the previous call left off. For instance, a series of 5 calls to get() would be needed to read in: 99 5.2 {1,2,3} "Hello" -1 On the sixth and any subsequent call to get() you would see a GET_EOF status. If you had something like: {1,2,xxx} in the input stream you would see a GET_FAIL error status because xxx is not a Euphoria object. Distinct "top-level" objects in the input stream must be separated from each other with one or more "whitespace" characters (blank, tab or \n). Whitespace is not necessary *within* a top-level object. Comments: The combination of print() and get() can be used to save any Euphoria object to disk and later read it back. This technique could be used to implement a database as one or more large Euphoria sequences stored in disk files. The sequences could be read into memory, updated and then written back to disk after each series of transactions is complete. The value returned is not meaningful unless you have a GET_SUCCESS status. Example: Suppose your program asks the user to enter a number from the keyboard. If he types 77.5, get(0) would return: {GET_SUCCESS, 77.5} whereas gets(0) would return "77.5\n" Example Program: see demo\mydata.ex. See Also: print, value, gets, getc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e i = get_active_page() Description: Some graphics modes on most video cards have multiple pages of memory. This lets you write screen output to one page while displaying a different page. get_active_page() returns the current page number that screen output is being sent to. Comments: The active and display pages are both 0 by default. video_config() will tell you how many pages are available in the current graphics mode. See Also: set_active_page, get_display_page, video_config ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e s = get_all_palette() Description: Retrieve color intensities for the entire set of colors in the current graphics mode. s is a sequence of the form: {{r,g,b}, {r,g,b}, ..., {r,g,b}} Each element specifies a color intensity {red, green, blue} for the corresponding color number, starting with color number 0. The values for red, green and blue will be in the range 0 to 63. Comments: This function might be used to get the palette values needed by save_bitmap(). Remember to multiply these values by 4 before calling save_bitmap(), since save_bitmap() expects values in the range 0 to 255. See Also: palette, all_palette, read_bitmap, save_bitmap, save_screen ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e i = get_display_page() Description: Some graphics modes on most video cards have multiple pages of memory. This lets you write screen output to one page while displaying another. get_display_page() returns the current page number that is being displayed on the monitor. Comments: The active and display pages are both 0 by default. video_config() will tell you how many pages are available in the current graphics mode. See Also: set_display_page, get_active_page, video_config ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = get_key() Description: Return the key that was pressed by the user, without waiting for carriage return. Return -1 if no key was pressed. Special codes are returned for the function keys, arrow keys etc. Comments: DOS can hold a small number of key-hits in its keyboard buffer. get_key() will return the next one from the buffer, or -1 if the buffer is empty. Run the key.bat program to see what key code is generated for each key on your keyboard. See Also: wait_key, getc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include mouse.e x1 = get_mouse() Description: Return the last mouse event in the form: {event, x, y} or return -1 if there has not been a mouse event since the last time get_mouse() was called. Constants have been defined in mouse.e for the possible mouse events: global constant MOVE = 1, LEFT_DOWN = 2, LEFT_UP = 4, RIGHT_DOWN = 8, RIGHT_UP = 16, MIDDLE_DOWN = 32, MIDDLE_UP = 64 x and y are the coordinates of the mouse pointer at the time that the event occurred. get_mouse() returns immediately with either a -1 or a mouse event. It does not wait for an event to occur. You must check it frequently enough to avoid missing an event. When the next event occurs, the current event will be lost, if you haven't read it. In practice it is not hard to catch almost all events. Losing a MOVE event is generally not too serious, as the next MOVE will tell you where the mouse pointer is. Sometimes multiple events will be reported. For example, if the mouse is moving when the left button is clicked, get_mouse() will report an event value of LEFT_DOWN+MOVE, i.e. 2+1 or 3. For this reason you should test for a particular event using and_bits(). See examples below. Comments: You need a DOS mouse driver to use this routine. You can use get_mouse() in most text and pixel-graphics modes. The first call that you make to get_mouse() will turn on a mouse pointer, or a highlighted character. In text modes you will probably want to scale the x and y coordinates to get line and column positions. DOS generally does not support the use of a mouse in SVGA graphics modes (beyond 640x480 pixels). This restriction has been removed in Windows 95 (DOS 7.0). The x,y coordinate returned could be that of the very tip of the mouse pointer or might refer to the pixel pointed-to by the mouse pointer. Test this if you are trying to read the pixel color using get_pixel(). You may have to read x-1,y-1 instead. Example 1: a return value of: {2, 100, 50} would indicate that the left button was pressed down while the mouse pointer was at position x=100, y=50 on the screen. Example 2: To test for LEFT_DOWN, write something like the following: object event while 1 do event = get_mouse() if sequence(event) then if and_bits(event[1], LEFT_DOWN) then -- left button was pressed exit end if end if end while See Also: mouse_events, mouse_pointer, and_bits ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x = get_pixel(s) Description: When s is a 2-element screen coordinate {x, y}, get_pixel() returns the color of the pixel on the pixel-graphics screen at that point. When s is a 3-element sequence of the form: {x, y, n} get_pixel() returns a sequence of n color values for the points starting at {x, y} and moving to the right {x+1, y}, {x+2, y} etc. Points off the screen have unpredictable color values. Comments: When n is specified, a very fast algorithm is used to read the pixel colors on the screen. It is much faster to call get_pixel() once, specifying a large value of n, than it is to call it many times, reading one pixel color at a time. Example: object x x = get_pixel({30,40}) -- x is set to the color value of point x=30, y=40 x = get_pixel({30,40,100}) -- x is set to a sequence of 100 integer values, representing -- the colors starting at {30,40} and going to the right See Also: pixel, graphics_mode, get_position ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e s = get_position() Description: Return the current line and column position of the cursor as a 2-element sequence {line, column}. Comments: In pixel-graphics modes no cursor will be displayed, but get_position() will return the line and column where the next character will be displayed. The coordinate system for displaying text is different from the one for displaying pixels. Pixels are displayed such that the top-left is (x=0,y=0) and the first coordinate controls the horizontal, left-right location. In pixel-graphics modes you can display both text and pixels. get_position() returns the current line and column for the text that you are displaying, not the pixels that you may be plotting. There is no corresponding routine for getting the current pixel position. See Also: position, get_pixel ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e s = get_vector(i) Description: Return the current protected mode far address of the handler for interrupt number i. s will be a 2-element sequence: {16-bit segment, 32-bit offset}. Example: s = get_vector(#1C) -- s will be set to the far address of the clock tick -- interrupt handler, for example: {59, 808} Example Program: demo\hardint.ex See Also: set_vector, lock_memory ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = getc(fn) Description: Get the next character (byte) from file fn. The character will have a value from 0 to 255. -1 is returned at end of file. Comments: File input using getc is buffered, i.e. getc does not actually go out to the disk for each character. Instead, a large block of characters will be read in at one time and returned to you one by one from a memory buffer. See Also: gets, get_key, wait_key, open ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x = getenv(s) Description: Return the value of a DOS environment variable. If the variable is undefined return -1. Example: e = getenv("EUDIR") -- e will be "C:\EUPHORIA" -- or perhaps D:, E: etc. Comments: Because either a sequence or an atom (-1) might be returned, you should probably assign the result to a variable declared as object. See Also: command_line ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x = gets(fn) Description: Get the next sequence (one line, including '\n') of characters from file fn. The characters will have values from 0 to 255. The atom -1 is returned on end of file. Comments: Because either a sequence or an atom (-1) might be returned, you should probably assign the result to a variable declared as object. The last line in a file might not end with a new-line '\n' character. Example: sequence buffer object line -- read a text file into a sequence buffer = {} while 1 do line = gets(0) if atom(line) then exit -- end of file end if buffer = append(buffer, line) end while See Also: getc, puts, open ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e i1 = graphics_mode(i2) Description: Select graphics mode i2. See graphics.e for a list of valid graphics modes. If successful, i1 is set to 0, otherwise i1 is set to 1. Comment: Some modes are referred to as "text" modes because they only let you display text. Other modes are referred to as "pixel-graphics" modes because you can display pixels, lines, ellipses etc., as well as text. As a convenience to your users, it is usually a good idea to switch back from a pixel-graphics mode to the standard text mode before your program terminates. You can do this with graphics_mode(-1). If a pixel-graphics program leaves your screen in a mess, you can clear it up with the DOS CLS command, or by running ex or ed. Example: if graphics_mode(18) then puts(SCREEN, "need VGA graphics!\n") abort(1) end if draw_line(BLUE, {{0,0}, {50,50}}) See Also: text_rows, video_config ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e s = int_to_bits(a, i) Description: Returns the low-order i bits of a, as a sequence of 1's and 0's. The least significant bits come first. For negative numbers the two's complement bit pattern is returned. Comments: You can use subscripting, slicing, and/or/not of entire sequences etc. to manipulate sequences of bits. Shifting of bits and rotating of bits are easy to perform. Example: s = int_to_bits(177, 8) -- s is {1,0,0,0,1,1,0,1} -- "reverse" order See Also: bits_to_int, and_bits, or_bits, xor_bits, not_bits, and/or/not of entire sequences in refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e s = int_to_bytes(a) Description: Convert an integer into a sequence of 4 bytes. These bytes are in the order expected on the 386+, i.e. least significant byte first. Comments: You might use this routine prior to poking the 4 bytes into memory for use by a machine language program. The integer can be negative. Negative byte-values will be returned, but after poking them into memory you will have the correct (two's complement) representation for the 386+. This function will correctly convert integer values up to 32-bits. For larger values, only the low-order 32-bits are converted. Euphoria's integer type only allows values up to 31-bits, so declare your variables as atom if you need a larger range. Example 1: s = int_to_bytes(999) -- s is {231, 3, 0, 0} Example 2: s = int_to_bytes(-999) -- s is {-231, -4, -1, -1} See Also: bytes_to_int, int_to_bits, bits_to_int, peek, poke ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = integer(x) Description: Return 1 if x is an integer in the range -1073741824 to +1073741823. Otherwise return 0. Comments: This serves to define the integer type. You can also call it like an ordinary function to determine if an object is an integer. Example 1: integer z z = -1 Example 2: if integer(y/x) then puts(SCREEN, "y is an exact multiple of x") end if See Also: atom, sequence, floor ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = length(s) Description: Return the length of s. s must be a sequence. An error will occur if s is an atom. Comments: The length of each sequence is stored internally by the interpreter for quick access. (In other languages this operation requires a search through memory for an end marker.) Example 1: length({{1,2}, {3,4}, {5,6}}) -- 3 Example 2: length("") -- 0 Example 3: length({}) -- 0 See Also: sequence ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e lock_memory(a, i) Description: Prevent the block of virtual memory starting at address a, of length i, from ever being swapped out to disk. Comments: Use this to ensure that all code and data required for handling interrupts is kept in memory at all times while your program is running. Example Program: demo\hardint.ex See Also: get_vector, set_vector ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = log(x1) Description: Return the natural logarithm of x1. Comments: This function may be applied to an atom or to all elements of a sequence. Note that log is only defined for positive numbers. Your program will abort with a message if you try to take the log of a negative number or zero. Example: a = log(100) -- a is 4.60517 See Also: sin, cos, tan, sqrt ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include wildcard.e x2 = lower(x1) Description: Convert an atom or sequence to lower case. Example: s = lower("Euphoria") -- s is "euphoria" a = lower('B') -- a is 'b' s = lower({"Euphoria", "Programming"}) -- s is {"euphoria", "programming"} See Also: upper ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x1 = machine_func(a, x) Description: see machine_proc() below ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: machine_proc(a, x) Description: Perform a machine-specific operation such as graphics and sound effects. This routine should normally be called indirectly via one of the library routines in a Euphoria include file. A direct call can cause a machine exception if done incorrectly. See Also: machine_func ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = match(s1, s2) Description: Try to match s1 against some slice of s2. If successful, return the element number of s2 where the (first) matching slice begins, else return 0. Example: location = match("pho", "Euphoria") -- location is set to 3 See Also: find, compare, wildcard_match ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: mem_copy(a1, a2, i) Description: Copy a block of i bytes of memory from address a2 to address a1. Comments: The bytes of memory will be copied correctly even if the block of memory at a2 overlaps with the block of memory at a1. mem_copy(a1, a2, i) is equivalent to: poke(a1, peek({a2, i})) but is much faster. Example: dest = allocate(50) src = allocate(100) poke(src, {1,2,3,4,5,6,7,8,9}) mem_copy(dest, src, 9) See Also: mem_set, peek, poke, allocate, allocate_low ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: mem_set(a1, i1, i2) Description: Set i2 bytes of memory, starting at address a1, to the value of i1. Comments: The low order 8 bits of i1 are actually stored in each byte. mem_set(a1, i1, i2) is equivalent to: poke(a1, repeat(i1, i2)) but is much faster. Example: destination = allocate(1000) mem_set(destination, ' ', 1000) See Also: mem_copy, peek, poke, allocate, allocate_low ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include mouse.e mouse_events(i) Description: Use this procedure to select the mouse events that you want get_mouse() to report. By default, get_mouse() will report all events. mouse_events() can be called at various stages of the execution of your program, as the need to detect events changes. Comments: It is good practice to ignore events that you are not interested in, particularly the very frequent MOVE event, in order to reduce the chance that you will miss a significant event. The first call that you make to mouse_events() will turn on a mouse pointer, or a highlighted character. Example: mouse_events(LEFT_DOWN + LEFT_UP + RIGHT_DOWN) -- will restrict get_mouse() to reporting the left button being pressed down or released, and the right button being pressed down. All other events will be ignored. See Also: get_mouse, mouse_pointer ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include mouse.e mouse_pointer(i) Description: If i is 0 hide the mouse pointer, otherwise turn on the mouse pointer. Multiple calls to hide the pointer will require multiple calls to turn it back on. The first call to either get_mouse() or mouse_events() above, will also turn the pointer on (once). Comments: It may be necessary to hide the mouse pointer temporarily when you update the screen. After a call to text_rows() you may have to call mouse_pointer(1) to see the mouse pointer again. See Also: get_mouse, mouse_events ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = not_bits(x1) Description: Perform the logical NOT operation on each bit in x1. A bit in x2 will be 1 when the corresponding bit in x1 is 0, and will be 0 when the corresponding bit in x1 is 1. Comments: The argument to this function may be an atom or a sequence. The rules for arithmetic operations on sequences apply. The argument must be representable as a 32-bit number, either signed or unsigned. If you intend to manipulate full 32-bit values, you should declare your variables as atom, rather than integer. Euphoria's integer type is limited to 31-bits. Results are treated as signed numbers. They will be negative when the highest-order bit is 1. Example: a = not_bits(#000000F7) -- a is -248 (i.e. FFFFFF08 interpreted as a negative number) See Also: and_bits, or_bits, xor_bits, int_to_bits ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: fn = open(s1, s2) Description: Open a file or device, to get the file number. -1 is returned if the open fails. s1 is the path name of the file or device. s2 is the mode in which the file is to be opened. Possible modes are: "r" - open text file for reading "rb" - open binary file for reading "w" - create text file for writing "wb" - create binary file for writing "u" - open text file for update (reading and writing) "ub" - open binary file for update "a" - open text file for appending "ab" - open binary file for appending Files opened for read or update must already exist. Files opened for write or append will be created if necessary. A file opened for write will be set to 0 bytes. Output to a file opened for append will start at the end of file. Output to text files will have carriage-return characters automatically added before linefeed characters. On input, these carriage-return characters are removed. A control-z character (ASCII 26) will signal an immediate end of file. I/O to binary files is not modified in any way. Any byte values from 0 to 255 can be read or written. Some typical devices that you can open are: "CON" the console (screen) "AUX" the serial auxiliary port "COM1" serial port 1 "COM2" serial port 2 "PRN" the printer on the parallel port "NUL" a non-existent device that accepts and discards output Comment: When running under Windows 95, you can open any existing file that has a long file or directory name in its path (i.e. greater than the standard DOS 8.3 format) using any open mode - read, write etc. However, if you try to create a *new* file (open with "w" or "a" and the file does not already exist) then the name will be truncated if necessary to an 8.3 style name. We hope to support creation of new long-filename files in a future release. Example: integer file_num, file_num95 sequence first_line constant ERROR = 2 file_num = open("myfile", "r") if file_num = -1 then puts(ERROR, "couldn't open myfile\n") else first_line = gets(file_num) end if file_num = open("PRN", "w") -- open printer for output -- on Windows 95: file_num95 = open("bigdirectoryname\\verylongfilename.abcdefg", "r") if file_num95 != -1 then puts(1, "it worked!\n") end if See Also: close ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x3 = or_bits(x1, x2) Description: Perform the logical OR operation on corresponding bits in x1 and x2. A bit in x3 will be 1 when a corresponding bit in either x1 or x2 is 1. Comments: The arguments to this function may be atoms or sequences. The rules for arithmetic operations on sequences apply. The arguments must be representable as 32-bit numbers, either signed or unsigned. If you intend to manipulate full 32-bit values, you should declare your variables as atom, rather than integer. Euphoria's integer type is limited to 31-bits. Results are treated as signed numbers. They will be negative when the highest-order bit is 1. Example 1: a = or_bits(#0F0F0000, #12345678) -- a is #1F3F5678 Example 2: a = or_bits(#FF, {#123456, #876543, #2211}) -- a is {#1234FF, #8765FF, #22FF} See Also: and_bits, xor_bits, not_bits, int_to_bits ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e x = palette(i, s) Description: Change the color for color number i to s, where s is a sequence of color intensities: {red, green, blue}. Each value in s can be from 0 to 63. If successful, a 3-element sequence containing the previous color for i will be returned, and all pixels on the screen with value i will be set to the new color. If unsuccessful, the atom -1 will be returned. Example: x = palette(0, {15, 40, 10}) -- color number 0 (normally black) is changed to a shade of mainly green. See Also: all_palette ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = peek(a) or ... s = peek({a, i}) Description: Return a single byte value in the range 0 to 255 from machine address a, or return a sequence containing i consecutive byte values starting at address a in memory. Comments: Since addresses are 32-bit numbers, they can be larger than the largest value of type integer (31-bits). Variables that hold an address should therefore be declared as atoms. It is faster to read several bytes at once using the second form of peek() than it is to read one byte at a time in a loop. Remember that peek takes just one argument, which in the second form is actually a 2-element sequence. Example: The following are equivalent: -- method 1 s = {peek(100), peek(101), peek(102), peek(103)} -- method 2 s = peek({100, 4}) See Also: poke, allocate, free, allocate_low, free_low, call ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: pixel(x1, s) Description: Set one or more pixels on a pixel-graphics screen starting at point s, where s is a 2-element screen coordinate {x, y}. If x1 is an atom, one pixel will be set to the color indicated by x1. If x1 is a sequence then a number of pixels will be set, starting at s and moving to the right (increasing x value, same y value). Comments: When x1 is a sequence, a very fast algorithm is used to put the pixels on the screen. It is much faster to call pixel() once, with a sequence of pixel colors, than it is to call it many times, plotting one pixel color at a time. In graphics mode 19, pixel() is highly optimized. Example 1: pixel(BLUE, {50, 60}) -- the point {50,60} is set to the color BLUE Example 2: pixel({BLUE, GREEN, WHITE, RED}, {50,60}) -- {50,60} set to BLUE -- {51,60} set to GREEN -- {52,60} set to WHITE -- {53,60} set to RED See Also: get_pixel, graphics_mode ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: poke(a, x) Description: If x is an atom, write a single byte value to memory address a. If x is a sequence, write a sequence of byte values to consecutive memory locations starting at location a. Comments: The lower 8-bits of each byte value, i.e. remainder(value, 256), is actually stored in memory. It is faster to write several bytes at once by poking a sequence of values, than it is to write one byte at a time in a loop. Writing to the screen memory with poke() can be much faster than using puts() or printf(), but the programming is more difficult. In most cases the speed is not needed. For example, the Euphoria editor never uses poke(). Example: a = allocate(100) -- allocate 100 bytes in memory -- poke one byte at a time: poke(a, 97) poke(a+1, 98) poke(a+2, 99) -- poke 3 bytes at once: poke(a, {97, 98, 99}) Example Program: see demo\callmach.ex See Also: peek, allocate, free, allocate_low, free_low, call ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e polygon(i1, i2, s) Description: Draw a polygon with 3 or more vertices given in s, on a pixel-graphics screen using a certain color i1. Fill the area if i2 is 1. Don't fill if i2 is 0. Example: polygon(GREEN, 1, {{100, 100}, {200, 200}, {900, 700}}) -- makes a solid green triangle. See Also: draw_line, ellipse ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: position(i1, i2) Description: Set the cursor to line i1, column i2, where the top left corner of the screen is line 1, column 1. The next character displayed on the screen will be printed at this location. position() will report an error if the location is off the screen. Comments: The coordinate system for displaying text is different from the one for displaying pixels. Pixels are displayed such that the top-left is (x=0,y=0) and the first coordinate controls the horizontal, left-right location. In pixel-graphics modes you can display both text and pixels. position() only sets the line and column for the text that you display, not the pixels that you plot. There is no corresponding routine for setting the next pixel position. Example: position(2,1) -- the cursor moves to the beginning of the second line from the top See Also: get_position, puts, print, printf ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x3 = power(x1, x2) Description: Raise x1 to the power x2 Comments: The arguments to this functions may be atoms or sequences. The rules for arithmetic operations on sequences apply. Powers of 2 are calculated very efficiently. Example 1: ? power(5, 2) -- 25 is printed Example 2: ? power({5, 4, 3.5}, {2, 1, -0.5}) -- {25, 4, 0.534522} is printed Example 3: ? power(2, {1, 2, 3, 4}) -- {2, 4, 8, 16} Example 4: ? power({1, 2, 3, 4}, 2) -- {1, 4, 9, 16} See Also: log, sqrt ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: s2 = prepend(s1, x) Description: Prepend x to the start of sequence s1. The length of s2 will be length(s1) + 1. Comments: If x is an atom this is the same as s2 = x & s1. If x is a sequence it is definitely not the same. e.g. prepend({1,2,3}, {0,0}) -- {{0,0}, 1, 2, 3} {0,0} & {1,2,3} -- {0, 0, 1, 2, 3} The case where s1 and s2 are the same variable is handled very efficiently. Example: s = {} for i = 1 to 10 do s = prepend(s, i) end for -- s is {10,9,8,7,6,5,4,3,2,1} See Also: append, concatenation (&) and sequence-formation {,,} operators in refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: print(fn, x) Description: Print, to file or device fn, an object x with braces { , , , } to show the structure. Comment: If you want to see a string of characters, rather than just the ASCII codes, you need to use puts or printf. Example 1: print(1, "ABC") -- output is: {65, 66, 67} puts(1, "ABC") -- output is: ABC Example 2: print(1, repeat({10,20}, 3)) -- output is: {{10,20},{10,20},{10,20}} See Also: ?, puts, printf, get ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: printf(fn, st, x) Description: Print x, to file or device fn, using format string st. If x is an atom then a single value will be printed. If x is a sequence, then formats from st are applied to successive elements of x. Thus printf always takes exactly 3 arguments. Only the length of the last argument, containing the values to be printed, will vary. The basic formats are: %d - print an atom as a decimal integer %x - print an atom as a hexadecimal integer %o - print an atom as an octal integer %s - print a sequence as a string of characters %e - print an atom as a floating point number with exponential notation %f - print an atom as a floating-point number with a decimal point but no exponent %g - print an atom as a floating point number using either the %f or %e format, whichever seems more appropriate %% - print the '%' character itself Field widths can be added to the basic formats, e.g. %5d, or %8.2f. The number before the decimal point is the minimum field width to be used. The number after the decimal point is the precision to be used. If the field width is negative, e.g. %-5d then the value will be left-justified within the field. Normally it will be right- justified. If the field width starts with a leading 0, e.g. %08d then leading zeros will be supplied to fill up the field. If the field width starts with a '+' e.g. %+7d then a plus sign will be printed for positive values. Example 1: rate = 7.875 printf(myfile, "The interest rate is: %8.2f\n", rate) The interest rate is: 7.88 Example 2: name="John Smith" score=97 printf(1, "%15s, %5d\n", {name, score}) John Smith, 97 Comments: Watch out for the following common mistake: printf(1, "%s", name) This will print only the first character of name, as each element of name is taken to be a separate value to be formatted. You must say this instead: printf(1, "%s", {name}) Now, the third argument of printf is a one-element sequence containing a single value to be formatted. See Also: sprintf, puts, open ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: puts(fn, x) Description: Output, to file or device fn, a single byte (atom) or sequence of bytes. The low order 8-bits of each value is actually sent out. If fn is the screen you will see text characters displayed. Comment: When you output a sequence of bytes it must not have any (sub)sequences within it. It must be a sequence of atoms only. (Typically a string of ASCII codes). Example 1: puts(SCREEN, "Enter your first name: ") Example 2: puts(output, 'A') -- the single byte 65 will be sent to output See Also: printf, gets, open ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = rand(x1) Description: Return a random integer from 1 to x1, where x1 may be from 1 to the largest positive value of type integer (1073741823). Comments: This function may be applied to an atom or to all elements of a sequence. Example: s = rand({10, 20, 30}) -- s might be: {5, 17, 23} or {9, 3, 12} etc. See Also: set_rand ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e x = read_bitmap(st) Description: st is the name of a .BMP "bitmap" file. The file should be in the bitmap format. The most common variations of the format are supported. If the file is read successfully the result will be a 2-element sequence. The first element is the palette, containing intensity values in the range 0 to 255. The second element is a 2-d sequence of sequences containing a pixel-graphics image. You can pass the palette to all_palette() (after dividing it by 4 to scale it). The image can be passed to display_image(). Bitmaps of 2, 4, 16 or 256 colors are supported. If the file is not in a good format, an error code (atom) is returned instead: global constant BMP_OPEN_FAILED = 1, BMP_UNEXPECTED_EOF = 2, BMP_UNSUPPORTED_FORMAT = 3 Comments: You can create your own bitmap picture files using Windows Paintbrush and many other graphics programs. You can then incorporate these pictures into your Euphoria programs. Example: x = read_bitmap("c:\\windows\\arcade.bmp") -- note: double backslash needed to get single backslash in a string Example Program: demo\bitmap.ex See Also: palette, display_image ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x3 = remainder(x1, x2) Description: Compute the remainder after dividing x1 by x2. The result will have the same sign as x1, and the magnitude of the result will be less than the magnitude of x2. Comments: The arguments to this function may be atoms or sequences. The rules for arithmetic operations on sequences apply. Example 1: a = remainder(9, 4) -- a is 1 Example 2: s = remainder({81, -3.5, -9, 5.5}, {8, -1.7, 2, -4}) -- s is {1, -0.1, -1, 1.5} Example 3: s = remainder({17, 12, 34}, 16) -- s is {1, 12, 2} Example 4: s = remainder(16, {2, 3, 5}) -- s is {0, 1, 1} ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: s = repeat(x, a) Description: Create a sequence of length a where each element is x. Comments: When you repeat a sequence or a floating-point number the interpreter does not actually make multiple copies in memory. Rather, a single copy is "pointed to" a number of times. Example 1: repeat(0, 10) -- {0,0,0,0,0,0,0,0,0,0} Example 2: repeat("JOHN", 4) -- {"JOHN", "JOHN", "JOHN", "JOHN"} See Also: append, prepend, sequence-formation operator {,,} in refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e i = save_bitmap(s, st) Description: Create a Windows bitmap (.BMP) file from a 2-element sequence s. st is the name of a .BMP "bitmap" file. s[1] is the palette: {{r,g,b}, {r,g,b}, ..., {r,g,b}} Each red, green, or blue value is in the range 0 to 255. s[2] is a 2-d sequence of sequences containing a pixel-graphics image. The sequences contained in s[2] must all have the same length. s is in the same format as the value returned by read_bitmap(). The result will be one of the following codes: global constant BMP_SUCCESS = 0, BMP_OPEN_FAILED = 1, BMP_INVALID_MODE = 4 -- either invalid graphics mode or invalid argument Comments: If you use get_all_palette() to get the palette before calling this function, you must multiply the returned intensity values by 4 before calling save_bitmap(). save_bitmap() produces bitmaps of 2, 4, 16, or 256 colors and these can all be read with read_bitmap(). Windows Paintbrush and some other tools do not support 4-color bitmaps. save_bitmap() works in pixel-graphics modes. Example: paletteData = get_all_palette() * 4 code = save_bitmap({paletteData, imageData}, "c:\\example\\a1.bmp") See Also: save_image, read_bitmap, save_screen, get_all_palette ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e s3 = save_image(s1, s2) Description: Save a rectangular image from a pixel-graphics screen. The result is a 2-d sequence of sequences containing all the pixels in the image. You can redisplay the image using display_image(). s1 is a 2-element sequence {x1, y1} specifying the top-left pixel in the image. s2 is a sequence {x2, y2} specifying the bottom-right pixel. Comments: You might use this in a graphical user interface to save a portion of the screen before you display a drop-down menu or dialog box. Example: s = save_image({0,0}, {50,50}) display_image({100,200}, s) display_image({300,400}, s) -- saves a 51x51 square image, then redisplays it at {100,200} -- and at {300,400} See Also: display_image, save_text_image ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e i = save_screen(x1, st) Description: Save the whole screen or a rectangular region of the screen as a Windows bitmap (.BMP) file. To save the whole screen, pass the integer 0 for x1. To save a rectangular region of the screen, x1 should be a sequence of 2 sequences: {{topLeftXPixel, topLeftYPixel}, {bottomRightXPixel, bottomRightYPixel}} st is the name of a .BMP "bitmap" file. The result will be one of the following codes: global constant BMP_SUCCESS = 0, BMP_OPEN_FAILED = 1, BMP_INVALID_MODE = 4 -- either invalid graphics mode or invalid argument Comments: save_screen() produces bitmaps of 2, 4, 16, or 256 colors and these can all be read with read_bitmap(). Windows Paintbrush and some other tools do not support 4-color bitmaps. save_screen() only works in pixel-graphics modes, not text modes. Example 1: code = save_screen(0, "c:\\example\\a1.bmp") Example 2: err = save_screen({{0,0},{200, 15}}, "b1.bmp") See Also: save_image, read_bitmap ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e s3 = save_text_image(s1, s2) Description: Save a rectangular region of text from a text-mode screen. The result is a sequence of sequences containing ASCII characters and attributes from the screen. You can redisplay this text using display_text_image(). s1 is a 2-element sequence {line1, column1} specifying the top-left character. s2 is a sequence {line2, column2} specifying the bottom right character. Comments: Because the character attributes are also saved, you will get the correct foreground and background color for each character if you redisplay the text. An attribute byte is made up of two 4-bit fields that encode the foreground and background color of a character. The high-order 4 bits determine the background color, while the low-order 4 bits determine the foreground color. This routine only works in text modes. You might use this function in a text-mode graphical user interface to save a portion of the screen before displaying a drop-down menu, dialog box, alert box etc. If you are flipping video pages, note that this function reads from the current active page. Example: If the top 2 lines of the screen have: Hello World s = save_text_image({1,1}, {2,5}) Then s is something like: {"H-e-l-l-o-", "W-o-r-l-d-"} where we have indicated the attribute bytes by '-' See Also: display_text_image, save_image, set_active_page ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e scroll(i1, i2, i3) Description: Scroll a region of text on the screen either up (i1 positive) or down (i1 negative) by i1 lines. The region is the series of lines on the screen from i2 (top line) to i3 (bottom line), inclusive. A new blank line will appear at the top or bottom. Example Program: see bin\ed.ex See Also: clear_screen, text_rows ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include file.e i1 = seek(fn, i2) Description: Seek (move) to any byte position in the file fn or to the end of file if i2 is -1. For each open file there is a current byte position that is updated as a result of I/O operations on the file. The initial file position is 0 for files opened for read, write or update. The initial position is the end of file for files opened for append. The value returned by seek() is 0 if the seek was successful, and non-zero if it was unsuccessful. It is possible to seek past the end of a file. In this case undefined bytes will be added to the file to make it long enough for the seek. See Also: where, open ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: i = sequence(x) Description: Return 1 if x is a sequence else return 0. Comments: This serves to define the sequence type. You can also call it like an ordinary function to determine if an object is a sequence. Example 1: sequence s s = {1,2,3} Example 2: if sequence(x) then sum = 0 for i = 1 to length(x) do sum = sum + x[i] end for else -- x must be an atom sum = x end if See Also: atom, object type in refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e set_active_page(i) Description: Select video page i to send all screen output to. Comments: With multiple pages you can instantaneously change the entire screen without causing any visible "flicker". You can also save the screen and bring it back quickly. video_config() will tell you how many pages are available in the current graphics mode. By default, the active page and the display page are both 0. This works under DOS, or full-screen under Windows. In a partial-screen window you cannot change the active page. Example: include image.e -- active & display pages are initially both 0 puts(1, "\nThis is page 0\n") set_active_page(1) -- screen output will now go to page 1 clear_screen() puts(1, "\nNow we've flipped to page 1\n") if getc(0) then -- wait for key-press end if set_display_page(1) -- "Now we've ..." becomes visible if getc(0) then -- wait for key-press end if set_display_page(0) -- "This is ..." becomes visible again set_active_page(0) See Also: get_active_page, set_display_page ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include image.e set_display_page(i) Description: Set video page i to be mapped to the visible screen. Comments: With multiple pages you can instantaneously change the entire screen without causing any visible "flicker". You can also save the screen and bring it back quickly. video_config() will tell you how many pages are available in the current graphics mode. By default, the active page and the display page are both 0. This works under DOS, or full-screen under Windows. In a partial-screen window you cannot change the active page. Example: See set_active_page example. See Also: get_display_page, set_active_page ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e set_rand(a1) Description: Set the random number generator to a certain state, a1, so that you will get a known series of random numbers on subsequent calls to rand(). The lower 32 bits of the value of a1 are used. Comments: Normally the numbers returned by the rand() function are totally unpredictable, and will be different each time you run your program. Sometimes however you may wish to repeat the same series of numbers, perhaps because you are trying to debug your program, or maybe you want the ability to generate the same output (e.g. a random picture) for your user upon request. Example: sequence s, t s = repeat(0, 3) t = s set_rand(12345) s[1] = rand(10) s[2] = rand(100) s[3] = rand(1000) set_rand(12345) -- same value for set_rand() t[1] = rand(10) -- same arguments to rand() as before t[2] = rand(100) t[3] = rand(1000) -- at this point s and t will be identical See Also: rand ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e set_vector(i, s) Description: Set s as the new address for handling interrupt number i. s must be a protected mode far address in the form: {16-bit segment, 32-bit offset}. Comments: Before calling set_vector() you must store a machine-code interrupt handling routine at location s in memory. The 16-bit segment can be the code segment used by Euphoria. To get the value of this segment see demo\hardint.ex. The offset can be the 32-bit value returned by allocate(). Euphoria runs in protected mode with the code segment and data segment pointing to the same physical memory, but with different access modes. Interrupts occurring in either real-mode or protected mode will be passed to your handler. Your interrupt handler should immediately load the correct data segment before it tries to reference memory. Your handler might return from the interrupt using the iretd instruction, or jump to the original interrupt handler. It should save and restore any registers that it modifies. You should lock the memory used by your handler to ensure that it will never be swapped out. See lock_memory(). It is highly recommended that you study demo\hardint.ex before trying to set up your own interrupt handler. You should have a good knowledge of machine-level programming before attempting to write your own handler. You can call set_vector() with the far address returned by get_vector(), when you want to restore the original handler. Example: set_vector(#1C, {code_segment, my_handler_address}) Example Program: demo\hardint.ex See Also: get_vector, lock_memory ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = sin(x1) Description: Return the sine of x1, where x1 is in radians. Comments: This function may be applied to an atom or to all elements of a sequence. Example: sin_x = sin({.5, .9, .11}) -- sin_x is {.479, .783, .110} See Also: cos, tan ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include sort.e s2 = sort(s1) Description: Sort s1 into ascending order using a fast sorting algorithm. The elements of s1 can be any mix of atoms or sequences. Atoms come before sequences, and sequences are sorted "alphabetically" where the first elements are more significant than the later elements. Comments: By defining your own compare function to override the built-in compare(), you can change the ordering of values from sort(), and perhaps choose a field or element number on which to base the sort. Define your compare() as a global function before including sort.e. Example 1: x = 0 & sort({7,5,3,8}) & 0 -- x is set to {0, 3, 5, 7, 8, 0} Example 2: y = sort({"Smith", "Jones", "Doe", 5.5, 4, 6}) -- y is {4, 5.5, 6, "Doe", "Jones", "Smith"} Example 3: database = sort({{"Smith", 95.0, 29}, {"Jones", 77.2, 31}, {"Clinton", 88.7, 44}}) -- The 3 database "records" will be sorted by the first "field" -- i.e. by name. Where the first field (element) is equal it -- will be sorted by the second field etc. -- database is {{"Clinton", 88.7, 44}, {"Jones", 77.2, 31}, {"Smith", 95.0, 29}} See Also: compare, match, find ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e sound(i) Description: Turn on the PC speaker at frequency i. If i is 0 the speaker will be turned off. Example: sound(1000) -- starts a fairly high pitched sound ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: s = sprintf(st, x) Description: This is exactly the same as printf(), except that the output is returned as a sequence of characters, rather than being sent to a file or device. st is a format string, x is the value or sequence of values to be formatted. printf(fn, st, x) is equivalent to puts(fn, sprintf(st, x)). Comments: Some typical uses of sprintf are: 1. Converting numbers to strings. 2. Creating strings to pass to system(). 3. Creating formatted error messages and passing them to a common error message handler. Example: s = sprintf("%08d", 12345) -- s is "00012345" See Also: printf, value, get ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = sqrt(x1) Description: Calculate the square root of x1. Comments: This function may be applied to an atom or to all elements of a sequence. Taking the square root of a negative number will abort your program with a run-time error message. Example: r = sqrt(16) -- r is 4 See Also: log, power ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: system(s, i) Description: Pass a command string s to the DOS command interpreter for execution. The argument i indicates the manner in which to return from the system call. value of i return action ---------- ------------- 0 - restore previous graphics mode (clears the screen) 1 - make a beep sound, wait for a key press, then restore the graphics mode 2 - do not restore graphics mode Comments: Action 2 should only be used when it is known that the system call will not change the graphics mode. You can use Euphoria as a sophisticated DOS "batch" language by making calls to system(). A Euphoria program will start off using extended memory. If extended memory runs out the program will consume conventional memory. If conventional memory runs out it will use virtual memory, i.e. swap space on disk. The DOS command run by system() will fail if there is not enough conventional memory available. To avoid this situation you can reserve some conventional (low) memory by typing: SET CAUSEWAY=LOWMEM:xxx where xxx is the number of K of conventional memory to reserve. Type this before running your program. You can also put this in a .bat file that runs your program, or in AUTOEXEC.BAT. For example: SET CAUSEWAY=LOWMEM:80 ex myprog.ex This will reserve 80K of conventional memory, which should be enough to run simple DOS commands like COPY, MOVE, MKDIR etc. Example: system("copy temp.txt a:\\temp.bak", 2) -- note use of double backslash in literal string to get single backslash Example Program: see install.ex See Also: dir, current_dir, getenv, command_line ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: x2 = tan(x1) Description: Return the tangent of x1, where x1 is in radians. Comments: This function may be applied to an atom or to all elements of a sequence. Example: t = tan(1.0) -- t is 1.55741 See Also: sin, cos, arctan ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e text_color(i) Description: Set the foreground text color. Add 16 to get blinking text in some modes. See graphics.e for a list of possible colors. Comments: Text that you print *after* calling text_color will have the desired color. When your program terminates, the last color that you selected and actually printed on the screen will remain in effect. Thus you may have to print something, maybe just '\n', in WHITE to restore white text, especially if you are at the bottom line of the screen, ready to scroll up. Example: text_color(BRIGHT_BLUE) See Also: bk_color ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include graphics.e i2 = text_rows(i1) Description: Set the number of lines on a text-mode screen to i1 if possible. i2 will be set to the actual new number of lines. Comments: Values of 25, 28, 43 and 50 lines are supported by most video cards. See Also: graphics_mode ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Syntax: include machine.e tick_rate(a) Description: Specify the number of clock-tick interrupts per second. This determines the precision of the time() library routine. It also affects the sampling rate for time profiling. Comments: On a PC the clock-tick interrupt normally occurs at 18.2 interrupts per second. tick_rate() lets you increase that rate, but not decrease it. tick_rate(0) will restore the rate to the normal 18.2 rate. Euphoria will also restore the rate automatically when it exits, even when it finds an error in your program. If a program runs in a DOS window with a tick rate other than 18.2, the time() function will not advance unless the window is the active window. While ex.exe is running, the system will maintain the correct time of day. However if ex.exe should crash (e.g. you see a "Causeway..." error) while the tick rate is high, you (or your user) may need to reboot the machine to restore the proper rate. If you don't, the system time may advance too quickly. This problem does not occur on Windows 95, only on DOS or Windows 3.1. You will always get back the correct time of day from the battery-operated clock in your system when you boot up again. Example: tick_rate(100) -- time() will now advance in steps of .01 seconds -- instead of the usual .055 seconds See Also: time, discussion of time profiling in refman.doc ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ