pp4th(1)

NAME

pp4th - a portable Forth preprocessor supporting a (modified) subset of ANS-Forth

SYNTAX

pp4th [options] [file] [argument .. argument]

DESCRIPTION

pp4th is a command line bytecode compiler, preprocessor, virtual machine, decompiler 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

-V  show version and exit

-v  enter verbose mode

-x  execute a 4tH program

-p  preprocess a 4tH preprocessor file

-d  decompile a 4tH program

-c  load a sourcefile and compile it

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

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

-k  keep intermediate file

-n  enables a symbolic decompile in conjunction with the -d option

-i  show all files included hierarchically

-o filename
    specify the name of the output file when preprocessing, generating or saving

-D symbol
    define symbol as a CONSTANT, with value 1. You may add as many -D options as you require

-D symbol=value
    define symbol as a CONSTANT, with value value. You may add as many -D options as you require

COMMANDS

\ s The remainder of the line s is discarded. Used for comment.

( s)
    Discard comment s that is delimited by a right parenthesis. A blank after the leading parenthesis is required.

char c
    Replaces character c as with its ASCII value.

[char] c
    Replaces character c as with its ASCII value.

include s
    The contents of file s, delimited by whitespace, are inserted at this position.

[needs s]
    The contents of file s, delimited by a right bracket, are inserted at this position.

:macro s
    Create a macro with the name s, delimited by a semi-colon. When s is encountered it is replaced by the contents of the macro. A macro may contain any sequence of valid 4tH words, including conditional and loop statements, but no macros or include files.

scrap: s
    Delete a macro with the name s. After that, s will not be expanded anymore and name s can be used to define a new macro. Note that the macro space allocated by s is not freed.

let s
    Expand FORTRAN formula s.

[single]
    Set FORTRAN formula translation to single word precision.

[double]
    Set FORTRAN formula translation to double word precision.

[float]
    Set FORTRAN formula translation to floating point.

[binary]
    Sets radix to binary.

[octal]
    Sets radix to octal.

[decimal]
    Sets radix to decimal.

[hex]
    Sets radix to hexadecimal.

MACROS

@n@ Parses the next string and puts it in register n.

#n# Prints the contents of register n.

>n> Pushes the contents of register n on the string stack.

<n< Pops the "top of string stack" and puts it in register n.

$n$ Parses the next string, using the delimiter following it, and puts it in register n.

$#$ Parses the next string, using the delimiter following it, and pushes it on the string stack.

>#> Parses the next string and pushes it on the string stack.

<#< Discards the "top of string stack". Aka '@drop'.

|#| Prints the "top of string stack" without white space.

_#_ Prints the "top of string stack" with white space.

>>> Pushes the string following it on the string stack.

@cr Prints a line delimiter.

@if If the numerical value of the "top of string stack" is zero, the rest of the macro definition is skipped.

@dup
    Duplicates the "top of string stack".

@nip
    Discards the "second of string stack".

@add
    Adds the numerical value of the "top of string stack" and the numerical value of the "second of string stack".

@mul
    Multiplies the numerical value of the "top of string stack" and the numerical value of the "second of string stack".

@divrm
    Divides the numerical value of the "second of string stack" by the numerical value of the "top of string stack" and leaves the quotient and remainder.

@over
    Duplicates the "second of string stack".

@else
    If the numerical value of the "top of string stack" is non-zero, the rest of the macro definition is skipped. Aka '@ifnot'.

@exist
    Pops the "top of string stack". If this represents a valid macro name, a TRUE value is pushed onto the string stack.

@minus
    Negates the "top of string stack".

@eval
    Pops the "top of string stack". If the "top of the string stack" contains the name of a macro, it will be executed. If it doesn't, it is printed.

@cell
    Pops the "top of string stack". If it contains a numerical value, a TRUE value is pushed onto the string stack.

@sign
    Pops the "top of string stack". If it's numerical value is negative, "-1" is pushed onto the string stack. If it is zero, "0" is pushed onto the string stack, otherwise "1".

@match
    Pops the "top of string stack" and "second of string stack". If both strings are equal, "0" is pushed on the string stack. If "second of string stack" is smaller than "top of string stack", a negative value is pushed on the string stack, otherwise a positive value.

@until
    Pops the "top of string stack" and "second of string stack". If both strings are equal, the rest of the macro definition is skipped.

@while
    Pops the "top of string stack" and "second of string stack". If the strings differ, the rest of the macro definition is skipped.

FILES

*.4th; text files containing 4tH source (script)
*.4pp; text files containing 4tH preprocessor 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.

EXAMPLES

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

pp4th -cso object.hx source.4th

To compile a 4tH program and execute it:

pp4th -x source.4th

To decompile a 4tH program with symbols:

pp4th -dn source.4th

To convert a 4tH program to C source:

pp4th -cgo source.c source.4th

AUTHORS

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

SEE ALSO

gforth(1)