From 278ab91df569d338973bae957974425dcdb698fe Mon Sep 17 00:00:00 2001 From: Matthias Lang Date: Fri, 29 Oct 2010 07:47:20 +0200 Subject: Improve the 're' manpage by correcting typos and rewording Correct typos (e.g. it's -> its as appropriate). Reword some sections for clarity. --- lib/stdlib/doc/src/re.xml | 141 ++++++++++++++++++++++------------------------ 1 file changed, 67 insertions(+), 74 deletions(-) diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 80adc3e347..056e7bc9b9 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -37,29 +37,24 @@ Perl like regular expressions for Erlang -

This module contains functions for regular expression - matching for strings and binaries.

+

This module contains regular expression matching functions for + strings and binaries.

The regular expression syntax and semantics resemble that of - Perl. This library in many ways replaces the old regexp library - written purely in Erlang, as it has a richer syntax as well as - many more options. The library is also faster than the - older regexp implementation.

- -

Although the library's matching algorithms are currently based - on the PCRE library, it is not to be viewed as an Erlang to PCRE - mapping. Only parts of the PCRE library is interfaced and the re - library in some ways extend PCRE. The PCRE documentation contains - many parts of no interest to the Erlang programmer, why only the - relevant part of the documentation is included here. There should - bee no need to go directly to the PCRE library documentation.

+ Perl. This library replaces the deprecated pure-Erlang regexp + library; it has a richer syntax, more options and is faster.

+ +

The library's matching algorithms are currently based on the + PCRE library, but not all of the PCRE library is interfaced and + some parts of the library go beyond what PCRE offers. The sections of + the PCRE documentation which are relevant to this module are included + here.

-

The Erlang literal syntax for strings give special - meaning to the "\" (backslash) character. To literally write - a regular expression or a replacement string containing a - backslash in your code or in the shell, two backslashes have to be written: - "\\".

+

The Erlang literal syntax for strings uses the "\" + (backslash) character as an escape code. You need to escape + backslashes in literal strings, both in your code and in the shell, + with an additional backslash, i.e.: "\\".

 @@ -72,7 +67,7 @@ - a binary is allowed as the tail of the list unicode_binary() = binary() with characters encoded in UTF-8 coding standard - unicode_char() = integer() representing valid unicode codepoint + unicode_char() = integer() representing a valid unicode codepoint chardata() = charlist() | unicode_binary() @@ -82,9 +77,9 @@ mp() = Opaque datatype containing a compiled regular expression. - The mp() is guaranteed to be a tuple() having the atom - 're_pattern' as it's first element, to allow for matching in + 're_pattern' as its first element, to allow for matching in guards. The arity of the tuple() or the content of the other fields - is however not to be trusted. + may change in future releases. @@ -132,7 +127,7 @@ dollar_endonly A dollar metacharacter in the pattern matches only at the end of the subject string. Without this option, a dollar also matches immediately before a newline at the end of the string (but not before any other newlines). The dollar_endonly option is ignored if multiline is given. There is no equivalent option in Perl, and no way to set it within a pattern. dotall - A dot maturate in the pattern matches all characters, including those that indicate newline. Without it, a dot does not match when the current position is at a newline. This option is equivalent to Perl's /s option, and it can be changed within a pattern by a (?s) option setting. A negative class such as [^a] always matches newline characters, independent of the setting of this option. + A dot in the pattern matches all characters, including those that indicate newline. Without it, a dot does not match when the current position is at a newline. This option is equivalent to Perl's /s option, and it can be changed within a pattern by a (?s) option setting. A negative class such as [^a] always matches newline characters, independent of this option's setting. extended Whitespace data characters in the pattern are ignored except when escaped or inside a character class. Whitespace does not include the VT character (ASCII 11). In addition, characters between an unescaped # outside a character class and the next newline, inclusive, are also ignored. This is equivalent to Perl's /x option, and it can be changed within a pattern by a (?x) option setting. @@ -214,9 +209,10 @@ This option makes it possible to include comments inside complicated patterns. N or as a pre compiled mp() in which case it is executed against the subject directly.

-

When compilation is involved, the exception badarg is thrown if - a compilation error occurs. To locate the error in the regular - expression, use the function re:compile/2 to get more information.

+

When compilation is involved, the exception badarg is + thrown if a compilation error occurs. Call re:compile/2 + to get information about the location of the error in the + regular expression.

If the regular expression is previously compiled, the option list can only contain the options anchored, @@ -246,7 +242,7 @@ This option makes it possible to include comments inside complicated patterns. N how captured substrings are to be returned (as index tuples, lists or binaries). The capture option makes the function quite flexible and powerful. The different options are described - in detail below

+ in detail below.

If the capture options describe that no substring capturing at all is to be done ({capture, none}), the function will @@ -256,7 +252,7 @@ This option makes it possible to include comments inside complicated patterns. N be done either by specifying none or an empty list as ValueSpec.

-

A description of all the options relevant for execution follows:

+

The options relevant for execution are:

anchored @@ -270,27 +266,25 @@ This option makes it possible to include comments inside complicated patterns. N global -

Implements global (repetitive) search as the g flag in - i.e. Perl. Each match found is returned as a separate +

Implements global (repetitive) search (the g flag in + Perl). Each match is returned as a separate list() containing the specific match as well as any matching subexpressions (or as specified by the capture option). The Captured part of the return value will - hence be a list() of list()'s when this + hence be a list() of list()s when this option is given.

-

When the regular expression matches an empty string, the - behaviour might seem non-intuitive, why the behaviour requites - some clarifying. With the global option, re:run/3 - handles empty matches in the same way as Perl, meaning that a - match at any point giving an empty string (with length 0) will - be retried with the options - [anchored, notempty] as well. If that - search gives a result of length > 0, the result is included. - An example:

+

The interaction of the global option with a regular + expression which matches an empty string surprises some users. + When the global option is given, re:run/3 handles empty + matches in the same way as Perl: a zero-length match at any + point will be retried with the options [anchored, + notempty] as well. If that search gives a result of length + > 0, the result is included. For example:

re:run("cat","(|at)",[global]). -

The matching will be performed as following:

+

The following matching will be performed:

At offset 0 The regexp (|at) will first match at the initial @@ -302,11 +296,11 @@ This option makes it possible to include comments inside complicated patterns. N The search is retried with the options [anchored, notempty] at the same position, which does not give any interesting result of longer - length, why the search position is now advanced to the next + length, so the search position is now advanced to the next character (a). At offset 1 - Now the search results in - [{1,0},{1,0}] meaning this search will also be repeated + This time, the search results in + [{1,0},{1,0}], so this search will also be repeated with the extra options. At offset 1 with [anchored, notempty] Now the ab alternative @@ -333,16 +327,17 @@ This option makes it possible to include comments inside complicated patterns. N entire match fails. For example, if the pattern

a?b?

is applied to a string not beginning with "a" or "b", it - matches the empty string at the start of the subject. With - notempty given, this match is not valid, so re:run/3 searches - further into the string for occurrences of "a" or "b".

+ would normally match the empty string at the start of the + subject. With the notempty option, this match is not + valid, so re:run/3 searches further into the string for + occurrences of "a" or "b".

Perl has no direct equivalent of notempty, but it does make a special case of a pattern match of the empty string within its split() function, and when using the /g modifier. It is possible to emulate Perl's behavior after matching a null string by first trying the match again at the same offset with - notempty and anchored, and then if that fails by + notempty and anchored, and then, if that fails, by advancing the starting offset (see below) and trying an ordinary match again.

 @@ -352,7 +347,7 @@ This option makes it possible to include comments inside complicated patterns. N string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without multiline (at compile time) causes circumflex never to - match. This option affects only the behavior of the circumflex + match. This option only affects the behavior of the circumflex metacharacter. It does not affect \A. noteol @@ -388,7 +383,7 @@ This option makes it possible to include comments inside complicated patterns. N bsr_anycrlf - Specifies specifically that \R is to match only the cr, lf or crlf sequences, not the Unicode specific newline characters.(overrides compilation option) + Specifies specifically that \R is to match only the cr, lf or crlf sequences, not the Unicode specific newline characters. (overrides compilation option) bsr_unicode Specifies specifically that \R is to match all the Unicode newline characters (including crlf etc, the default).(overrides compilation option) @@ -444,7 +439,7 @@ This option makes it possible to include comments inside complicated patterns. N none Do not return matching subpatterns at all, yielding the single atom match as the return value of the function when matching successfully instead of the {match, list()} return. Specifying an empty list gives the same behavior. -

The value list is a list of indexes for the subpatterns to return, where index 0 is for all of the pattern, and 1 is for the first explicit capturing subpattern in the regular expression, and so forth. When using named captured subpatterns (see below) in the regular expression, one can use atom()'s or string()'s to specify the subpatterns to be returned. This deserves an example, consider the following regular expression:

+

The value list is a list of indexes for the subpatterns to return, where index 0 is for all of the pattern, and 1 is for the first explicit capturing subpattern in the regular expression, and so forth. When using named captured subpatterns (see below) in the regular expression, one can use atom()s or string()s to specify the subpatterns to be returned. For example, consider the regular expression:

".*(abcd).*"

matched against the string ""ABCabcdABC", capturing only the "abcd" part (the first explicit subpattern):

re:run("ABCabcdABC",".*(abcd).*",[{capture,[1]}]). @@ -455,7 +450,7 @@ This option makes it possible to include comments inside complicated patterns. N ".*(?<FOO>abcd).*"

With this expression, we could still give the index of the subpattern with the following call:

re:run("ABCabcdABC",".*(?<FOO>abcd).*",[{capture,[1]}]). -

giving the same result as before. But as the subpattern is named, we can also give its name in the value list:

+

giving the same result as before. But, since the subpattern is named, we can also specify its name in the value list:

re:run("ABCabcdABC",".*(?<FOO>abcd).*",[{capture,['FOO']}]).

which would yield the same result as the earlier examples, namely:

{match,[{3,4}]} @@ -473,15 +468,15 @@ This option makes it possible to include comments inside complicated patterns. N

Optionally specifies how captured substrings are to be returned. If omitted, the default of index is used. The Type can be one of the following:

index - Return captured substrings as pairs of byte indexes into the subject string and length of the matching string in the subject (as if the subject string was flattened with iolist_to_binary/1 or unicode:characters_to_binary/2 prior to matching). Note that the unicode option results in byte-oriented indexes in a (possibly imagined) UTF-8 encoded binary. A byte index tuple {0,2} might therefore represent one or two characters when unicode is in effect. This might seem contra-intuitive, but has been deemed the most effective and useful way to way to do it. To return lists instead might result in simpler code if that is desired. This return type is the default. + Return captured substrings as pairs of byte indexes into the subject string and length of the matching string in the subject (as if the subject string was flattened with iolist_to_binary/1 or unicode:characters_to_binary/2 prior to matching). Note that the unicode option results in byte-oriented indexes in a (possibly virtual) UTF-8 encoded binary. A byte index tuple {0,2} might therefore represent one or two characters when unicode is in effect. This might seem counter-intuitive, but has been deemed the most effective and useful way to way to do it. To return lists instead might result in simpler code if that is desired. This return type is the default. list - Return matching substrings as lists of characters (Erlang string()'s). It the unicode option is used in combination with the \C sequence in the regular expression, a captured subpattern can contain bytes that has is not valid UTF-8 (\C matches bytes regardless of character encoding). In that case the list capturing may result in the same types of tuples that unicode:characters_to_list/2 can return, namely three-tuples with the tag incomplete or error, the successfully converted characters and the invalid UTF-8 tail of the conversion as a binary. The best strategy is to avoid using the \C sequence when capturing lists. + Return matching substrings as lists of characters (Erlang string()s). It the unicode option is used in combination with the \C sequence in the regular expression, a captured subpattern can contain bytes that are not valid UTF-8 (\C matches bytes regardless of character encoding). In that case the list capturing may result in the same types of tuples that unicode:characters_to_list/2 can return, namely three-tuples with the tag incomplete or error, the successfully converted characters and the invalid UTF-8 tail of the conversion as a binary. The best strategy is to avoid using the \C sequence when capturing lists. binary - Return matching substrings as binaries. If the unicode option is used, these binaries is in UTF-8. If the \C sequence is used together with unicode the binaries may be invalid UTF-8. + Return matching substrings as binaries. If the unicode option is used, these binaries are in UTF-8. If the \C sequence is used together with unicode the binaries may be invalid UTF-8. -

In general, subpatterns that got assigned no value in the match are returned as the tuple {-1,0} when type is index. Unassigned subpatterns are returned as the empty binary or list respectively for other return types. Consider the regular expression:

+

In general, subpatterns that were not assigned a value in the match are returned as the tuple {-1,0} when type is index. Unassigned subpatterns are returned as the empty binary or list, respectively, for other return types. Consider the regular expression:

".*((?<FOO>abdd)|a(..d)).*"

There are three explicitly capturing subpatterns, where the opening parenthesis position determines the order in the result, hence ((?<FOO>abdd)|a(..d)) is subpattern index 1, (?<FOO>abdd) is subpattern index 2 and (..d) is subpattern index 3. When matched against the following string:

"ABCabcdABC" @@ -533,8 +528,8 @@ This option makes it possible to include comments inside complicated patterns. N NLSpec = cr | crlf | lf | anycrlf | any -

Replaces the matched part of the Subject string with the content of Replacement.

-

Options are given as to the re:run/3 function except that the capture option of re:run/3 is not allowed. +

Replaces the matched part of the Subject string with the contents of Replacement.

+

The permissible options are the same as for re:run/3, except that the capture option is not allowed. Instead a {return, ReturnType} is present. The default return type is iodata, constructed in a way to minimize copying. The iodata result can be used directly in many i/o-operations. If a flat list() is desired, specify {return, list} and if a binary is preferred, specify {return, binary}.

@@ -544,7 +539,7 @@ This option makes it possible to include comments inside complicated patterns. N a Unicode charlist(). If compilation is done implicitly and the unicode compilation option is given to this function, both the regular expression and the Subject - should be given as valid Unicode charlist()'s.

+ should be given as valid Unicode charlist()s.

The replacement string can contain the special character &, which inserts the whole matching expression in the @@ -554,7 +549,7 @@ This option makes it possible to include comments inside complicated patterns. N generated by the regular expression, nothing is inserted.

To insert an & or \ in the result, precede it with a \. Note that Erlang already gives a special - meaning to \ in literal strings, why a single \ + meaning to \ in literal strings, so a single \ has to be written as "\\" and therefore a double \ as "\\\\". Example:

re:replace("abcd","c","[&]",[{return,list}]). @@ -611,7 +606,7 @@ This option makes it possible to include comments inside complicated patterns. N a Unicode charlist(). If compilation is done implicitly and the unicode compilation option is given to this function, both the regular expression and the Subject - should be given as valid Unicode charlist()'s.

+ should be given as valid Unicode charlist()s.

The result is given as a list of "strings", the preferred datatype given in the return option (default iodata).

@@ -656,25 +651,25 @@ This option makes it possible to include comments inside complicated patterns. N

Here the regular expression matched first the "l", causing "Er" to be the first part in the result. When the regular expression matched, the (only) subexpression was - bound to the "l", why the "l" is inserted + bound to the "l", so the "l" is inserted in the group together with "Er". The next match is of the "n", making "a" the next part to be - returned. As the subexpression is bound to the substring + returned. Since the subexpression is bound to the substring "n" in this case, the "n" is inserted into this group. The last group consists of the rest of the string, as no more matches are found.

By default, all parts of the string, including the empty - strings are returned from the function. As an example:

+ strings, are returned from the function. For example:

re:split("Erlang","[lg]",[{return,list}]). -

The result will be:

+

will return:

["Er","an",[]] -

as the matching of the "g" in the end of the string +

since the matching of the "g" in the end of the string leaves an empty rest which is also returned. This behaviour differs from the default behaviour of the split function in Perl, where empty strings at the end are by default removed. To @@ -701,10 +696,10 @@ This option makes it possible to include comments inside complicated patterns. N

Note that the last part is "ang", not "an", as we only specified splitting into two parts, - and the splitting stops when enough parts are given, why the - result differs from that of trim.

+ and the splitting stops when enough parts are given, which is + why the result differs from that of trim.

-

More than three parts are not possible with this indata, why

+

More than three parts are not possible with this indata, so

re:split("Erlang","[lg]",[{return,list},{parts,4}]). @@ -745,7 +740,7 @@ This option makes it possible to include comments inside complicated patterns. N the parts of the string matching the subexpressions of the regexp.

The return value from the function will in this case be a - list() of list()'s. Each sublist begins with the + list() of list()s. Each sublist begins with the string picked out of the subject string, followed by the parts matching each of the subexpressions in order of occurrence in the regular expression.

@@ -782,10 +777,8 @@ This option makes it possible to include comments inside complicated patterns. N PERL LIKE REGULAR EXPRESSIONS SYNTAX

The following sections contain reference material for the regular expressions used by this module. The regular expression - reference is taken from the PCRE documentation, but converted as - needed.

-

The documentation is altered where appropriate and where the re - module behaves differently than the PCRE library.

+ reference is based on the PCRE documentation, with changes in + cases where the re module behaves differently to the PCRE library.

PCRE regular expression details -- cgit v1.2.3