OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.13 Data Type Conversion | Up: 8 API Reference | 8.15 Searching > | 9 Release Notes >>

## 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

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.13 Data Type Conversion | Up: 8 API Reference | 8.15 Searching > | 9 Release Notes >>