Durchsucht eine Zeichenfolge mit einem Suchmuster in Form eines "regulären Ausdrucks" (regular expression).
FoundPos := RegExMatch(Haystack, NeedleRegEx [, UnquotedOutputVar = "", StartingPosition = 1])
| FoundPos | RegExMatch() gibt in dieser Variablen die Position des ersten Zeichens des ersten Treffers zurück. Dabei steht 1 für das erste Zeichen der durchsuchten Zeichenfolge. Wenn das Suchmuster nicht gefunden wird, wird 0 geliefert. Wenn ein Fehler auftritt (wie z.B. ein Syntaxfehler in NeedleRegEx) ist die Variable leer und ErrorLevel wird nicht auf 0 sondern auf einen der unten angegebenen Werte gesetzt. |
| Haystack | (Heuhaufen) Die Zeichenfolge, die durchsucht wird. |
| NeedleRegEx | (Nadel : Die Nadel im Heuhaufen suchen!) Das Suchmuster als "Perl-compatible Regular Expression" (PCRE). Alle Optionen müssen am Anfang des Musters eingefügt und mit einer schließenden runden Klammer ")" abgeschlossen werden. Das Muster "i)abc.*123" schaltet z.B. die Option "i" (case-insensitive) ein und sucht nach "abc", gefolgt von keinem oder beliebig vielen beliebigen Zeichen, gefolgt von "123". Wenn keine Optionen verwendet werden, ist die ")" optional: ")abc" und "abc" sind gleichbedeutend. |
| UnquotedOutputVar | Mode 1 (Standard): UnquotedOutputVar ist der (nicht in Anführungszeichen eingeschlossene) Name einer Variablen, in der der Teil von Haystack abgelegt wird, der dem kompletten Suchmuster entspricht. Wenn das Muster nicht gefunden wird, liefert die Funktion 0 und die Variable sowie ggf. die nachfolgend beschriebenen Arrayelemente sind leer. Wenn NeedleRegEx capturing subpatterns (auszugebende Teilmuster) enthält, werden die zugehörigen Treffer in einem Array mit dem Stammnamen UnquotedOutputVar abgelegt. Ist der Name der Variablen z.B. Match, wird der auf das erste Teilmuster passende Treffer in Match1 gespeichert, der zweite in Match2, usw. Eine Ausnahme bilden named subpatterns (benannte Teilmuster). Sie werden unter Verwendung des Namens gespeichert. Der dem benannten Teilmuster (?P<Year>\d{4}) zugehörige Treffer wird z.B. in der Variablen MatchYear gespeichert. Wenn für ein Teilmuster keine Übereinstimmung gefunden wird oder die Funktion 0 zurückgibt, ist die zugehörige Variable leer. Wenn innerhalb einer Funktion mit RegExMatch() ein Array erzeugt wird, das nicht nur lokal sondern auch global ansprechbar sein soll, muss der Stammname des Arrays (hier z.B. Match) vorher als globale Variable deklariert werden. Das Umgekehrte gilt für Funktionen die als assume-global deklariert wurden. Mode 2 (Position und Länge): Wenn die Optionen den Buchstaben P enthalten (wie z.B. "P)abc.*123") wird die Länge des Treffers für das komplette Suchmuster in OutputVar gespeichert, bzw. 0, wenn nichts gefunden wurde. Wenn das Suchmuster auszugebende Teilmuster enthält, werden deren Positionen und Längen in zwei Arrays gespeichert: OutputVarPos und OutputVarLen. Wenn der Variablenname z.B. Match ist, wird die Position des dem ersten Teilmuster zugehörigen Treffers in MatchPos1 und seine Länge in MatchLen1 abgelegt. Wenn ein Teilmuster nicht gefunden wurde oder die gesamte Funktion 0 zurückgibt, werden beide Variablen auf 0 gesetzt. Die Ausnahme sind wieder benannte Teilmuster. Sie werden unter Verwendung des Namens und nicht einer laufenden Nummer gespeichert (z.B. MatchPosYear und MatchLenYear). |
| StartingPosition | Wenn StartingPosition nicht angegeben wird, beginnt die Suche beim 1. Zeichen (am Anfang von Haystack). Bei Angabe von 2 beginnt sie beim zweiten, bei 3 beim dritten Zeichen, usw. Wenn StartingPosition größer ist als die Länge von Haystack, beginnt die Suche mit dem Leerstring am Ende von Haystack und findet normalerweise keinen Treffer. Wenn StartingPosition einen Wert kleiner als 1 enthält, wird dieser als Distanz zum Ende von Haystack behandelt. 0 startet die Suche z.B. beim letzten Zeichen und -1 beim vorletzten Zeichen. Wenn die Distanz größer ist als die Länge von Haystack, wird der komplette Haystack durchsucht. Die zurückgelieferte Position ist unabhängig vom Wert in StartingPosition immer relativ zum Anfang von Haystack. Die Position von "abc" in "123abc789" ist z.B. immer 4. |
ErrorLevel wird auf einen der folgenden Werte gesetzt:
Am Anfang eines regulären Ausdrucks können die folgenden Optionen gefolgt von einer abschließenden runden Klammer ")" angegeben werden. Das Suchmuster "im)abc" sucht z.B. nach abc und verwendet dabei die Optionen i (case-insensitive) und m (multiline). Die Klammer ")" kann entfallen, wenn keine Optionen angegeben werden. Dies entspricht zwar nicht der traditionellen PCRE-Syntax, doch man kommt ohne spezielle Begrenzer wie z.B. den Schrägstrich "/" aus und diese müssen deshalb im Suchmuster auch nicht maskiert werden. Außerdem wird die Performance verbessert, weil die Optionen so leichter erkannt werden können.
| i | Case-insensitive: Buchstaben werden ohne Berücksichtigung der Groß- / Kleinschreibung gesucht. |
| m | Multiline (mehrzeilig). Haystack wird, falls es Zeilenvorschübe (LF: `n) enthält, als mehrere aufeinanderfolgende Zeilen betrachtet. Das verändert insbesondere das folgende Verhalten: 1) Circumflex (^) sucht direkt hinter allen Zeilenvorschüben und nicht nur am Anfang von Haystack. Ein Zeilenvorschub am Ende von Haystack wird dabei aber ignoriert. 2) Dollarzeichen ($) sucht direkt vor jedem Zeilenvorschub und nicht nur am Ende von Haystack. Das Suchmuster "m)^abc$" wird z.B. im Haystack "xyz`r`nabc" nur mit der Option "m" gefunden. Bei Verwendung der Option "m" wird die eventuell zusätzlich vorhandene Option "D" ignoriert. |
| s | (DotAll) Mit dieser Option steht der Punkt (.) für alle Zeichen einschließlich des Zeilenvorschubs, der normalerweise nicht erfasst wird. Wenn als Zeilenvorschub das übliche CRLF (`r`n) eingestellt ist, werden für einen Treffer aber mindestens zwei Punkte benötigt. Unabhängig von dieser Option umfasst eine negative Zeichengruppe wie [^a] immer auch den Zeilenvorschub. |
| x | Durch diese Option werden "unsichtbare" Zeichen (white spaces) wie Tabulatoren und Zeilenvorschübe ignoriert, wenn sie nicht maskiert sind oder innerhalb einer Zeichengruppe "[]" stehen. Die Zeichen `n und `t gehören zu diesen Zeichen, weil sie zum Zeitpunkt der Übersetzung des PCRE bereits von AHK durch ihre eigentlichen Werte ersetzt wurden. Die Zeichen \n und \t werden dagegen nicht ignoriert, weil der Backslash ("\") das normale PCRE Escape-Zeichen ist. Die Option x ignoriert auch alle Zeichen zwischen einem nicht maskierten # außerhalb einer Zeichengruppe und dem folgenden Zeilenvorschub, inklusive #. So kann man Kommentare in komplizierte Suchmuster einfügen. Dies gilt aber nur für normale Zeichenfolgen. Innerhalb von bestimmten Zeichensequenzen wie z.B. "(?(", der Einleitung eines bedingten Teilmusters, dürfen solche Zeichen niemals stehen. |
| A | Bewirkt, dass das Suchmuster über den Anfang von Haystack gelegt (verankert) wird und nur dort einen Treffer erzielen kann. In den meisten Fällen entspricht das dem expliziten Verankern des Suchmusters mit "^". |
| D | Bewirkt, dass das Dollarzeichen ($) einen am Ende von Haystack stehenden Zeilenvorschub mit einbezieht. Ohne diese Option sucht $ nur bis zum letzten Zeichen vor einem abschließenden Zeilenvorschub. Hinweis: Diese Option wird ignoriert, wenn zusätzlich die Option "m" angegeben ist. |
| J | Erlaubt mehrere gleichnamige benannte Teilmuster. Diese Option kann verwendet werden, wenn feststeht, dass von mehreren gleichbenannten Teilmustern nur eines gefunden werden kann. Hinweis: Wenn dennoch mehrere gleichbenannte Teilmuster gefunden werden, wird nur der erste Treffer gespeichert. Weiter ist zu beachten, das die Namen nicht case-sensitive sind. |
| U | Ungreedy (ungierig). Bewirkt, dass die Mengenbezeichner *+?{} nur so viele Zeichen verbrauchen, wie für einen Treffer minimal benötigt werden, und weitere Zeichen der Suche nach dem nächsten Teilmuster überlassen. Wenn die Option "U" nicht angegeben ist, können einzelne Mengenbezeichner "ungierig" gemacht werden, indem man ihnen ein Fragezeichen (?) folgen lässt. Ist die Option "U" angegeben, macht das ? den voranstehenden Mengenbezeichner "gierig". |
| X | PCRE_EXTRA. Ermöglicht PCRE Eigenschaften, die zu Perl inkompatibel sind. Zur Zeit ist die einzige solche Eigenschaft, dass jeder Backslash (\) innerhalb eines Ausdrucks, dem ein Buchstabe folgt, der keine spezielle Funktion hat, als Fehler behandelt wird und ErrorLevel entsprechend gesetzt wird. Damit können bisher nicht verwendete Backslashsequenzen für eine mögliche spätere Verwendung reserviert werden. Ohne diese Option wird \ in Backslashsequenzen ohne besondere Funktion ignoriert, \g und g sind also gleichbedeutend. Bei nicht alphabetischen Backslashsequenzen ohne besondere Funktion wird der \ unabhängig von dieser Option immer ignoriert, \/ und / werden z.B. immer als / behandelt. |
| P | Position mode (Position und Länge). Bewirkt, dass statt der Trefferzeichenfolgen die Position und die Länge der Treffer zurückgeliefert wird. Einzelheiten finden sich oben unter OutputVar. |
| S | Das Suchmuster wird mit dem Ziel untersucht, die Performance zu verbessern. Diese Option kann nützlich sein, wenn ein komplexes Suchmuster viele Male wiederverwendet wird. Wenn PCRE eine Möglichkeit findet, die Performance zu verbessern, wird diese Möglichkeit zusätzlich im Hauptspeicher vorgehalten und bei späteren Ausführungen desselben Musters verwendet (weitere Verwendungen des Musters sollten ebenfalls die S-Option angeben, weil das Finden eines Treffers im Cache benötigt, dass die Optionsangaben exakt gleich sind, dies schließt auch deren Reihenfolge ein). |
| `n | Schaltet vom Standardzeilenvorschub CRLF (`r`n) auf ein einzelnes LF (`n) um, den Standard auf UNIX Systemen. Der ausgewählte Zeilenvorschub beeinflusst das Verhalten der Anker (^ und $) und des Punktes (.). |
| `r | Schaltet vom Standardzeilenvorschub CRLF (`r`n) auf ein einzelnes CR (`r) um. |
| `a | In v1.0.46.06+ erkennt `a alle Arten des Zeilenvorschubs, nämlich CR (`r), LF (`n), CRLF (`r`n), VT (`v /vertical tab/chr(0xB)), FF (`f /formfeed/chr(0xC)), und NEL/next-line/chr(0x85). In v1.0.47.05+, können Zeilenvorschübe auf CR, LF und CRLF beschränkt werden indem (*ANYCRLF) in Großbuchstaben am Beginn des Musters angegeben wird (nach den Optionen); z.B. im)(*ANYCRLF)^abc$ |
Hinweis: Die einzelnen Optionen können durch Leerzeichen und/oder Tabulatoren getrennt werden.
Bei der Suche nach einem einfachen Teilstring in einem größeren String ist InStr() in der Regel schneller als RegExMatch().
Für die Verbesserung der Performance werden die 100 zuletzt verwendeten regulären Ausdrücke in übersetzter Form im Hauptspeicher gehalten.
Die Option study (S) kann die Performance von regulären Ausdrücken verbessern, die z.B. in einer Schleife wiederholt aufgerufen werden.
Ein Teilmuster kann mit einem Namen versehen werden, wie z.B. Year im Muster (?P<Year>\d{4}). Die Namen dürfen bis zu 32 alphanumerische Zeichen und Unterstriche ("_") enthalten. Obwohl benannte Teilmuster innerhalb der RegEx- Anweisung auch über ihre Nummer angesprochen werden können (z.B. bei Rückverweisen), werden sie im Ausgabearray nur mit ihrem Namen aber nicht mit ihrer Nummer gespeichert. Wenn "Year" z.B. das erste Teilmuster ist, wird der zugehörige Treffer in OutputVarYear gespeichert. OutputVar1 bleibt unverändert, auch wenn sie noch einen Wert von einer früheren RegEx-Anweisung enthält. Wenn auf "Year" noch unbenannte Teilmuster folgen, werden sie beginnend mit OutputVar2 gespeichert und nicht mit OutputVar1.
Die meisten Zeichen wie abc123 können innerhalb eines regulären Ausdrucks normal verwendet werden. Den Zeichen \.*?+[{|()^$ sind aber bestimmte Funktionen zugeordnet. Ihnen muss deshalb ein Backslash ("\") vorangestellt werden, wenn sie als normale Zeichen behandelt werden sollen. \. ist z.B. ein normaler Punkt und \\ ein normaler Backslash. Diese Form der Maskierung ist unnötig, wenn man den Text in \Q und \E einschließt (z.B. \QNormaler Text mit Klammern ()\E).
Innerhalb eines regulären Ausdrucks können spezielle Zeichen wie Tabulator oder Zeilenvorschub sowohl mit dem AHK Escape-Zeichen (`) als auch mit dem Backslash (\) gekennzeichnet werden, `t ist z.B. gleichbedeutend mit \t.
Um die Grundbegriffe der regulären Ausdrücke zu erlernen oder das Gedächtnis aufzufrischen, siehe auch RegEx Quick Reference.
AutoHotkey's reguläre Ausdrücke sind als "Perl-compatible Regular Expressions" (PCRE) von www.pcre.org implementiert.
RegExReplace(), RegEx Quick Reference, InStr(), IfInString, StringGetPos, SubStr(), SetTitleMatchMode RegEx, Global matching and Grep (forum link)
Übliche Quellen für Textdaten: FileRead, UrlDownloadToFile, Clipboard, GUI Edit controls
FoundPos := RegExMatch("xxxabc123xyz", "abc.*xyz") ; Liefert 4, die Position auf der der Treffer beginnt.
FoundPos := RegExMatch("abc123123", "123$") ; Liefert 7, weil der Treffer wegen $ am Ende liegen muss.
FoundPos := RegExMatch("abc123", "i)^ABC") ; Liefert 1, weil wegen der Option i die Groß/Kleinschreibung nicht beachtet wird.
FoundPos := RegExMatch("abcXYZ123", "abc(.*)123", SubPat) ; Liefert 1 und speichert "XYZ" in SubPat1.
FoundPos := RegExMatch("abc123abc456", "abc\d+", "", 2) ; Liefert 7 anstelle von 1, weil wegen StartingPosition 2 erst ab der zweiten Stelle gesucht wird.
; Für weitere allgemeine RegEx Beispiele siehe auch RegEx Quick Reference.