4th(1)

NAME

4th - a portable Forth compiler supporting a (modified) subset of ANS-Forth

SYNTAX

4th [options] [file] [file | argument .. argument]

4thx [file] [argument .. argument]

DESCRIPTION

4th is a menudriven bytecode compiler, virtual machine, decompiler, line editor, RPN calculator and C-source generator rolled into one small program. You can use it to create portable bytecode programs, standalone executables or as a scripting language or a Forth-to-C translator. For details read the manual.

OPTIONS

m   enter interactive mode

e   edit a 4tH screenfile

c   load a sourcefile (.4th) and compile it

l   load an objectfile (.hx)

d   decompile a 4tH program

g   generate a C sourcefile (default: out.c)

s   save a 4tH program (default: out.hx)

x   execute a 4tH program

v   enter verbose mode

q   suppress copyright message

EDITOR

n D Delete line n but hold it in PAD. Line 15 becomes free as all statements move up 1 line.

n E Erase line n with blanks.

n I Insert the text from PAD at line n, moving the old line n and following lines down. Line 15 is lost.

n H Hold line n at PAD (used by system more often than by user).

n R Replace line n with the text in PAD.

n S Spread at line n. Line n and following lines move down 1 line. Line n becomes blank. Line 15 is lost.

n T Display line n and copy it to PAD.

n P text
    Put 'text' at line n, overwriting its previous contents.

n LIST
    List screen n and select it for editing: if screen n is not the current screen, it will request to load from memory.

n CLEAR
    Clear screen n with blanks and select it for editing.

n INSERT
    Insert screen n. The current screen n and all screens following it are moved down. The last screen is lost. Clear screen n with blanks and select it for editing. FLUSH Used at the end of an editing session to save the current screen to memory.

UNDO
    Used to reload the current screen again, thus undoing all changes since the last flush (triggered by CLEAR, FLUSH or LIST).

FLUSH
    Write updated screen to memory.

L   List the current screen. The cursor line is relisted after the screen listing to show the cursor position.

n M Move the cursor by n characters and the cursor line. The position of the cursor on its line is shown by a ^ (caret).

n W Wipe n characters to the left of the cursor.

TOP Position the cursor at the start of the screen.

B   Used after F to back up the cursor by the length of the most recent text.

C text
    Copy in text to the cursor line at the cursor position.

F text
    Search forward from the current cursor position until string 'text' is found. The cursor is left at the end of the string and the cursor line printed. If the string is not found an error message is given and the cursor repositioned to the top of the screen.

N   Find the next occurrence of the string found by an F command

TILL text
    Delete on the cursor line from the cursor till the end of string text.

X text
    Find and delete the next occurrence of the string 'text'.

EXPORT file
    Saves the current contents of all screens to text-file 'file'. No flushing is done.

WRITE
    Saves the current contents of all screens to the block-file. No flushing is done.

WQ  Flushes the current screen and saves the current contents of all screens to the block-file.

Q   Quits the editor without saving.

FILES

*.4th; text files containing 4tH source (script)
*.scr; block files containing 4tH source (script)
*.hx; Hcode eXecutables (bytecode)
*.c; C source files

ENVIRONMENT VARIABLES

DIR4TH
    If non-null the full pathname (including the trailing slash) for the 4tH root directory. Used only by the compiler.

EDIT4TH
    If non-null defines the user's preferred external utility to edit source files.

EXAMPLES

To compile a 4tH program and save the object code:

4th csv source.4th [object.hx]

To compile a 4tH program and execute it:

4th cx source.4th

To decompile object code:

4th ld object.hx

To convert object code to C source:

4th lg object.hx [source.c]

To load and execute object code:

4th lx object.hx [arguments]

To load and execute object code without arguments:

4th object.hx

To edit a 4tH screenfile:

4th e source.scr

To enter interactive mode:

4th m source.scr

To enter interactive mode (without a screenfile):

4th

AUTHORS

4tH was written by Hans Bezemer <the.beez.speaks@gmail.com>

SEE ALSO

gforth(1)