Commit 8cfc9af7 authored by Zachary Goldstein's avatar Zachary Goldstein
Browse files

Big Update: finished documentation AND added support for the native Sublime comment shortcut

parent 20ab91f5
UMASM Syntax Highlighters
Author: Zachary Goldstein (zgolds01), Tufts University
Created: 23 Apr 2020
Last Modified: 14 Nov 2020
A note from the author:
The inspiration for this package was my final project for COMP 0040 (in
the spring semester of 2020), the RPN calculator.
Designing an RPN calculator in an assembly-level language is an interesting
challenge, but I found that programming without UMASM specific syntax
highlighting was often frustrating.
After attempting to program in UMASM for a few hours, I decided that I
could not bring myself to work with unformatted, not-at-all-beautified,
plain-text code. Since I have a particular proclivity for productive
procrastination, I spent some time implementing a UMASM syntax highlighter
for Sublime 3.
I implemented two versions:
1) The first is simpler. It will style any .ums file using a color
scheme similar to Sublime's default C highlighter.
2) The second includes additional regex that can identify and
highlight ill-formed code.
Since then, support has (maybe) been added for other popular text editors.
......@@ -12,13 +12,41 @@ Purpose:
- highlight UMASM grammar violations to accelerate development cycle
Acknowledgements
- the color scheme is inspired by Sublime's default syntax
highlighter for C
- the UMASM grammar specification was provided by the COMP 0040
course staff at Tufts University
- http://www.sublimetext.com/docs/3/syntax.html
- https://www.sublimetext.com/docs/3/color_schemes.html
- https://sublime-text-unofficial-documentation.readthedocs.io/en/latest/reference/comments.html
File Overview:
- README
See README, section 'File Overview'
- umasm_improved-comments.tmPreferences
This file contains a description of how UMASM programs are commented,
which enables UMASM programmers to use the native Sublime 'primary+/'
shortcut to convenient comment-out highlighted text.
On Windows/Linux machines, the 'primary' key is CONTROL
On OSX machines, the 'primary' key is COMMAND
This package assumes that UMASM programmers prefer to use the '//'
character sequence to begin comments. If you instead prefer to use
the '#' character sequence, you can change the package comment
configuration here. There are comments within the file to guide you.
- umasm_improved.sublime-color-scheme
This file contains the styling data for each scope defined in the
'sublime-syntax' for UMASM Improved. If you want to change the color
and or styling for a particular scope, that can be done in this file.
and/or styling for a particular scope, that can be done in this file.
You can read up on Sublime Text 3 color schemes here:
https://www.sublimetext.com/docs/3/color_schemes.html
......@@ -35,11 +63,25 @@ File Overview:
Sublime in built on Python, we have access to a robust set of
'regex' tools). If you want to add additional scopes, that can be
done in this file.
By extending the regex patterns in this package, it is possible to
build a (rather cumbersome, but rather useful) pattern that identifies
and highlights syntactically invalid lines of UMASM source code. To do
this, you'll have to represent the entire UMASM grammar as a 'regex'
pattern. This functionality is built into the "UMASM Improved" syntax
highlighting package.
By extending the regex patterns in the simpler "UMASM" syntax
highlighting package, "UMASM Improved" can reliably identify and
highlight syntactically invalid lines of UMASM source code.
My implementation of the extended "UMASM Improved" grammar-checker
spans 84 lines of regex, but I'm confident that Norman Ramsey's
implementaiton would have been shorter :)
Additional Notes
- On the use of XML in "umasm_improved-comments.tmPreferences":
One advantge of Sublime 3 (over Sublime 2) is the ability to use
YAML in package development instead of XML. Confusingly, certain
Sublime 3 functionalities (like the native comment shortcut) are
not reliably supported by the considerly friendlier YAML.
Consequently, the native comment shortcut support must be implemented
in XML -- an unfortuante and archaic vestige of Sublime 2 package
development.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>name</key>
<string>Comments</string>
<key>scope</key>
<string>source</string>
<key>settings</key>
<dict>
<key>shellVariables</key>
<array>
<dict>
<key>name</key>
<string>TM_COMMENT_START</string>
<key>value</key>
<string>// </string>
<!-- if you want to change the default automatic
comment charafter sequence to '#' instead of
'//', swap line 17 with the following line
<string># </string>
-->
</dict>
</array>
</dict>
</dict>
</plist>
%YAML 1.2
---
# See http://www.sublimetext.com/docs/3/syntax.html
name: UMASM Improved
name: UMASM
file_extensions:
- ums
scope: source
......
......@@ -16,14 +16,35 @@ Acknowledgements
highlighter for C
- the UMASM grammar specification was provided by the COMP 0040
course staff at Tufts University
- http://www.sublimetext.com/docs/3/syntax.html
- https://www.sublimetext.com/docs/3/color_schemes.html
- https://sublime-text-unofficial-documentation.readthedocs.io/en/latest/reference/comments.html
File Overview:
- README
See README, section 'File Overview'
- umasm-comments.tmPreferences
This file contains a description of how UMASM programs are commented,
which enables UMASM programmers to use the native Sublime 'primary+/'
shortcut to convenient comment-out highlighted text.
On Windows/Linux machines, the 'primary' key is CONTROL
On OSX machines, the 'primary' key is COMMAND
This package assumes that UMASM programmers prefer to use the '//'
character sequence to begin comments. If you instead prefer to use
the '#' character sequence, you can change the package comment
configuration here. There are comments within the file to guide you.
- umasm.sublime-color-scheme
This file contains the styling data for each scope defined in the
'sublime-syntax' for UMASM. If you want to change the color and or
'sublime-syntax' for UMASM. If you want to change the color and/or
styling for a particular scope, that can be done in this file.
You can read up on Sublime Text 3 color schemes here:
......@@ -42,6 +63,26 @@ File Overview:
'regex' tools). If you want to add additional scopes, that can be
done in this file.
By extending the regex patterns in the simpler "UMASM" syntax
highlighting package, "UMASM Improved" can reliably identify and
highlight syntactically invalid lines of UMASM source code.
By extending the regex patterns in this package, it is possible to
build a (rather cumbersome, but rather useful) pattern that identifies
and highlights syntactically invalid lines of UMASM source code. To do
this, you'll have to represent the entire UMASM grammar as a 'regex'
pattern. This functionality is built into the "UMASM Improved" syntax
highlighting package.
My implementation of the extended "UMASM Improved" grammar-checker
spans 84 lines of regex, but I'm confident that Norman Ramsey's
implementaiton would have been shorter :)
Additional Notes
- On the use of XML in "umasm-comments.tmPreferences":
One advantge of Sublime 3 (over Sublime 2) is the ability to use
YAML in package development instead of XML. Confusingly, certain
Sublime 3 functionalities (like the native comment shortcut) are
not reliably supported by the considerly friendlier YAML.
Consequently, the native comment shortcut support must be implemented
in XML -- an unfortuante and archaic vestige of Sublime 2 package
development.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>name</key>
<string>Comments</string>
<key>scope</key>
<string>source</string>
<key>settings</key>
<dict>
<key>shellVariables</key>
<array>
<dict>
<key>name</key>
<string>TM_COMMENT_START</string>
<key>value</key>
<string>// </string>
<!-- if you want to change the default automatic
comment charafter sequence to '#' instead of
'//', swap line 20 with the following line
<string># </string>
-->
</dict>
</array>
</dict>
</dict>
</plist>
[
{ "keys": ["command+a"], "command": "toggle_comment", "args": { "block": false } }
]
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment