# get

Definition: | include get.e sequence s = get(integer fn)
Description: | Input, from file fn, a human-readable string of characters representing a Phix object, and convert the string into the numeric value of that object. s will be a 2-element sequence: {error status, value}.
pwa/p2js: | Not supported.
Comments: | Error status codes 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 Phix 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 its 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: 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 Phix object. 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). Whitespace is not necessary within a top-level object. A call to get() will read one entire top-level object, plus one additional (whitespace) character. The combination of print() and get() can be used to save a Phix object to disk and later read it back. The value returned is not meaningful unless you have a GET_SUCCESS status. Note this is an "inherited" routine, that I don’t much like. Whenever I try to use it, I tend to get stuck, give up, and roll my own. However if it works for you, then fine. There is also a map:get() routine, which is quite different.
Example: | Suppose your program asks the user to enter a number from the keyboard.
    -- If they type 77.5, get(0) would return:
    {GET_SUCCESS, 77.5}
    -- whereas gets(0) would return:
    "77.5\n"
See Also: | print, value, gets, getc, prompt_number, prompt_string, map:get