Syntax: include file.e
unlock_file(fn, s)
Description: Unlock an open file fn, or a portion of file fn. You must have previously locked the file using lock_file(). On DOS32 and WIN32 you can unlock a range of bytes within a file by specifying the s parameter as {first_byte, last_byte}. The same range of bytes must have been locked by a previous call to lock_file(). On Linux/FreeBSD you can currently only lock or unlock an entire file. The s parameter should be {} when you want to unlock an entire file. On Linux/FreeBSD, s must always be {}.
Comments: You should unlock a file as soon as possible so other processes can use it.
Any files that you have locked, will automatically be unlocked when your program terminates.
See lock_file() for further comments and an example.
See Also: lock_file


Syntax: include machine.e (or safe.e)
Description: Remove a block of memory from the list of safe blocks maintained by safe.e (the debug version of machine.e). The block starts at address a.
Comments: This routine is only meant to be used for debugging purposes. Use it to unregister blocks of memory that you have previously registered using register_block(). By unregistering a block, you remove it from the list of safe blocks maintained by safe.e. This prevents your program from performing any further reads or writes of memory within the block.
See register_block() for further comments and an example.
See Also: register_block, safe.e


Syntax: include wildcard.e
x2 = upper(x1)
Description: Convert an atom or sequence to upper case.
s = upper("Euphoria")

-- s is "EUPHORIA"

a = upper('g')

-- a is 'G'

s = upper({"Euphoria", "Programming"})


See Also: lower


Platform: DOS32
Syntax: include machine.e
Description: use_vesa(1) will force Euphoria to use the VESA graphics standard. This may cause Euphoria programs to work better in SVGA graphics modes with certain video cards. use_vesa(0) will restore Euphoria's original method of using the video card.
Comments: Most people can ignore this. However if you experience difficulty in SVGA graphics modes you should try calling use_vesa(1) at the start of your program before any calls to graphics_mode().

Arguments to use_vesa() other than 0 or 1 should not be used.


fail = graphics_mode(261)

See Also: graphics_mode


Syntax: include get.e
s = value(st)
Description: Read the string representation of a Euphoria object, and computes the value of that object. A 2 element sequence, {error_status, value} is actually returned, where error_status can be one of:
    GET_SUCCESS -- a valid object representation was found

    GET_EOF     -- end of string reached too soon

    GET_FAIL    -- syntax is wrong

    GET_NOTHING -- end of string reached without any value being even partially read

Comments: This works the same as get(), but it reads from a string that you supply, rather than from a file or device.

After reading one valid representation of a Euphoria object, value() will stop reading and ignore any additional characters in the string. For example, "36" and "36P" will both give you {GET_SUCCESS, 36}.

Example 1:
s = value("12345"}

-- s is {GET_SUCCESS, 12345}

Example 2:
s = value("{0, 1, -99.9}")

-- s is {GET_SUCCESS, {0, 1, -99.9}}

Example 3:
s = value("+++")

-- s is {GET_FAIL, 0} -- '+' is correct, but "++" is not

See Also: get, sprintf, print


If the representation was valid, you can use the third returned element to pick up where you left, like get() does in a file. There is no corresponding get_from(), at least because calling where() before and after get() will tell you how many characters were read. >
Syntax: include get.e
s = value_from(st, i)
Description: Read the string representation of a Euphoria object, and computes the value of that object. The string which is read is the tail of st which starts at index i. A 4-element sequence, {error_status, value, total characters read, number of leading whitespace} is actually returned, where error_status can be one of:
    GET_SUCCESS -- a valid object representation was found

    GET_EOF     -- end of string reached too soon

    GET_FAIL    -- syntax is wrong

    GET_NOTHING -- end of string reached without any value being even partially read

Comments: This works the same as value(), but
  • reading starts where you instruct the routine to, instead of starting from the beginning of the string. You can always pass value() a slice to achieve a similar effect.
  • it returns extra information value() doesn't.

After reading one valid representation of a Euphoria object, value_from() will stop reading and ignore any additional characters in the string. For example, "36" and "36P" will both give you {GET_SUCCESS, 36, 2, 0}.

Example 1:
s = value_from("  12345"} -- notice the two leading spaces

-- s is {GET_SUCCESS, 12345, 7, 2}

Example 2:
s = value_from("{0, 1, -99.9}")

-- s is {GET_SUCCESS, {0, 1, -99.9}, 13, 0}

Example 3:
s = value_from("+++")

-- s is {GET_FAIL, 0, 2, 0} -- error condition triggered on reading the 2nd character

See Also: get, sprintf, print


Syntax: include graphics.e
s = video_config()
Description: Return a sequence of values describing the current video configuration:
{color monitor?, graphics mode, text rows, text columns, xpixels, ypixels, number of colors, number of pages}

The following constants are defined in graphics.e:

    global constant VC_COLOR   = 1,

                    VC_MODE    = 2,

                    VC_LINES   = 3,

                    VC_COLUMNS = 4,

                    VC_XPIXELS = 5,

                    VC_YPIXELS = 6,

                    VC_NCOLORS = 7,

                    VC_PAGES   = 8

Comments: This routine makes it easy for you to parameterize a program so it will work in many different graphics modes.

On the PC there are two types of graphics mode. The first type, text mode, lets you print text only. The second type, pixel-graphics mode, lets you plot pixels, or points, in various colors, as well as text. You can tell that you are in a text mode, because the VC_XPIXELS and VC_YPIXELS fields will be 0. Library routines such as polygon(), draw_line(), and ellipse() only work in a pixel-graphics mode.

