|
int | close () |
| Closes the ReadOnlyFile object.
|
|
| constructor (string path, *string encoding) |
| Creates the ReadOnlyFile object.
|
|
| copy () |
| Creates a new ReadOnlyFile object with the same character encoding specification as the original, otherwise no other information is copied.
|
|
| destructor () |
| Closes the ReadOnlyFile if it is open and destroys the ReadOnlyFile object.
|
|
string | getEncoding () |
| Returns the character encoding for the ReadOnlyFile.
|
|
*string | getFileName () |
| returns the file path/name used to open the file if the file is open, otherwise NOTHING
|
|
int | getPos () |
| Returns the current file position as an integer giving the offset in bytes from the beginning of the file (starting from zero)
|
|
*string | getchar () |
| Reads one character from the file and returns it as a string; returns NOTHING if no data can be read from the file.
|
|
hash | hstat () |
| Returns a Stat Hash about the file's status or throws an exception if any errors occur.
|
|
bool | isDataAvailable (timeout timeout_ms=0) |
| Returns True if there is data available for reading from the file within the timeout period.
|
|
bool | isOpen () |
| returns True if the File is open, False if not
|
|
bool | isTty () |
| returns True if the File is connected to a terminal device, False if not
|
|
nothing | open (string path, *string encoding) |
| Opens a file in a particular mode; throws an exception on failure.
|
|
*string | read (softint size, timeout timeout_ms=-1) |
| Reads a certain number of bytes from the ReadOnlyFile within an optional timeout period and returns a string of the data read or NOTHING if no data can be read.
|
|
*binary | readBinary (softint size, timeout timeout_ms=-1) |
| Reads a certain number of bytes from the file within an optional timeout period and returns a binary object of the data read or NOTHING if no data can be read.
|
|
*string | readLine (bool incl_eol=True, *string eol) |
| Reads until an EOL marker is found and returns the string read or NOTHING if no data can be read.
|
|
*int | readi1 () |
| Reads a 1-byte signed integer from the file in binary format or NOTHING if no data can be read.
|
|
*int | readi2 () |
| Reads a 2-byte (16 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read.
|
|
*int | readi2LSB () |
| Reads a 2-byte (16 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read.
|
|
*int | readi4 () |
| Reads a 4-byte (32 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read.
|
|
*int | readi4LSB () |
| Reads a 4-byte (32 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read.
|
|
*int | readi8 () |
| Reads an 8-byte (64 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read.
|
|
*int | readi8LSB () |
| Reads an 8-byte (64 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read.
|
|
*int | readu1 () |
| Reads a 1-byte unsigned integer from the ReadOnlyFile in binary format or NOTHING if no data can be read.
|
|
*int | readu2 () |
| Reads a 2-byte (16 bit) unsigned integer from the ReadOnlyFile in binary big-endian format or NOTHING if no data can be read.
|
|
*int | readu2LSB () |
| Reads a 2-byte (16 bit) unsigned integer from the file in binary little-endian format or NOTHING if no data can be read.
|
|
*int | readu4 () |
| Reads a 4-byte (32 bit) unsigned integer from the file in big-endian format or NOTHING if no data can be read.
|
|
*int | readu4LSB () |
| Reads a 4-byte (32 bit) unsigned integer from the file in binary little-endian format or NOTHING if no data can be read.
|
|
nothing | setEncoding (*string encoding) |
| Sets the character encoding for the ReadOnlyFile; if called with no argument, the default encoding is set.
|
|
nothing | setEventQueue (Qore::Thread::Queue queue) |
| Sets a Queue object to receive file events.
|
|
nothing | setEventQueue () |
| Removes any Queue object from the ReadOnlyFile object so that file events are no longer added to the Queue.
|
|
int | setPos (int pos=0) |
| Sets the current file position (in bytes from the beginning of the file)
|
|
list | stat () |
| Returns a Stat List about the file's status or throws an exception if any errors occur.
|
|
hash | statvfs () |
| Returns a Filesystem Status Hash about the file's filesystem status or throws an exception if any errors occur.
|
|
The ReadOnlyFile class allows Qore programs to read existing files.
- Restrictions:
- Qore::PO_NO_FILESYSTEM
- Note
- This class is not available with the PO_NO_FILESYSTEM parse option
ReadOnlyFile objects are opened with a specific character encoding, meaning that any string read from the file will be tagged with the file's character encoding. If no character encoding is specified, then the default character encoding is assumed for the file.
This class supports posting read events to a Queue. See I/O Event Handling for more information.
- See Also
- file_events for a list of I/O events raised by this object
- Since
- Qore 0.8.6 this class was split from the Qore::File class and added as a base class of Qore::File
nothing Qore::ReadOnlyFile::open |
( |
string |
path, |
|
|
*string |
encoding |
|
) |
| |
Opens a file in a particular mode; throws an exception on failure.
Opens the file in the mode given; if the ReadOnlyFile was previously open, it is closed first. Optionally the ReadOnlyFile's default character encoding can be specified.
Note that if no encoding is specified, the ReadOnlyFile will be tagged with the character encoding set in the ReadOnlyFile's constructor. Any string data written to the ReadOnlyFile will be converted to the ReadOnlyFile's encoding, and any string data read from the ReadOnlyFile will be automatically tagged with the ReadOnlyFile's encoding.
If an error occurs, a READONLYFILE-OPEN-ERROR
exception is thrown.
- Example:
try {
$f.open($fn, "iso-8859-1");
}
printf(
"%s: %s: %s\n", $fn, $ex.err, $ex.desc);
}
- Events:
- EVENT_OPEN_FILE, EVENT_FILE_OPENED
- Parameters
-
- Exceptions
-
READONLYFILE-OPEN-ERROR | an error occurred opening the file |
ILLEGAL-EXPRESSION | this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set |
*string Qore::ReadOnlyFile::read |
( |
softint |
size, |
|
|
timeout |
timeout_ms = -1 |
|
) |
| |
Reads a certain number of bytes from the ReadOnlyFile within an optional timeout period and returns a string of the data read or NOTHING if no data can be read.
Reads a certain amount of string data from the ReadOnlyFile; the size argument is required. To read binary data, use the ReadOnlyFile::readBinary() method.
Note that the amount of data read from the file may be less than the size given, for example if the file does not contain enough data to fulfill the request. In this case, only the data available in the file is returned.
An optional timeout period in milliseconds can be passed as well (or a relative date/time value may be passed instead of an integer to make the timeout units clear; ex: 25ms
). If a timeout value is passed and the data cannot be read within the timeout period, then a READONLYFILE-READ-TIMEOUT
exception is thrown. If no timeout value is passed or a negative value is given, then the call will never timeout until either the requested amount of data has been read from the ReadOnlyFile or an end-of-file condition has been reached.
- Example:
my *
string $data = $f.read(-1); #
read an entire text file into a variable
- Events:
- EVENT_DATA_READ
- Parameters
-
size | the number of bytes to read of the file, -1 will read the entire file |
timeout_ms | a timeout period with a resolution of milliseconds (a relative date/time value; integer arguments will be assumed to be milliseconds); if not given or negative the call will never time out and will only return when the data has been read |
- Returns
- the data read from the file, returned as a string tagged with the ReadOnlyFile's character encoding. NOTHING is returned if end-of-file is encountered, however, if data has been read before EOF, the data read will be returned and NOTHING (signifying EOF) will be returned on the next call to this method.
- Exceptions
-
READONLYFILE-READ-PARAMETER-ERROR | zero size argument passed |
FILE-READ-ERROR | file is not open |
FILE-READ-TIMEOUT | timeout limit exceeded |
ILLEGAL-EXPRESSION | this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set |
- See Also
- File::readBinary()
*binary Qore::ReadOnlyFile::readBinary |
( |
softint |
size, |
|
|
timeout |
timeout_ms = -1 |
|
) |
| |
Reads a certain number of bytes from the file within an optional timeout period and returns a binary object of the data read or NOTHING if no data can be read.
Reads a certain amount of string data from the file; the size argument is required. To read string data, use the ReadOnlyFile::read() method.
Note that the amount of data read from the file may be less than the size given, for example if the file does not contain enough data to fulfill the request. In this case, only the data available in the file is returned.
An optional timeout period in milliseconds can be passed as well (or a relative date/time value may be passed instead of an integer to make the timeout units clear; ex: 25ms
). If a timeout value is passed and the data cannot be read within the timeout period, then a FILE-READ-TIMEOUT
exception is thrown. If no timeout value is passed or a negative value is given, then the call will never timeout until either the requested amount of data has been read from the file or an end-of-file condition has been reached.
- Events:
- EVENT_DATA_READ
- Example:
my *
binary $data = $f.readBinary(-1); #
read an entire file into a variable
- Parameters
-
size | the number of bytes to read of the file, -1 will read the entire file |
timeout_ms | a timeout period with a resolution of milliseconds (a relative date/time value; integer arguments will be assumed to be milliseconds); if not given or negative the call will never time out and will only return when the data has been read |
- Returns
- the data read from the file, returned as a binary object. NOTHING is returned if end-of-file is encountered, however, if data has been read before EOF, the data read will be returned and NOTHING (signifying EOF) will be returned on the next call to this method.
- Exceptions
-
READONLYFILE-READ-BINARY-PARAMETER-ERROR | zero size argument passed |
FILE-READ-ERROR | file is not open |
FILE-READ-TIMEOUT | timeout limit exceeded |
ILLEGAL-EXPRESSION | this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set |
- See Also
- ReadOnlyFile::read()