The Command Palette is used for the following:
- To change settings.
- To Find a text string in the current file or another file.
- Goto a specific line or character in the current file or another file.
- Seek and load files.
- Find all occurrences in the current file, Find-in-File (FF).
- Perform a Find-in-Files (FIF) for all occurrences of a search string in multiple files.
The Command Palette is implemented as a red popup pane reached by typing F8. It is a file that you can edit like other files (deleting, copying, pasting). It accumulates a history of previous commands that can be re-used.
The Command Palette uses a small grammar to parse and syntax-highlight commands.
In brief: To execute a command to search for text or load a file, open the Command Palette with F8 and type the command on a single line and press Enter.
Note: The Command Palette is experimental and incomplete. We appreciate any comments or ideas regarding the Command Palette knowing that it has quirks. It is slated for a redesign in the future to make it simpler to use with greater fidelity and efficiency.
There’s a silly notion that failure’s not an option at NASA. Failure is an option here. If things are not failing, you are not innovating enough.Elon Musk
The Command Palette Interpreter
The Command Palette performs many functions. The Command Palette Interpreter (CPI) deciphers the single-line command to determine which function to perform. The interpreter uses a precedence order and a “colon syntax” to figure out exactly which action to perform with which set of parameters.
The interpreter isn’t always intuitive (a current design shortcoming) and may load a file when your intent was to find a text string. Or it may interpret searching for text as an attempt to change an Iron setting. The colon syntax, described in more detail below, can be used to clarify for the interpreter the exact action you’re intending to perform.
Note: It is not necessary to execute commands just at the end of the Command Palette file. Use the up and down arrows to scroll to a previous commands then edit or re-use the command by pressing Enter. You can also insert blank lines using Shift+Enter and type new commands anywhere in the file.
Use Shift+F8 to repeat the last successfully executed command.
Find a Matching Text String
The most common use of the Command Palette is to find a text string in the current file. Simply type the string on a single line and press Enter. The Command Palette will search forward from the current caret position and then wrap to the top of the file to find a match. The first match will be selected.
If there is no match, Iron will issue an audible warning, indicate “Not found” in the Status pane and drop an animated 3D fling.
The Command Palette Interpreter may confuse your search with a command to load a file if the text string matches a file name in the directory search path. To prevent this, prefix your search with a colon, for example:
This will search for the text string “iron_edit.slang” in the current file instead of attempting to load a file named iron_edit.slang.
Use Ctrl+F (FInd) to search for a text string. This will bring up the Command Palette already prefixed with a colon on the last line. If the caret is over an identifier, the identifier will be appended after a colon. Or if the current pane has a one-line selection, that selected text will be copied and appended after the colon ready to another find the next instance of the same text string.
Use Alt+F (Seek & Load) to load a file. This will bring up the Command Palette suffixed with a colon and the caret positioned so when you type a file name, the file name is inserted before the colon.
To search again, use F3 (Find Next) which uses the last text string used for a successful search.
Note: Search strings are case-insensitive. Regular expression (regex) search patterns are not yet implemented. Only searching forward is implemented and wrapping to the top of the file cannot yet be disabled.
Seek And Load Files
Instead of loading a file with the File|Open menu item or Ctrl+O key binding which both use the File Open Dialog provided by the operating system, files can be quickly loaded using the Command Palette by simply typing in the file name and pressing Enter.
The Command Palette Interpreter will use the directory search path and the file name extension list to locate the file to load. How to setup the Directory Search Path and Extensions is described in another section below.
If the file is not found, the interpreter attempts to search for a matching string in the current file using the same text string. To avoid this possible confusion, append a colon at the end of file name:
Use Alt+F to Seek and Load a file. This will bring up the Command Palette with a colon already suffixed on a blank line at the end of the Command Palette file.
Note: You can also drag-and-drop a file or directory onto a text pane.
Goto a Specific Line or Character
The Command Palette is also used for going to a specific line or character in the current file. Simply prefix the line number with a colon and press Enter. For example, to goto the 127th line in the file, use the command:
To place the caret at the 13th character on line 127, use:
To place the caret at the 42nd character on the current line, use a double colon:
Use Ctrl+G to goto a specific line or character in the current file. This will bring up the Command Palette with a colon already prefixed with a colon on the bottom line.
Change Iron Settings
There are hundreds of settings (internal variables) that can be changed in Iron using the Command Palette.
An assignment statement construct is used by the Command Palette Interpreter to change a setting in Iron. The left side of the assignment is the internal variable name. The right side of the assignment is a simple constant — either an integer, a fully qualified real number, a boolean value or a quoted string. Here are four examples of assignments that change internal variables in Iron:
line_per_view_extra = 1
pane_change_duration = 0.1
globes_toggle = false
fif_ext = “slang;c;cpp;hpp”;
The trailing semicolon is optional. When a setting is changed successfully, “CPI Command” will echo the command in the Status pane. If there is an error (like an unknown setting or bad value), an audible warning will be issued and “Bad CPI assignment.” will be echoed to the Status pane.
Because the interpreter attempts to change a setting when it sees an assignment statement, searching for an assignment statement within your source needs to be prefixed with a colon:
:my_integer = 0;
The Command Palette Interpreter’s colon syntax is described in more detail in another section.
Note: Though settings can be changed via the Command Palette, Iron does not yet implement processing of settings files. This is coming soon along with documentation that will detail all the internal settings and actions that can be changed and processed in Iron.
Find-in-Files (FIF) and Find-in-File (FF)
The Command Palette can be used to find a text string in multiple files. Simply prefix your text string with “fif “ (no quotes, the space is required).
Here’s an example Find-in-Files (FIF) command that searches for all instances of the string “hello” (no quotes) across all files reachable in the Directory Search Path with extensions defined in Iron’s fif_ext variable:
This FIF command will search all the files currently open plus all the files in the directory search path for the string “hello”. How to setup the Directory Search Path and fif_ext string variable are described below.
The FIF command creates an iron.results file and will open it in the current or an adjacent pane. Side-by-side viewing of the results file and source code is the best (use Ctrl+Alt+F2 for two pane viewing or Ctrl+Alt+Shift+F2 to include the Status pane). Use the arrow keys to move up and down in the results file. Pressing the Enter key will load a source file and place the caret on the corresponding line in that file.
With multiple text panes open, searching within the iron.results file using F3 (Find Next) is a convenient way to jump to and inspect each instance of the text string, quickly, across multiple files.
Super-convenient is using Ctrl+Shift+F while the caret is over an identifier or when a single line selection has been made. This performs a Find-in-Files Quick using the identifier or the selected text and performs the FIF command without opening the Command Palette at all.
To find all the instances of search string just in the current file, use the Find-in-File (FF) command:
The Find-in-File(s) commands are case-insensitive by default. The Command Palette can be used to change the FIF and FF to be case-sensitive by changing the fif_case_sensitive setting:
fif_case_sensitive = false
The FIF commands use the fif_ext setting to determine which file name extensions are valid to search and can be changed in Command Palette. The default setting is:
fif_ext = “c;cpp;h;hpp;keymap;macro;menu;scope;txt;bat”
There is no regular expression (regex) searching just yet. However, a single wildcard can be accomplished using an asterisk which matches any file name extension. Care should be taken with regards to non-text (binary) files in the directory search path, Iron doesn’t yet detect binary files and will attempt to load them with unpredictable results (usually displays nothing).
fif_ext = “*” // Any file name extension
Of note, the fif_ext setting is echoed on the second line of the iron.results file. It is just a semicolon separated list of file name extensions to be searched.
Note: There are no wildcards (except the single asterisk “*” for matching all extensions) nor means to exclude extensions or directories just yet, that’s coming.
Note: You will need to setup a Directory Search Path for Find-in-Files FIF to search for files that are not currently opened in Iron. See below.
The Command Palette Interpreter uses an experimental grammar to parse commands and execute actions.
A command is typed onto one line and interpreted when the Enter key is pressed. The grammar first looks for keywords “fif ” and “ff ” (no quotes but with required space) which indicates the command is either a Find-in-Files (multiple files) or a Find-in-File (current file) command, each of which generates an iron.results file.
If not a Find-in-File(s) command, the interpreter then looks for a settings assignment which is composed of an identifier (the name of an Iron internal variable), an equals sign “=” operator, an assignment value constant and an optional semicolon. An example is:
exit_on_escape_toggle = true;
Failing to match any of the above command formats, the interpreter then inspects the line using the Command Palette’s colon syntax. Here’s the general form:
file_name.extension : line_number : column_number : pattern
Each of the named elements above are optional as are spaces before the final colon. So it is possible to seek and load a file, goto a particular line or character and start a Find from that point forward. Here are some examples:
iron_edit // Attempts to load a file of that name or searches text
Iron_edit.slang: // Loads a file
:iron_edit // Searches for a text string match (Find)
Iron_edit.slang:117 // Loads a file and goes to line 117
Iron_edit:goodbye // Loads a file then searches from current caret position
Iron_edit:56:10:hello // Loads a file, goes to line 56, column 10 then searches
When Iron re-loads a file such as iron_edit.slang, it recalls its last caret position (and any selections) which means searching without a line_number will start from the current caret position, not from the top of the file.
Hint: Without regex search patterns or escape sequences, it’s difficult to search for lines where the Find string pattern contains colons “:” or an assignment statement using the equals sign “=”. The workaround is to use the Find-in-Files commands “fif ” or “ff ”.
Note: The Command Palette Interpreter and it’s grammar will be evolving in future releases.
Directory Search Path
Iron uses a Directory Search Path for two purposes: the Find-in-Files utility and for seeking and loading files via the Command Palette.
Setting up the search path directories is a simple manual process of typing in the directory path names into the Directory pane’s file. Type Ctrl+Alt+D to bring up the Directories popup pane.
Add one directory per line. The path name should be fully qualified with a drive letter. Wildcards and relative paths are not supported. Here’s some directory search path examples:
// Iron Stuff
Blank and comment lines are ignored.
When Iron performs a FIF command, it will search files already open in Iron and then search files in each of the directories in-order from the top of the list. As each directory is searched, only files with extensions specified in the fif_ext variable will be searched. See the Find-in-Files section above.
When Iron Seeks and Loads a file from the Command Palette, it uses the Directories Search Path and file name extensions listed in the Extensions pane’s file (not the fif_ext extensions). Type Ctrl+Alt+E to bring up the Extensions popup pane.
Here’s an example list of file name extensions:
// Source Code
// Zinc Files
Again, blank and comment lines are ignored.
Hint: Keep in mind that the extensions listed in the Extensions pane file are used for loading files and the fif_ext is used for FIF searches.
Note: Using a directory search path is legacy technology that will eventually be replaced with a Sidebar / Project / Workspace pane which will define the set of files and folders to be searched or loaded via the Command Palette.