Hot Keyboard

macros for Windows

Automate Windows with macros
Main Download Purchase Support
<< Previous | Table Of Contents | Next >>

The extended replace macro is designed to replace currently selected text according to user-defined rules. This type of macro is recommended for advanced users since it can perform very complex text transformations like converting a number into a string (e.g. 586 - five hundred and eighty six), etc.

Using the Extended Replace macro

  1. In a text editor or word processor, select text using your keyboard or mouse.
  2. Press a hot key associated with an extended replace macro.
  3. Hot Keyboard reads the selected text, transforms it according to defined rules (optionally displays additional dialogs where you can modify text and transformation rules), and inserts it back in place of previously selected text.

Extended Replace macro, simple mode

The Hot Keyboard Extended Replace macro has two functional modes - simple mode and advanced mode. The simple mode works like an universal Extended Search-and-Replace tool for almost any application. Check the 'Ask me' mode option to create simple Extended Replace macro:

extreplace_simple1.gif

Assign a hot key to the macro and click the OK button to save it. Then go to an application where you would like to search and/or replace something. Select the entire text in which the search/replace should be performed, and press the hot key assigned to the macro. This brings out the Extended Find and Replace dialog:

extreplace_simple2.gif

The large edit box at the top of the dialog contains text that you selected in the application. It can be viewed and edited right there.

Find what - here you can type in the text to search for, or paste it from the clipboard, or select one of the recent queries from the drop down list.

Replace with - here you can enter the replacement text. If you check the Regular expression option below, you can include captured subpatterns in the replacement text as ${1}, ${2} and so on. The ${1U} syntax allows to include the uppercase version of the corresponding subpattern (and the ${1L} - the lowercase version correspondingly).

Regular expression - if checked, text in the Find what field is treated as a Perl-Compatible Regular Expression, so you can search not just for an exact Find what text but for a regular expression match.

Ignore case - if checked, Hot Keyboard does not distinguish between uppercase and lowercase characters in the source text.

OK and Paste - when you are done with all replacements in the source text, click this button to paste the result text in place of a previously selected one. Two following paste options are available:

Use 'Play keys' mode - check this option to use the Play keys mode when pasting text back into the application (instead of using the clipboard). You can read more about this mode in the Paste text documentation.

Allow Paste Text extended syntax - check this option to enable additional Paste Text features like inserting date and time, content of a file, etc. That is, if you check this option and the result text being pasted contains, for example, $(Time:%x %X), Hot Keyboard will paste the current date and time. Normally you should not check this option. Please refer to the Paste text documentation for the full list of available special values.

Anvanced - click this button to switch to the Advanced Extended Replace mode. This mode is described below.

Replace all - if you click this button, Hot Keyboard replaces all occurrences of the search text beginning from the current cursor position in the text area at the top of the dialog.

Replace - click this button to replace the currently highlighted instance of the source text and find the next occurrence of the search string.

Find next - click this button to find and select the next occurrence of the search string.

Undo - click this button to undo the last replacement. Please note that you cannot undo with this button if you edit text directly in the edit box. Hot Keyboard undo buffer holds up to 20 replaces.

Advanced mode of Extended Replace Macro overview

The extended replace macro in the advanced mode consists of one or more replacement rules. Each replacement rule defines text to be replaced, the replacement text and a few replace flags. The text to be replaced may be an ordinary text string or a Perl-Compatible Regular Expression. Using a text string is simpler, but regular expressions allow much more powerful text conversions.

Hot Keyboard applies replacement rules in the ascending order, beginning from the first one. If the source text matches the current replacement rule, replacement is made and Hot Keyboard continues with other replacement rules or finishes macro execution depending on the continue flag state for this rule (see below for the flags section). If a continue flag is set, Hot Keyboard increases its internal iteration counter (which is set to zero when Hot Keyboard executes the macro) and proceeds to the next or first replacement rule, thus allowing iterational replacement. Internal iteration counter prevents Hot Keyboard from hanging up in case of an endless replacement loop due to invalid rules combination. Also, Hot Keyboard checks the source string length after each replacement to prevent running out of memory if the source string becomes too long. The iteration and string length limits are not fixed and can be set by the user.

