Quick Start

Top  Previous  Next

Agent Ransack includes a regular expression engine as one of its Expression Types. Regular expressions (some times shortened to regexp) provide a concise language to describe exactly what to search for. In very basic terms you can split an expression into two parts:

- what you are looking for

- the number of occurrences you want to find of it.

So let's take an example:

1. I want to find all files named abc, abbc, abbbc, abbbbc etc. So basically I want to find all files that begin with 'a' followed by one or more 'b' then followed by 'c'. The expression would be:

ab+c

Breaking that apart we read:

- find one occurrence of 'a'

- find at least one occurrence of 'b' (the '+' indicates 'one or more')

- find one occurrence of 'c'

The characters that specify the number of occurrences are:

+ one or more

* zero or more

? zero or one

So ab?c would find any file named abc or ac (i.e. there can be zero or one 'b').

A very important regexp character is the period '.' (the wildcard character) because it matches to ANY character. So a.c would match to aac, abc, acc, adc, aec, afc, a1c, a6c etc. And if we combine that with an occurrence character we can start producing some useful expressions:

dave.*vest

breaks down to:

- find one occurrence of 'd'

- then one occurrence of 'a'

- then one occurrence of 'v'

- then one occurrence of 'e'

- then zero or more occurrences of ANY character

- then one occurrence of 'v'

- then one occurrence of 'e'

- then one occurrence of 's'

- then one occurrence of 't'

and so matches to 'davevest', 'dave vest', 'dave is wearing a vest'.

There are other regexp characters and tricks on the following pages. More detail on regular expressions.

What is a regular expression?

Top  Previous  Next

A regular expression is a way of describing a group of words (referred to as a 'string'). It allows a user to build a complex set of rules to describe exactly what characteristics the string should have. While this documentation uses the word string you can think of a string as either a filename when searching for a filename using regular expressions, or as text in a document when using a regular expression to search the contents of files.

The simplest regular expression is a sequence of letters, numbers, or both. Such a regular expression matches any string that contains that sequence. For example:

The regular expression `foo' matches any string containing `foo'. So if you wanted to find a file with the letters 'fred' in it the regular expression would simply be 'fred'.

This is obviously a very simple example but you can express complicated rules. For example:

To find a file that begins with 'July' or 'August' followed at some point by 'Document' or 'Documents' followed at some point by a number and has a '.doc' extension the expression would be: '^(July|August).*Documents?.*[0-9]+.*\.doc$'

This expression would find:

Don't worry if the expression above looks confusing because it is. That is why Agent Ransack includes an Expression Wizard to guide you through building regular expressions using common English terms.

For more information please read regular expression basics.

Note: You can test out your expression against the Agent Ransack regular expression engine through the 'Tools' -> 'Regular Expression Tester...' menu option.

Regular expression basics

Top  Previous  Next

Regular expressions use special characters (also known as regular expression operators) to specify rules for strings. A summary of these characters are:

^        Beginning of string

$        End of string

.        Any character

[        Start of character list

]        End of character list

(        Start of expression group

)        End of expression group

|        ORs two expressions

\        Escape character

*        Preceding expression occurs zero or more times

?        Preceding expression occurs zero or one times

+        Preceding expression occurs one or more times

*, ?, + (Occurrence characters)

Top  Previous  Next

Specifies the number of occurrences of the preceding character or group. In a regular expression there are four possible choices when trying to specify how many occurrences the regular expression should match to:

Zero or one, the '?' character.

Zero or many, the '*' character.

One or many, the '+character.

Exactly one, the character itself not followed by any occurrence character.

For example:

If you entered the filename as the expression 'complaint ?doc' it would find all files that had the word 'complaint' followed by zero or one space followed by 'doc'. Therefore it would find files such as 'my complaint doc.doc' and 'mycomplaintdoc.txt', but would NOT find files such as 'my complaint_doc.doc' or 'my complaints doc.doc'.

If you entered the filename as the expression '^my.*doc$' it would find all files that began with the word 'my' followed by zero or more characters ending with 'doc' (note the use of '^' beginning of string, '.' any character, and '$' end of string special characters). Therefore it would find files such as 'my_note.doc', 'my_owndoc', and 'my_specialfile.doc' but would NOT find 'my_note.txt', 'thisis_my_note.doc'.

If you entered the filename as the expression '_file[0-9]+' would find all files that had the word '_file' followed by one or more numbers (note the use of '[' and ']' character list special characters). Therefore it would find files such as 'my_file245.doc' and 'the_file0023.txt' but would NOT find 'a_file_34.txt' or 'some_file 009.txt'.

\ (Escape character)

Top  Previous  Next

Escape character is used to suppress the special meaning of other special characters.

For example:

The expression 'Cost$' will match a string ending with 'Cost' whereas the expression 'Cost\$' will match a string that contains 'Cost$'. As you can see the escape character suppressed the special meaning of the '$' end of string character.

