Overview
The Octopus Writer extention provides the user with some handy new commands
meant to enable more effective text editing,
particularly focusing on the expanding on the multiple selections (A.K.A cursors) feature of Visual Studio Code.
The extension provides a set of new commands commands which can be found with Ctrl+Shift+P.
The provided commands are not keybound by default but it is strongly recommended to keybind the more common ones.
Since this extension is mostly focused on manipulating multiple selections at once,
it is recommended to first have a solid understanding of the multi-selection features that vscode already has:
If you are looking to get started with the multi-selection feature;
you can check out this official documentation page. There is also this youtube tutorial which might also be helpful for getting started with multi-selections.
The Captured Selections Stack
The extension maintains a stack (list) of captured selections,
these selections do not effect the editor until they are explicitly actiavted.
This stack can be manipulated using various commands detailed in Selections Stack Manipulation.
Learning how to use all of the stack commands at once can be overwhelming.
A good starting point would be to understanding the Capture Selections and Pop All Selections commands.
Text Editor Interface
Some of the commands which this extension provides, such as Generate Selections and Evaluate Selections receive
their parameters in a unique way which is somewhat similar to a command line interface:
The input is taken from the captured text section (usually highlighted in blue),
to pass multiple arguments, seperate arguments with a space.
TEI Output
Output text will be inserted to the text editor - replacing the current captured content.
The default output is "". In other words: commands with no output will simply delete the current captured content.
When a command is called, this input & output interface is applied to each active selection individually.
The commands apply to each of the active selections by their order (The earlier captured commands are first e.t.c).
Selections Stack Manipulation
Capture Selections
This command will push a copy of each active selections into the top of the stack.
Pop All Selections
When this command is called, the set of active selections is replaced by the set of selections
in the captured selections stack. After this command is called the captured selctions stack will remain empty.
Pop Last Selection
This command replaces the set of active selections with the last (top) selection to be inserted into
the stack. After the command executes the selection will no longer be in the stack.
Throw Captured Selections
This command empties the captured selections stack.
Generate Selections
TEI: <count> <offset>
For each of the active selections, the content captured by the selection will be deleted and interpreted
as the parameters for the Generate Selections command. The command has two parameters: count and offset.
The first parameter: count (decimal number) dictates the number of selections which will be generated.
The second parameter: offset (decimal number) dictates the number of lines separating the selections.
These parameters are given in the form of the Text Editor Interface.
All generated selections are appended to the The Captured Selections Stack
Text Manipulation Commands
Enumerate Selections
TEI: (no arguments)
When this command is called, each active selection is inserted with an index (the active selections are numbered from most oldest to most recent). If a selection bounds some text - that test will be replaced by the inserted index.
Evaluate Selections
TEI: <expression>
Each active selection is evaluated using eval() function in the javascript environment that runs the extension.
If the content of the selection can be succesfully evaluated and cast to string, that string value will replace the text captured by the selection.
The captured text is evaluated regardless of the ability to cast the evaluated value into string, in addition the javascript environment is
presistent between calls, which means if you first evaluate x=3 and then evaluate x; the latter will yeild 3.
