Documentation/How Tos/Regular Expressions in Writer

Introduction:

In simple terms regular expressions are a clever way to find & replace text. Regular expressions can be both powerful and complex, and it is easy for inexperienced users to make mistakes. We shall only describe some basics here, to allow an inexperienced user to get started.. (But more experienced users might find the Troubleshooting section at the end worthwhile).

A typical use for regular expressions is in finding text in a Writer document; for instance to locate all occurrences of man or woman in your document, you could search using a regular expression which would find both words.

Regular expressions are very common in some areas of computing, and are often known as regex or regexp. Not all regex are the same - so reading the relevant manual is sensible.

Where regular expressions may be used in OOo:

In Writer:

Edit - Find & Replace dialog

Edit - Changes - Accept/reject command (Filter tab)

In Calc:

Edit - Find & Replace dialog

Data - Filter - Standard filter

Functions, such as SUMIF, LOOKUP

In Base:

Find Record command

The dialogs that appear when you use the above commands generally have an option to use regular expressions (which is off by default). For example

[[Image:]]

A Simple Example

If you have little or no experience of regular expressions, you may find it easiest to study them in Writer rather than say Calc.

In Writer, bring up the Find and Replace dialog from the Edit menu.

One the dialog, choose More Options and tick the Regular Expressions box

In the Search box enter r.d - the dot here means 'any single character'.

Clicking the Find All button will now find all the places where an r is followed by another character followed by a d, for instance 'red' or 'hotrod 'or 'bride' or 'your dog' (this last example is r followed by a space followed by d - the space is a character).

If you type xxx into the Replace with box, and click the Replace All button, these become 'xxx', 'hotxxx', 'bxxxe', 'youxxxog'

That may not be very useful, but it shows the principle. We'll continue to use the Find and Replace dialog to explain in more detail.

How Regular Expressions are applied in OpenOffice.org

OpenOffice.org regular expressions divide the text to be searched into portions and examine each portion separately.

In Writer, text is separated by an end of paragraph mark or by a hard line break (Shift-Enter). For example r.d will not match r at the end of a paragraph with d beginning the next paragraph. Paragraphs are treated separately.

The least you need to know about regular expressions

If you don't want to find out exactly how regular expressions work, but just want to get a job done, try the HowTo: Common tasks with Regular Expressions (in preparation)

Otherwise, read on.

Literal characters

