crc/retroforth
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
retroforth/doc/html/chapters/techniques/files.html

198 lines
7.7 KiB
HTML
Raw Normal View History

generate & include html documentation files FossilOrigin-Name: 03f8a1f5293ceeb245b4e6315578c114c69eb4341027fad8eba5ec8c8dbca5fa
2021-01-21 13:40:28 +01:00
<?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>
rebuild .html documentation; correct a filename reference (Rx.md -> image/retro.muri) reported by Martin Hohmann-Marriott FossilOrigin-Name: 429b138d84f0284a5f7054165c02a40f33ecbe919165eebc5271a07a367864bc
2022-06-03 12:41:52 +02:00
<p><br/><br/>
generate & include html documentation files FossilOrigin-Name: 03f8a1f5293ceeb245b4e6315578c114c69eb4341027fad8eba5ec8c8dbca5fa
2021-01-21 13:40:28 +01:00
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/>
<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&nbsp;&nbsp;&nbsp;&nbsp;Open&nbsp;for&nbsp;appending;&nbsp;file&nbsp;pointer&nbsp;set&nbsp;to&nbsp;end&nbsp;of&nbsp;file</tt>
<tt class='indentedcode'>file:R&nbsp;&nbsp;&nbsp;&nbsp;Open&nbsp;for&nbsp;reading;&nbsp;file&nbsp;pointer&nbsp;set&nbsp;to&nbsp;start&nbsp;of&nbsp;file</tt>
<tt class='indentedcode'>file:R+&nbsp;&nbsp;&nbsp;Open&nbsp;for&nbsp;reading&nbsp;and&nbsp;writing</tt>
<tt class='indentedcode'>file:W&nbsp;&nbsp;&nbsp;&nbsp;Open&nbsp;for&nbsp;writing</tt>
<br/><br/>
<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&nbsp;file:R&nbsp;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&nbsp;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&nbsp;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&nbsp;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/>
<br/><br/>
To close a file, pass the file handle to <span class="tt">file:close</span>.
<br/><br/>
<tt class='indentedcode'>'/etc/motd&nbsp;file:A&nbsp;file:open&nbsp;file:close</tt>
<br/><br/>
<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&nbsp;file:read&nbsp;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&nbsp;file:read-line&nbsp;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/>
<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&nbsp;@FID&nbsp;file:write</tt>
<tt class='indentedcode'>$e&nbsp;@FID&nbsp;file:write</tt>
<tt class='indentedcode'>$l&nbsp;@FID&nbsp;file:write</tt>
<tt class='indentedcode'>$l&nbsp;@FID&nbsp;file:write</tt>
<tt class='indentedcode'>$o&nbsp;@FID&nbsp;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/>
<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&nbsp;file:delete</tt>
<br/><br/>
<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&nbsp;file:exists?</tt>
<br/><br/>
This will also return <span class="tt">TRUE</span> if the filename is a directory.
<br/><br/>
<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&nbsp;file:flush</tt>
<br/><br/>
<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&nbsp;@FID&nbsp;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/>
<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&nbsp;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/>
<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&nbsp;file:size</tt>
<br/><br/>
<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&nbsp;'/etc/motd&nbsp;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/>
<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&nbsp;'/tmp/test.txt&nbsp;file:spew</tt>
<br/><br/>
<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&nbsp;[&nbsp;s:put&nbsp;nl&nbsp;]&nbsp;file:for-each-line</tt>
</p>
</body></html>
Reference in a new issue Copy permalink