OpenEuphoria

8.14 Input Routines

8.14.1 Error Status Constants

These are returned from get and value.

8.14.1.1 GET_SUCCESS

include std/get.e
namespace stdget
public constant GET_SUCCESS

8.14.1.2 GET_EOF

include std/get.e
namespace stdget
public constant GET_EOF

8.14.1.3 GET_FAIL

include std/get.e
namespace stdget
public constant GET_FAIL

8.14.1.4 GET_NOTHING

include std/get.e
namespace stdget
public constant GET_NOTHING

8.14.2 Answer Types

8.14.2.1 GET_SHORT_ANSWER

include std/get.e
namespace stdget
public constant GET_SHORT_ANSWER

8.14.2.2 GET_LONG_ANSWER

include std/get.e
namespace stdget
public constant GET_LONG_ANSWER

8.14.3 Routines

8.14.3.1 get

include std/get.e
namespace stdget
public function get(integer file, integer offset = 0, integer answer = GET_SHORT_ANSWER)

Input, from an open file, a human-readable string of characters representing a Euphoria object. Convert the string into the numeric value of that object.

Parameters:

1. file : an integer, the handle to an open file from which to read
2. offset : an integer, an offset to apply to file position before reading. Defaults to 0.
3. answer : an integer, either GET_SHORT_ANSWER (the default) or GET_LONG_ANSWER.

Returns:

A sequence, of length 2 (GET_SHORT_ANSWER) or 4 (GET_LONG_ANSWER), made of

• an integer, the return status. This is any of:
  • GET_SUCCESS -- object was read successfully
  • GET_EOF -- end of file before object was read completely
  • GET_FAIL -- object is not syntactically correct
  • GET_NOTHING -- nothing was read, even a partial object string, before end of input
• an object, the value that was read. This is valid only if return status is GET_SUCCESS.
• an integer, the number of characters read. On an error, this is the point at which the error was detected.
• an integer, the amount of initial whitespace read before the first active character was found

Comments:

When answer is not specified, or explicitly GET_SHORT_ANSWER, only the first two elements in the returned sequence are actually returned.

The GET_NOTHING return status will not be returned if answer is GET_SHORT_ANSWER.

get() can read arbitrarily complicated Euphoria objects. You could have a long sequence of values in braces and separated by commas and comments, e.g. {23, {49, 57}, 0.5, -1, 99, 'A', "john"}. A single call to get() will read in this entire sequence and return its value as a result, as well as complementary information.

If a nonzero offset is supplied, it is interpreted as an offset to the current file position, and the file will be seek()ed there first.

get() returns a 2 or 4 element sequence, like value() does:

• a status code (success/error/end of file/no value at all)
• the value just read (meaningful only when the status code is GET_SUCCESS) (optionally)
• the total number of characters read
• the amount of initial whitespace read.

Using the default value for answer, or setting it to GET_SHORT_ANSWER, returns 2 elements. Setting it to GET_LONG_ANSWER causes 4 elements to be returned.

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. And seeing

-- something\nBut no value

and the input stream stops right there, you'll receive a status code of GET_NOTHING, because nothing but whitespace or comments was read. If you had opted for a short answer, you'd get GET_EOF instead.

Multiple "top-level" objects in the input stream must be separated from each other with one or more "whitespace" characters (blank, tab, \r or \n). At the very least, a top level number must be followed by a white space from the following object. Whitespace is not necessary within a top-level object. Comments, terminated by either '\n' or '\r', are allowed anywhere inside sequences, and ignored if at the top level. A call to get() will read one entire top-level object, plus possibly one additional (whitespace) character, after a top level number, even though the next object may have an identifiable starting point.

The combination of print() and get() can be used to save a 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. Remember to write out a whitespace character (using puts()) after each call to print(), at least when a top level number was just printed.

The value returned is not meaningful unless you have a GET_SUCCESS status.

Example 1:

-- If he types 77.5, get(0) would return:
{GET_SUCCESS, 77.5}

-- whereas gets(0) would return:
"77.5\n"

Example 2:

See bin\mydata.ex

See Also:

value

8.14.3.2 value

include std/get.e
namespace stdget
public function value(sequence st, integer start_point = 1, integer answer = GET_SHORT_ANSWER)

Read, from a string, a human-readable string of characters representing a Euphoria object. Convert the string into the numeric value of that object.

Parameters:

1. st : a sequence, from which to read text
2. offset : an integer, the position at which to start reading. Defaults to 1.
3. answer : an integer, either GET_SHORT_ANSWER (the default) or GET_LONG_ANSWER.

Returns:

A sequence, of length 2 (GET_SHORT_ANSWER) or 4 (GET_LONG_ANSWER), made of

• an integer, the return status. This is any of
  • GET_SUCCESS -- object was read successfully
  • GET_EOF -- end of file before object was read completely
  • GET_FAIL -- object is not syntactically correct
  • GET_NOTHING -- nothing was read, even a partial object string, before end of input
• an object, the value that was read. This is valid only if return status is GET_SUCCESS.
• an integer, the number of characters read. On an error, this is the point at which the error was detected.
• an integer, the amount of initial whitespace read before the first active character was found

Comments:

When answer is not specified, or explicitly GET_SHORT_ANSWER, only the first two elements in the returned sequence are actually returned.

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}.

The function returns {return_status, value} if the answer type is not passed or set to GET_SHORT_ANSWER. If set to GET_LONG_ANSWER, the number of characters read and the amount of leading whitespace are returned in 3rd and 4th position. The GET_NOTHING return status can occur only on a long answer.

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}

See Also:

get

8.14.3.3 defaulted_value

include std/get.e
namespace stdget
public function defaulted_value(object st, object def, integer start_point = 1)

Perform a value() operation on a sequence, returning the value on success or the default on failure.

Parameters:

1. st : object to retrieve value from.
2. def : the value returned if st is an atom or value(st) fails.
3. start_point : an integer, the position in st at which to start getting the value from. Defaults to 1

Returns:

• If st, is an atom then def is returned.
• If value(st), call is a success, then value()[2], otherwise it will return the parameter #def#.

Examples:

object i = defaulted_value("10", 0)
-- i is 10

i = defaulted_value("abc", 39)
-- i is 39

i = defaulted_value(12, 42)
-- i is 42

i = defaulted_value("{1,2}", 42)
-- i is {1,2}

See Also:

value