add new tabstop-sets feature

ironsheep · Dec 10, 2022 · b92171f · b92171f
1 parent 4ac6205
commit b92171f
Show file tree

Hide file tree

Showing 8 changed files with 449 additions and 67 deletions.
diff --git a/InsertMode.md b/InsertMode.md
@@ -1,23 +1,21 @@
-# Insert Modes for Spin/Spin2 VSCode Extensions
+# Edit Modes for Spin/Spin2 VSCode Extensions
 
 
 ![Project Maintenance][maintenance-shield]
 [![License][license-shield]](LICENSE) 
 
 
-Recreation of [Parallax Propeller Tool](https://www.parallax.com/package/propeller-tool-software-for-windows-spin-assembly-2/) Insert Modes: Overtype, Insert, and Align for VSCode
+Recreation of [Parallax Propeller Tool](https://www.parallax.com/package/propeller-tool-software-for-windows-spin-assembly-2/) Edit Modes: Overtype, Insert, and Align for VSCode
 
 ## Features
 
 Adds an overtype mode to vscode based editors, plus a couple of bells and whistles.
 
-### Basic Insert Mode Usage
+### Edit Mode Usage
 
-The Insert Mode support for Spin/Spin2 provides three modes: Overtype, Insert and Align.
+The Edit Mode support for Spin/Spin2 provides three modes: **Overtype**, **Insert** and **Align**.
 
-The aptly named **Overtype mode** allows one to type over and replace existing characters in one's text editor. The most common scenario for overtype mode is when it's activated by accident by an unsuspecting user who can't figure out why the computer is eating all the words they already typed.
-
-To rotate through all insert modes, press the `Insert` key. If you don't have an `Insert` key, you can press `Fn+Enter` (on Mac). As an alternative you can also click on the Insert/Overtype/Align label to rotate through the insert modes.
+To rotate through all Edit Modes, press the `Insert` key. If you don't have an `Insert` key, you can press `Fn+Enter` (on Mac). If these don't work for you then `F11` also steps through the modes. As an alternative you can also click on the Insert/Overtype/Align label to rotate through the Edit Modes.
 
 If, instead, you wish to toggle back and forth between the Insert and Align modes only, press `Ctrl+Shift+I` (on Windows and Linux) or `Cmd+Shift+I` (on Mac)
 
@@ -29,25 +27,122 @@ If you don't care for these keybindings, you can customize them in your Keyboard
 |`Ctrl+Shift+I` (on Windows and Linux) </br>`Cmd+Shift+I` (on Mac) | `spin2.insertMode.toggle`:</br>Rotate thru: Insert -> Align -> and back to Insert...
 
 
-### Visual Demo: Overtype vs. Insert modes
+#### Edit Mode: Insert 
+
+This mode is your everyday typing mode. Where your cursor is you type and characters are entered shoving text to the right of the cursor to the right.
+
+#### Edit Mode: Overtype
+
+The aptly named **Overtype mode** allows one to type over and replace existing characters in one's text editor. The most common scenario for overtype mode is when it's activated by accident by an unsuspecting user who can't figure out why the computer is eating all the words they already typed.
+
+
+#### Edit Mode: Visual Demo: Overtype vs. Insert
 
 ![Basic demo](DOCs/demo-basic.gif)
 
-### Settings: Global or per-editor
 
-It's bad enough that you have to keep track of that damn overtype indicator at the bottom of the window... but you want to have a separate overtype setting for *each editor?*
+#### Edit Mode: Align
+
+*(Excerpt from Parallax "Propeller Tool" help)*:
+
+The **Align mode** is a special version of Edit Mode designed specifically for maintaining source code.  To understand Align mode we first need to consider common programming techniques. There are two very common practices used when writing modern source code:
+
+- indention of code
+- alignment of comments to the right of code
+
+It is also common for source code to be viewed and edited using more than one editor application. Historically, programmers have used either tabs or spaces for indention and alignment porposes, both of which prove problematic. Tab characters cause alignment issues because some ediros use different sized tab setting than others. Both tab and space characters cause alignment issues because future edits cause right-side comments to shift out of alignment. 
+
+For our spin code this alignment problem is solved first by disallowing tab characters (Tab key presses emit the proper number of space characters), and second by providing the Align Edit mode. While in Align mode characters inserted into a line affect the neighboring characters but not characters separated by more than one space. The result is that comments and other items separated by more than one space maintain their intended alignment for as long as possible.
+
+Note: This Align mode affects the behavior of the [Tab], [Shift+Tab], [Backspace], and [Delete] keys as well as pasting copied text.
+
+Since the Align mode maintains existing alignments as much as possible, much less time is wasted relaigning elements due to future edits by the programmer.  Additionally, since spaces are used instead of tab characters, the code maintains the same look and feel in any editor that displays it with a mono-spaced font.
+
+The Align mode isn't perfect for all situations, however. We recommend you use Insert mode for most code writing and briefly switch to Align mode to maintain existing code where alignment is a concern. The [Insert] key (or [F11]) rotates the mode through Insert -> Overwrite -> Align and back to Insert again.  The Ctrl+Shift+I (Cmd+Shift+I on mac) key shortcut toggles onlyh between Insert and Align modes.  A little practice with the Align and Insert modes will help you write code more time-efficiently.
+
+Note: since this Align mode is provided by our Spin2 VSCode extension, non-spin source (without the .spin or .spin2 extension) is not presented with align mode.
+
+The higher-level language (spin or spin2) for the propeller is fairly similar to python in that it has code indented to veriaous levels followed by comments:
+
+##### Example spin2 code:
+
+```spin
+PUB stopAfterTime(nTime, eTimeUnits) | timeNow
+'' Stops the motor, after {time} specified in {timeUnits} [DTU_MILLISEC or DTU_SEC] has elapsed.
+'' USE WITH:  driveAtPower()
+'' Will ABORT if {time} < 1
+    if nTime < 1                                   ' units make sense? (positive?)
+        abort                                      ' NO: abort
+
+    case eTimeUnits                                ' ensure we have a valid request
+        DTU_MILLISEC:
+        DTU_SEC:
+        other:
+            abort
+
+    if eTimeUnits == DTU_SEC                       ' want result in seconds
+        timeNow := getms()
+        motorStopMSecs := timeNow + (nTime * 1_000)
+    else
+        timeNow := getms()                         ' wants milliseconds
+        motorStopMSecs := timeNow + nTime
+
+PUB stopMotor()
+'' Stops the motor, killing any motion that was still in progress
+''  AFFECTED BY:holdAtStop()
+    setTargetAccel(0)
+
+PUB emergencyCutoff()
+'' EMERGENCY-Stop - Immediately stop motor, killing any motion that was still in progress
+    e_stop := TRUE
+    setTargetAccel(0)
+```
+
+While our lower-level propeller assembly code (pasm, pasm2) has, typically four or five columns to be aligned.
+
+##### Example pasm2 code:
+
+```pasm
+DAT
+        org
+.chr
+              call      #hsync                          'do hsync
+
+              add       font_line, #$08                 ' increment chr line selector
+              cmpsub    font_line, #$20         wz
+    if_z      add       font_base, #$080                ' increment top/middle/bottom lines selector
+    if_z      cmpsub    font_base, #$180        wz
+    if_z      add       screen_base, #cols              ' increment screen pointer and row
+    if_z      incmod    rowx, #rows-1           wz
+    if_nz     jmp       #.line                          ' loop until all rows output
+
+
+              callpa    #14, #blank                     ' bottom blanks
+
+              mov       pa, #10                         ' low vertical syncs
+.vsync1       xcont     m_880, #sync_color2
+              call      #hsync
+              djnz      pa, #.vsync1
+              
+              ...
+```
+
+**Formatting pasm code** - Aligning code like this is where Align mode shines!
+
+### Settings: Global or per-editor
 
-Fine.
+By default the Edit Mode setting is for all open editor windows.  However, if you wish it to be unique to each open editor window then we have a setting for you!
 
 ```json
 "spinInsertMode.perEditor": true
 ```
 
-> Sets the insert/overtype mode per editor.
+> Sets the insert/overtype mode per editor.</br>
+> Default: false
 
 ### Settings: Overtype Paste behavior
 
-If you want to enable "Hard Mode", you can turn on overtype paste mode. This setting applies overtype behavior to when you paste text into your editor. Here are the rules:
+If you want to enable it, you can turn on overtype paste mode. This setting applies overtype behavior to when you paste text into your editor. Here are the rules:
 
 - If you paste part of a line of text into another line of text, the clipboard contents will overwrite characters until it's done pasting, unless it hits the end of the line first, in which case it'll just extend that line.
 - If you already have some text selected when you paste, that text will *always* be overwritten, even if the contents of the clipboard are smaller.
@@ -57,16 +152,17 @@ If you want to enable "Hard Mode", you can turn on overtype paste mode. This set
 Some additional tips for using overtype paste:
 
 - Don't forget your Undo shortcut(s).
-- I know this doesn't work like [insert editor here]. Every single freaking editor handles overtype paste differently. It's not my fault.
-- If you think you have a saner way to handle this, for the love of everything warm and cuddly, let us know.
+- I know this doesn't work like [insert editor here]. Every single editor handles overtype paste differently. 
+- If you think you have a better way to handle this, please let us know.
 
-Without further ado...
+And here's the setting:
 
 ```json
 "spinInsertMode.overtypePaste": true
 ```
 
-> When in overtype mode, uses overtype behavior when pasting text.
+> When in overtype mode, uses overtype behavior when pasting text.</br>
+> Default: false
 
 ### Settings: Enable Align Mode
 
@@ -93,15 +189,15 @@ Don't worry, we've got just the setting for you!
 "spinInsertMode.labelAlignMode": "Aln"
 ```
 
-> Shows an abbreviated overtype status (`Ovr`) in the status bar if active, an abbreviated align status (`Aln`) in the status bar if activ and nothing for the "normal" insert mode.
+> Shows an abbreviated overtype status (`Ovr`) in the status bar if active, an abbreviated align status (`Aln`) in the status bar if activ and nothing for the "normal" Edit Mode.
 
 ```json
 "spinInsertMode.labelInsertMode": "",
 "spinInsertMode.labelOvertypeMode": ""
 "spinInsertMode.labelAlignMode": ""
 ```
 
-> Disable showing the insert mode status in the status bar completely.
+> Disable showing the Edit Mode status in the status bar completely.
 
 ### Settings: Overtype cursor style
 
@@ -118,7 +214,7 @@ Set the `spinInsertMode.secondaryCursorStyle` to either one of:
 e.g.
 
 ```json
-"spinInsertMode.secondaryCursorStyle": "underline"
+"spinInsertMode.secondaryCursorStyle": "block"
 ```
 
 > Sets the overtype cursor style.</br>

diff --git a/README.md b/README.md
@@ -22,8 +22,9 @@ The **P2 Forum Thread** containing discussion of [this VSCode support](https://f
 - **Syntax and Semantic Highlighting** for both Spin and Pasm
 - **Syntax and Semantic Highlighting** for both Spin2 and Pasm2 including all Streamer and Smart-pin Symbols as well as all debug() statements with parameter validation for all display types
 - **Custom tabbing** Tab-stop support per section à la Parallax **Propeller Tool**
+- **Tab Sets** You can choose between `Propeller Tool`, `IronSheep`, and `User1` (*adjust in settings to make your favorite set*)
 - File navigation from **Outline View**
-- Insert Mode support à la Parallax **Propeller Tool** [Insert, Overtype and Align]
+- **Edit Mode** support à la Parallax **Propeller Tool** [Insert, Overtype and Align]
 - Works with your favorite VSCode themes
 - Offers companion Theme (Two themes: Syntax+Semantic, and Syntax only - mostly used during semantic highlighting development)
 
@@ -62,47 +63,22 @@ This repository contains a single subproject which is the vscode extension:
 - SPIN2/SPIN and PASM2/PASM syntax Highlighting and code navigation [spin2](./spin2) - *Builds*
 
 
+
 ---
 
-> If you like my work and/or this has helped you in some way then feel free to help me out for a couple of :coffee:'s or :pizza: slices! 
-> 
-> [![coffee](https://www.buymeacoffee.com/assets/img/custom_images/black_img.png)](https://www.buymeacoffee.com/ironsheep)
+> If you like my work and/or this has helped you in some way then feel free to help me out for a couple of :coffee:'s or :pizza: slices!
+>
+> [![coffee](https://www.buymeacoffee.com/assets/img/custom_images/black_img.png)](https://www.buymeacoffee.com/ironsheep) &nbsp;&nbsp; -OR- &nbsp;&nbsp; [![Patreon](./DOCs/patreon.png)](https://www.patreon.com/IronSheep?fan_landing=true)[Patreon.com/IronSheep](https://www.patreon.com/IronSheep?fan_landing=true)
 
 ---
 
-
 ## Credits
 
 Ray [Cluso99] in our [Propeller 2 Forums](https://forums.parallax.com/categories/propeller-2-multicore-microcontroller) which started this effort for us.
 
 Patrick (GitHub [Entomy](https://github.com/Entomy)) for a spin1 extension which helped me get further along with this one.
 
-
-## Older install info (for reference only)
-
-If you had downloaded the .vsix.zip from our [Propeller 2 Forum thread](https://forums.parallax.com/discussion/170068/visual-studio-code-editor-for-p1-amp-p2-spin-amp-pasm#latest) then skip to the next section "**Load Extention into vscode**".
-
-While it's no longer needed, we still maintain our [Releases Page](https://github.com/ironsheep/P2-vscode-extensions/releases).
-
-### Manually Load Extension into vscode
-
-Now that you have downloaded the .vsix.zip file simply unzip it to get the .vsix file.
-
-Open a Command window (on linux, macos, rpi open a terminal window) and cd to the directory containing this file. 
-
-Execute this command:
-
-```bash
-code --install-extension {filename}.vsix
-```
-
-*(replacing {filename} with the name of your file, of course.)*
-
-After restarting VSCode you should be ready to start editing spin2 code.  Enjoy!
-
-NOTE: to activate one of the experimental themes distributed with this extension using Ctl-K Ctl-T (on macOS Cmd-K, Cmd-T) and select "Spin2 Ironsheep" or "Spin2 Cluso99".  Of course, your favorte themes should work as well.
-
-
+Jay B. Harlow for contributing the initial elastic tabs feature.
 
 ## License
 
@@ -113,8 +89,6 @@ Follow these links for more information:
 
 ### [Copyright](copyright) | [License](LICENSE)
 
-
-
 [maintenance-shield]: https://img.shields.io/badge/maintainer-stephen%40ironsheep%2ebiz-blue.svg?style=for-the-badge
 
 [marketplace-version]: https://vsmarketplacebadge.apphb.com/version-short/ironsheepproductionsllc.spin2.svg

diff --git a/spin2/CHANGELOG.md b/spin2/CHANGELOG.md
@@ -13,7 +13,6 @@ Work to appear in upcoming releases:
 
 Possible next additions:
 
-- Add Named TAB configurations (have "Propeller Tool" tabs and your own custom set of tabs)
 - Add Hover popups for `PUB` and `PRI` method signature (help text)
 - Add Hover popups for pasm instructions (help text for each instruction)
 - Update theme to work better with a couple common languages we use near our P2 projects (e.g., Python)
@@ -22,6 +21,14 @@ Possible next additions:
 - Add new-file templates as Snippets
 - Add additional Snippets as the community identifies them
 
+## [1.7.3] 2022-12-09
+
+Minor update to Extension Settings
+
+- Add Named TAB configurations (select between `Propeller Tool`, `IronSheep` or your own custom `User1` tabs)
+- The extension default is `Propeller Tool`
+- The `IronSheep` configuration is derived from Propeller Tool but realigned to "tabstop: 4" (every 4 spaces)
+
 ## [1.7.2] 2022-12-07
 
 Update Spin highlighting (syntax and/or semantic parser fixes)

diff --git a/spin2/README.md b/spin2/README.md
@@ -1,6 +1,6 @@
 # P1 and P2 Syntax highlighting and Code Navigation for VSCode
 
-This Extension is continually in development. Things may not totally work correctly. See _Support_, below, for how to report issues.
+This Extension is continually in development. Things may, occasionally, not work correctly. See _Support_, below, for how to report issues.
 
 ## ABOUT
 
@@ -36,7 +36,7 @@ _Hint:_ Configure the OUTLINE panel to `"Sort by Position"` to reflect the order
 - Place cursor on line and press `TAB` or `Shift-TAB` to indent or outdent the text
 - Place cursor on line and press `Ctrl+Alt+Tab` to generate tab location comment
 - Supports the InsertMode operations à la Propeller Tool (*INSERT / OVERTYPE / ALIGN modes*) see [Insert Mode for Spin/Spin2](https://github.com/ironsheep/P2-vscode-extensions/blob/main/InsertMode.md) for more detailed info on this InsertMode feature.
-
+- **Tab Sets** You can choose between `Propeller Tool`(*Default*), `IronSheep`, and `User1` (*adjust in settings to make your favorite set*)
 
 ## Possible Conflicts with other VSCode Extensions
 
@@ -59,3 +59,11 @@ We are working on fixes to the following issues we've seen during our testing. H
 ## Reporting Issues
 
 An active list of issues is maintained at github. [P2-vscode-extensions/Issues](https://github.com/ironsheep/P2-vscode-extensions/issues). When you want to report something missing, not working right, or even request a new feature please submit an issue. By doing so you will be able to track progress against the request and learn of the new version containing your fix/enhancement when it is available.
+
+---
+
+> If you like my work and/or this has helped you in some way then feel free to help me out for a couple of :coffee:'s or :pizza: slices!
+>
+> [![coffee](https://www.buymeacoffee.com/assets/img/custom_images/black_img.png)](https://www.buymeacoffee.com/ironsheep) &nbsp;&nbsp; -OR- &nbsp;&nbsp; [![Patreon](./Images/patreon.png)](https://www.patreon.com/IronSheep?fan_landing=true)[Patreon.com/IronSheep](https://www.patreon.com/IronSheep?fan_landing=true)
+
+---