pp4th(1)

📦 version 3.64.2, in nixpkgs unstable

pp4th(1) 💅 A Portable Forth Preprocessor That Slays

okay so bestie, meet pp4th — a portable Forth preprocessor that supports a (modified) subset of ANS-Forth. iykyk. ✨

✨ SYNTAX ✨

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

🦋 DESCRIPTION 🦋

okay so pp4th is literally a command line bytecode compiler, preprocessor, virtual machine, decompiler and C-source generator all rolled into one tiny little program. no cap. you can use it to create portable bytecode programs, standalone executables, or as a scripting language or a Forth-to-C translator. for the full tea, read the manual. periodt. 💅

🎀 OPTIONS 🎀

  • -V — show version and exit. simple, iconic.
  • -v — enter verbose mode. she's chatty now.
  • -x — execute a 4tH program. run it, bestie.
  • -p — preprocess a 4tH preprocessor file.
  • -d — decompile a 4tH program. reverse engineering vibes.
  • -c — load a sourcefile and compile it.
  • -s — save a 4tH program. default is out.hx. 🫶
  • -g — generate a C sourcefile. default is out.c.
  • -k — keep intermediate file. no deleting the evidence.
  • -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. literally stack 'em.

🌸 COMMANDS 🌸

  • \ s — the remainder of the line s is discarded. used for comment. it's giving "not me writing notes in the margins".
  • ( s) — discard comment s that is delimited by a right parenthesis. a blank after the leading parenthesis is required. don't forget the space, bestie.
  • 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. so no nesting, okay? 🙈
  • 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. it's giving "she's gone but her ghost is still here".
  • 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. 01100110 01110101 01101110 💀
  • [octal] — sets radix to octal.
  • [decimal] — sets radix to decimal. the normie choice.
  • [hex] — sets radix to hexadecimal. edgy.

💜 MACROS 💜

  • @n@ — parses the next string and puts it in register n. lowkey stash it.
  • #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. fancy.
  • $#$ — 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'. bye bestie.
  • |#| — prints the "top of string stack" without white space.
  • _#_ — prints the "top of string stack" with white space. give her some room.
  • >>> — pushes the string following it on the string stack.
  • @depth — pushes the number of elements contained in the string stack on the string stack.
  • @cr — prints a line delimiter. new line who dis.
  • @if — if the numerical value of the "top of string stack" is zero, the rest of the macro definition is skipped. conditional queen.
  • @dup — duplicates the "top of string stack". she's seeing double.
  • @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. math slay.
  • @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. she's either a doer or a talker.
  • @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". giving main character energy.
  • @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. loop her until she matches. 🔥

🍓 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. she needs her root, okay? 🫶

👑 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>. we stan.

⭐ SEE ALSO ⭐

gforth(1)

and that's the tea, bestie! this manual page was brought to you by Hans Bezemer, version 3.64.1, dated 3.64.1 (yes same number, iconic). catch you on the flip side! 🫶💖✨

📦 where this page comes from