Differences

This shows you the differences between two versions of the page.

--- action:Search_using_Regular_Expression [2017/09/07 08:11] – [Topics] peternlewis
+++ action:Search_using_Regular_Expression [2022/04/17 21:37] (current) – [Examples] ccstone
@@ Line 1: / Line 1: @@
-The //Search using Regular Expression// action allows you to search a clipboard, variable, a file or some text for a [[:Regular Expressions|regular expression]] and capture what you find to one or more variables. This can be very useful for splitting apart the contents of a variable.
+====== Search using Regular Expression Action ======
+{{:regex-icon.png?nolink|}}
+The //Search using Regular Expression// action allows you to search a clipboard, variable, a file (v8+) or some text (v8+) for a [[:Regular Expressions|regular expression]] and capture what you find to one or more variables. This can be very useful for splitting apart the contents of a variable.
+:!:  **Note:  This RegEx Search returns _only the first_ match in the source text.**\\
+If you want to process _all_ matches, you will need to use a [[action:For_Each|For Each Action]] as [[:Regular_Expressions#Examples|Shown in this Example]].
 {{:action:search-using-regex.png?nolink&516|}}
-Select the source to search to search using the //Search// pop-up.
+===== How To Use =====
+==== Source ====
+Select the source to search to search using the //Search// pop-up.  In all of the RegEx searches, you can choose to search in any one of the following: System Clipboard, Variable, File, Text entered into the Action, and Named Clipboard.
+==== Case Sensitivity ====
+Select whether or not to match the case from the //using Regular Expression// pop-up. You can also use a RegEx flag at the beginning of the pattern to indicate case insensitive matching:  `(?i)`
+==== RegEx Pattern to Search For ====
+Then enter the RegEx pattern to search for in the text area.
+==== Save Capture Groups to Variables ====
-You can search for Regular Expression, matching case sensitively or ignoring the case.
+Enter the [[manual:Variables|Variable]] for each the entire Match and each Capture Group you wish to save as a Variable.  This output section will auto-expand to present one field for each Capture Group in your RegEx pattern.
-Select whether or not to match the case from the //using Regular Expression// pop-up. Then enter the text to search for in the text area.
+For more information, see [[https://www.regular-expressions.info/brackets.html | Capture Groups]].
-Select where to save results with the //and save capture groups to Variables// section. The entire match, and each capture group (enclosed in brackets) can be saved to variables.  Depending on the nature of your search you may simply be presented with an //All// option, or with the opportunity to save multiple results to multiple variables.
+==== Handling Search Failure ====
-If the search fails, by default (7.1+) the action will abort the macro and notify you of the failure.  The destination variables will not be modified.  You can turn off aborting the macro and/or notifying you in the gear menu (the destination variables will still not be modified in this case).
+If the search fails (no match), by default (7.1+) the action will abort the macro and notify you of the failure.  The destination variables will not be modified.  You can turn off aborting the macro and/or notifying you in the gear menu (the destination variables will still not be modified in this case).
-Examples:
+===== Examples =====
-  * Use a regular expression to search through a product price list and save only certain parts of it.
+**1. Use a regular expression to search through a product price list and save only certain parts of it.**
-Given a line like
-//SKU1234	Widget 1	$12.95//
+If your Source String (data) is:
+```text
+SKU1234Δ    Widget 1Δ	$12.95
+```
+(the "Δ" character is a TAB character)\\
-this could look like the following:
+then you would use a RegEx pattern like:\\
+`(SKU\d{4})\h(.+)\h(.+)`
-Search for: (SKU\d{4})\t(.+)\t(.+)
+To see a detailed explanation, and live editor, see https://regex101.com/r/MQ5FwG/1/.\\
-And capture: the first and third bracketed items to save only the SKU number and the price.
+Save the first and third bracketed items (Capture Groups) to save the SKU number and the price.
 To work through a list you would need to include a loop or repeat of some kind.
-{{:action:searchvariableexample.png|}}
+{{:action:searchvariableexample.png?514|}}
 Which results in:
-{{:action:searchvariableresult.png|}}
+{{:action:searchvariableresult.png?345|}}
 ===== See Also =====