212 lines
8.4 KiB
HTML
212 lines
8.4 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
|
<title>.</title>
|
|
<style type="text/css">
|
|
|
|
* { color: #000; background: #fff; max-width: 700px; }
|
|
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
|
white-space: pre; display: block; width: 100%; }
|
|
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
|
.codeblock {
|
|
background: #dedede; color: #111; font-family: monospace;
|
|
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
|
padding: 7px;
|
|
display: block;
|
|
}
|
|
|
|
.indentedlist { margin-left: 2em; color: #000; }
|
|
|
|
span { white-space: pre; }
|
|
.text { color: #000; white-space: pre; background: #dedede; }
|
|
.colon { color: #000; background: #dedede; }
|
|
.note { color: #000; background: #dedede; }
|
|
.str { color: #000; text-decoration: underline; background: #dedede; }
|
|
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
|
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
|
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
|
.fetch { color: #000; font-style: italic; background: #dedede; }
|
|
.store { color: #000; font-style: italic; background: #dedede; }
|
|
.char { color: #000; background: #dedede; }
|
|
.inst { color: #000; background: #dedede; }
|
|
.defer { color: #000; background: #dedede; }
|
|
.imm { color: #000; font-weight: bold; background: #dedede; }
|
|
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
|
|
|
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
|
|
|
.h1, .h2, .h3, .h4 { white-space: normal; }
|
|
.h1 { font-size: 125%; }
|
|
.h2 { font-size: 120%; }
|
|
.h3 { font-size: 115%; }
|
|
.h4 { font-size: 110%; }
|
|
.hr { display: block; height: 2px; background: #000000; }
|
|
</style>
|
|
</head><body>
|
|
<p><span class="h1">Working With Files</span>
|
|
<br/><br/>
|
|
On Unix and Windows systems RETRO provides a set of words for
|
|
working with files. As a pragmatic choice these are mostly
|
|
modeled after the file functions in libc.
|
|
<br/><br/>
|
|
The file words are in the <span class="tt">file:</span> namespace.
|
|
<br/><br/>
|
|
<span class="h2">File Access Modes</span>
|
|
<br/><br/>
|
|
You can open a file for various operations. The functionality
|
|
allowed depends on the file access mode. Valid modes in RETRO
|
|
are:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>file:A Open for appending; file pointer set to end of file</tt>
|
|
<tt class='indentedcode'>file:R Open for reading; file pointer set to start of file</tt>
|
|
<tt class='indentedcode'>file:R+ Open for reading and writing</tt>
|
|
<tt class='indentedcode'>file:W Open for writing</tt>
|
|
<br/><br/>
|
|
<span class="h2">Opening A File</span>
|
|
<br/><br/>
|
|
To open a file, pass the file name and a file mode to <span class="tt">file:open</span>.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>'/etc/motd file:R file:open</tt>
|
|
<br/><br/>
|
|
On a successful open this will return a file handle greater than
|
|
zero.
|
|
<br/><br/>
|
|
Additionally, RETRO provides a few other forms for opening files.
|
|
<br/><br/>
|
|
To open a file for reading:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>'/etc/motd file:open-for-reading</tt>
|
|
<br/><br/>
|
|
This will return the size of the file (as NOS) and the file handle
|
|
(as TOS).
|
|
<br/><br/>
|
|
To open a file for writing:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>'/tmp/test file:open-for-writing</tt>
|
|
<br/><br/>
|
|
This returns the file handle.
|
|
<br/><br/>
|
|
To open a file for append operations:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>'/tmp/test file:open-for-append</tt>
|
|
<br/><br/>
|
|
As with <span class="tt">file:open-for-reading</span>, this returns both the size of
|
|
the file and the file handle.
|
|
<br/><br/>
|
|
<span class="h2">Closing A File</span>
|
|
<br/><br/>
|
|
To close a file, pass the file handle to <span class="tt">file:close</span>.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>'/etc/motd file:A file:open file:close</tt>
|
|
<br/><br/>
|
|
<span class="h2">Reading From A File</span>
|
|
<br/><br/>
|
|
To read a byte from an open file, pass the file handle to the
|
|
<span class="tt">file:read</span> word.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>@FID file:read n:put</tt>
|
|
<br/><br/>
|
|
To read a line from a file, pass the file handle to the word
|
|
<span class="tt">file:read-line</span>.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>@FID file:read-line s:put</tt>
|
|
<br/><br/>
|
|
The line is read into a temporary string buffer. Move the
|
|
text to a safe place if you aren't using it quickly or if
|
|
the length of the line is bigger than the size of a temporary
|
|
string.
|
|
<br/><br/>
|
|
<span class="h2">Writing To A File</span>
|
|
<br/><br/>
|
|
To write a byte to a file, pass it and the file handle to
|
|
<span class="tt">file:write</span>.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>$h @FID file:write</tt>
|
|
<tt class='indentedcode'>$e @FID file:write</tt>
|
|
<tt class='indentedcode'>$l @FID file:write</tt>
|
|
<tt class='indentedcode'>$l @FID file:write</tt>
|
|
<tt class='indentedcode'>$o @FID file:write</tt>
|
|
<br/><br/>
|
|
Though cells are 32 or 64 bits in size, only the byte value will
|
|
be written to the file.
|
|
<br/><br/>
|
|
<span class="h2">Deleting Files</span>
|
|
<br/><br/>
|
|
You can delete a file by passing the file name to <span class="tt">file:delete</span>.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>/tmp/test file:delete</tt>
|
|
<br/><br/>
|
|
<span class="h2">Check For File Existance</span>
|
|
<br/><br/>
|
|
Use <span class="tt">file:exists?</span> to detect the existance of a file. Pass it a
|
|
file name and it will return <span class="tt">TRUE</span> if existing or <span class="tt">FALSE</span> if
|
|
it does not.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>'/etc/motd file:exists?</tt>
|
|
<br/><br/>
|
|
This will also return <span class="tt">TRUE</span> if the filename is a directory.
|
|
<br/><br/>
|
|
<span class="h2">Flush Caches</span>
|
|
<br/><br/>
|
|
Use <span class="tt">file:flush</span> to flush the system caches for a file. Pass a
|
|
file handle to this.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>@FID file:flush</tt>
|
|
<br/><br/>
|
|
<span class="h2">Seek A Position Within A File</span>
|
|
<br/><br/>
|
|
You can use <span class="tt">file:seek</span> to move the internal file pointer
|
|
for a given file. Pass this the new location and a file.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>#100 @FID file:seek</tt>
|
|
<br/><br/>
|
|
The location for the file pointer is a fixed offset from the
|
|
start of the file, not a relative offset.
|
|
<br/><br/>
|
|
<span class="h2">Get The Current Position Within A File</span>
|
|
<br/><br/>
|
|
To find the current value of the file pointer within a file
|
|
just pass the file handle to <span class="tt">file:tell</span>.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>@FID file:tell</tt>
|
|
<br/><br/>
|
|
This returns a number that is the number of bytes into the file
|
|
that the file pointer is currently at.
|
|
<br/><br/>
|
|
<span class="h2">Determine The Size Of A File</span>
|
|
<br/><br/>
|
|
Use <span class="tt">file:size</span> to return the size of a file. Pass this a file
|
|
handle and it will return the size of a file, or 0 if empty. If
|
|
the file is a directory, it returns -1.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>@FID file:size</tt>
|
|
<br/><br/>
|
|
<span class="h2">Reading An Entire File</span>
|
|
<br/><br/>
|
|
If you want to read an entire file into memory you can use
|
|
<span class="tt">file:slurp</span>. This takes the starting address of a memory
|
|
region and the name of the file.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>here '/etc/motd file:slurp</tt>
|
|
<br/><br/>
|
|
Take care that the memory buffer is large enough for the file
|
|
being read or you will run into problems.
|
|
<br/><br/>
|
|
<span class="h2">Writing A String To A File</span>
|
|
<br/><br/>
|
|
If you have a string that you want to write to a file, replacing
|
|
any existing contents, you can use <span class="tt">file:spew</span>. This takes the
|
|
string to write and a file name.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>'hello_world '/tmp/test.txt file:spew</tt>
|
|
<br/><br/>
|
|
<span class="h2">Iterating Over A File, Line By Line</span>
|
|
<br/><br/>
|
|
You can easily iterate over each line in a file using the word
|
|
<span class="tt">file:for-each-line</span>. This will take a file name and a quote,
|
|
read each line into a temporary string, then pass this string to
|
|
the quote.
|
|
<br/><br/>
|
|
<tt class='indentedcode'>'/etc/motd [ s:put nl ] file:for-each-line</tt>
|
|
</p>
|
|
</body></html>
|