diff --git a/README.md b/README.md index 96d28ab..595183c 100755 --- a/README.md +++ b/README.md @@ -58,6 +58,8 @@ Glossary of Words ----------------- * [Standard Core](./doc/standard.md) +* [ANSI Terminal](./doc/ansiterm.md) +* [Assertions & Testing](./doc/assert.md) * [Block File](./doc/block.md) * [Double-Cell](./doc/double.md) * [File Access](./doc/file.md) diff --git a/doc/README.md b/doc/README.md index 65dabf2..dcdd7af 100644 --- a/doc/README.md +++ b/doc/README.md @@ -8,6 +8,8 @@ Glossary of Words ----------------- * [Standard Core](standard.md) +* [ANSI Terminal](ansiterm.md) +* [Assertions & Testing](assert.md) * [Block File](block.md) * [Double-Cell](double.md) * [File Access](file.md) diff --git a/doc/ansiterm.md b/doc/ansiterm.md new file mode 100644 index 0000000..d721aa1 --- /dev/null +++ b/doc/ansiterm.md @@ -0,0 +1,125 @@ +Post4 (Post-Forth) +================== + +Copyright 2007, 2024 Anthony Howe. All rights reserved. + + +### ANSI Terminal Words + +Post4 assumes that the terminal is ANSI / VT-100 compatible. + + +#### AT-XY +( `col` `row` -- ) +Position cursor on the terminal, `row` and `col` are zero (0) based. This word is a standard word. + +- - - +#### PAGE +( -- ) +Clear the terminal (advance next page). This word is a standard word. + +- - - + +### Post4 Specific Words + +To use this extension word set: + + include-path post4/ansiterm.p4 + + +#### ansi_normal +( -- ) + +- - - +#### ansi_bold +( -- ) + +- - - +#### ansi_dim +( -- ) + +- - - +#### ansi_standout +( -- ) + +- - - +#### ansi_underline +( -- ) + +- - - +#### ansi_blink +( -- ) + +- - - +#### ansi_reverse +( -- ) + +- - - +#### ansi_hide +( -- ) + +- - - +#### ansi_black +( -- ) + +- - - +#### ansi_red +( -- ) + +- - - +#### ansi_green +( -- ) + +- - - +#### ansi_yellow +( -- ) + +- - - +#### ansi_blue +( -- ) + +- - - +#### ansi_magenta +( -- ) + +- - - +#### ansi_cyan +( -- ) + +- - - +#### ansi_white +( -- ) + +- - - +#### ansi_bg_black +( -- ) + +- - - +#### ansi_bg_red +( -- ) + +- - - +#### ansi_bg_green +( -- ) + +- - - +#### ansi_bg_yellow +( -- ) + +- - - +#### ansi_bg_blue +( -- ) + +- - - +#### ansi_bg_magenta +( -- ) + +- - - +#### ansi_bg_cyan +( -- ) + +- - - +#### ansi_bg_white +( -- ) + +- - - diff --git a/doc/assert.md b/doc/assert.md new file mode 100644 index 0000000..6db73e4 --- /dev/null +++ b/doc/assert.md @@ -0,0 +1,96 @@ +Post4 (Post-Forth) +================== + +Copyright 2007, 2024 Anthony Howe. All rights reserved. + + +### Test Case Words + +To use this extension word set: + + include-path post4/assert.p4 + +A test case typically takes the form of + + T{ -> }T + +For example: + + T{ 1 2.71828 3 -> 1 2.71828 3 }T + T{ 1 2 + -> 3 }T + +- - - +#### T{ +( -- ) +Start a test case. + +- - - +#### -> +( -- ) +Separate the test case results from the expected data and float stack. + +- - - +#### }T +( -- ) +Compare the test results on the stacks against the expected data and float stacks, counting a pass, fail, or skipped result if the stacks fail to match. + +- - - + +### Post4 Specific Words + +An example of a test group: + + .( INVERT ) test_group + t{ FALSE INVERT -> TRUE }t + t{ TRUE INVERT -> FALSE }t + t{ 0 INVERT -> -1 }t + test_group_end + +See the Post4 unit test suite (`test/units.p4`) based on the Forth Standard section F for examples. + +- - - +#### assert +( `bool` -- ) +If `bool` is `TRUE` then count a pass result, otherwise count a failed result. + +- - - +#### assert_not +( `bool` -- ) +If `bool` is `FALSE` then count a pass result, otherwise count a failed result. + +- - - +#### assert_skip +( `bool` -- ) +If `bool` is `TRUE` then count a pass result, otherwise count a skipped result. + +- - - +#### assert_not_skip +( `bool` -- ) +If `bool` is `FALSE` then count a pass result, otherwise count a skipped result. + +- - - +#### test_group +( -- ) +Start a test group and set a marker `rm_test_group`. + +- - - +#### test_group_end +( -- ) +End a test group and execute `rm_test_group` to clean-up the environment of test data and words. + +- - - +#### test_suite +( -- ) +Start a test suite, which is a collection of test groups and test cases. The stacks and counts are also cleared. + +- - - +#### test_suite_end +( -- ) +End a test suite and report the results, stack size, passed, failed, and skipped. If there were any failures, then Post4 exits with status code `1`; skipped results do not terminate Post4. + +- - - +#### ts{ +( -- ) +Start a test case and if the result is a failure, count it as skipped instead. Test-skip is useful while developing a test case or if a test case is expected fail, but the test suite should continue. + +- - -