DDWSnippets
Extension
ExtensionDescription
DDWSnippets stores "snippets" -- brief, reusable code templates that can be inserted into active documents using short names. It can also save the snippet repository to disk, and load it automatically at sclang startup.
It uses the Document interface to insert a snippet into the active code document. It is tested only with ScIDE document integration. It may be possible to support other Document classes, but this will depend on testing from other users.
Usage
All methods are class methods.
Add snippets using DDWSnippets: *put. Both the snippets themselves and their names should be strings. Within the snippet text, use ## to denote where to position the cursor after insertion. A pair of ## delimiters indicates a range of text that will be selected after insertion.
To use a snippet in a document, press ctrl-` (backtick). Begin typing the snippet name in the pop-up window; the list will be filtered automatically. You may also use the up and down arrow keys. Press Return to insert it, or Esc to cancel.
DDWSnippets.learn to type the desired hotkey. Read the DDWSnippets: *learn method documentation carefully -- there are caveats. Alternately, see DDWSnippets: *hotkeyCode and DDWSnippets: *hotkeyMods below.Class Methods
Snippet management
.put
Add a snippet to the repository.
Arguments:
| name |
A string, uniquely identifying the snippet. |
| value |
The snippet, as a string. It may contain |
.at
Retrieve a snippet from the repository, by name.
Arguments:
| name |
A string, uniquely identifying the snippet. |
Returns:
The snippet, as a string, or nil if not found.
.removeAt
Delete a snippet, by name, from the repository.
Arguments:
| name |
A string, uniquely identifying the snippet. |
.snips
Configuration
.learn
Open a GUI window, where you can type the hotkey you want to activate the snippet selector.
Be aware:
- Visible characters may be entered into the code document, even with Alt- or Ctrl- modifiers. DDWSnippets cannot prevent this. For instance, in Linux, Ctrl-` (the default hotkey) is invisible, but Ctrl-' is visible, and will type the single quote into the document.
- SC GUI windows can receive some keystrokes that are "swallowed" by IDE code windows, e.g., the GUI can receive <Esc>, but the IDE does not pass <Esc> through to sclang. So, it's possible to choose a hotkey through the 'learn' interface that will not work when typing.
.hotkeyCode
An integer, corresponding to the keycode argument into key action functions. Frequently this will be an ASCII code, but not always, e.g. <Esc> translates into keycode 65307. Use at your own risk.
Returns:
The keycode (Integer).
.hotkeyMods
An integer, corresponding to the modifiers argument into key action functions. See Modifier Keys. Use at your own risk.
Returns:
The modifier mask (Integer).
.enable
Activates DDWSnippets by adding the ctrl-` hotkey into Document: *globalKeyDownAction. If DDWSnippets: *autoEnable is true, this method is called one second after class library initialization.
.disable
Deactivates DDWSnippets by removing the ctrl-` hotkey from Document: *globalKeyDownAction.
.autoEnable
Boolean. If true, enable the hotkey automatically at startup. You may set this in your Sclang Startup File. Its value is also saved by default into the DDWSnippets configuration file.
The default is true.
Returns:
A Boolean.
.verbose
Boolean. If true, print status messages in the post window. You may set this in your Sclang Startup File. Its value is also saved by default into the DDWSnippets configuration file.
The default is true.
Returns:
A Boolean.
.path
A string, specifying the default DDWSnippets configuration file location. If not explicitly set in your startup file, a default location in your Platform#*userConfigDir is used. There is no need to set it explicitly.
Returns:
A String.
.write
Write the snippet repository to disk.
Arguments:
| filePath |
If specified, this string overrides |
| fullConfig |
A Boolean. If true, DDWSnippets: *autoEnable and DDWSnippets: *verbose will be included in the saved file. If false, they are omitted. The default is |
Returns:
A Boolean.
.read
Read the snippet repository from disk. DDWSnippets.snips is not emptied; new items will be added, but old ones will not be removed.
Arguments:
| filePath |
If specified, this string overrides |
| warn |
A Boolean. If true, a warning will be posted if the file could not be found. During startup, this is called with |
Returns:
A Boolean.
Programmatic usage
.makeGui
Opens the snippet-selection window.
Arguments:
| doc |
An instance of Document or TextView. If not specified, the default is |