Stream oriented I/O class.
Class Stream
Stream class is a common interface for I/O operations. The class itself is to be considered "abstract". It should never be directly instantiated, as factory functions, subclasses and embedding applications will provide fully readied stream objects.
Stream I/O is synchronous, but it's possible to wait for the operation to be nonblocking with the readAvailable() and writeAvailable() methods.
Generally, all the methods in the stream class raise an error in case of I/O failure.
Streams provide also a character encoding layer; readText() and writeText() are meant to decode and encode falcon strings based on character encoding set with setEncoding(). Method as read() and write() are not affected, and seek operations works bytewise regardless the character conversion being used.
| Properties | |
| encoding | Name of the set encoding, if given, for text operations |
| eolMode | Mode of EOL conversion in text operations. |
| Methods | |
| clone | Clone the stream handle. |
| close | Closes the stream. |
| eof | Checks if the last read operation hit the end of the file. |
| errorDescription | Returns a system specific textual description of the last error. |
| flush | Flushes a stream. |
| getBuffering | Returns the size of I/O buffering active on this stream. |
| grab | Grabs binary data from the stream. |
| grabLine | Grabs a line of text encoded data. |
| grabText | Grabs text encoded data from the stream. |
| isOpen | Checks if the stream is currently open. |
| lastError | Return the last system error. |
| lastMoved | Return the amount of data moved by the last operation. |
| read | Reads binary data from the stream. |
| readAvailable | Checks if data can be read, or wait for available data. |
| readLine | Reads a line of text encoded data. |
| readText | Reads text encoded data from the stream. |
| seek | Moves the file pointer on seekable streams. |
| seekCur | Moves the file pointer on seekable streams relative to current position. |
| seekEnd | Moves the file pointer on seekable streams relative to end of file. |
| setBuffering | Set the buffering state of this stream. |
| setEncoding | Set the text encoding and EOL mode for text-based operations. |
| tell | Return the current position in a stream. |
| truncate | Resizes a file. |
| write | Write binary data to a stream. |
| writeAvailable | Checks if data can be written, or wait until it's possible to write. |
| writeText | Write text data to a stream. |
Name of the set encoding, if given, for text operations
Name of the set encoding, if given, for text operations
Mode of EOL conversion in text operations.
Mode of EOL conversion in text operations.
Clone the stream handle.
Stream.clone()
| Return | A new copy of the stream handle. | ||
| Raise |
|
The resulting stream is interchangeable with the original one. From this point on, write and read operations are not reflected on the cloned object, so two stream objects can be effectively used to read and write at different places in the same resource, unless the underlying stream is not seekable (in which case, reads are destructive).
The underlying resource remains open until all the instances of the streams are closed.
Closes the stream.
Stream.close()
All the operations are flushes and system resources are freed. This method is also called automatically at garbage collection, if it has not been called before.
Checks if the last read operation hit the end of the file.
Stream.eof()
| Return | True if file pointer is at EOF. |
Returns true if the last read operation hit the end of file.
Returns a system specific textual description of the last error.
Stream.errorDescription()
| Return | A string describing the system error. |
Returns a system specific textual description of the last error occurred on the stream.
Flushes a stream.
Stream.flush()
Ensures that the operations on the stream are correctly flushed.
Returns the size of I/O buffering active on this stream.
Stream.getBuffering()
| Return | 0 if the stream is unbuffered or a positive number if it is buffered. |
See also: Stream.
Grabs binary data from the stream.
Stream.grab( size )
| size | Maximum size to be read. | ||
| Return | A string containing binary data from the stream. | ||
| Raise |
|
This metod creates a string wide enough to read size bytes, and then tries to fill it with binary data coming from the stream.
Grabs a line of text encoded data.
Stream.grabLine( [size] )
| size | Maximum count of characters to be read before to return anyway. | ||
| Return | A string containing the read line, or oob(0) when the file is over. | ||
| Raise |
|
This function works as Stream.grabText, but if a new line is encountered, the read terminates. Returned string does not contain the EOL sequence.
At EOF, the function returns an oob(0), which in normal tests is translated as "false", and that can be used to build sequences.
Note: An empty line is returned as an empty string. Please, notice that empty lines are returned as empty strings, and that empty strings, in Falcon, assume "false" value when logically evaluated. On loops where not checking for an explicit EOF to be hit in the stream, you will need to check for the returned value to be != 0, or not out of band.
For example, a normal loop may look like:
s = InputStream( "file.txt" )
while (l = s.grabLine()) != 0
> "LINE: ", l
end
s.close()
But it is possible to use the fuinction also in for/in loops:
s = InputStream( "file.txt" ) for line in s.grabLine: > "LINE: ", line s.close()
Or even comprehensions:
s = InputStream( "file.txt" ) lines_in_file = List().comp( s.grabLine ) s.close()
Note: As Stream.readLine recycles a pre-allocated buffer provided as parameter it is more efficient than grabLine, unless you need to store each line for further processing later on.
Grabs text encoded data from the stream.
Stream.grabText( size )
| size | Optionally, a maximum size to be read. | ||
| Return | A string containing the read text. | ||
| Raise |
|
This method reads a string from a stream, eventually parsing the input data through the given character encoding set by the Stream.setEncoding method, and returns it in a newly allocated string.
If the function is successful, the buffer may contain size characters or less if the stream hadn't enough characters to read.
In case of failure, an IoError is raised.
Notice that this function is meant to be used on streams that are known to have available all the required data. For streams that may perform partial updates (i.e. network streams), a combination of binary reads and transcodeFrom calls should be used instead.
Checks if the stream is currently open.
Stream.isOpen()
| Return | True if the file is open. |
Return true if the stream is currently open.
Return the last system error.
Stream.lastError()
| Return | An error code. |
Returns a system specific low level error code for last failed I/O operation on this stream, or zero if the last operation was succesful.
Return the amount of data moved by the last operation.
Stream.lastMoved()
| Return | An amount of bytes. |
Returns the amount of bytes moved by the last write or read operation, in bytes. This may differ from the count of characters written or read by text-oriented functions.
Reads binary data from the stream.
Stream.read( buffer, [size] )
| buffer | A string or MemBuf that will be filled with read data. | ||
| size | Optionally, a maximum size to be read. | ||
| Return | Amount of data actually read. | ||
| Raise |
|
This method uses an already existing and pre-allocated string or Memory Buffer, filling it with at maximum size bytes. If size is not provided, the method tries to read enough data to fill the given buffer. A string may be pre-allocated with the strBuffer function.
If size is provided but it's larger than the available space in the given buffer, it is ignored. If there isn't any available space in the target buffer, a ParamError is raised.
If the buffer is a string, each read fills the string from the beginning. If it is a MemBuffer, the space between MemoryBuffer.limit and len is filled. This allow for partial reads in slow (i.e. network) streams.
Checks if data can be read, or wait for available data.
Stream.readAvailable( [seconds] )
| seconds | Maximum wait in seconds and fraction (defaults to infinite). | ||||
| Return | True if data is available, false otherwise. | ||||
| Raise |
|
This function checks if data is available on a stream to be read immediately, or if it becomes available during a determined time period. The seconds parameter may be set to zero to perform just a check, or to a positive value to wait for incoming data. If the parameter is not given, or if it's set to a negative value, the wait will be infinite.
A read after readAvailable has returned succesfully is granted not to be blocking (unless another coroutine or thread reads data from the same stream in the meanwhile). Performing a read after that readAvailable has returned false will probably block for an undefined amount of time.
This method complies with the Falcon Virtual Machine Preemptibility of the Virtual Machine.
Reads a line of text encoded data.
Stream.readLine( buffer, [size] )
| buffer | A string that will be filled with read data. | ||
| size | Maximum count of characters to be read before to return anyway. | ||
| Return | True if a line was read, false otherwise. | ||
| Raise |
|
This function works as Stream.readText, but if a new line is encountered, the read terminates. Returned string does not contain the EOL sequence. Also, the returned string may be empty if the line was empty.
At EOF, the function returns false. Example:
s = InputStream( "file.txt" ) line = strBuffer(4096) while s.readLine( line ): > "LINE: ", line s.close()
Note: It is possible to obtain a newly allocated line instead of having to provide a target buffer through the Stream.grabLine method.
See also: Stream.
Reads text encoded data from the stream.
Stream.readText( buffer, [size] )
| buffer | A string that will be filled with read data. | ||
| size | Optionally, a maximum size to be read. | ||
| Return | Amount of data actually read. | ||
| Raise |
|
This method reads a string from a stream, eventually parsing the input data through the given character encoding set by the Stream.setEncoding method. The number of bytes actually read may vary depending on the decoding rules.
If the size parameter is given, the function will try to read at maximum size characters, enlarging the string if there isn't enough room for the operation. If it is not given, the current allocated memory of buffer will be used instead.
Note: This differ from Stream.read, where the buffer is never grown, even when it is a string.
If the function is successful, the buffer may contain size characters or less if the stream hadn't enough characters to read.
In case of failure, an IoError is raised.
Notice that this function is meant to be used on streams that are known to have available all the required data. For streams that may perform partial updates (i.e. network streams), a combination of binary reads and transcodeFrom calls should be used instead.
Moves the file pointer on seekable streams.
Stream.seek( position )
| position | Position in the stream to seek. | ||
| Return | Position in the stream after seek. | ||
| Raise |
|
Changes the position in the stream from which the next read/write operation will be performed. The position is relative from the start of the stream. If the stream does not support seeking, an IoError is raised; if the position is greater than the stream size, the pointer is set to the end of the file. On success, it returns the actual position in the file.
Moves the file pointer on seekable streams relative to current position.
Stream.seekCur( position )
| position | Position in the stream to seek. | ||
| Return | Position in the stream after seek. | ||
| Raise |
|
Changes the position in the stream from which the next read/write operation will be performed. The position is relative from the current position in the stream, a negative number meaning "backward", and a positive meaning "forward". If the stream does not support seeking, an IoError is raised. If the operation would move the pointer past the end of the file size, the pointer is set to the end; if it would move the pointer before the beginning, it is moved to the beginning. On success, the function returns the position where the pointer has been moved.
Moves the file pointer on seekable streams relative to end of file.
Stream.seekEnd( position )
| position | Position in the stream to seek. | ||
| Return | Position in the stream after seek. | ||
| Raise |
|
Changes the position in the stream from which the next read/write operation will be performed. The position is relative from the end of the stream. If the stream does not support seeking, an error is raised. If the operation would move the pointer before the beginning, the pointer is set to the file begin. On success, the function returns the position where the pointer has been moved. Use seekEnd( 0 ) to move the pointer to the end of the stream.
On success, the function returns the position where the pointer has been moved.
Set the buffering state of this stream.
Stream.setBuffering( size )
| size | Buffering size; pass 0 to disable. |
This method activates or disactivates I/O buffering on this stream.
When buffering is active, every read/write operation is first cached in memory, provided the size of the memory buffer is wide enough to store the data being written or to provide the data being read.
Seek operations invalidate the buffer, that is automatically flushed when necessary.
Local filesystem providers and standard I/O streams are buffered by default; other streams may be created with buffering enabled or not, buffered or not depending on their and common usage patterns (network streams are usually unbuffered).
You may want to disable buffering when preparing binary data in memory, or parsing big chunks of binary data at once via block (MemBuf) read/write operations. However, notice that buffering is always optimizing when chunk width is 1/4 of the buffer size or less, and causes only minor overhead in the other cases.
Set the text encoding and EOL mode for text-based operations.
Stream.setEncoding( encoding, [EOLMode] )
| encoding | Name of the encoding that is used for the stream. |
| EOLMode | How to treat end of line indicators. |
This method sets an encoding that will affect readText() and writeText() methods. Provided encodings are:
As EOL manipulation is also part of the text operations, this function allows to chose how to deal with EOL characters stored in Falcon strings when writing data and how to parse incoming EOL. Available values are:
If not provided, this parameter defaults to SYSTEM_DETECT.
If the given encoding is unknown, a ParamError is raised.
Return the current position in a stream.
Stream.tell()
| Return | Position in the stream. | ||
| Raise |
|
Returns the current read/write position in the stream. If the underlying stream does not support seeking, the operation raises an IoError.
Resizes a file.
Stream.truncate( [position] )
| position | If given, truncate at given position. | ||
| Return | Position in the stream. | ||
| Raise |
|
Truncate stream at current position, or if a position parameter is given, truncate the file at given position relative from file start. To empty a file, open it and then truncate it, or pass 0 as parameter.
If the underlying stream does not support seek operation, this function will raise an error.
Write binary data to a stream.
Stream.write( buffer, [size],[start] )
| buffer | A string or a MemBuf containing the data to be written. | ||
| size | Number of bytes to be written. | ||
| start | A position from where to start writing. | ||
| Return | Amount of data actually written. | ||
| Raise |
|
Writes bytes from a buffer on the stream. The write operation is synchronous, and will block the VM until the stream has completed the write; however, the stream may complete only partially the operation. The number of bytes actually written on the stream is returned.
When the output buffer is a string, a size parameter can be given; otherwise the whole binary contents of the stream are written. A start position may optionally be given too; this allows to iterate through writes and send part of the data that coulden't be send previously without extracting substrings or copying the memory buffers.
MemBuf items can participate to stream binary writes through their internal position pointers. The buffer is written from MemoryBuffer.position up to MemoryBuffer.limit, and upon completion MemoryBuffer.position is advanced accordingly to the number of bytes effectively stored on the stream. When a MemBuf is used, size and start parameters are ignored.
Checks if data can be written, or wait until it's possible to write.
Stream.writeAvailable( [seconds] )
| seconds | Maximum wait in seconds and fraction (defaults to infinite). | ||||
| Return | True if data can be written, false otherwise. | ||||
| Raise |
|
This function checks if the stream is available for immediate write, or if it becomes available during a determined time period. The seconds parameter may be set to zero to perform just a check, or to a positive value to wait for the line being cleared. If the seconds is not given, or if it's set to a negative value, the wait will be infinite.
A write operation after writeAvailable has returned succesfully is granted not to be blocking (unless another coroutine or thread writes data to the same stream in the meanwhile). Performing a read after that readAvailable has returned false will probably block for an undefined amount of time.
This method complies with the Falcon Virtual Machine Preemptibility of the Virtual Machine.
Write text data to a stream.
Stream.writeText( buffer, [start],[end] )
| buffer | A string containing the text to be written. | ||
| start | The character count from which to start writing data. | ||
| end | The position of the last character to write. | ||
| Raise |
|
Writes a string to a stream using the character encoding set with Stream.setEncoding method. The begin and end optional parameters can be provided to write a part of a wide string without having to create a temporary substring.
In case of failure, an IoError is raised.