If your regular expression contains characters other than the so-called 'special characters' . ^ $ * + ? \ [ ( { | then those characters are matched literally.

For example: red matches red redraw and Freddie.

OpenOffice.org allows you to choose whether you care if a character is 'UPPER CASE' or 'lower case'. If you tick the box to 'match case' on the Find and Replace dialog, then red will not match Red or FRED; if you un-tick that box then the case is ignored and both will be matched.

Special characters

The special characters are . ^ $ * + ? \ [ ( { |

They have special meanings in a regular expression, as we're about to describe.

If you wish to match one of these characters literally, place a backslash \ before it.

For example: to match $100 use \$100 - the \$ is taken to mean $ .

Single character match (. ?)

The dot . special character stands for any single character.

For example: r.d matches 'red' and 'hotrod ' and 'bride' and 'your dog'

The question mark ? special character means 'match zero or one of the preceding character' - or 'match the preceding character if it is found'.

For example: rea?d matches 'red' and 'read' - a? means 'match a single a if there is one'.

Repeating match (+ *)

The plus + special character means 'match one or more of the preceding character'.

For example: re+d matches 'red' and 'reed' and 'reeeeed' - e+ means match one or more e's.

The star * special character means 'match zero or more of the preceding character'.

For example: rea*d matches 'red' and 'read' and 'reaaaaaaad' - a* means match zero or more a's .

A common use for * is after the dot character - ie .* which means 'any or no characters'.

Use the star * with caution; it will grab everything it can:

For example: r.*d matches 'red' but in Writer if your paragraph is actually 'The referee showed him the red card again' the match found is 'referee showed him the red card' - that is, the first r and the last possible d. Regular expressions are greedy by nature.

Positional match (^ $)

The circumflex ^ special character means 'match at the beginning of the text'.

The dollar $ special character means 'match at the end of the text'.

Remember that OpenOffice.org regular expressions divide up the text to be searched - each paragraph in Writer (or part of a paragraph separated by hard line breaks) is examined separately.

For example: ^red matches 'red' at the start of a paragraph (red night shepherd's delight).

For example: red$ matches 'red' at the end of a paragraph (he felt himself go red)

Alternative matches [...] |

Characters enclosed in square brackets are alternatives - any one of them may match. You can also include ranges of characters, such as a-z or 0-9, rather than typing in abcdefghijklmnopqrstuvwxyz or 0123456789

For example: r[eo]d matches 'red' and 'rod' but not 'rid'

For example: [m-p]ut matches 'mut' and 'nut' and 'out' and 'put'

For example: [hm-p]ut matches 'hut' and 'mut' and 'nut' and 'out' and 'put'

The pipe character | is a special character which allows the expression either side of the | to match.

For example: red|blue matches 'red' and 'blue'

Full list of OOo regular expressions

We've discussed some of the things you can do with regular expressions.

Help - OpenOffice.org Help has a full list; however please see Troubleshooting below for some caveats...

Troubleshooting and Weird things in OOo regular expressions

If you are new to regular expressions, please realise that they can be tricky - if you are not getting the results you expect, you might need to check that you understand well enough. Try to keep regular expressions as simple and unambitious as possible.

On the other hand, there are some 'points of interest' with OOo regular expressions that may surprise experienced users.

• [:digit:] [:space:] [:print:] [:cntrl:] [:alnum:] [:alpha:] [:lower:] [:upper:] - these do not function as they stand. The workaround is to enclose them in brackets, eg ([:digit:])
  

• [:space:] or rather ([:space:]) matches the space character, but does not match other whitespace characters such as tab (contrary to what Help says)
  

• [:print:] or rather ([:print:]) does not match the double quote characters “” (and possibly some others?), nor does it match tab. It does match space.
  

• [:cntrl:] or rather ([:cntrl:]) matches tab and hard line break, but not paragraph mark. In view of the comments on paragraph marks later, this is perhaps to be expected.
  

• There are currently no 'sub-matches' in OOo regular expressions. Most other regex allow a syntax like \1 and \2 to manipulate the first / second group matches found. The target for implementation of sub-matches is OOo2.4. A workaround until then is to use Find all, then immediately use Find/Replace again in the selection. This may (or may not) allow you to do what you want.
  

• The OOo regular expression behaviour when matching paragraph marks and hard line breaks is 'unusual'. This is partly because regular expressions in other software usually deal with ordinary plain text, whereas OOo regular expressions divide the text at paragraph marks and hard line breaks. For whatever reason, this is what you can do:
  • $ on its own will match a paragraph mark - and can be replaced by say a space, or indeed nothing, in order to merge two paragraphs together. Note that red$ will match red at the end of a paragraph, and if you replace it with say a space, you simply get a space where red was - and the paragraphs are unaffected - the paragraph mark is not replaced.
  • ^$ will match an empty paragraph, which can be replaced by say nothing, in order to remove the empty paragraph. Note that ^red$ matches a paragraph with only 'red' in it - replacing this with nothing leaves an empty paragraph - the paragraph marks at either end are not replaced.
  • \n will match a hard line break (Shift-Enter) if it is entered in the Search box. In this context it is simply treated like a character, and can be replaced by say a space, or nothing. The regular expression red\n will match red followed by a hard line break character - and if replaced simply by say blue the hard line break will also be replaced. The regular expression red$ will match red followed by a hard line break. In this case, replacing with blue will only replace red - and will leave the hard line break intact.
  • If you wish to replace every hard line break with a paragraph mark, firstly you will search for \n with Find All to select the hard line breaks. Then in the Replace box you enter \n, which in the Replace box stands for a paragraph mark and choose Replace All. This is somewhat bizarre, but at least now you know. If you wished to replace something with a hard line break, you could presumably enter it as a \xXXXX hexadecimal code. Note that \r is interpreted as a literal 'r', not a carriage return.
    

• ([:lower:]) and ([:upper:]) are not functional unless the Match case box is ticked - although a possible source of confusion, this does work as the Help says.
  

• \<red will match red at the beginning of a word, as the Help says. The test used to define the beginning of a word seems to be that the preceding character is a space, tab, newline, paragraph mark or any non-alphanumeric character - so “red” (with double quotes) or @red with both match.
  

• red\> will match red at the end of a word similarly.