FSSystem(FSSystemUtility) |
The FSSystemUtility category adds methods to F-Script's builtin sys object that are useful for command-line scripts.
Extends Class: FSSystem
Declared In: FSSystemUtility.h
The FSSystemUtility category adds methods to F-Script's System class, making them effectively global functions, as there is only one single sys object. Most of the methods deal with importing other files as libraries.
addLibrary: |
- (void) addLibrary:(NSString*)libraryLocation;
Add another library to the end of the list of directories searched by import:.
args |
- (NSArray*) args;
Returns an array of command-line arguments to the script, or nil if the interpreter is running in interactive mode.
err |
- (FSFile*) err;
Returns an instance of FSFile representing standard error, like System.err in Java.
exec:args: |
- (NSString*) exec:(NSString*)command args:(NSArray*)args;
Equivalent to sys exec:'commandName' args:{ ... } input:nil..
exec:args:input: |
- (NSString*) exec:(NSString*)command args:(NSArray*)args input:(NSString*)input;
command PATH environment variable, e.g. ls will be translated to /bin/ls. If the program cannot be found in your PATH, the method will throw an exception.args input Runs a program and returns its output as a string, similar to Perl's backtick operator. The following Perl code:
$output = `myProgram arg1 arg2 arg3`;
can be implemented in F-Script as:
output := sys exec:'myProgram' args:{'arg1', 'arg2', 'arg3'} input:nil.
will search your PATH environment variable to find the program if you do not specify an absolute path. If you specify an absolute program that does not exist, or a relative path that cannot be found, the method will throw an exception.
Unlike the backticks operator, exec:args:input: does not perform shell interpolation or redirection. If you want to use the shell to interpret variables or redirect streams, use the method execAsShell:args:input:.
exec:args:input: does not return the program's exit status. If you want the exit status instead of the output, use execNoOutput:args:input:. If you want both, use the Foundation class NSTask, which exec:args:input: is built on.
IMIPORTANT NOTE: as of fscript 1.5 and Mac OS X 10.4.10, there is a bug in the NSTask class of Apple's Foundation Kit, on which the exec: methods rely. If you call more exec: many times during the execution of a script (over 200 or so), the method will throw an exception relating to an NSDictionary null-key violation. This is a bug in Apple's code; they have been notified, and hopefully it will be fixed in the future. For the moment, try to limit the number of exec: calls you make in a single script.
execNoOutput:args: |
- (int) execNoOutput:(NSString*)command args:(NSArray*)args;
Similar to exec:args:input:, runs a program and returns its exit status, rather than its output.
execShell: |
- (NSString*) execShell:(NSString*)command;
This method is an exact duplicate for Perl's backticks operator. The command will be passed to your current shell (as defined by the SHELL environment variable) for processing, and the output (if any) will be returned. The shell will handle command location, variable interpolation, and I/O redirection, with all the flexibility and danger that implies.
exit |
- (void) exit;
Immediately exits the program with status 0.
exitWithStatus: |
- (void) exitWithStatus:(NSNumber*)status;
Immediately exits the program with the given status indicator. Typically, non-zero exit statuses are used to indicate error conditions to parent processes such as shell scripts.
help |
- (FSToolHelp*) help;
Returns a singleton instance of FSToolHelp, which contains information about the current environment. The help object has methods version, frameworks, import, and quit.
import: |
- (void) import:(NSString*)fileName;
Loads and runs another F-Script file. This method is intended to be used with files that implement classes with FSClass, or for large programs that can be logically separated into multiple files. The main script can load all the appropriate libraries, pull in the supporting files, and then start the program's processing.
fileName can omit the trailing ".fs", and import: will add it; sys import:'MyClass'. is thus equivalent to sys import:'MyClass.fs'.. import: will search the following directories, in order, for the specified file:
FSCRIPT_LIB exists, it is considered to be a colon-separated list of additional directories, in the manner of PATH-type variables
If the file cannot be found or contains syntax errors, import: will throw an exception.
import: expects that the final value of the file will be nil. If the library encounters any problems during initialization, it should return a suitable error message instead, which import: will throw as an exception. For example, if a library file expects a particular environment variable to be set and it is not, it should return the string "Environment variable FOO not set".
The file will be executed in the same interpreter as the original program, so any variable declarations will go into the global namespace, possibly clobbering any existing objects there. Care should be taken to only declare objects and classes that are documented for the user. Internal library variables (e.g. class data) should be prefixed with "_" or another suitable indicator.
import: caches the modification times of loaded files, so a second invocation to load the same file will only reparse it if it has changed since it was first loaded. This makes the importation of library files effectively idempotent. However, if you are working on a script and have an interpreter prompt open, you can repeatedly call sys import:filename. to reload the file as you tweak your code.
in |
- (FSFile*) in;
Returns an instance of FSFile representing standard input, like System.in in Java.
libraries |
- (NSArray*) libraries;
Returns the list of library directories used by import:.
out |
- (FSFile*) out;
Returns an instance of FSFile representing standard output, like System.out in Java.
scriptName |
- (NSString*) scriptName;
Returns the name of the currently executing script, or nil if the interpreter is running in interactive mode.
© Andrew Weinrich Last Updated: Wednesday, October 15, 2008