FSFile

Extension of NSFileHandle with methods convenient for text-file handling

Superclass: NSFileHandle
Declared In: FSFile.h

Discussion

FSFile is a subclass of NSFileHandle that provides text-file handling methods similar to other scripting languages. To open a file, use FSFile's open: method, which uses the same mode specifiers as Perl's open function. You can then use readln, print:, println:, and printf:withValues: to perform input and output.

FSFile is a subclass of NSFileHandle, so the more fine-grained methods of that class for non-text files are also available, such as seeking through the file and calculating offsets. It is important to note that FSFile keeps its own buffer for readln and related methods, so mixing calls to readln and other NSFileHandle methods like seekToFileOffset: or readDataOfLength: will produce unpredictable results and will probably result in data being skipped. If you wish to switch between line- and offset-oriented modes, use the FSFile method reset. This method will clear all buffers and set the file pointer back to 0.

Methods

+fromNSFileHandle:
-newln
+open:
+open:mode:
-print:
-printf:withValues:
-println
-println:
-readlines
-readlinesWithSeparator:
-readln
-readlnWithSeparator:
-reset

fromNSFileHandle:

+ (FSFile*) fromNSFileHandle:(NSFileHandle*)handle;

Discussion

Creates an FSFile object that wraps an existing NSFileHandle. Use this method if you have created a non-file NSFileHandle - such as one end of a pipe - you can use this method to create an FSFile that supports print and readln.

newln

- (void) newln;

Discussion

Prints a single newline (ASCII 13) character to the file.

open:

+ (FSFile*) open:(NSString*)path;

Discussion

Equivalent to open:path mode:@"" Creates an FSFile object that wraps an existing NSFileHandle. Use this method if you have created a non-file NSFileHandle - such as one end of a pipe - you can use this method to create an FSFile that supports print and readln.

open:mode:

+ (FSFile*) open:(NSString*)path mode:(NSString*)mode;

Discussion

Opens a file for use. mode should be one of the following Perl-style mode strings:


Mode	Read	Write	Append to existing data	Create file if not existing	Throw error if file does not exist
<	Yes	No		No	Yes
>	No	Yes	No	Yes	No
>>	No	Yes	Yes	Yes	No
<+	Yes	Yes		No	Yes
>+	Yes	Yes	No	Yes	No
<<+	Yes	Yes	Yes	Yes	No

If mode is not one of the above strings, the method will throw an exception.

print:

- (void) print:(NSObject*)string;

Discussion

Prints an object (typically a string) to a file. If the object is not an NSString, the description will be used to obtain a string representation. Using this method on a read-only file (such as standard input) will throw an error.

printf:withValues:

- (void) printf:(NSString*)format withValues:(NSArray*)values;

Discussion

Equivalent to print:(format sprintf:values).

println

- (void) println;

Discussion

Prints a blank line.

println:

- (void) println:(NSObject*)string;

Parameters

string: The object to print. If the object is not an NSString, it will be sent a -description message to produce a printable string.

Discussion

Equivalent to print:, but also prints a newline character after printing the string (similar to Java's PrintStream.println method).

readlines

- (NSArray*) readlines;

Discussion

Equivalent to readlinesWithSeparator:'\n'.

readlinesWithSeparator:

- (NSArray*) readlinesWithSeparator:(NSString*)separator;

Discussion

Reads in all the lines of the file and returns them in an array. The returned array may be quite large, depending on the size of the file, so use this method with caution.

The F-Script code lines := file readLines. is equivalent to the Perl code @lines = split "\n", <FILE>;.

readln

- (NSString*) readln;

Discussion

Equivalent to readlnWithSeparator:'\n'.

readlnWithSeparator:

- (NSString*) readlnWithSeparator:(NSString*) separator;

Discussion

Reads in data until either the specified separator (which can be a single character or a string) is encountered, chops off the separator, and returns the read data as a string. Plain readln uses a newline character as a separator; if you need to specify a custom line break (such as when reading DOS/Windows-formatted text files) use readlnWithSeparator.

readlnWithSeparator: will return nil if there is no more data left in the file, so you can use it in loops like these:

file := NSFile open:'.....'.
line := nil.
[ line := file readln. line == nil ] whileTrue:[
 obj doSomethingWith:line.
]

 
file2 := FSFile open:'....'.
sys foreach:[ file readln ] do:[ :line |
 out println:line.
].

reset

- (void) reset;

Discussion

Clears all line-oriented buffers and resets the file pointer back to zero. If, for some reason, you want to stop using the line-oriented methods of FSFile like readln, use this method before starting to use the NSFileHandle byte-oriented methods.

This method will throw an exception if the filehandle does not support seeking.