Execution of the macro ends when:
- The source text does not match any replacement rule, or
- The source text matches certain replacement rule and the continue flag for that rule is set to Stop macro execution state.

Text to be replaced

If you specify that the text to be replaced is a text string (not a regular expression), Hot Keyboard searches the source text for the first occurrence (or all occurrences if the "Replace all" flag is set, see flags below) and replaces it with the replacement text.

If you specify that the text to be replaced is a Perl-compatible regular expression, Hot Keyboard checks if it matches the source text, and if it does, replaces the part of the source text that matched the current regular expression with the replacement text. If the "Replace all" flag is set, Hot Keyboard tries to find next match in the rest of the source text, and so on.

The replacement text

When not using regular expressions (plain text mode), the replacement text is an ordinary text string too. No special characters or advanced features are available.

In case of a regular expression mode, the replacement text can contain the following special variables:

$n - reference to a part of the source string that matched the n-th group in the regular expression. Special case $0 denotes the part of the source string that matched the entire expression. The ${n} form is also available to delimit special variable from the following digits.

${nU} means exactly the same as ${n} but the matched part is converted to the uppercase before replacement.

${nL} - the same as ${nU}, but conversion to the lowercase is done instead.

Also, the following special characters are available:

\$ - the dollar sign;
\\ - backslash;
\r - the carriage return (CR, 0x0D) symbol;
\n - the line feed (LF, 0x0A) symbol;
\t - tabulation (0x09);
\xHH - an ASCII char with hexadecimal code HH.

Please note that most Windows applications use the combination of \r\n symbols for the line break.

Extended replace rule flags

Each rule has four flags:

RegExp - if set, the current rule uses the regular expression mode (this means that the text to be replaced is a regular expression and the special features described above are available for the replacement text). Otherwise, the plain text mode is used.

Replace all - if set, Hot Keyboard replaces all occurences of the search string, otherwise only the first one.

No case - if set, the case of the source string is ignored when applying this rule.

Continue - this flag defines what Hot Keyboard does when the current rule matches. It can be set to Stop macro execution, Continue with the next rule and Restart from the first rule states. This flag is available only through the Extended Replace macro editor that is opened on clicking the Adv. button.

Extended replace macro dialog

extreplace_macro1.gif

If your macro has exactly one rule, you can set its parameters directly in the macro properties dialog. Otherwise such a macro is considered an advanced one and must be edited with the Extended replace macro editor that can be opened by clicking the Adv. button.

The Play keys option allows Hot Keyboard to use the play keys method (see the Paste text macro documentation for details) instead of the clipboard when pasting processed text back to the application.

The 'Ask me' mode option, if checked, converts this macro into an Advanced Search-and-Replace tool and is already described in details above. When this option is checked, the state of the Quiet checkbox is ignored.

Quiet - if checked, Hot Keyboard immediately performs the specified replace action according to defined rules (the same behavior as in the 3.0 version), otherwise Advanced Replace dialog is displayed where you can modify source text and edit rules.

Extended Replace Macro Editor

When your extended replace macro has two or more replacement rules, it cannot be edited in the macro settings window since it is too small for this purpose. In such a case you must open extended replace macro editor by clicking the Adv. button.

Also, this dialog is shown when you execute an Extended Replace macro with both Ask me and Quiet options not set.

extreplace_editor.gif

Extended replace macro editor consists of the list of defined rules and buttons to organize these rules. The list has four columns: rule number, text to be replaced, replacement text, and flags. The flags column shows letters corresponding to the flags set:

R - the RegExp (regular expression) flag is set;
G - the Replace All (global) flag is set;
I - the No Case flag is set;
Cf - the Continue flag is set to restart from the first rule and
Cn - the Continue flag is set to continue with the next replacement rule.

