{"id":21970661,"url":"https://github.com/sirwumpus/post4","last_synced_at":"2025-10-17T17:35:21.666Z","repository":{"id":62281781,"uuid":"144337747","full_name":"SirWumpus/post4","owner":"SirWumpus","description":"Post4 is an indirect threaded Forth interpreter written in C.","archived":false,"fork":false,"pushed_at":"2025-09-06T11:40:46.000Z","size":9416,"stargazers_count":11,"open_issues_count":6,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-09-06T13:23:53.312Z","etag":null,"topics":["c","data-stack","float-stack","forth","forth-2012","forth-2019","interpreter","jni","jni-java"],"latest_commit_sha":null,"homepage":"","language":"Forth","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SirWumpus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-08-10T22:31:55.000Z","updated_at":"2025-09-06T11:41:26.000Z","dependencies_parsed_at":"2024-07-27T12:32:32.725Z","dependency_job_id":"a69966be-d88f-48d4-aa50-8c5d03298153","html_url":"https://github.com/SirWumpus/post4","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/SirWumpus/post4","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SirWumpus%2Fpost4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SirWumpus%2Fpost4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SirWumpus%2Fpost4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SirWumpus%2Fpost4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SirWumpus","download_url":"https://codeload.github.com/SirWumpus/post4/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SirWumpus%2Fpost4/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279385892,"owners_count":26160195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-17T02:00:07.504Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","data-stack","float-stack","forth","forth-2012","forth-2019","interpreter","jni","jni-java"],"created_at":"2024-11-29T14:41:37.846Z","updated_at":"2025-10-17T17:35:21.658Z","avatar_url":"https://github.com/SirWumpus.png","language":"Forth","funding_links":[],"categories":[],"sub_categories":[],"readme":"Post4 (Post-Forth)\n==================\nPrimary Repository https://codeberg.org/SirWumpus/post4\n\nCopyright 2007, 2024 Anthony Howe.  All rights reserved.\n\n\nOverview\n--------\n\nPost4 is a hosted indirect threaded Forth dialect written in C, based on the [\"Forth 200x Draft 19.1, 2019-09-30\"](http://www.forth200x.org/documents/forth19-1.pdf).  Post4 aims to implement the fewest possible built-in words in C, those that are needed to interact with memory and I/O, leaving the remaining standard words to be implemented in Forth.\n\n        usage: post4 [-TV][-b file][-c file][-h size][-i file][-m size]\n                     [script [args ...]]\n        \n        -b file         open a block file\n        -c file         word definition file; default post4.p4 from $POST4_PATH\n        -h size         history size in lines; default 16\n        -i file         include file; can be repeated; searches $POST4_PATH\n        -m size         data space memory in KB; default 128\n        -T              enable tracing; see TRACE\n        -V              build and version information\n        \n        If script is \"-\", read it from standard input.\n\n\nThe environment variable `POST4_PATH` provides a colon separated search path for the `post4.p4` core word definitions file and include files.  If `POST4_PATH` is undefined, then an OS specific default path is used.  A specific word definition file can be specified with `-c`.\n\nBy default no block file is opened.  Use `-b file` to open a block file at start-up; otherwise see [OPEN-BLOCK](./doc/block.md) and [CLOSE-BLOCK](./doc/block.md) words.\n\nPost4 reads input from standard input and writes to standard output, which can be redirected:\n\n**Example 1 - pipe input**  \n\n        echo \"123 69 + .\" | post4\n\n**Example 2 - here document**  \n\n        post4 - hey babe \u003c\u003cEOF\n        include-path dumpargs.p4\n        args .s dropall cr\n        s\\\" Hello world (again)!\\r\\n\" type\n        EOF\n\nPost4 cell size is equivalent to C's `intptr_t`, which for most current systems are 64 bits.\n\n\nExit Status\n-----------\n\n- 0     Post4 and application exited successfully.\n- 1     The application returned a negative result.\n- 2     Command line usage error.\n- 3     One or more uncaught exceptions occurred.\n- \\\u003e3    Some application error occurred.\n\n\nGlossary of Words\n-----------------\n\n* [Standard Core](./doc/standard.md)\n* [ANSI Terminal](./doc/ansiterm.md)\n* [Assertions \u0026 Testing](./doc/assert.md)\n* [Block File](./doc/block.md)\n* [Double-Cell](./doc/double.md)\n* [File Access](./doc/file.md)\n* [Floating-Point](./doc/float.md)\n* [Memory](./doc/memory.md)\n* [Seach-Order](./doc/search.md)\n* [String](./doc/string.md)\n* [Tool](./doc/tools.md)\n* [THROW Codes](./doc/throw_codes.md)\n\n\nBuilding\n--------\n\nPost4 is written in ISO C17 using only one extension, `Labels As Values`, which is supported by `gcc` and `clang` compilers.  Post4 has been built and tested on [NetBSD](https://netbsd.org/), [Cygwin](https://www.cygwin.com/), [Alpine Linux](https://alpinelinux.org/), [Rocky Linux](https://rockylinux.org), and [Ubuntu Linux](https://ubuntu.com/).  Its been reported to build on MacOS too.\n\n        $ ./configure --help\n        $ ./configure\n        $ make tests\n        $ make run              # Manually test in the source tree.\n        ok BYE\n        $ sudo make install\n        $ post4\n\nIf `gcc` is the default compiler, it is possible to override that to test building with a different C compiler suite, most likely [Clang](https://clang.llvm.org/) for example:\n\n        $ make CC=clang clean build\n\nBuilding for debug can be done in two ways.  The first enables debug options in Post4 amd JNI as needed:\n\n        $ ./configure --enable-debug\n        $ make clean build tests\n\nAlternative following an earlier configuration, possible to build a temporary debug build:\n\n        $ ./configure\n        $ cd src\n        $ make DBG='-g -O0' clean build\n\nThe `DBG` macro can be used to override default `CFLAGS` to try different compiler optimisations.  In the case of `-O` the last one specified overrides the previous occurences.  By default Post4 builds with `-Os`, because `small is beautiful`.  If speed is more of concerning simply use `DBG='-O2'` or `DBG='-O3'`.\n\nJava Native Interface\n---------------------\n\nJNI support is availble.  See the [JNI documentation](./jni/README.md) about building, API, and examples.\n\n\nInteractive Usage\n-----------------\n\nWhen Post4 is invoked without a script file argument or redirected input, then the user is presented with an `ok` prompt.  The user can enter Post4 numbers and words.  Pressing the terminal `Enter` (`Return`) key ends the input line, which will be interpreted.  All Post4 words are treated as case-insensitive.\n\nTo leave Post4 either type the `EOF` terminal character, `BYE`, or `code BYE-CODE` (where `code` is number to return to the user's shell).  For those not familiar with Forth, there is a `QUIT` word, but it only terminates a running program; it does not return to the host OS.\n\n\n### TTY Line Editing\n\nPost4 implements simple TTY style line editing and history for interactive input.  GNU `readline`, BSD `libedit`, and `rlwrap` are not supported.  See also `stty(1)`.\n\n        up      ^K      Cycle to the previous input line to edit.\n        down    ^L      Cycle to the next input line to edit.\n        left    right   Cursor left or right within line.\n        ERASE   ^H  ^?  Erase character before the cursor.\n        WERASE          Erase the previous white space delimited word.\n        KILL            Erase current line input.\n        EOL     ^M  ^J  Newline submits input line.\n        EOF             End of file.\n\n* *Assumes ANSI terminal escape sequences.*\n\n### Numeric I/O\n\nThe default numeric input/output base is decimal (base 10).  Setting variable `BASE` will change the default radix used for numeric I/O, which can be between between 2 and 36, eg. `16 BASE !` sets hexadecimal.  There are four shorthand words `BINARY`, `OCTAL`, `DECIMAL`, and `HEX` that set `BASE` to 2, 8, 10, or 16 repectively.\n\nRegardless of the current value of `BASE`, it is possible to input numbers in one of the three common bases without having to change the value of `BASE`.  Prefixing a number with `%`, `#`, `$` can set a binary, decimal, or hex value; an optional minus sign given after the prefix to indicate a negative number.  For example:\n\n        %1111111  = #127  = $7f  = $000000000000007f\n        %-1111111 = #-127 = $-7f = $ffffffffffffff81\n\nWhen current `BASE` is ten (10) its possible to input floating point numbers (provided support is enabled) with a decimal point and/or scientific notation.  For example:\n\n         0.0    =  0E0  =  0e0\n         1.0    =  1E0  =  1e0  =  +1.E0\n         12.3   =  123E-1\n        -0.123  = -123e-3\n\nFloating point numbers are placed on the float stack, which is separate from the data and return stacks.  Also the float stack is small, though at least six (6) deep.  See [Floating-Point Words](./doc/float.md), in particular words [f.](./doc/float.md) and [fs.](./doc/float.md) to start with.\n\n- *Note the input notation, `123E`, where there is no value following the exponent is not supported.*\n\nIt is also possible to input a character constant or backslash escape character.  Simple use single-quotes around the character or backslash-escape string (see also `CHAR` and `[CHAR]`).  For example:\n\n        'A'     ASCII upper case A.             '_'     ASCII underscore.\n        'b'     ASCII lower case B.             '\\n'    ASCII linefeed.\n        '9'     ASCII digit 9.\n\n\nThe following C-style backslash escapes are supported:\n\n        \\?      delete                          \\n      linefeed\n        \\\\      backslash                       \\r      carriage-return\n        \\a      bell                            \\s      space\n        \\b      backspace                       \\t      tab\n        \\e      escape                          \\v      vertical tab\n        \\f      formfeed                        \\z      nul\n\n\nBecause Forth uses whitespace for input delimiters, in particular space (ASCII 32), the only way to input a literal space character is with:\n\n        32      ASCII numeric value.\n        '\\s'    Backslash escape.\n        BL      Forth word, short for blank.\n\nForth has strings: counted and length prefixed.  Counted strings are a carry-over from historical Forth, where the string stored in memory, is prefixed by a length octet, limiting the string length to 255 ASCII octets.  The standard Forth character string, when stored in memory, is prefixed with an unsigned numeric length cell.  As a Post4 extension, character strings are always NUL terminated as a convenience for interacting with the C library and host OS API.\n\nSome examples of words using strings.  Note that the whitespace character (space, tab, newline) immediately after the word, eg. `S\\\"`, delimits the word from the text that follows and is not part of the text:\n\n        .\" some text\"                           Print some text at runtime.\n        C\" counted text\"                        Define a counted string.\n        .\"  \u003c- space printed\"                   Print text with leading space (or tab, hard to tell).\n        .\\\" \\s\u003c- space printed\"                 Print text with leading space escaped for clarity.\n        S\" some text\"                           Store some text.\n        S\\\" escaped\\atext\\r\\n\"                  Store some escaped text.\n        .( lots of text\n           spanning multiple lines)             Show some text (now).\n        .( ed(1\\) is the standard text editor)  Escape terminating delimiter.\n        ABORT\" text message\"                    What I do wrong now?\n\n\nExamples\n--------\n\n### catch_throw.p4\n\nA demonstration of using CATCH and THROW.\n\n        $ post4 -i catch_throw.p4\n        Enter TRY-IT or RETRY-IT words to test CATCH / THROW.\n        ok \n\n\n### dumpargs.p4\n\nSimple demonstration on how to access the command line arguments.\n\n        $ post4 dumpargs.p4 hello world, tell us more!\n\n\n### ed.p4\n\nBlock Editor;  actually three block editor word sets:\n\n1. An `ed(1)` like block line editor using `LIST`, `PRINT`, and `CHANGE`.\n2. An interactive single line editor using `EDIT`; left \u0026 right cursor keys, tab toggles insert or replace mode, delete backspace, ESC quits.\n3. A full \"screen\" block editor using `ED`; all the commands of the interactive single line editor, plus up \u0026 down cursor keys, `CTRL+G` goto block, `CTRL+P` \u0026 `CTRL+N` block, and `ESC` menu.\n\nNOTE: that `EDIT` and `ED` are hard coded with ANSI terminal escape sequences.\n\n        $ post4 -b .post4.blk -i ed.p4\n        Type ED to start editor.\n        ok ED\n\n\n### life.p4\n\n[Conway's Game of Life](http://en.wikipedia.org/wiki/Conway%27s_Game_of_Life)\n\n**Rules**\n\nThe universe of the Game of Life is an infinite two-dimensional orthogonal\ngrid of square cells, each of which is in one of two possible states, live\nor dead. Every cell interacts with its eight neighbours, which are the cells\nthat are directly horizontally, vertically, or diagonally adjacent. At each\nstep in time, the following transitions occur:\n\n   1. Any live cell with fewer than two live neighbours dies, as if caused by under population.\n   2. Any live cell with more than three live neighbours dies, as if by overcrowding.\n   3. Any live cell with two or three live neighbours lives on to the next generation.\n   4. Any dead cell with exactly three live neighbours becomes a live cell.\n\nThe initial pattern constitutes the seed of the system. The first generation\nis created by applying the above rules simultaneously to every cell in the\nseed - births and deaths happen simultaneously, and the discrete moment at\nwhich this happens is sometimes called a tick (in other words, each generation\nis a pure function of the one before). The rules continue to be applied\nrepeatedly to create further generations.\n\n        $ post4 life.p4\n\n\n### life1d.p4\n\n[One Dimensional Cellular Atomata](https://en.wikipedia.org/wiki/Cellular_automaton)\n\nThis example demostrates five Wolfram rules 30, 90, 110, 184, and 104 using the same initial state.\n\n        $ post4 life1d.p4\n\n\n### rand.p4\n\nPseudo-random number generators.  One is the simple code example from the ISO C11 draft April 12, 2011,\n\n        \\ Example from the ISO C11 draft April 12, 2011\n        \n        SRAND ( -- aaddr )\n            Random number seed variable.\n            \n        RAND ( -- u )\n            Return random number between 0..32767.\n        \n        \\ Pseudo-Random Sequence Generator for 32-Bit CPUs\n        \\ Bruce Schneier, Dr. Dobb's Journal, v. 17, n. 2, February 1992, pp. 34-40.\n        \n        RANDA ( -- aaddr )\n        RANDB ( -- aaddr )\n        RANDC ( -- aaddr )\n            Random number seed variables for three Linear Feedback Shift\n            Registers.\n            \n        RANDOMXOR ( bits -- u )\n            Return random number u generated from bits, XORing the bits from the\n            three generators.\n            \n        RANDOMMAJ ( bits -- u )\n            Return random number u generated from bits, based on the majority of\n            one or zero returned from the three generators.\n\nExample:\n\n        $ post4\n        ok INCLUDE rand.p4\n        ok 12345 SRAND !\n        ok RAND . RAND . RAND . CR\n        21468 9988 22117\n        ok 12345 RANDA ! 54321 RANDB ! $deadbeef RANDC !\n        ok 16 RANDOMXOR U. 16 RANDOMXOR U. 16 RANDOMXOR U. CR\n        52917 27383 64651\n        ok 16 RANDOMMAJ U. 16 RANDOMMAJ U. 16 RANDOMMAJ U. CR\n        7 9885 36906\n        ok \n\n\n### wumpus.p4\n\n[Hunt The Wumpus](https://en.wikipedia.org/wiki/Hunt_the_Wumpus) game ported from the original BASIC source written by Gregory Yob.\n\n        $ post4 -i wumpus.p4\n        ... instructions ...\n        Type PLAY to start.\n        ok PLAY\n        \n        BATS NEARBY\n        YOU ARE IN ROOM 8\n        TUNNELS LEAD TO    1   7   9\n        (S)HOOT OR (M)OVE? M\n        WHERE TO? 7\n        ZAP--SUPER BAT SNATCH! ELSEWHEREVILLE FOR YOU!\n        \n        YOU ARE IN ROOM 13\n        TUNNELS LEAD TO   12  14  20\n        (S)HOOT OR (M)OVE? M\n        WHERE TO? 14\n        \n        I SMELL A WUMPUS!\n        YOU ARE IN ROOM 14\n        TUNNELS LEAD TO    4  13  15\n        (S)HOOT OR (M)OVE? \n\n\nReferences\n----------\n\nForth  \n\u003chttps://en.wikipedia.org/wiki/Forth_(programming_language)\u003e\n\nForth 200x  \n\u003chttp://www.forth200x.org/\u003e\n\nForth Standard  \n\u003chttps://forth-standard.org/\u003e\n\nForth Discussions  \n\u003chttps://github.com/ForthHub/discussion/discussions\u003e\n\nStarting Forth  \n\u003chttps://www.forth.com/starting-forth/\u003e\n\nThinking Forth  \n\u003chttps://thinking-forth.sourceforge.net/\u003e\n\nMoving Forth Series  \n\u003chttps://www.bradrodriguez.com/papers/\u003e\n\nThreaded Interpretive Languages  \n\u003chttps://archive.org/details/R.G.LoeligerThreadedInterpretiveLanguagesTheirDesignAndImplementationByteBooks1981\u003e\n\nBack \u0026 Forth (YouTube video series)  \n\u003chttps://www.youtube.com/@HansBezemer\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsirwumpus%2Fpost4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsirwumpus%2Fpost4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsirwumpus%2Fpost4/lists"}