The expression 'file.txt' will match a string that contains 'file' followed by any character followed by 'txt, whereas the expression 'file\.txt' will match a string that contains 'file.txt'. This time the escape character suppressed the meaning of the special character '.' any character.

Finally, the expression to actually search for the '\' character is preceded with the '\', i.e. suppress the escape character, e.g. to search for '3\4' use the expression '3\\4'.

| (Expression OR)

Top  Previous  Next

Use the | when either one expression or another will do.

For example:

Both the expressions '(stabilised|stabilized) condition' and 'stabili(z|s)ed condition' will match 'stabilised condition' and 'stabilized condition'.

'(1|2|3) (person|people)' will match '1 person' and '2 people' and '3 people' but will not match '4 people' (it will also match '2 person' etc.). Note: this expression could have also been expressed using a character list.

(...) (Expression group)

Top  Previous  Next

Parentheses are used for grouping in regular expressions as in arithmetic. They are often used with the '|' ORfunctionality to group alternatives.

For example:

The expression '12 Mar(ch)? 2000' would find the string '12 March 2000' and '12 Mar 2000'. Note the use of the'?' zero or more occurrence character.

If you entered the filename as the expression '^myfile\.(txt|doc)$' it would find any file that whose name was 'myfile.txt' or 'myfile.doc'. Note the use of the '^' beginning of the string character, the '\' escape character to treat the '.' in '.txt' literally, and the '$' end of the string character.

[...] (Character lists)

Top  Previous  Next

Specifies a list of characters that are valid in the string. Characters can be listed individually or a range of characters can be indicated by giving two characters and separating them by a '-'. For example, '[abc]' will match any of the characters 'a', 'b', or 'c'; this is the same as '[a-c]', which uses a range to express the same set of characters.

You can match the characters not within a range by complementing the set. This is indicated by using a '^' as the first character in the list (note: this is the same character as the beginning of string character). For example, '[^5]' will match any character except '5'.

Multiple ranges are allowed. E.g., the list '[A-Z0-9]' is a common way to express the idea of "all alphanumeric characters." To include one of the characters `\', `]', `-' or `^' in a character list use the '\' escape character.

For example:

The expression '[0-9]+' will find any number in a string (note the use of the '+' occurrence character).

The expression '[0-9]+/[0-9]+/[0-9]+' is a expression that could be used to search for dates within a string. Although it does not check the validity of the date it is unlikely that any other string would be match that pattern.

. (Wildcard character)

Top  Previous  Next

Matches any single character. It is used to specify an unknown portion in the string. Because the period is used in almost all Windows file names it is very common to forget that it has a very special meaning in regular expressions. If the user wishes to use the period literally in a search it must be preceded by the '\' escape character. For example:

If you entered the filename as the expression 'mydoc.doc' it would find any file that had 'mydoc' followed by any character followed by 'doc'. Therefore although it would find 'mydoc.doc' it would also find 'mydoc1doc' and 'mydocXdoc'. If you wanted to just search for 'mydoc.doc' the expression would be 'mydoc\.doc'.

Example:

If you entered the filename as the expression '^mydocument..\.txt$' it would find any file that began with 'mydocument' followed by exactly any two characters and ended with '.txt' (note the use of the '^' beginning of the string character, and the '\' escape character to treat the '.' in '.txt' literally, and the '$' end of the stringcharacter). Therefore it would find files such as 'mydocument_1.txt' and 'mydocument1a.txt' but would not find files such as 'mydocument.txt' and 'mydocument_1a.txt'.

The expression 'my.*\.txt' would find any file that includes 'my' followed by any number of characters followed by '.txt' (note the use of '*' to specify zero or more occurrences). Therefore it would find files such as 'my_examples.txt' and 'this is my file.txt.doc' but would not find files such as 'myfile.doc' and 'm_y_file.txt'.

$ (End of string)

Top  Previous  Next

Matches the end of a string (to match the beginning of a string use '^').

For example:

If you entered the filename as the expression 'complaint\.doc$' it would find all files that ended with 'complaint.doc' (note the use of the '\' escape character for the '.'). Therefore it would find files such as 'bank_complaint.doc' and 'my_complaint.doc' but would not find files such as 'some_complaint.txt' or 'some_complaint_2.doc'.

^ (Beginning of string)

Top  Previous  Next

Matches the beginning of a string (to match the end of a string use '$').

For example:

If you entered the filename as the expression '^win' it would find all files that began with the name 'win'. Therefore it would find files such as 'winhelp.exe' and 'windows_questions.txt' but would not find files such as 'Copy of winhelp.exe' and 'some_winfile.txt.

Other Examples

Top  Previous 

AND

Although the regular expression engine does not directly support the concept of the boolean AND operation it can, in a limited way, be simulated. e.g.

To search for a line containing 'error' AND 'log' the expression would be '(error.*log)|(log.*error)'. Basically the different possible combinations have been combined, i.e. find 'error' followed by 'log' OR find 'log' followed by 'error'. While this works for a small number of words it does become infeasible with a larger number of words.

Obviously the simplest way to specify an AND style expression is to use the Boolean expression engine.