175 lines
5.5 KiB
HTML
175 lines
5.5 KiB
HTML
<!--
|
|
Copyright 2021 Bradley D. Nelson
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<h5>Shell Utilities</h5>
|
|
<p><b>Requires v7.0.7.3+ -- ONLY Posix + ESP32</b></p>
|
|
<pre>
|
|
cp ( "src" "dst" -- ) Copy "src" file to "dst".
|
|
mv ( "src" "dst" -- ) Rename "src" file to "dst".
|
|
rm ( "path" -- ) Remove "path" file.
|
|
touch ( "path" -- ) Create "path" file if it doesn't exist.
|
|
cat ( "path" -- ) Print contents of "path" file.
|
|
ls ( "path" -- ) List files or directories in "path".
|
|
</pre>
|
|
<p><b>Requires v7.0.7.3+ -- ONLY Posix</b></p>
|
|
<pre>
|
|
cd ( "path" -- ) Change director to "path".
|
|
mkdir ( "path" -- ) Create directory "path".
|
|
rmdir ( "path" -- ) Remove directory "path".
|
|
pwd ( -- ) Print current directory.
|
|
</pre>
|
|
|
|
<h5>Visual Editor</h5>
|
|
<p><b>Requires v7.0.7.2+</b></p>
|
|
<pre>
|
|
VISUAL EDIT ( "path" --) Enters a visual editor opening file "path".
|
|
|
|
NOTE: On ESP32 requires connection over an ANSI serial terminal like Putty.
|
|
|
|
LIMITATIONS: Terminal doesn't know screen dimensions
|
|
and is very redraw inefficient.
|
|
|
|
Keys:
|
|
Ctrl-S -- Save now.
|
|
Ctrl-X / Ctrl-Q -- Quit, asking Y/N to save.
|
|
Ctrl-L -- Redraw the screen.
|
|
Backspace -- Delete a character backwards.
|
|
Arrow Keys -- Movement.
|
|
PgUp/PgDn -- Scroll up/down a page.
|
|
</pre>
|
|
|
|
<h5>Blocks</h5>
|
|
<pre>
|
|
USE ( "name" -- ) Use "name" as the blockfile, e.g. USE /spiffs/foo
|
|
OPEN-BLOCKS ( a n -- ) Open a file as the block file
|
|
LOAD ( n -- ) Evaluate a block
|
|
THRU ( a b -- ) Load blocks a thru b
|
|
LIST ( n -- ) List a block
|
|
BLOCK ( n -- a ) Get a 1024 byte block
|
|
BUFFER ( n -- a ) Get a 1024 byte block without regard to old contents
|
|
UPDATE ( -- ) Mark the last block modified
|
|
FLUSH ( -- ) Save and empty all buffers
|
|
EMPTY-BUFFERS ( -- ) Empty all buffers
|
|
SAVE-BUFFERS ( -- ) Save all buffers
|
|
SCR ( -- a ) Pointer to last listed block
|
|
</pre>
|
|
|
|
<h5>Block Editor</h5>
|
|
These words are available inside the <code>EDITOR</code> vocabulary.
|
|
Note the block editor places newlines in the 63rd column of each line
|
|
to make the block file readable in a text editor.
|
|
<pre>
|
|
WIPE ( -- ) Blank out the current block
|
|
L ( -- ) List the current block
|
|
D ( n -- ) Delete a line in the current block
|
|
E ( n -- ) Clear a line in the current block
|
|
R ( n "text" -- ) Replace a line in the current block
|
|
A ( n "text" -- ) Add (insert) a line in the current block
|
|
P ( -- ) Move to the previous block
|
|
N ( -- ) Move to the next block
|
|
</pre>
|
|
|
|
<h5>Sockets</h5>
|
|
<p><b>Requires v7.0.7.2+ for UDP</b></p>
|
|
These words are available inside the <code>sockets</code> vocabulary.
|
|
<pre>
|
|
socket ( domain type protocol -- sock/err )
|
|
setsockopt ( sock level optname optval optlen -- 0/err )
|
|
bind ( sock addr addrlen -- 0/err )
|
|
listen ( sock connections -- 0/err )
|
|
sockaccept ( sock addr addrlen -- sock/err ) -- varies from bsd socks
|
|
connect ( sock addr addrlen -- 0/err )
|
|
select ( numfds readfds writefds errfds timeout -- fd/err )
|
|
poll ( pollfds n timeout -- fd/err )
|
|
send ( sock a n flags -- n/err )
|
|
sendto ( sock a n flags addr addrlen -- n/err )
|
|
sendmsg ( sock msg flags -- n/err )
|
|
recv ( sock a n flags -- n/err )
|
|
recvfrom ( sock a n flags addr addrlen -- n/err )
|
|
recvmsg ( sock msg flags -- n/err )
|
|
gethostbyname ( hostnamez -- hostent/0 )
|
|
errno ( -- err ) -- ESP32 only as of v7.0.7.2
|
|
|
|
sockaddr ( "name" -- ) creates a sockaddr structure
|
|
->port@ ( a -- n ) get port from sockaddr
|
|
->port! ( n a -- ) set port in sockaddr
|
|
->addr@ ( a -- n ) get big-endian address from sockaddr
|
|
->addr! ( n a -- ) set big-endian address in sockaddr
|
|
ip. ( n -- ) Print address as x.y.z.w IP address.
|
|
|
|
( Constants )
|
|
SOCK_STREAM SOCK_DGRAM SOCK_RAW
|
|
AF_INET
|
|
sizeof(sockaddr_in)
|
|
SOL_SOCKET
|
|
SO_REUSEADDR
|
|
</pre>
|
|
|
|
<p>
|
|
</p>
|
|
|
|
<h5 id="dictimages">Dictionary Images and Startup</h5>
|
|
|
|
<p>
|
|
<b>WARNING: Danger ahead.</b><br/>
|
|
Snapshotting the dictionary may not be stable across reinstallations of the C build of Forth.
|
|
</p>
|
|
|
|
<p>
|
|
A collection of non-standard words is provided that allow snapshotting
|
|
the dictionary and restoring it at startup, with a start word.
|
|
</p>
|
|
|
|
<pre>
|
|
SAVE ( "name" -- ) Saves a snapshot of the current dictionary to a file.
|
|
RESTORE ( "name" -- ) Restore a snapshot from a file.
|
|
REMEMBER ( -- ) Save a snapshot to the default file
|
|
(./myforth or /spiffs/myforth on ESP32).
|
|
STARTUP: ( "name" -- ) Save a snapshot to the default file arranging for
|
|
"name" to be run on startup.
|
|
REVIVE ( -- ) Restore the default filename.
|
|
RESET ( -- ) Delete the default filename.
|
|
</pre>
|
|
|
|
<p>
|
|
Here's an example usage:
|
|
</p>
|
|
|
|
<pre>
|
|
: welcome ." Hello!" cr 100 0 do i . loop cr ;
|
|
startup: welcome
|
|
bye
|
|
|
|
( Next boot will run a custom startup message )
|
|
|
|
reset
|
|
|
|
( Reset removes the custom message )
|
|
</pre>
|
|
|
|
<p>
|
|
The <code>INTERNALS</code> vocabulary has some additional words
|
|
for more control.
|
|
</p>
|
|
|
|
<pre>
|
|
SAVE-NAME ( a n -- ) Save a snapshot if the current vocabulary to a file.
|
|
RESTORE-NAME ( a n -- ) Restore a snapshot from a file.
|
|
'COLD ( -- a ) Address of the word that will be run on startup.
|
|
REMEMBER-FILENAME ( -- a n ) Deferred word specifying the platform specific
|
|
default snapshot filename.
|
|
</pre>
|