spec Command Extension for Visual Studio Code
!NOTE: The mechanism to use user-defined dictionary was totally revamped since v2.0.0. See User-Defined Dictionaries section below and CHANGELOG.md for the new mechanism.
The extension is designed to assist editing spec command files with Visual Studio Code.
spec command files referred to here are also called spec macro files and spec script files; they are typically loaded by qdo or qdofile() after a user writes macros and functions in them.
While qdo or qdofile() does not care about the filename extension, most command files installed with spec are named *.mac (e.g., SPECD/standard.mac).
Therefore, this VS Code extension treats .mac as the file extension of spec command files (language identifier: spec-command).
However, VS Code provides ways for a user to change the association.
Read Language Support in Visual Studio Code (official document of VS Code) for further details.
What's spec?
spec is internationally recognized as the leading software for instrument control and data acquisition in X-ray diffraction experiments.
It is used at more than 200 synchrotrons, industrial laboratories, universities and research facilities around the globe.
cited from CSS - Certified Scientific Software homepage.
Note that the extension is not the official one developed by Certified Scientific Software.
Use GitHub issues for bug reports and feature requests about the extension.
Features
- Diagnostics - syntax check
- Syntax highlighting
- Code completion and hinting
- Hovers
- Code completion proposals
- Code snippets - templates that make it easier to enter repeating code patterns, such as loops and conditional-statements
- Help with function signatures - help that appears during a user types an argument in a function call
- Code navigation
- Symbol navigation in a document - available at Go to Symbol in Editor (Ctrl+Shift+O) menubar item and the navigation bar at the top the editor pane (aka breadcrumbs)
- Symbol navigation in workspaces - available at Go to Symbol in Workspace (Ctrl+T) menubar item
- Show definitions of a symbol - jump to where the symbol is defined, available at Go to Definition (F12) and Peek Definition (Alt+F12) in right-click menu
- Commands - Several commands explained below can be invoked from the command pallate (Ctrl+Shit+P).
This extension treats user-defined symbols declared at the top level (i.e., not in a code block, curly brackets) as global and those in code blocks as local.
Global symbols are visible beyond a file where the symbol is defined; local symbols are visible only when the cursor is in the same block.
Tip: A comment line that starts with # MARK:, # FIXME: or # TODO: is treated as a breadcrumb. Optionally, -- devides the text with the main and subsidiary parts.
The extension was developed with reference to the recent official PDF document about spec release 6 (version 3 of the spec documentation, printed 16 July 2017).
The help text of built-in symbols are cited from this document, except where otherwise noted.
Requirements
The spec grammar is torelant and its behavior is determined only at runtime, which makes it impossible for the extension to mimic spec's interpreter perfectly.
For example, the extension regards f(var) in a spec script as a function call (like most people assume) but there is another possibility:
1.SEPC> def f1(var) '{p var}' # function definition
2.SEPC> f1(123) # function call, common
123
3.SEPC> f1(123) f1(456) # invalid syntax
syntax error on ";"
4.SEPC> def f2 '{p "$*"}' # macro definition
5.SEPC> f2(123) # macro call, anomalous but valid
(123)
5.SEPC> f2(123) f2(456) # also valid
(123) f2(456)
Macros made of an imperfect statement are another examples the extension can not handle well
(ifd and ifp defined in SPECD/standard.mac are exceptionally supported).
User-defined macros must be made of one or more perfect sentenses.
def ifd 'if (DATAFILE != "" && DATAFILE != "/dev/null")'
ifd do_something; else do_otherthing;
This extension also requires stricter coding than the spec interpreters does.
For example, spec interpreters evaluate the following two lines equivalently:
qdo /home/myuser/mymacro.mac
qdo "/home/myuser/mymacro.mac"
but the extension shows an alert on the first line because it expects explicit quotation marks for a string literal.
Extension Settings
This extension contributes configuration options, configurable in the Settings editor (Win/Linux: Ctrl+,, Mac: Cmd+,).
Read Visual Studio Code User and Workspace Settings for the basic functionality of Settings.
Explanations of the respective settings are available in the Settings editor. Below is additional information for several settings that do not have enough space in a limited space of the setting editor.
- spec-command.suggest.codeSnippets - provides a place to add code snippet templates that can include special placeholders for motor (
%MOT) and counter (%CNT) mnemonics. Optionally, descriptive text can be appended after a hash sign (#). Example: { "mv2": "mv ${1%MOT1} ${2:pos1} ${3%MOT2} ${4:pos2} # 2-motor move" }. For detailed syntax including other placeholders and choices, read Snippets in Visual Studio Code. Snippets for mv, mvr, umv, umvr, ascan, dscan, a2scan, d2scan, a3scan, d3scan, a4scan, d4scan, a5scan, d5scan, mesh, and dmesh are defined by the extension and thus, a user does not need to add them manually.
- spec-command.suggest.motors, spec-command.suggest.counters - registers motor/counter mnemonics and their explanatory texts as the keys and the values. They are used by IntelliSense features including code snippets above.
The extension refers to the following built-in setting:
User-Defined Dictionaries
Users can provide user-defined dictionaries to add custom symbols for code completion and hinting.
Motors and counters can be added here, in addition to the settings.
The extension stores dictionaries in either the Global State or Workspace State.
When a dictionary is stored in the former state, defined symbols are available across all workspaces; when in the latter state, only in the workspace.
Use the following commands to manage user-defined dictionaries:
- "Open Dictionary Preview" (
spec-command.showDictionaryPreview)
- "Show User-Defined Dictionary in Editor" (
spec-command.showDictionarySource)
- "Register Editor Content as User-Defined Dictionary" (
spec-command.registerDictionary)
- "Delete User-Defined Dictionary" (
spec-command.deleteDictionary)
"Show User-Defined Dictionary in Editor" command can also be used to create a new user-defined dictionary from command files in the workspace.
As a starting point to create a dictionary, it is recommended to use this command.
After editing the content, use "Register Editor Content as User-Defined Dictionary" command to send it to the global/workspace state.
The dictionary content is expected to be a JSON object conforming to the schema the extension provides.
If you want to save a copy of the dictionary, it is recommended to set a file name ending with .scdict.json, then VS Code will automatically validate it against the schema.
Otherwise, to let VS Code validate the content, the JSON object should have $schema property whose value is either the local path to the schema file bundled in the installed extension or the online URI shown below:
https://raw.githubusercontent.com/fujidana/vscode-spec-command/refs/heads/master/schema/scdict.schema.json
To let VS Code use the online schema, add https://raw.githubusercontent.com/fujidana/ to the json.schemaDownload.trustedDomains setting.
Known Issues
- Syntax check by this extension has small differences with actual spec interpreters.
- Statement continuation by putting a backslash at the end of the line is not fully supported in syntax highlighting.
Also read GitHub issues.
Release Notes
See CHANGELOG.md.
Acknowledgements
The extension relies on various npm packages.
Thanks to the authors of these packages.
The licenses of the software embedded into the extension's code after minification by esbuild are shown in ThirdPartyNotices.txt.
Contributing
The extension is open to contributions. Create an issue in GitHub Issues for a bug report or a feature request. If you want to contribute code, please read CONTRIBUTING.md.
