EKeys plugin for Take Command / TCC / 4NT

beta version 0.50.0     2018-12-03

Charles Dye

Purpose:

This plugin allows you to define custom hotkeys, which edit the space-delimited ‘word’ at the cursor. It adds one new command, EKEY.

Installation:

To use this plugin, copy EKeys.dll to some known location on your hard drive. (If you are using the 64-bit version of Take Command, take EKeys-x64.dll instead of EKeys.dll.) Load the plugin with a PLUGIN /L command, for example:

plugin /l c:\bin\tcmd\test\ekeys.dll

If you copy this file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

Using the Hotkeys:

While typing a command line, move the cursor to any word and press a hotkey (defined with the EKEY command). The plugin will find the space-delimited word at the cursor, and replace it with the text defined for that particular hotkey. A number sign in the hotkey text will be replaced with the original word from the command line.

Depending on how you define it, a hotkey can:

EKEY Command:

EKEY — Define, list, or remove hotkeys.

Syntax:
EKEY /B /C /D /E /I /L /O /Q /R:file /S:file /T /U /X /Z hotkey=text

/Bno error beep
/Cfirst word of text is a command
/Ddelete the definition for hotkey
/Eautomatically execute the command line
/Iinsert text at cursor position if cursor is not at a word
/Llist all supported hotkeys
/Ouse with /S: to overwrite an existing file
/Qquote resulting text if needed
/R:fileread hotkey definitions from a file
/S:filesave hotkey definitions to a file
/Tchange a TCC option
/Uunquote the word at the cursor
/Xexpand variables and functions in the modified word
/Zquiet; suppresses many messages
hotkeythe hotkey to define, list, or delete
textthe replacement text when the hotkey is pressed

To define a hotkey, use the format EKEY hotkey=text :

ekey alt-t=Test

Pressing Alt-T will replace the word at the cursor with the word “Test”. If you don’t specify any text, then the hotkey will simply delete the word at the cursor:

ekey ctrl-bksp=

Now Ctrl-Backspace will delete the entire word at the cursor. A more useful hotkey can incorporate the original word from the cursor into its replacement:

ekey alt-s=%%@search[#]

Alt-S will wrap an %@search[] around the word at the cursor. For example, if the cursor is on the word chkdsk, Alt-S will replace it with %@search[chkdsk].


The number sign # symbolizes the word at the cursor. You will almost always want a # in your hotkey text. Unless you include the number sign, the word at the cursor will be discarded.


You might want to expand a variable or function automatically when you press the hotkey. To do this, specify /X when you define the hotkey:

ekey /x alt-s=%%@search[#]

The new definition replaces the old one. Now, pressing Alt-S while the cursor is on chkdsk will replace it with C:\WINDOWS\system32\chkdsk.exe. You can create a similar hotkey to do math at the command line:

ekey /x alt-==%%@eval[#]

If the cursor is on 1+2*3, then Alt-= will replace it with the value 7. You could even type 912559=X and press Alt-= to convert that number to hexadecimal — then press Alt-= a second time to convert it back to decimal!

The plugin will beep if there is any error while expanding variables and functions. To suppress the error beep, use /B when defining the hotkey.


An EKeys hotkey operates on the word at the cursor. If you press a hotkey when the cursor is not at a word, it won’t do anything. You can modify this behavior with option /I. If you press a hotkey defined with /I while the cursor is not at a word, the replacement text will be inserted at the cursor position; any # sign in the text will be omitted.

ekey /i /x alt-d=%%_isodate
ekey /i /x alt-t=%%_time


If you specify /Q, then the replacement text will automatically be quoted if it contains spaces, control characters, or any of &,;<>=|


You might also want to insert a word at the beginning of the command line. If you specify /C when defining your hotkey, then the first word in the key’s text (up to the first unquoted space) will be prefixed to the command line:

ekey /c alt-b=bdebugger "%%@search[#]"

Press Alt-B, and the word at the cursor will be wrapped in the "%@SEARCH[]" function, and BDEBUGGER will be inserted at the start of the command line.


If you specify /E, the resulting command line will be run automatically after text is replaced and variables are expanded, as if you had pressed Enter. This is most likely to be useful with /C.


If you want to include a literal # character in the replacement text, there are two ways to do this. You can double the number sign, ##; or you can use %@CHAR[65283], which the text-replacement routine will automatically change to a number sign. (If you want to put a number sign immediately after the word from the command line, you must use the second method.)


You can also define hotkeys to change TCC’s internal OPTION settings on-the-fly. Use /T and set the hotkey text to the directive’s name and new value, separated by a space or equals sign. For example:

ekey /t alt-a=appendtodir=yes
ekey /t ctrl-a=appendtodir=no

If the hotkey text contains only a directive name, with no space or equals sign, then the plugin will read the current value for that setting and toggle it — changing ‘Yes’ to ‘No’, ‘On’ to ‘Off’, 0 to 1, nonzero numbers to 0, and so on. (Of course, if that particular directive doesn’t happen to be of the on-or-off type, then the result will probably not be good.)

ekey /t alt-a=appendtodir

Now pressing Alt-A will toggle the internal setting which controls whether or not tab filename completion appends a backslash to directory names.

Changing CompleteHidden will instead set both CompleteHiddenDirs and CompleteHiddenFiles.

/T hotkeys to change OPTION settings work a little differently: the cursor does not need to be at a word, and the number sign has no special meaning.


To remove a key definition, use the format EKEY /D hotkey :

ekey /d alt-t

You can remove all key definitions at once with an alternate syntax:

ekey /d:*


To list all defined hotkeys, just type EKEY with no options. To list the definition for a single key, type EKEY hotkey :

ekey alt-s


You can save the current hotkey definitions to a file with EKEY /S:file :

ekey /s:hotkeys.txt

The save file is just a UTF-8 encoded text file, which can be edited with any modern text editor. You can reload the definitions later with EKEY /R:file. The filename may contain TCC directory aliases.

The file Examples.EK contains most of the demo key definitions from this documentation.

Autoload file:

When the plugin is loaded, it will look for a file named Auto.EK in the same directory where EKeys.dll is located. If it finds this file, EKeys will try to read key definitions from it. If Auto.EK does not exist in the DLL’s directory, the plugin will try again in TCC.EXE’s directory.

Startup Message:

This plugin displays an informational line when it initializes. The message will be suppressed in transient or pipe shells. You can disable it for all shells by defining an environment variable named NOLOADMSG, for example:

set /e /u noloadmsg=1

Status and Licensing:

Consider this beta software. It may well have issues. Try it at your own risk. If you find a problem, you can report it in the JP Software support forum.

EKeys is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.

Download:

You can download the current version of the plugin from http://prospero.unm.edu/dl/ekeys.zip or ftp://prospero.unm.edu/ekeys.zip.