20 support dialects of basic (#30)

* Prepare basic-mode to support different dialects Different BASIC dialects will be supported using derived modes with their own set of keywords to highlight. Change variables related to syntax highlighting and indentation so they can be modified by a derived mode. Add new function basic-mode-initialize that uses the variables to initialize syntax highlighting and indentation at the end of the derived mode initialization. Add some derived modes as examples. * Improved M100 support (#31) * First pass at N82 support * Sample program basic-m100-mode * Finish up m100 keywords There were several keywords that were misfiled or simply missing. Those have been double checked now against a few different sources.:(ASCII listing of all possible BASIC tokens, Exploring the M100 (Appendix C), the Disk/Video Interface Manual, The Tandy 200 Technical Reference. * Sample CRT-BASIC extension CRT-BASIC is what NEC called the version of BASIC that appears when the CRT (Tube) monitor adatper (NEC PC-8341A) is plugged in. It has facilities for drawing lines, boxes, and circles. * Cleaned up N82 BASIC and M100 BASIC; added CRT-BASIC Used M100 Disk/Video Interface manual to ensure correctness of added BASIC commands. (eg DSKI$) Used N82 BASIC Reference plus my own tokenized token detector to add unusal N82 commands. (DSKF, FORMAT) Used NEC manual for PC-8341A (CRT adapter for the PC-8201A) to add the BASIC keywords that are availble using it (COLOR, CIRCLE, BOXa, etc.) * Add QuickBasic mode and generic mode Remove all but the most basic functions, builtins and keywords from the main basic-mode. Add basic-generic-mode as the default mode for unknown BASIC dialects. * Update documentation Co-authored-by: hackerb9 <[email protected]>
dykstrom · Dec 17, 2022 · b719ab1 · b719ab1
1 parent 1d6cd9a
commit b719ab1
Show file tree

Hide file tree

Showing 8 changed files with 891 additions and 89 deletions.
diff --git a/README.md b/README.md
@@ -11,8 +11,23 @@
 
 Package basic-mode provides a major mode for editing BASIC code in GNU Emacs.
 Features include syntax highlighting and indentation, as well as support for
-auto-numbering and renumering of code lines.
-
+auto-numbering and renumbering of code lines.
+
+<!-- TOC -->
+* [basic-mode](#basic-mode)
+  * [Installation](#installation)
+  * [BASIC Dialects](#basic-dialects)
+    * [Setting Sub Mode](#setting-sub-mode)
+      * [Manually](#manually)
+      * [File Variable](#file-variable)
+      * [Init File](#init-file)
+    * [Available Sub Modes](#available-sub-modes)
+  * [Usage](#usage)
+    * [Formatting Code](#formatting-code)
+    * [Line Numbers](#line-numbers)
+    * [Navigation](#navigation)
+  * [Configuration](#configuration)
+<!-- TOC -->
 
 ## Installation
 
@@ -22,11 +37,92 @@ To install manually, place basic-mode.el in your load-path, and add the
 following lines of code to your init file:
 
 ```elisp
-(autoload 'basic-mode "basic-mode" "Major mode for editing BASIC code." t)
-(add-to-list 'auto-mode-alist '("\\.bas\\'" . basic-mode))
+(autoload 'basic-generic-mode "basic-mode" "Major mode for editing BASIC code." t)
+(add-to-list 'auto-mode-alist '("\\.bas\\'" . basic-generic-mode))
+```
+
+
+## BASIC Dialects
+
+Package basic-mode supports some of the many
+[BASIC dialects](https://en.wikipedia.org/wiki/List_of_BASIC_dialects) using
+sub modes derived from the main basic-mode. Section
+[Available Sub Modes](#available-sub-modes) lists the currently existing
+sub modes. In addition, basic-mode also provides a generic sub mode that will
+be used if no sub mode is specified.
+
+The sub mode configures, among other things, syntax highlighting and indentation,
+which differs between dialects.
+
+
+### Setting Sub Mode
+
+By default, basic-mode will open BASIC files in sub mode _basic-generic-mode_.
+There are several ways to change that behaviour if you prefer a specific sub mode.
+
+
+#### Manually
+
+After opening a file in Emacs, you can type _M-x MODE-NAME_ to set the sub mode,
+e.g. _M-x basic-zx81-mode_ to set the Sinclair ZX81 sub mode.
+
+
+#### File Variable
+
+You can specify the sub mode as a file variable in the first line of the file, see
+[Specifying File Variables](https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html)
+in the GNU Emacs Manual. For example, a file beginning with this line, will open in
+the TRS-80 Model 100 sub mode.
+
+```BASIC
+10 REM -*- basic-m100 -*-
+```
+
+#### Init File
+
+If you are always working with a specific BASIC dialect, you can configure Emacs to
+always open BASIC files in that sub mode. For example, adding the below line to your
+init file will open all BASIC files in the Sinclair ZX81 sub mode.
+
+```elisp
+(add-to-list 'auto-mode-alist '("\\.bas\\'" . basic-zx81-mode))
 ```
 
 
+### Available Sub Modes
+
+This table lists the existing sub modes. If you feel that a sub mode
+is missing, the best way to bring it into existence is to create it
+yourself, and submit a pull request to include it in basic-mode.
+
+<table>
+  <tr>
+    <th align="left">BASIC Dialect</th>
+    <th align="left">Sub Mode</th>
+  </tr>
+  <tr>
+    <td>Microsoft QuickBasic 4.5</td>
+    <td>basic-qb45-mode</td>
+  </tr>
+  <tr>
+    <td>Sinclair ZX81</td>
+    <td>basic-zx81-mode</td>
+  </tr>
+  <tr>
+    <td>Sinclair ZX Spectrum</td>
+    <td>basic-spectrum-mode</td>
+  </tr>
+  <tr>
+    <td>TRS-80 Model I and III</td>
+    <td>basic-trs80-mode</td>
+  </tr>
+  <tr>
+    <td>TRS-80 Model 100</td>
+    <td>basic-m100-mode</td>
+  </tr>
+</table>
+
+
 ## Usage
 
 
@@ -124,3 +220,6 @@ in some way:
     <td>t</td>
   </tr>
 </table>
+
+Additionally, each sub mode will also define a hook variable, named like
+the sub mode, e.g. _basic-generic-mode-hook_ for the generic sub mode.