routine or constant name search

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)

reads from an open file a human-readable string of characters representing a Euphoria object. Converts 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 two (GET_SHORT_ANSWER) or four (GET_LONG_ANSWER) consisting 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. For example: {23, {49, 57}, 0.5, -1, 99, 'A', "john"}. A single call to get will read in this entire sequence, return its value as a result, and return complementary information.

The function get() is guaranteed to read a value produced by print(). It is often necessary to leave a new line between objects printed though. The user should not use get() or value() to read number notations that use bases other than ten or sixteen. Hexadecimal values will not be read unless they are preceeded by a hash mark (#).

If a nonzero offset is supplied, it is interpreted as an offset to the current file position; the file will start seek from there first.

get returns a two or four element sequence; similar to what value returns:

  • 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 two elements. Setting it to GET_LONG_ANSWER causes four elements to be returned.

Each call to get picks up where the previous call left off. For instance: a series of five calls to get would be needed to read in this sequence: `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.

After seeing -- something\nBut no value and the input stream stops right there, you will receive a status code of GET_NOTHING, because nothing but whitespace or comments was read. If you had opted for a short answer, you would 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 .../euphoria/demo/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)

reads, from a string, a human-readable string of characters representing a Euphoria object. Converts 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 two (GET_SHORT_ANSWER) or four (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)

calls the value function and returns the resulting value on success or the default 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 calling value(st) is a success. then value()[2], otherwise it will return the parameter def.
Example 1:
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