diff --git a/readme b/readme deleted file mode 100644 index a7ccc99..0000000 --- a/readme +++ /dev/null @@ -1,61 +0,0 @@ -# Hello, world! - -This is my first VS Code extension from the ground up! It's my sandbox, not really meant for public consumption :) - -It follows the guide at [Visual Studio Code - Your First Extension](https://code.visualstudio.com/api/get-started/your-first-extension). - -I'll try to leave extensive comments for reference to those writing their first VS Code extension :) feel free to [open an issue](https://github.com/mark-wiemer/vscode-helloworld/issues) if you have any questions about first time extension development! - -## Tests - -[Test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) is a major priority of this project. All code will be thoroughly tested before being committed. - -All tests run using the standard `npm run test`, documented in `package.json`. - -Unit tests focus on miscellaneous functionality of the app. They're written following the official [Testing Extensions guide](https://code.visualstudio.com/api/working-with-extensions/testing-extension). - -Grammar tests focus on the tokenization via the TextMate grammar detailed in [Syntax Highlight Guide](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide) - -## Engineering quality - -Another main goal is to create a project that's very easy to maintain. - -- Make use of automation whenever possible -- Automated checks at PR time -- Pre-commit hooks for formatting and linting - -### Pre-commit hooks - -Pre-commit hooks are setup using `husky` and `lint-staged`. When a commit is attempted, `lint-staged` validates the staged files for correctness (compilation errors, lint problems, and formatting). If anything is wrong, the commit will fail. - -To test that pre-commit hooks have been set up correctly, introduce compilation, lint, or formatting issues to a file. Save the file without fixing these issues. Then stage it and try to commit. The relevant check should fail, the commit should be aborted, and the filesystem should not be changed. - -## Syntax highlighting - -Syntax highlighting support follows [VS Code's syntax highlighting guide](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide). - -This extension... - -1. declares that it `contributes` `languages` and `grammars` in `package.json` -1. defines grammar in YAML for readability (see [Using YAML to write a grammar](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide#tokenization:~:text=USING%20YAML%20TO%20WRITE%20A%20GRAMMAR)) -1. converts YAML grammar to JSON using `npm run compile_grammar` - -VS Code... - -1. tries to parse relevant files with the grammar using [microsoft/vscode-textmate](https://github.com/Microsoft/vscode-textmate) - -## Next steps - -I want to improve [AutoHotkey Plus Plus](https://github.com/mark-wiemer/vscode-autohotkey-plus-plus). Right now, I'm focusing on syntax- and semantic-highlighting. - -The [Semantic Token Provider](https://code.visualstudio.com/api/references/vscode-api#DocumentSemanticTokensProvider) mentioned in the [Tokenization section of the Syntax Highlight Guide](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide#tokenization) looks like a promising way to provide detailed tokens as well. - -Resources: - -- [Syntax Highlight Guide](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide) -- [microsoft/vscode-textmate](https://github.com/Microsoft/vscode-textmate) is the library that tokenizes code via TextMate grammars -- [PanAeon/vscode-tmgrammar-test](https://github.com/PanAeon/vscode-tmgrammar-test) is recommended by Microsoft to write unit tests for TextMate grammars - -## Further reading - -See the `/docs` folder for additional documentation. diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..6cd80e4 --- /dev/null +++ b/readme.md @@ -0,0 +1,172 @@ +# AutoHotkey Plus Plus (AHK++) + +AutoHotkey Plus Plus (AHK++) provides AutoHotkey language support for VS Code. For AHK v1, this includes: + +- IntelliSense +- syntax highlighting +- debug support +- formatting +- quick help +- ...and more! + +## Install + +Install from VS Code or install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=mark-wiemer.vscode-autohotkey-plus-plus). + +## AHK v2 full support in pre-release! + +AutoHotkey v2 support has been a [long-requested feature](https://github.com/mark-wiemer-org/ahkpp/issues/96), and v5.0.0 supports many key features. The latest [๐Ÿงช pre-release version](https://code.visualstudio.com/updates/v1_63#_pre-release-extensions), v5.1.0, adds full v2 support! + +Supported features include: + +- Running and debugging v1 and v2 scripts without changing settings +- Full syntax highlighting for v2 scripts +- "Open help" (Ctrl + F1) opens language-specific help (and includes your text selection!) +- Unique icons for v1 (blue) and v2 (green) +- Rich IntelliSense support with snippets and hover text (๐Ÿงช pre-release only) +- Formatting files (๐Ÿงช pre-release only) + +For known issues, see [the changelog](./Changelog.md) + +Please [๐Ÿ› report any issues](https://github.com/mark-wiemer-org/ahkpp/issues/new/choose), it helps bring full v2 support to the release version faster ๐Ÿง‘โ€๐Ÿ’ป + +๐Ÿ’š Special thanks to [thqby](https://github.com/thqby), as this would not have been possible without thqby's open-source [AutoHotkey v2 Language Support](https://marketplace.visualstudio.com/items?itemName=thqby.vscode-autohotkey2-lsp)! + +## Why AutoHotkey Plus Plus? + +AutoHotkey Plus Plus is one of many extensions that offer VS Code language support. So why should you use this one? + +- **Supports both v1 and v2**: AHK++ supports both AHK v1 and v2, making it the only extension to support both major versions of AutoHotkey! +- **Actively maintained**: Any issues encountered while using this extension can be reported and fixed. With other extensions, anything that's broken will stay broken forever. You can report any issues with AHK++ (and view all issues) through the [issue tracker](https://github.com/mark-wiemer-org/ahkpp/issues). +- **IntelliSense**: Smart code completion, syntax highlighting, code navigation, and more. +- **Debug support**: Run and debug AHK scripts from VS Code. +- **New features**: Another benefit to active maintenance is that AHK++ can add new features as users request them. For example, quick help, formatter directives, and custom new file templates were all added based on user feedback! + +## Commands + +With AHK++, you can compile, debug, and run your scripts with keyboard shortcuts. You can also run a selection as a standalone script. + +- Compile: `Ctrl + Shift + F9` +- Debug: `Ctrl + Alt + F9` +- Open help: `Ctrl + F1` +- Run: `Ctrl + F9` +- Run selection: `Ctrl + F8` + +## Debug + +> There are some [known issues with the debugger](https://github.com/mark-wiemer-org/ahkpp/issues?q=is%3Aopen+is%3Aissue+label%3Adebugger). If you need an advanced setup, we recommend [zero-plusplus.vscode-autohotkey-debug](https://marketplace.visualstudio.com/items?itemName=zero-plusplus.vscode-autohotkey-debug) for now. Please [open an issue](https://github.com/mark-wiemer-org/ahkpp/issues/new/choose) if the built-in debugger does not support your needs. As `zero-plusplus.vscode-autohotkey-debug` is [closed-source](https://github.com/zero-plusplus/vscode-autohotkey-debug/discussions/332), we will be working to introduce advanced debugger features to ensure an open-source, collaborative, complete extension is available to the AHK community ๐Ÿ™‚ + +1. Click the debug button in the editor title menu (at the top right of the editor) or press `Ctrl + Alt + F9`. +2. The debugger supports breakpoints, stack tracing, and variable watching + + ![Debug](image/debug.gif) + +### Debug features + +1. **Output message**: You can use `OutputDebug` command instead of `MsgBox` to log values. + + ![Output](image/output.jpg) + +2. **Evaluate**: Set and get variable values through the debug console. + + ![Evaluate](image/evalute.jpg) + +This extension provides basic debugging functions. If you need more debugging functions (such as conditional breakpoints), you can add an additional extension: [Install vscode-autohotkey-debug](https://marketplace.visualstudio.com/items?itemName=zero-plusplus.vscode-autohotkey-debug). + +## Language Features + +### IntelliSense + +Supports IntelliSense for variables and functions. + +### Function symbol + +1. You can add a comment to the function using a semicolon on the line above the function declaration + +### Go to definition + +1. Supports navigation to symbol definition. +2. Usage: Ctrl-click on the symbol to navigate to its definition. + +![Goto Definition](image/gotoDefinition.jpg) + +### Find symbol references + +Select a symbol, then: + +- Right-click and select `Find All References`. +- Or press `Shift + F12`. + +### Hover tip + +Usage: Hover over symbol to see IntelliSense documentation. + +![Hover](image/hover.png) + +### Outline + +Assign name to block of code via double semicolon comment `;;Name` and go to it from outline. + +![Block Name](image/blockName.png) + +### Folding + +Custom folding regions: + +```autohotkey +;region +MsgBox % "Collapse me!" +;endregion + +; Block comments with regions +/* ;region +Collapse me! +*/ ;endregion +``` + +### Code format + +Supports standard VS Code formatting with a few options. + +![Code Format](image/codeFormat.jpg) + +#### Formatter Directives + +Formatter directives instruct the formatter to behave a certain way on sections of code. + +1. `FormatBlockComment`: + + ```autohotkey + ;@AHK++FormatBlockCommentOn + /* + ;All text inside block comment will be formatted like regular code. + */ + ;@AHK++FormatBlockCommentOff + ``` + +2. `AlignAssignment`: + + ```autohotkey + ;@AHK++AlignAssignmentOn + a = 5 ; number five + str = legacy text = with equal symbol + inputFile := "movie.mkv" + abc := "abc" ; string + abc := a + b + ;@AHK++AlignAssignmentOff + ``` + +## Credits + +This extension relies heavily on open-source code. A huge thank you to all these open-source participants who made the extension what it is today! + +- [AutoHotkey Plus by cweijan](https://marketplace.visualstudio.com/items?itemName=cweijan.vscode-autohotkey-plus): AHK++ is a fork of AutoHotkey Plus by cweijan (Weijan Chen) +- [Contributions to AHK++ by kyklish](https://github.com/mark-wiemer-org/ahkpp/commits/main?author=kyklish): Greatly improved formatting and snippets by both fixing bugs and adding features +- [AutoHotkey v2 Language Support by thqby](https://marketplace.visualstudio.com/items?itemName=thqby.vscode-autohotkey2-lsp): The source of the v2 grammar and other great contributions +- [Lexikos/vscode-auto-select](https://github.com/Lexikos/vscode-auto-select): The core code for automatically switching AHK versions +- [AutoHotkey by stef-levesque](https://marketplace.visualstudio.com/items?itemName=slevesque.vscode-autohotkey): AutoHotkey Plus is a fork of stef-levesque's original AutoHotkey extension, which provided the original grammar and snippets for AHK + +## Links + +- [GitHub](https://github.com/mark-wiemer-org/ahkpp): View code, file bugs, and join discussions +- [Reviews](https://marketplace.visualstudio.com/items?itemName=mark-wiemer.vscode-autohotkey-plus-plus&ssr=false#review-details): Help others discover AHK++ by leaving a review