XRegex Reference

XReguex is an AppleScript library to process text with regular rexpressions. It's a wrapper of NSRegularExpression.

In simple cases, class methods of search, search_all and replace_matches.

search methods returns a MatchResult object for first matched text.When matched texts with the regular expressions can not be found, missig value is returned.

You can obtaine matched texts and range by using capture and range methods of MatchResult object.

When the regular expression is used repeatedly, compile the regular rexpression with make_with and store obtained XRegex instance. And use instance methods of first_match, matches_in, replace.

For syntax of regular expression, see the pages of NSRegularExpression and ICU.

Examples

use XRegex : script "XRegex"

(*** Using Class methods ***)
-- Obtain first matche
tell XRegex's search("\\d{4}", "1972-01-27")
if it is not missing value then
log capture(0) (*1972*)
log range(0) (*length:4, location:0*)
end if
end tell

-- Obtain all mathes
tell XRegex's search_all("\\d{2}", "1972-01-27")
repeat with a_match in it
tell a_match
log capture(0)
log range(0)
(*19*)
(*length:2, location:0*)
(*72*)
(*length:2, location:2*)
(*01*)
(*length:2, location:5*)
(*27*)
(*length:2, location:8*)
end tell
end repeat
end tell

-- Replace
log XRegex's replace_matches("\\d{2}", "1972-01-27", "xx") (*xxxx-xx-xx*)

(*** Compiling Regular Expression and Working with Instance Methods ***)
-- Simple cases
tell XRegex's make_with("(\\d{4})-\\d{1,2}-\\d{1,2}")
log count_in("2020-10-10") (*1*)

tell first_match("2020-10-10")
if it is not missing value then
log (count it) (*2*)
log its capture(0) -- 2020-10-10 : whole match
log its capture(1) -- 2020 : first capture
end if
end tell
end tell

-- Obtain matched all sub-texts
tell XRegex's make_with("\\d{2}")
set matches to matches_in("2021-10-20")
end tell
log (count matches) (*4*)
tell item 1 of matches
log (count it) (*1*)
log capture(0) (*20*)
log range(0) (*length:2, location:0*)
end tell

tell item 2 of matches
log (count it) (*1*)
log capture(0) (*21*)
set {location:loc, length:len} to range(0) (*length:2, location:2*)
--obtain substring
log substring(loc + 3, len) (*10*)
end tell


-- Replace
tell XRegex's make_with("http://([^/]+)(/[^/]+)*")
log replace("http://www.script-factory.net/index.html", ¬
"https://$1")
(*https://www.script-factory.net*)
end tell

Class Methods

Returns the first match of the regular expression in the text.

search_all

Returns a list containing all the matches of the regular expression in the text.

count_matches

Returns the number of matches of the regular expression in the text.

replace_matches

Returns a new text containing matching regular expressions replaced with the template text.

Constructor Methods

make_with

Compile a regular expression and return a new XRegex instance.

Instance Methods

first_match

Returns the first match of the regular expression in the text.

matches_in

Returns a list containing all the matches of the regular expression in the text.

count_in

Returns the number of matches of the regular expression in the text.

replace

Returns a new text containing matching regular expressions replaced with the template text.

MatchResult

MatchResult is a wapper of NSTextCheckingResult which expresses pattern maching results. Each MatchResult object contains infomation about matched texts with the pattern and caputred groups. These infomation can be obtained by using capture and range methods.

MatchResult objects are returned by search, search_all, first_match and matches_in.

The location value of range is zero based i.e. follows the manner of NSString not the manner of AppleScript's text.To obtain substring of the range calculated from returned value of range in the searched text, use substring or substring_from, because NSString's character counts and indexes may not be able to exchanged for AppleScript's text.

count

Returns a number of matched ranges.

capture

Returns a text matched with the regular expression and texts of capture groups.

as_text

Returns a whole text matched with the regular expression.

range

Returns the range mateched with the regular expression and groups.

substring

Returns the substring specified with location and langth in searched text

substring_from

Returns the substring from specified location to the end in searched text.