Raven Manual - File Access

Quick 'n Dirty

The majority of file handling done in the average script is not complicated. Often you just want to generate some data and write it to a file all in one go, or perhaps read an entire text file into memory, work on it, and then discard it. A lot of people simply never bother with reading files a line at a time, or messing about with file pointers and handles.

Therefore at the simplest level, raven caters to this common quick and dirty methodology.

The word read ( filename -- string ) reads an entire file into memory as a string.

'myfile.txt' read as $string 

The word write ( string filename -- ) writes a string to mass storage as a file.

$string 'myfile.txt' write 

The word status ( filename -- hash ) returns a hash array of file parameters.

'myfile.txt' status as $stat 

The words exists ( filename -- flag ) and delete ( filename -- ) are hopefully obvious.

'myfile.txt' delete 
 
'myfile.txt' exists 
if   'oops, delete failed' 
else 'hooray!' 
print 

Resources

For the times when file access needs to be finer and more complex, resources come ino play, allowing files to be treated in a more traditional fashion by providing persistent and incremental file access.

The word open ( descriptor -- handle ) controls opening and creating of files depending on the format of the descriptor (actually a form of URL). It returns a resource handle which may be used to identify and access the file.

'file://r:/home/me/myfile.txt' open as $handle 

In the resource descriptor string above:

• file:// says the resource is a file (as opposed to a database, or a socket, etc).
• r is the access flags similar to those passed to libc's fopen, for example w+ would have meant read/write. Note the trailing : (colon) to separate the flags from the rest of the string.
• /home/me/myfile.txt is the actual path to the file.

Introduced above, read and write are smart enough to know the difference between a string file name and a resource handle. They will both operate on an open file resource exactly as they would on a file name, providing the correct access flags have been used to open the resource.

$handle read as $content 
 
'file://w+:/home/me/myfile2.txt' open as $handle2 
'hello world' $handle2 write 

Handles allow files to be read a line ( handle -- ) at a time.

'file://r:/home/me/myfile3.txt' open as $handle 
'line 1 is: ' print $handle line print 
'line 2 is: ' print $handle line print 
'line 3 is: ' print $handle line print 

Handles allow files to be read in arbitrary chunks by supplying an additional integer argument to read ( handle chunk -- data ).

'file://r:/home/me/myfile4.txt' open as $handle 
'1024 byte chunk 1 is: ' print $handle 1024 read print 
'1024 byte chunk 2 is: ' print $handle 1024 read print 
'1024 byte chunk 3 is: ' print $handle 1024 read print 

The words seek and tell allow a file resource handle's pointer to be adjusted and referenced.

'file://r:/home/me/myfile5.txt' open as $handle 
$handle tell "%d\n" format print 
$handle 1024 seek 
$handle tell "%d\n" format print 

0 
1024 

Finally, all resources must be closed with close ( handle -- ) when finished with.

$handle close 
$handle2 close