read_file
| Definition: |
include builtins\read_file.e object o = read_file(object file, integer as_text = BINARY_MODE) |
| Description: | Return the contents of a file as a single string (sequence of bytes), or -1 if the file cannot be opened.
file: an object, either a file path or the handle to an open file. as_text: integer, BINARY_MODE (the default) assumes binary mode that causes every byte to be read in, whereas TEXT_MODE assumes text mode that ensures lines end with just a Ctrl-J (NewLine) character, with the first byte value of 26 (Ctrl-Z) interpreted as end-of-file. |
| pwa/p2js: | Not supported. |
| Comments: |
This is a quick and dirty compatibility shim for Euphoria; where possible get_text()
should be used instead, with GT_WHOLE_FILE+GT_BINARY and GT_LF_LEFT quite likely to yield the same results as
BINARY_MODE and TEXT_MODE respectively, but not guaranteed, especially the Ctrl-Z part.
As this is a simple compatibility shim for Euphoria, the constants BINARY_MODE and TEXT_MODE are declared in builtins\read_file.e, rather than psym.e, and cannot be used before the include statement. When using BINARY_MODE, each byte in the file is returned as an element in the return sequence/string. When not using BINARY_MODE, the file will be interpreted as a text file. This means that all line endings will be transformed to a single 0x0A character and the first 0x1A character (Ctrl-Z) will indicate the end of file (all data after this will not be returned to the caller.) The file parameter can be a string, in which case the file is opened and closed by this routine, or an integer from a previous call to open(), in which case it is not closed by this routine. If the file cannot be opened, -1 is returned. |
| Example 1: |
data = read_file("my_file.txt")
-- data contains the entire contents of my_file.txt
|
| Example 2: |
fh = open("my_file.txt", "r")
data = read_file(fh)
close(fh)
-- data contains the entire contents of my_file.txt
|
| Example 3: |
{} = system_exec("dir > lsoutput",4)
object results = read_file("lsoutput",TEXT_MODE)
puts(1,results)
|
| See Also: | get_text, read_lines, system_exec |