Function and classes supporting OS and environment.
This group of functions and classes is meant to provide OS and environmental basic support to Falcon scripts.
Creates a stream for input and output.
IOStream( fileName, [createMode],[shareMode] )
| fileName | A relative or absolute path to a file to be opened for input |
| createMode | If given, the ownership of the created file. |
| shareMode | If given, the share mode. |
| Return | A new valid Stream instance on success. |
If the function is successful, it creates the given fileName and returns a valid stream object by which the underlying file may be read. If an already existing file name is given, then the file is truncated and its access right are updated. Calling read methods on the returned object will fail, raising an error.
If the file can be created, its sharing mode can be controlled by providing a shareMode parameter. In case the shareMode is not given, then the maximum publicity is used.
If the file cannot be created, an error containing a valid fsError code is raised.
See Stream factory functions for a description of the shared modes.
Open a system file for reading.
InputStream( fileName, [shareMode] )
| fileName | A relative or absolute path to a file to be opened for input |
| shareMode | If given, the share mode. |
| Return | A new valid Stream instance on success. |
If the function is successful, it opens the given fileName and returns a valid stream object by which the underlying file may be read. Calling write methods on the returned object will fail, raising an error.
If the optional share parameter is not given, the maximum share publicity available on the system will be used.
If the file cannot be open, an error containing a valid fsError code is raised.
See Stream factory functions for a description of the shared modes.
Creates a stream for output only.
OutputStream( fileName, [createMode],[shareMode] )
| fileName | A relative or absolute path to a file to be opened for input |
| createMode | If given, the ownership of the created file. |
| shareMode | If given, the share mode. |
| Return | A new valid Stream instance on success. |
If the function is successful, it creates the given fileName and returns a valid stream object by which the underlying file may be read. If an already existing file name is given, then the file is truncated and its access right are updated. Calling read methods on the returned object will fail, raising an error.
If the file can be created, its sharing mode can be controlled by providing a shareMode parameter. In case the shareMode is not given, then the maximum publicity is used.
If the file cannot be created, an error containing a valid fsError code is raised.
See Stream factory functions for a description of the shared modes.
Requires immediate termination of the program.
exit( value )
| value | an item representing VM exit code. |
The VM execution will be interrupted, with normal state, and the item will be passed in the A register of the VM, where embedding application expects to receive the exit value. Semantic of the exit value will vary depending on the embedding application. The Falcon command line tools (and so, stand alone scripts) will pass this return value to the system if it is an integer, else they will terminate passing 0 to the system.
This function terminates the VM also when there are more coroutines running.
Copies a whole file from one position to another.
fileCopy( source, dest )
| source | Source file to be copied | ||
| dest | Destination file. | ||
| Raise |
|
This function performs a file copy. The function is still experimental and needs addition of VM interruption protocol compliancy, as well as the possibility to preserve or change the system attributes in the target copy.
Return a dictionary containing all the environment variables.
getEnviron()
| Return | A dictionary where each key is an environment variable. |
Get environment variable value.
getenv( varName )
| varName | Environment variable name (as a string) |
| Return | The value of the environment variable or nil if it is not present. |
This function returns a string containing the value set for the given environment variable by the operating system before starting the Falcon process or or by a previous call to setenv(). If the given variable name is not declared, the function will return nil.
On some systems (e.g. MS-Windows), setting a variable to an empty string is equivalent to unsetting it, so getenv() will never return an empty string. On other systems, environment variables may be set to empty strings, that may be returned by getenv().
Set environment variable value.
setenv( varName, value )
| varName | Environment variable name (as a string) | ||
| value | a value for the given variable. | ||
| Raise |
|
This function sets the given value for the given environment variable. The varName parameter must be a string, while value may be any Falcon value. If the value is not a string, it will be converted using the toString() function.
If the variable was previously set to a different value, its value is changed; if it doesn't existed, it is created.
The function may fail if the system cannot perform the operation; this may happen if the space that the system reserves for environment variables is exhausted. In this case, the function raises an error.
Creates an object mapped to the standard error of the Virtual Machine.
stdErr()
| Return | A new valid Stream instance on success. |
The returned stream maps output operations on the standard error stream of the virtual machine hosting the script.
The returned stream is a clone of the stream used by the Virtual Machine as standard error stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder.
As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function.
Read operations will fail raising an I/O error.
Creates a stream that interfaces the standard error stream of the host process.
stdErrRaw()
| Return | A new valid Stream instance on success. |
The returned stream maps output operations on the standard error stream of the process hosting the script. The returned stream is bound directly with the process error stream, without any automatic transcoding applied. Stream.writeText will write the text as stream of bytes to the stream, unless Stream.setEncoding is explicitly called on the returned instance.
Closing this stream has the effect to close the standard error stream of the process running the script (if the operation is allowed by the embedding application). Applications reading from the error stream of the script will be notified that the stream has been closed, and won't be left pending in reading this stream.
The stream is write only. Read operations will cause an I/O to be raised.
Creates an object mapped to the standard input of the Virtual Machine.
stdIn()
| Return | A new valid Stream instance on success. |
The returned read-only stream is mapped to the standard input of the virtual machine hosting the script. Read operations will return the characters from the input stream as they are available. The readAvailable() method of the returned stream will indicate if read operations may block. Calling the read() method will block until some character can be read, or will fill the given buffer up the amount of currently available characters.
The returned stream is a clone of the stream used by the Virtual Machine as standard input stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder.
As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function.
Read operations will fail raising an I/O error.
Creates a stream that interfaces the standard input stream of the host process.
stdInRaw()
| Return | A new valid Stream instance on success. |
The returned stream maps input operations on the standard input of the process hosting the script. The returned stream is bound directly with the process input stream, without any automatic transcoding applied. Stream.readText will read the text as stream of binary data coming from the stream, unless Stream.setEncoding is explicitly called on the returned instance.
Closing this stream has the effect to close the standard input stream of the process running the script (if the operation is allowed by the embedding application). Applications trying to write data to the script process will be notified that the script has closed the stream and is not willing to receive data anymore.
The stream is read only. Write operations will cause an I/O to be raised.
Creates an object mapped to the standard output of the Virtual Machine.
stdOut()
| Return | A new valid Stream instance on success. |
The returned stream maps output operations on the standard output stream of the process hosting the script.
The returned stream is a clone of the stream used by the Virtual Machine as standard output stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder.
As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function.
Read operations will fail raising an I/O error.
Creates a stream that interfaces the standard output stream of the host process.
stdOutRaw()
| Return | A new valid Stream instance on success. |
The returned stream maps output operations on the standard output stream of the process hosting the script. The returned stream is bound directly with the process output, without any automatic transcoding applied. Stream.writeText will write the text as stream of bytes to the stream, unless Stream.setEncoding is explicitly called on the returned instance.
Closing this stream has the effect to close the standard output of the process running the script (if the operation is allowed by the embedding application). Print functions, fast print operations, default error reporting and so on will be unavailable from this point on.
Applications reading from the output stream of the process running the scripts, in example, piped applications, will recognize that the script has completed its output, and will disconnect immediately, while the script may continue to run.
The stream is write only. Read operations will cause an IoError to be raised.
Clear environment variable value.
unsetenv( varName )
| varName | Environment variable name (as a string) |
This function removes a given variable setting, causing subsequents getenv( varName ) to return nil.