vc = video_config()  -- in mode 3 with 25-lines of text:

-- vc is {1, 3, 25, 80, 0, 0, 32, 8}

See Also: graphics_mode


Syntax: include get.e
i = wait_key()
Description: Return the next key pressed by the user. Don't return until a key is pressed.
Comments: You could achieve the same result using get_key() as follows:
    while 1 do

        k = get_key()

        if k != -1 then


        end if

    end while

However, on multi-tasking systems like Windows or Linux/FreeBSD, this "busy waiting" would tend to slow the system down. wait_key() lets the operating system do other useful work while your program is waiting for the user to press a key.

You could also use getc(0), assuming file number 0 was input from the keyboard, except that you wouldn't pick up the special codes for function keys, arrow keys etc.

See Also: get_key, getc


Syntax: include file.e
i1 = walk_dir(st, i2, i3)
Description: This routine will "walk" through a directory with path name given by st. i2 is the routine id of a routine that you supply. walk_dir() will call your routine once for each file and subdirectory in st. If i3 is non-zero (TRUE), then the subdirectories in st will be walked through recursively.

The routine that you supply should accept the path name and dir() entry for each file and subdirectory. It should return 0 to keep going, or non-zero to stop walk_dir(). walk_dir() returns 0 when it runs successfully to completion. It returns -1 if it can't open the path name st. Otherwise, it returns whatever non-zero value your routine returned when it chose to stop walk_dir prematurely.

Comments: This mechanism allows you to write a simple function that handles one file at a time, while walk_dir() handles the process of walking through all the files and subdirectories.

By default, the files and subdirectories will be visited in alphabetical order. To use a different order, set the global integer my_dir to the routine id of your own modified dir() function that sorts the directory entries differently. See the default dir() function in file.e.

The path that you supply to walk_dir() must not contain wildcards (* or ?). Only a single directory (and its subdirectories) can be searched at one time.

function look_at(sequence path_name, sequence entry)

-- this function accepts two sequences as arguments

    printf(1, "%s\\%s: %d\n",

           {path_name, entry[D_NAME], entry[D_SIZE]})

    return 0 -- keep going

end function

exit_code = walk_dir("C:\\MYFILES", routine_id("look_at"), TRUE)

Example Program: euphoria\bin\search.ex
See Also: dir, current_dir


Syntax: include file.e
a1 = where(fn)
Description: This function returns the current byte position in the file fn. This position is updated by reads, writes and seeks on the file. It is the place in the file where the next byte will be read from, or written to.
See Also: seek, open


Syntax: include wildcard.e
i = wildcard_file(st1, st2)
Description: Return 1 (true) if the filename st2 matches the wild card pattern st1. Return 0 (false) otherwise. This is similar to DOS wildcard matching, but better in some cases. * matches any 0 or more characters, ? matches any single character. On Linux and FreeBSD the character comparisons are case sensitive. On DOS and Windows they are not.
Comments: You might use this function to check the output of the dir() routine for file names that match a pattern supplied by the user of your program.

In DOS "*ABC.*" will match all files. wildcard_file("*ABC.*", s) will only match when the file name part has "ABC" at the end (as you would expect).

Example 1:
i = wildcard_file("AB*CD.?", "aB123cD.e")

-- i is set to 1 on DOS or Windows, 0 on Linux or FreeBSD

Example 2:
i = wildcard_file("AB*CD.?", "abcd.ex")

-- i is set to 0 on all systems, 

-- because the file type has 2 letters not 1

Example Program: bin\search.ex
See Also: wildcard_match, dir


Syntax: include wildcard.e
i = wildcard_match(st1, st2)
Description: This function performs a general matching of a string against a pattern containing * and ? wildcards. It returns 1 (true) if string st2 matches pattern st1. It returns 0 (false) otherwise. * matches any 0 or more characters. ? matches any single character. Character comparisons are case sensitive.
Comments: If you want case insensitive comparisons, pass both st1 and st2 through upper(), or both through lower() before calling wildcard_match().

If you want to detect a pattern anywhere within a string, add * to each end of the pattern:

i = wildcard_match('*' & pattern & '*', string)

There is currently no way to treat * or ? literally in a pattern.
Example 1:
i = wildcard_match("A?B*", "AQBXXYY")

-- i is 1 (TRUE)

Example 2:
i = wildcard_match("*xyz*", "AAAbbbxyz")

-- i is 1 (TRUE)

Example 3:
i = wildcard_match("A*B*C", "a111b222c")

-- i is 0 (FALSE) because upper/lower case doesn't match

Example Program: bin\search.ex
See Also: wildcard_file, match, upper, lower, compare


Syntax: include graphics.e
Description: Allow text to wrap at the right margin (i = 1) or get truncated (i = 0).
Comments: By default text will wrap.

Use wrap() in text modes or pixel-graphics modes when you are displaying long lines of text.

puts(1, repeat('x', 100) & "\n\n")

-- now have a line of 80 'x' followed a line of 20 more 'x'


puts(1, repeat('x', 100) & "\n\n")

-- creates just one line of 80 'x'

See Also: puts, position


Syntax: x3 = xor_bits(x1, x2)
Description: Perform the logical XOR (exclusive OR) operation on corresponding bits in x1 and x2. A bit in x3 will be 1 when one of the two corresponding bits in x1 or x2 is 1, and the other is 0.
Comments: The arguments to this function may be atoms or sequences. The rules for 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 = xor_bits(#0110, #1010)

-- a is #1100

See Also: and_bits, or_bits, not_bits, int_to_bits, int_to_bytes