Files
From RevaWiki
Contents |
Files & File Handling
Let's explain the Reva words that deal with files and file handling.
To know which words deal with file handling, use the help facility calling file-io to get the Reva words related to file & file handling.
ok> help file-io
file-io
Context: meta
Source in: src/reva.f
The file-io words supported by Reva are:
creat open/r open/rw read write fsize seek tell rename
delete stat mtime
SEE ALSO: (seek) close creat delete fsize ioerr mtime open/r open/rw read rename
seek stat tell write
ok>
ioerr
This is a variable that holds the result of the last i/o operation. Since this is a variable, we should use @ to get the contents.
... any file operation... ok> .s (0) ok> ioerr @ . 0 ok>
0 is the answer when a successful i/o has been done.
File handling
These words are used to create, remove o rename a file.
creat
According to the help facility, creat does create a new file if it doesn't exist.
creat ( a n -- fileid ) 'forth
Context: ~io
Source in: src/core{lin,win}.asm
Create a new file for reading and writing.
Warning!!!... Be careful to type creat and not create that does a very different thing!. Create is used to create a new entry in the dictionary and has nothing to do with files!.
The way to use creat is:
ok> " testfile.txt" creat ok> .s (1) 2024 ok> constant myfile ok> .s (0) ok> myfile close ok> ioerr @ . 0 ok> .s (0) ok>
And the result is a file of zero length in the directory where Reva was started. Notice that creat lets the file open for reading and writing, so if we don't want to do anything else with it, we have to close it.
C:\reva>dir testfile.txt
Volume in drive C has no label.
Volume Serial Number is 5CC0-9DEE
Directory of C:\reva
25-Apr-07 06:05 PM 0 testfile.txt
1 File(s) 0 bytes
0 Dir(s) 2.331.078.656 bytes free
C:\reva>
delete
Delete does remove the filename from the current directory. If we look into the help facility
delete ( a n -- ) 'forth
Context: ~io
Source in: src/reva.f
Delete the named file
Let's erase our test file:
ok> " testfile.txt" delete ok> ioerr @ . 0 ok>
rename
Rename does allow for a name change. The file should be an existing one, otherwise we get an error.
rename ( a1 n1 a2 n2 -- ) 'forth
Context: ~io
Source in: src/reva.f
Rename the file named "a1,n1" to the new name "a2,n2"
So, let's try to rename our deleted test file to see what happens
ok> " testfile.txt" " newfile.txt" rename ok> ioerr @ . -1 ok>
The contents of ioerr does show that a problem has happened, in this case a reference to a non existing file.
File contents
To use a file, we have to open it first and to close it after use, as usual To do so, we got three words:
open/r
We can take a glimpse to the help facility:
ok> help open/r
open/r ( a n -- h ) 'forth
Context: ~io
Source in: src/core{lin,win}.asm
Open the named file for reading. Sets 'ioerr' appropriately to
indicate failure.
Will fail if the file does not exist or if the user has
insufficient privileges to access it. In these cases, the
value of 'h' is indeterminate.
Let's try to open a file:
ok> .s (0) ok> " C:/julio/bacardi.txt" ok> .s (2) 6275521 20
Now we have in the stack the ( a n -- ) part (the string containing the name) so lets open it:
ok> open/r ok> .s (1) 28 ok>
Now we have a fileid in the stack. It's worth to save it as a constant, because it will save us to type @ to get the contents...
ok> .s (1) 28 ok> ok> constant myfile ok> .s (0) ok> myfile .s (1) 28 ok>
At any time we type "myfile" we'll get the fileid onto the stack. Convenient!.
open/rw
The same as in open/r, this word opens the file, but this time writing is allowed.
close
As usual, we look at the help facility
ok> help close
close ( fileid -- ) 'forth
Context: ~io
Source in: src/core{lin,win}.asm
Close "fileid" previously opened with 'open/r' 'open/rw' or
'creat'.
In our case, to close our opened file above:
ok> .s (0) ok> ok> myfile .s (1) 28 ok> close ok> ioerr @ ok> .s (1) 0 ok>
Hopefully everything was ok.
read and write
According to the help facility
read ( a n fileid - n2 ) 'forth
Context: ~io
Source in: src/core{lin,win}.asm
Reads from 'fileid' into the buffer 'a n'. 'n2' is the number of
bytes read.
write ( a n fileid -- ) 'forth
Context: ~io
Source in: src/core{lin,win}.asm
Write 'n' bytes from address 'a' to 'fileid'.
read and write are similar but read returns the number of bytes read. Let's start by allocating a 128 byte buffer
ok> 128 allocate ok> .s (1) 1638472 ok> constant buffer ok> .s (0) ok> buffer .s (1) 1638472 ok>
Once we have a buffer where read data in, we proceed to open the file and do the reading.
ok> " f:/reva/README.txt" open/r
ok> .s
(1) 0
ok> constant myfile
ok> buffer 128 myfile read
ok> ioerr @ .
0
ok> buffer 128 type
Reva 6.1 - 23 Oct 2006
by Ron Aaron (ron@ronware.org)
This document is intended as a "first ste
ok>
Does this text sound familial to you?...
Writing needs the same procedures, only the sense is reversed. Data flows from the buffer to disk.
tell
tell and seek are used to move a "file pointer" along the file. Subsequent read statements will read from the file pointer on. Whilst seek moves the pointer, tell tells the pointer position.
tell ( fileid -- n ) 'forth
Context: ~io
Source in: src/reva.f
Report on the position in 'fileid' relative to the beginning of
the file
Let's check where our file pointer is
ok> myfile tell ok> .s (1) 128 ok>
that is 128 as expected (the file counter starts from zero).
seek
seek ( n fileid -- ) 'forth
Context: ~io
Source in: src/reva.f
Move current position of 'fileid' to n bytes from the beginning of
the file
Lets move then then the file pointer 64 bytes ahead and let's read from there:
ok> 64 myfile seek ok> ioerr @ . 0 ok> buffer 128 myfile read ok> buffer 128 type ron (ron@ronware.org) This document is intended as a "first step" to get you up and running Reva. The complete documentation is ok>
As we can see, the file pointer has been bumped 64 bytes ahead. To move the file pointer back, we should provide a negative number.
(seek)
(seek) is a building block used to construct seek.
(seek) ( whence offset handle -- ) 'forth
Context: ~io
Source in: src/reva.f
Used to implement "seek"; this word is similar to the Unix "fseek"
word, and has the same semantics. "whence" is one of:
0 - SEEK_SET, from the beginning of the file
1 - SEEK_CUR, relative to the current position, or
2 - SEEK_END, from the end of the file
File Information
stat
Stat gives back the file attributes of a file.
stat ( a n -- n ) 'forth
Context: ~io
Source in: src/reva.f
Get the permissions (file attributes) of the named file.
ok> " newfile.txt" stat ok> ioerr @ . 0 ok> .s (1) 32 ok>
The meaning of the attributes depends on the Operating System Reva is running on.
mtime
This word shows the "modified time" for the file. According to the help facility:
ok> help mtime mtime ( a n -- n ) 'forth Context: ~io Source in: src/reva.f Gets the last-modified time of the named file, in Unix "seconds since 1/1/1970" format. ok>
Let's try it: we need date/util to translate the unix date to human
ok> needs date/util ok> ~util ok> .s (0) ok> " C:/julio/bacardi.txt" mtime ok> .s (1) 1175445505 ok> unix>time&date ok> .s (6) 25 38 16 30 3 2007 ok>
We can conclude that the file was last modified by 30th March 2007, at 16:38:25
