Releasing Version 1.0.0

- Added the `%exit` command language command to exit the tbp debugger. Closes #1. - Now tbp behaves like a normal command line application when the user hits `CTRL+C` and `CTRL+D`. Closes #3. - Fixed the copyright on top of all Python files. For some reason I thought it was 2004. Closes #43. - Added the combined coverage report summary to the CI.yml output. That makes it easier to see what didn't have coverage. Closes #44. - Added the `tiny_basic_grammar.ebnf` and `grammar_tests.txt` that I forgot to bring over from the dead repository. Closes #45. - Added better error reporting on `INPUT` entry errors and escaped syntax error strings, so characters like `\n` are displayed correctly. Closes #46. - Did a pass to eliminate any dead code. Closes #47. - Did a final editing pass on all documentation.
John-Robbins · Sep 16, 2024 · 275b3be · 275b3be
2 parents 1e585cd + 65b939d
commit 275b3be
Show file tree

Hide file tree

Showing 48 changed files with 841 additions and 342 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -273,14 +273,18 @@ jobs:
         pattern: covdata-*
         merge-multiple: true
     - name: "Combine and Report"
-      # Get the code coverage data.
+      # Get the code coverage data. Since GITHUB_STEP_SUMMARY is markdown, I
+      # need to add the ```test...``` around the report output so it's rendered
+      # as text and looks normal.
       run: |
         coverage combine
-        coverage report --precision=2 --show-missing --sort=Cover --skip-covered
+        echo '```' >> $GITHUB_STEP_SUMMARY
+        coverage report --precision=2 --show-missing --sort=Cover --skip-covered >> $GITHUB_STEP_SUMMARY
+        echo '```' >> $GITHUB_STEP_SUMMARY
         coverage json --fail-under=98
         export TOTAL_COVERAGE=$(python -c "import json;print(round(float(json.load(open('coverage.json'))['totals']['percent_covered']),2))")
         echo "total_coverage=$TOTAL_COVERAGE" >> $GITHUB_ENV
-        echo "## Total coverage: :fire: ${TOTAL_COVERAGE}% :fireworks:" >> $GITHUB_STEP_SUMMARY
+        echo "## Total Coverage: :fire: ${TOTAL_COVERAGE}% :fire:" >> $GITHUB_STEP_SUMMARY
     - name: "Make Coverage Badge"
       # Code coverage is only updated on main branch.
       if: (github.ref == 'refs/heads/main')

diff --git a/.vscode/ltex.dictionary.en-US.txt b/.vscode/ltex.dictionary.en-US.txt
@@ -77,3 +77,7 @@ monorepo
 %endraw%
 hack-arounds
 mergeable
+KeyBoardInterrupt
+EOFError
+controlkeys
+uv
diff --git a/.vscode/ltex.hiddenFalsePositives.en-US.txt b/.vscode/ltex.hiddenFalsePositives.en-US.txt
@@ -33,3 +33,5 @@
 {"rule":"TOO_LONG_PARAGRAPH","sentence":"^\\Q^8: And pointing the fickle finger of blame!\\E$"}
 {"rule":"UNLIKELY_OPENING_PUNCTUATION","sentence":"^\\Q:crossed_fingers: (Thanks for your patience!)\\E$"}
 {"rule":"WORD_CONTAINS_UNDERSCORE","sentence":"^\\Q:crossed_fingers: (Thanks for your patience!)\\E$"}
+{"rule":"NON_STANDARD_WORD","sentence":"^\\QHow does tbp handle CTRL+C and CTRL+D (CTRL+Z, ENTER on Windows)?\\E$"}
+{"rule":"EN_A_VS_AN","sentence":"^\\QIf you do forget to end on an \\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q statement, tbp handles that case correctly.\\E$"}
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -51,6 +51,7 @@
         "Dependa",
         "Diffie",
         "dorny",
+        "ELIT",
         "España",
         "Esser",
         "ETURN",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,34 @@
 
 ---
 
