The Action panel is the place where you tell RegexMagic which action you plan to take with your regular expression. You can collect parts of the text matched by the regular expression, or replace them with different parts or with new text. The settings on the Action panel determine the replacement text that is generated, if any. Together, the Samples, Match, and Action panels define a RegexMagic formula to generate a regular expression, and possibly a replacement text.
In the default layout, the Action panel shares the top left tab with the Samples and Match panels. Depending on which panel you last used, that tab will say “Samples, Match” or “Samples, Action”. Click that tab, and then on the Action tab inside it, to activate the Action panel in the default layout. In the side by side layout, the Match and Action panels are combined into one tab labeled “Match, Action”. Clicking that tab shows both panels. In the dual monitor tabbed layout, the Action panel has its own tab in RegexMagic’s main window. In the dual monitor side by side layout, the Action panel is always visible in the main window.
Press Alt+4 on the keyboard to move keyboard focus to the Samples panel, and to make it visible if it was hidden. Or, select the Samples item in the View menu. You can access that menu by the View button on the Assistant panel, and by right-clicking on the caption or tab of any panel in RegexMagic.
You can tell RegexMagic to add capturing groups to your regular expression. Capturing groups make it possible to extract different parts of the regex match. All programming languages that support regular expressions provide functions or variables that allow you to retrieve the text matched by each of the capturing groups. More advanced software tools also allow you to work with text matched by capturing groups. E.g. in PowerGREP, you can run a “collect data” action that collects the text matched by one or more capturing groups, instead of or in addition to the overall regex match.
The other major purpose of capturing groups is to reinsert parts of the regex match into the replacement text while doing a search-and-replace. RegexMagic automatically creates the needed capturing groups and uses backreferences to those groups to the replacement text when you tell RegexMagic to replace fields. If your regex matches three fields, and you tell RegexMagic to replace field with field , then RegexMagic adds capturing groups to capture the text matched by fields and . The replacement text will have one backreference to field (essentially leaving the text matched by that field in place), and two backreferences to field (the first one replacing field with field , and the second one leaving field in place).
This is the list of capturing groups that you have defined. The name of each group is shown. If you have generated the regular expression, the actual backreferences are shown between brackets.
Select a capturing group in this list to edit it.
RegexMagic may automatically create capturing groups if those are needed by other options that you have selected, such as an action to replace certain fields. Those capturing groups are marked as "auto-generated". RegexMagic will automatically recreate or delete those as needed when you generate the regular expression.
Add a new capturing group. After adding the group, type in its name and choose what to capture.
Delete the selected capturing group.
Delete all the capturing groups that you have added.
Auto-generated capturing groups that are needed for the "action to take" will not be deleted. Set "action to take" to "no action" and regenerate the regex if you want to remove the auto-generated groups too.
Type in a name for the capturing group. Only the letters A-Z and the digits 0-9 are permitted.
If your regular expression flavor supports named capture, RegexMagic will use this name in the regular expression. If not, you can still give the group a name for easy reference within RegexMagic, even though the actual backreference will be a number.
If you do not give the group a name, RegexMagic will generate a numbered capturing group.
After you generate the regular expression, this field will show the actual backreferences that you can use to get the text matched by this capturing group. Normally, this backreference will be the same as the name of the group, or a number if your regex flavor does not support named capture.
It is possible that RegexMagic will generate the same capturing group more than once. This will happen when you want to capture a part of something that generates multiple alternatives in the regular expression. Usually, only one of those backreferences will have actually captured something when your regex finds a match.
If a capturing group is unused, RegexMagic will display "none" as the actual backreference. This will happen if you chose to capture something that is not added to the regular expression, e.g. the decimal separator of a field that matches integer numbers only.
The actual backreferences will be indicated as "unknown" if you haven't generated the regular expression yet.
Choose which part of the regular expression the selected capturing group should capture.
Select the field that the selected capturing group should capture. This is the list of fields you defined on the Match panel.
Select the last field that the selected capturing group should capture. This is the list of fields you defined on the Match panel.
Select which part of the field you want to capture. The available parts depend on the pattern you're using for the field.
Regular expressions are used for three common tasks: finding text, splitting text, and replacing text. If you just want to run a search, select “no action”. If you want to split text along regex matches, select “split subject along regex”. RegexMagic will not generate a replacement text for these two choices.
When doing a search-and-replace, the entire regex match is always replaced. To replace only part of the regex match, capturing groups have to be used to reinsert the parts that you don’t want to change back into the replacement text. RegexMagic automatically takes care of this when you select one of the actions that replace only one or only certain fields.
Choose if you want to take a certain action on each regular expression match. The action you select here determines the functions available on the Use panel.
Select the field that you want to replace with something new. You can choose from the list of capturing groups you defined on the Action panel.
Select the field that you want to replace with something new. This is the list of fields you defined on the Match panel.
Choose if you want to take a certain action on each regular expression match. The action you select here determines the functions available on the Use tab.
A backreference that holds the text matched by this capturing group will be inserted into the replacement text. You can choose from the list of capturing groups you defined on the Action panel.
A backreference that holds the text matched by this field will be inserted into the replacement text. This is the list of fields you defined on the Match panel. If you did not define a capturing group for this field, RegexMagic will automatically create one.
Select the replacement text flavor this replacement text was created for.
If this flavor is different than the flavor for the final replacement text, RegexMagic will automatically convert the replacement text below before inserting it into the final replacement text.
Type in the replacement text you want to use.
If you chose for RegexMagic to interpret backreferences in this replacement text, they will be highlighted according to the regular expression flavor that you selected. Use the right-click menu to insert backreferences to the capturing groups that you defined.
Turn on to limit the number of items in the resulting array when the subject string is split. Turn off to split the subject string as many times as possible along all regex matches.
Enter the maximum the number of items in the resulting array when the subject string is split. The subject string will be split at most one time less than the number you enter, with the last element in the array being the unsplit remainder of the subject string. The minimum number you can enter is 2 to split the string once on the first regex match and return an array with 2 strings.
Turn on the add text matched by capturing groups to the returned array between the split parts of the subject string. In most applications, capturing groups added to the array do not count towards the limit that you may have specified for the number of strings in the returned array.
Turn off to discard text matched by capturing groups.
Turn on to add empty strings to the array when adjacent regex matches are found. Depending on the application, the array may or may not have trailing empty strings when a regex match is found at the end of the subject string.
Turn off to never add any empty strings to the returned array.