Iteration limit defines the maximum number of replacements that can be made during execution of this macro. If this limit is exceeded, Hot Keyboard stops macro execution and shows an error message. This prevents Hot Keyboard from hanging in case of an endless replace loop due to invalid rules combination.

String length limit defines the maximum source text length in kilobytes. If the replacement makes the source text longer than this limit, Hot Keyboard stops the macro execution and displays an error message. This prevents Hot Keyboard from running out of memory in case of a very long source string.

Allow Paste Text extended syntax and Use Paste Text 'Play keys' mode options work in the same way as described above.

The buttons in the rules editor dialog are used to organize macro rules. Most of them become enabled when you select a rule in the list.

The Source text box contains text that was grabbed from the active application (if you selected something and then executed the macro). It can be viewed and edited here.

If you open this dialog from the macro properties window, this box is initially empty. But you can type any text here to test the macro being edited.

Result text shows the result text after all transformations. It can be updated automatically (if you check the Automatically update box) soon after you modify the source text or change a rule. Otherwise it must be updated manually by clicking the Update button.

The View macro steps button allows to view how the source text is being transformed by the macro rules, step by step. This is useful if you want to debug a macro. Clicking this button opens the Macro Steps dialog that is described below.

To edit a rule, you can select it in the list and click the Edit rule button, or double click the rule directly in the list.

To add a rule, you can click the New rule button or double click the << New rule >> line in the list. If you selected some rule and then click the New rule button, the new rule will be inserted right before the selected one. Otherwise it will be added to the end of the list.

To delete a rule, select it and click the Delete rule button. Please delete rules with care since you cannot undelete them back later.

When you are done with editing the rules, click the OK button to save them into the macro and (if you executed this macro by a hotkey) to paste the result text in place of previously selected one.

Extended Replace rule editor dialog

Editing existing rule or adding a new one brings up the Extended replace rule editor dialog. This dialog allows you to define all rule parameters.

extreplace_rule.gif

Extended Replace macro steps dialog

This dialog shows how the source text is transformed by a macro step-by-step.

extreplace_debug.gif

All transformation steps are showed in the list. The first column contains step number, the second one shows number of the rule that matched and the third column displays the source text right before it was transformed by the corresponding rule. This means that the original source text is shown in the first line of the list.

The Current step part of the dialog shows information about the selected step in the list. The Find what, Replace with, Regilar expression, Ignore case, Replace all and the continue radio group elements represent the rule that matched at the selected step. The rule parameters can be changed right there.

The Text before box shows the source text right before the matched rule is applied to it (it is the same string as shown in the third column of the list).

The Text after box shows the same text but after transformation by the matched rule. According to the Extended Replace macro logic, this becomes the source text for the next rule.

The Parameters and Paste parameters groups contain controls that were already described above.

Restart - click this button to fully restart macro execution from the first step.

Continue - click this button to continue macro execution from the selected step.

Step - click this button to execute next step of the macro.

Usage Tips

If you are a Perl programmer, you may often want to comment out a block of Perl code. In this case, you have to add a sharp sign (#) to each line of the code manually. This can be very annoying if you need to comment a large block. But with Hot Keyboard and extended replace macro you can do it with a single hot key press!

Just create a new extended replace macro, name it and assign a hot key to it. Then enter the following string into the Text to replace field:

(?m)^(.*)$

And into the Replacement text field:

# $1

Then check the Regular Expression and Replace all flags.

Click the OK button, the macro is ready! Open your text editor, select a block of Perl code and press the selected hot key. Just in a moment selected block becomes commented!

Usage ideas:

  • Easily perform uppercase and lowercase modifications in any text editor, for any part of the text
  • Replace common misspellings - all at once
  • Use Find and Replace features in applications that normally doesn't provide that capability
  • Convert multiline paragraphs to a single text line
  • Create macros to quickly comment out blocks of code in almost any programming language
<< Previous | Table Of Contents | Next >>

  © 1998-2014 Imposant