+## 1.0.0 (2024-09-15)
+
+- Added the `%exit` command language command to exit the tbp debugger. Documented [here](https://john-robbins.github.io/tbp/tbp-command-language#exiting-the-debugger-e--exit). Closes [#1](https://github.com/John-Robbins/tbp/issues/1).
+- Now tbp behaves like a normal command line application when the user hits `CTRL+C` and `CTRL+D`. Documented [here](https://john-robbins.github.io/tbp/faq#general-usage). Closes [#3](https://github.com/John-Robbins/tbp/issues/3).
+- Fixed the copyright on top of all Python files. For some reason I thought it was 2004. Closes [#43](https://github.com/John-Robbins/tbp/issues/43).
+- Added the combined coverage report summary to the CI.yml output. That makes it easier to see what didn't have coverage. Closes [#44](https://github.com/John-Robbins/tbp/issues/44). Sorry, the below is just too sexy not to show. :joy_cat:
+
+    ```text
+    Name                        Stmts   Miss Branch BrPart   Cover   Missing
+
+    ------------------------------------------------------------------------
+
+    tests/controlkeys_test.py      88      0     20      1  99.07%   72->exit
+    tests/interpreter_test.py     510      0     14      2  99.62%   885->exit, 904->exit
+    ------------------------------------------------------------------------
+
+    TOTAL                        2253      0    252      3  99.88%
+
+    13 files skipped due to complete coverage.
+    ```
+
+- Added the `tiny_basic_grammar.ebnf` and `grammar_tests.txt` that I forgot to bring over from the dead repository. Closes [#45](https://github.com/John-Robbins/tbp/issues/45).
+- Added better error reporting on `INPUT` entry errors and escaped syntax error strings, so characters like `\n` are displayed correctly. Closes [#46](https://github.com/John-Robbins/tbp/issues/46).
+- Did a pass to eliminate any dead code. Closes [#47](https://github.com/John-Robbins/tbp/issues/47).
+- Did a final editing pass on all documentation.
+
+---
+
 ## 0.9.1 (2024-09-09)
 
 ---
@@ -12,6 +40,8 @@
 - Updated the README and [Getting Started Installation](https://john-robbins.github.io/tbp/getting-started#installation) section to point to the Latest releases.
 - This is basically a practice release to ensure I have the steps down. :crossed_fingers: (Thanks for your patience!)
 
+---
+
 ## 0.9.0 (2024-09-06)
 
 ---

diff --git a/README.md b/README.md
@@ -60,7 +60,7 @@ It seemed nuts to put this up on PyPI, which is for important modules, not learn
 
 ### Cloning and Installing
 
-Download the code from the [Latest](https://github.com/John-Robbins/tbp/releases/latest) release. Expand the compressed file into a directory, then execute the following.
+Download the code from the [Latest Releases](https://github.com/John-Robbins/tbp/releases/latest). Expand the compressed file into a directory, then execute the following.
 
 ```bash
 % pip install .
@@ -70,7 +70,7 @@ Download the code from the [Latest](https://github.com/John-Robbins/tbp/releases
 
 ## :book: Documentation
 
-Everything about tbp is lovingly documented to death in the GitHub Pages for this repository: [https://John-Robbins.github.io/tbp](https://John-Robbins.github.io/tbp).
+Everything about tbp is lovingly documented to death in over 17,000 words in the GitHub Pages for this repository: [https://John-Robbins.github.io/tbp](https://John-Robbins.github.io/tbp).
 
 ## :clap: Acknowledgements
 
@@ -92,7 +92,7 @@ Marco's [TinyBasicBlazor](https://retrobits.altervista.org/tinybasicblazor/), a
 
 ### :heart: YOU! :heart:
 
-Thank you so much for looking at tbp. It's my first Python project and first time using GitHub Actions so any feedback on what I can do better, or what I did wrong, greatly is appreciated. Hit me up in the [Issues](https://github.com/John-Robbins/tbp/issues).
+Thank you so much for looking at tbp. It's my first Python project and first time using GitHub Actions so any feedback on what I can do better, or what I did wrong, is greatly appreciated. Hit me up in the [Issues](https://github.com/John-Robbins/tbp/issues).
 
 *To all of you, thanks! I'm a Python beginner standing on the shoulders of giants!*
 

diff --git a/docs/_config.yml b/docs/_config.yml
@@ -61,4 +61,4 @@ liquid:
 # Footer content appears at the bottom of every page's main content
 # Note: The footer_content option is deprecated and will be removed in a future major release.
 # Please use `_includes/footer_custom.html` for more robust markup / liquid-based content.
-footer_content: "Copyright &copy; 2024 John Robbins. Distributed by an <a href=\"https://github.com/John-Robbins/tbp/tree/main/LICENSE.txt\">MIT license.</a>"
+footer_content: "Copyright &copy; 2024 John Robbins. Distributed by an <a href=\"https://github.com/John-Robbins/tbp/blob/main/LICENSE\">MIT license.</a>"
diff --git a/docs/_data/version.yml b/docs/_data/version.yml
@@ -1 +1 @@
-number: 0.9.1
+number: 1.0.0
diff --git a/docs/docs/command-language.md b/docs/docs/command-language.md
@@ -92,7 +92,7 @@ LINT #04: Potentially uninitialized variable 'B'.
 ---------------------------------^
 ```
 
-Ideally, the next step would be to build an engine that would walk the program looking for the execution flow to find if the program initializes a variable during a run. That's something I do want to look at.
+Ideally, the next step would be to build an engine that would walk the program looking for the execution flow to find if the program initializes a variable during a run. That's something I do want to look at in future versions of tbp.
 
 #### `%lint` Command Error Messages
 
@@ -109,11 +109,6 @@ Loads the specified file from disk. You must surround the filename by quote char
 
 When loading a file, tbp assumes all lines in the file are [Tiny BASIC language](tb-language) statements, so any tbp command language commands will be reported as an error.
 
-```text
-tbp:>%lf "./examples/srps.tbp"
-tbp:>
-```
-
 If the `run_on_load` option is true, the loaded file will automatically execute a [`RUN`](tb-language#run---execute-the-program-in-memory) statement. The default for `run_on_load` is false.
 
 Obviously, you cannot use the `%loadfile` command if stopped at a breakpoint.[^3]
@@ -207,11 +202,11 @@ tbp:>run
 
 ## The Tiny BASIC in Python Debugger
 
-The tbp debugger is a full-featured debugger that allows breakpoints on lines, stepping, variable display, and call stack display. What more could a developer want? For this section, I will be debugging the [`pas.tbp`](https://github.com/John-Robbins/tbp/blob/main/examples/pas.tbp) program, which you can find in the tbp examples folder, if you would like to practice as you read along.
+The tbp debugger is a full-featured debugger that allows breakpoints on lines, stepping, variable display, and call stack display. What more could a developer want? For this section, I will be debugging [Winston (Winny) Weinert's](https://github.com/winny-/tinybasic.rkt) wonderful Pascal Triangle program, [`pas.tbp`](https://github.com/John-Robbins/tbp/blob/main/examples/pas.tbp), which you can find in the tbp examples folder, if you would like to practice as you read along.
 
 ### Setting and Listing Breakpoints: `%bp` | `%break`
 
-To start a debugging session, start by setting a breakpoint on the line number where you want to stop. In the example below, I wanted to set breakpoints on several lines of a loaded program.
+To enter a debugging session, start by setting a breakpoint on the line number where you want to stop. In the example below, I wanted to set breakpoints on several lines of a loaded program.
 
 ```text
 tbp:>list 180,220
@@ -275,7 +270,7 @@ Breakpoint: 200
 DEBUG(200):>
 ```
 
-When you hit a breakpoint, tbp displays the line in square brackets and changes the prompt to show you are in the debugger with `DEBUG` and the line number of the breakpoint. In this case, the prompt is `DEBUG(200):>`.
+When you hit a breakpoint, tbp displays the breakpoint line in square brackets and changes the prompt to show you are in the debugger with `DEBUG` and the line number of the breakpoint. In this case, the prompt is `DEBUG(200):>`.
 
 ### Show Variables: `%v` | `%vars`
 
@@ -315,7 +310,7 @@ C=3         I=1         J=26        N=10        S=256
 DEBUG(200):>
 ```
 
-### Seeing the Call Stack
+### Seeing the Call Stack: `%bt` | `%backtrace`
 
 While Tiny BASIC is not a language you are going use to write a recursive descent parser, it does support calling procedures with [`GOSUB`](tb-language#gosubreturn---call-toreturn-from-a-procedure) and [`RETURN`](tb-language#gosubreturn---call-toreturn-from-a-procedure). Using the [`deep.tbp`](https://github.com/John-Robbins/tbp/blob/main/examples/deep.tbp) test program here's an example of its output.
 
@@ -333,6 +328,15 @@ DEBUG(200):>%bt
 DEBUG(200):>
 ```
 
+### Exiting the Debugger: `%e` | `%exit`
+
+If you want to stop debugging and end program execution while at a debugger prompt, use the `%e` command to return to the normal tbp prompt.
+
+```text
+DEBUG(420):>%exit
+tbp:>
+```
+
 ### Debugging Tips and Tricks
 
 When stopped at the debugger prompt, if you want to change a variable, use the regular Tiny BASIC assignment statement.

diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md
@@ -20,16 +20,15 @@ Thank you so much for any and all contributions to Tiny BASIC in Python! As this
 Before submitting a pull request, please help me out by doing the following.
 
 - File an issue explaining the bug or mistake in the code.
-- If the issue is not following best practices, please explain what I did wrong or include a link to a website/repository showing why I need to make the change.
-- This is all about me learning after all, so I appreciate the pointers.
+- If the issue is not following best practices, please explain what I did wrong or include a link to a website/repository showing why I need to make the change. This is all about me learning after all, so I really appreciate the pointers.
 
 ## Setting Up Your Development Environment
 
 All my development occurred on Python version 3.12.1, but any higher versions will work as the CI GitHub Actions are using 3.12.5.
 
 ### macOS Sonoma and Linux
 
-Note: I haven't tested these scripts on Linux, but they should work. Let me know if they don't.
+*Note: I haven't tested these scripts on Linux, but they should work. Let me know if they don't.*
 
 In the `./tools` directory are two shell scripts I used to jump set up my environment. First ensure that you don't have a virtual environment active. If you do, execute `deactivate`. In the tbp code root directory, run the following three commands in your terminal.
 
@@ -53,7 +52,7 @@ Note that I don't have a Windows computer, so I am going off memory and reading
 
 For Windows, you will need to do the script steps manually in the tbp code root directory at a PowerShell command prompt.
 
-First look to see if the `VIRTUAL_ENV` is set, which says you have a virtual environment already active. Run the Windows equivalent to `deactivate` to disable that virtual environment.
+First look to see if the `VIRTUAL_ENV` environment variable exists, which indicates you have a virtual environment already active. Run the Windows equivalent to `deactivate` to disable that virtual environment.
 
 In your PowerShell command prompt, execute the following commands to create a virtual environment for tbp.
 
@@ -67,17 +66,17 @@ You may have to shut down and restart PowerShell.
 In your PowerShell command prompt, in the tbp code root directory, execute the following commands.
 
 ```powershell
-python -m pip install $dryrun --upgrade pip
-python -m pip install $dryrun .[dev]
-python -m pip install $dryrun --editable .
+python -m pip install --upgrade pip
+python -m pip install .[dev]
+python -m pip install --editable .
 ```
 
 ## Key Development Notes
 
 <!-- markdownlint-disable-next-line -->
 <span style="color:red">**UNIT TESTS AND CODE COVERAGE ARE EVERYTHING!**</span>
 
-At the time of this writing, there are 280 unit tests and the combined operating system code coverage of 99.92%. For any pull requests, I'll obviously be checking that any code changes have tests that execute the code. _No coverage, no merge._
+At the time of this writing, there are 290 unit tests and the combined operating system code coverage of 99.88% with 100% coverage for the tbp code. For any pull requests, I'll obviously be checking that any code changes have tests that execute the code. *No coverage, no merge!*
 
 If you have a version of `make` installed, the root directory has the `Makefile` that automates a ton of work for you. Simply running `make` will do the work of running `mypy`, `ruff`, `pylint`, `coverage.py`, and `pytest`.
 
@@ -86,7 +85,7 @@ Here's what the output looks like on macOS. `Makefile` is your best friend when
 ```text
 % make
 mypy --config-file pyproject.toml src/ tests/
-Success: no issues found in 28 source files
+Success: no issues found in 29 source files
 ruff check --config ./pyproject.toml src/ tests/
 All checks passed!
 pylint --rcfile pyproject.toml src/ tests/
@@ -100,40 +99,41 @@ platform darwin -- Python 3.12.1, pytest-8.3.2, pluggy-1.5.0
 rootdir: /Users/johnrobbins/Code/tbp
 configfile: onsole_output_style=classic
 plugins: anyio-4.4.0
-collected 280 items
-
-tests/cmd_lang_test.py ..........                                        [  3%]
-tests/debugger_test.py .....................                             [ 11%]
-tests/driver_test.py ........................                            [ 19%]
-tests/helpers_test.py ...........                                        [ 23%]
-tests/interpreter_test.py .............................................. [ 40%]
-...........................                                              [ 49%]
-tests/lang_test.py ..                                                    [ 50%]
-tests/linter_test.py ..........................                          [ 59%]
-tests/memory_test.py .                                                   [ 60%]
+collected 290 items
+
+tests/cmd_lang_test.py ...........                                       [  3%]
+tests/controlkeys_test.py .......                                        [  6%]
+tests/debugger_test.py .......................                           [ 14%]
+tests/driver_test.py ........................                            [ 22%]
+tests/helpers_test.py ...........                                        [ 26%]
+tests/interpreter_test.py .............................................. [ 42%]
+...........................                                              [ 51%]
+tests/lang_test.py ..                                                    [ 52%]
+tests/linter_test.py ..........................                          [ 61%]
+tests/memory_test.py .                                                   [ 61%]
 tests/parser_test.py ................................................... [ 78%]
 .................                                                        [ 84%]
 tests/scanner_test.py ...................................                [ 96%]
 tests/symboltable_test.py ........                                       [ 99%]
 tests/tokens_test.py .                                                   [100%]
 
 ------ generated xml file: /Users/johnrobbins/Code/tbp/.test-results.xml -------
-============================= 280 passed in 1.05s ==============================
+============================= 290 passed in 0.93s ==============================
 coverage report --precision=2 --show-missing --sort=Cover --skip-covered
 Name                        Stmts   Miss Branch BrPart   Cover   Missing
 ------------------------------------------------------------------------
-src/tbp/helpers.py             82      8     22      2  90.38%   21-23, 187-191, 235-236
-src/tbp/driver.py             216      4    108      6  96.91%   86->88, 89->91, 138, 166, 311-312, 389->exit, 421->exit
-src/tbp/astprinter.py         142      3     28      2  97.06%   111-112, 277
-src/tbp/interpreter.py        499      5    186      7  98.25%   201->205, 356->360, 415->420, 578->exit, 600->603, 1047-1048, 1134-1136
-src/tbp/parser.py             275      3    116      2  98.72%   359->364, 486-488, 509->526
+src/tbp/helpers.py             79      4     22      1  95.05%   21-23, 231-232
+src/tbp/driver.py             237      2    120      8  97.20%   87->89, 90->92, 128->112, 142->112, 180, 211, 436->exit, 466->exit
+src/tbp/interpreter.py        496      2    186      6  98.83%   209->213, 359->363, 418->423, 581->exit, 603->606, 1053-1054
 src/tbp/languageitems.py      170      1      8      1  98.88%   192
 src/tbp/scanner.py            242      1    128      3  98.92%   211->exit, 320, 356->360
+tests/controlkeys_test.py      88      0     20      1  99.07%   72->exit
+src/tbp/parser.py             271      0    116      2  99.48%   357->362, 502->519
 tests/interpreter_test.py     510      0     14      2  99.62%   885->exit, 904->exit
 ------------------------------------------------------------------------
-TOTAL                        3994     25    870     25  98.97%
+TOTAL                        4108     10    910     24  99.32%
 
-19 files skipped due to complete coverage.
+20 files skipped due to complete coverage.
 coverage lcov
 Wrote LCOV report to .coverage.lcov
 ```