aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/regexp.xml
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2011-05-06 15:58:09 +0200
committerHans Bolinder <[email protected]>2011-05-12 08:03:42 +0200
commit229d0d8ca88bc344bed89e46541b325c1d267996 (patch)
tree74fec344df8596c868c36cec5ac08102008cacf3 /lib/stdlib/doc/src/regexp.xml
parent68fe6a14539b82250373ef114d6576e74e1b8f2e (diff)
downloadotp-229d0d8ca88bc344bed89e46541b325c1d267996.tar.gz
otp-229d0d8ca88bc344bed89e46541b325c1d267996.tar.bz2
otp-229d0d8ca88bc344bed89e46541b325c1d267996.zip
r
Use Erlang specs and types for documentation
Diffstat (limited to 'lib/stdlib/doc/src/regexp.xml')
-rw-r--r--lib/stdlib/doc/src/regexp.xml152
1 files changed, 59 insertions, 93 deletions
diff --git a/lib/stdlib/doc/src/regexp.xml b/lib/stdlib/doc/src/regexp.xml
index 8c4191c88f..35d8e1c3f8 100644
--- a/lib/stdlib/doc/src/regexp.xml
+++ b/lib/stdlib/doc/src/regexp.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2009</year>
+ <year>1996</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -40,176 +40,150 @@
<p>This module contains functions for regular expression
matching and substitution.</p>
</description>
+ <datatypes>
+ <datatype>
+ <name name="errordesc"></name>
+ </datatype>
+ <datatype>
+ <name name="regexp"></name>
+ <desc><p>Internal representation of a regular expression.</p></desc>
+ </datatype>
+ </datatypes>
<funcs>
<func>
- <name>match(String, RegExp) -> MatchRes</name>
+ <name name="match" arity="2"/>
<fsummary>Match a regular expression</fsummary>
- <type>
- <v>String = RegExp = string()</v>
- <v>MatchRes = {match,Start,Length} | nomatch | {error,errordesc()}</v>
- <v>Start = Length = integer()</v>
- </type>
<desc>
- <p>Finds the first, longest match of the regular expression <c>RegExp</c> in <c>String</c>. This function searches for the longest possible match and returns the first one found if there are several expressions of the same length. It returns as follows:</p>
+ <p>Finds the first, longest match of the regular expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>. This function searches for the longest possible match and returns the first one found if there are several expressions of the same length. It returns as follows:</p>
<taglist>
- <tag><c>{match,Start,Length}</c></tag>
+ <tag><c>{match,<anno>Start</anno>,<anno>Length</anno>}</c></tag>
<item>
- <p>if the match succeeded. <c>Start</c> is the starting
- position of the match, and <c>Length</c> is the length of
+ <p>if the match succeeded. <c><anno>Start</anno></c> is the starting
+ position of the match, and <c><anno>Length</anno></c> is the length of
the matching string.</p>
</item>
<tag><c>nomatch</c></tag>
<item>
<p>if there were no matching characters.</p>
</item>
- <tag><c>{error,Error}</c></tag>
+ <tag><c>{error,<anno>Error</anno>}</c></tag>
<item>
- <p>if there was an error in <c>RegExp</c>.</p>
+ <p>if there was an error in <c><anno>RegExp</anno></c>.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>first_match(String, RegExp) -> MatchRes</name>
+ <name name="first_match" arity="2"/>
<fsummary>Match a regular expression</fsummary>
- <type>
- <v>String = RegExp = string()</v>
- <v>MatchRes = {match,Start,Length} | nomatch | {error,errordesc()}</v>
- <v>Start = Length = integer()</v>
- </type>
<desc>
- <p>Finds the first match of the regular expression <c>RegExp</c> in <c>String</c>. This call is
+ <p>Finds the first match of the regular expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>. This call is
usually faster than <c>match</c> and it is also a useful way to ascertain that a match exists. It returns as follows:</p>
<taglist>
- <tag><c>{match,Start,Length}</c></tag>
+ <tag><c>{match,<anno>Start</anno>,<anno>Length</anno>}</c></tag>
<item>
- <p>if the match succeeded. <c>Start</c> is the starting
- position of the match and <c>Length</c> is the length of
+ <p>if the match succeeded. <c><anno>Start</anno></c> is the starting
+ position of the match and <c><anno>Length</anno></c> is the length of
the matching string.</p>
</item>
<tag><c>nomatch</c></tag>
<item>
<p>if there were no matching characters.</p>
</item>
- <tag><c>{error,Error}</c></tag>
+ <tag><c>{error,<anno>Error</anno>}</c></tag>
<item>
- <p>if there was an error in <c>RegExp</c>.</p>
+ <p>if there was an error in <c><anno>RegExp</anno></c>.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>matches(String, RegExp) -> MatchRes</name>
+ <name name="matches" arity="2"/>
<fsummary>Match a regular expression</fsummary>
- <type>
- <v>String = RegExp = string()</v>
- <v>MatchRes = {match, Matches} | {error, errordesc()}</v>
- <v>Matches = list()</v>
- </type>
<desc>
<p>Finds all non-overlapping matches of the
- expression <c>RegExp</c> in <c>String</c>.
+ expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>.
It returns as follows:</p>
<taglist>
- <tag><c>{match, Matches}</c></tag>
+ <tag><c>{match, <anno>Matches</anno>}</c></tag>
<item>
<p>if the regular expression was correct.
- The list will be empty if there was no match. Each element in the list looks like <c>{Start, Length}</c>, where <c>Start</c> is the starting position of the match, and <c>Length</c> is the length of the matching string.</p>
+ The list will be empty if there was no match. Each element in the list looks like <c>{<anno>Start</anno>, <anno>Length</anno>}</c>, where <c><anno>Start</anno></c> is the starting position of the match, and <c><anno>Length</anno></c> is the length of the matching string.</p>
</item>
- <tag><c>{error,Error}</c></tag>
+ <tag><c>{error,<anno>Error</anno>}</c></tag>
<item>
- <p>if there was an error in <c>RegExp</c>.</p>
+ <p>if there was an error in <c><anno>RegExp</anno></c>.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>sub(String, RegExp, New) -> SubRes</name>
+ <name name="sub" arity="3"/>
<fsummary>Substitute the first occurrence of a regular expression</fsummary>
- <type>
- <v>String = RegExp = New = string()</v>
- <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v>
- <v>RepCount = integer()</v>
- </type>
<desc>
- <p>Substitutes the first occurrence of a substring matching <c>RegExp</c> in <c>String</c> with the string <c>New</c>. A <c><![CDATA[&]]></c> in the string <c>New</c> is replaced by the matched substring of <c>String</c>. <c><![CDATA[\&]]></c> puts a literal <c><![CDATA[&]]></c> into the replacement string. It returns as follows:</p>
+ <p>Substitutes the first occurrence of a substring matching <c><anno>RegExp</anno></c> in <c><anno>String</anno></c> with the string <c><anno>New</anno></c>. A <c><![CDATA[&]]></c> in the string <c><anno>New</anno></c> is replaced by the matched substring of <c><anno>String</anno></c>. <c><![CDATA[\&]]></c> puts a literal <c><![CDATA[&]]></c> into the replacement string. It returns as follows:</p>
<taglist>
- <tag><c>{ok,NewString,RepCount}</c></tag>
+ <tag><c>{ok,<anno>NewString</anno>,<anno>RepCount</anno>}</c></tag>
<item>
- <p>if <c>RegExp</c> is correct. <c>RepCount</c> is the number of replacements which have been made
+ <p>if <c><anno>RegExp</anno></c> is correct. <c><anno>RepCount</anno></c> is the number of replacements which have been made
(this will be either 0 or 1).</p>
</item>
- <tag><c>{error, Error}</c></tag>
+ <tag><c>{error, <anno>Error</anno>}</c></tag>
<item>
- <p>if there is an error in <c>RegExp</c>.</p>
+ <p>if there is an error in <c><anno>RegExp</anno></c>.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>gsub(String, RegExp, New) -> SubRes</name>
+ <name name="gsub" arity="3"/>
<fsummary>Substitute all occurrences of a regular expression</fsummary>
- <type>
- <v>String = RegExp = New = string()</v>
- <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v>
- <v>RepCount = integer()</v>
- </type>
<desc>
<p>The same as <c>sub</c>, except that all non-overlapping
occurrences of a substring matching
- <c>RegExp</c> in <c>String</c> are replaced by the string <c>New</c>. It returns:</p>
+ <c><anno>RegExp</anno></c> in <c><anno>String</anno></c> are replaced by the string <c><anno>New</anno></c>. It returns:</p>
<taglist>
- <tag><c>{ok,NewString,RepCount}</c></tag>
+ <tag><c>{ok,<anno>NewString</anno>,<anno>RepCount</anno>}</c></tag>
<item>
- <p>if <c>RegExp</c> is correct. <c>RepCount</c> is the number of replacements which have been made.</p>
+ <p>if <c><anno>RegExp</anno></c> is correct. <c><anno>RepCount</anno></c> is the number of replacements which have been made.</p>
</item>
- <tag><c>{error, Error}</c></tag>
+ <tag><c>{error, <anno>Error</anno>}</c></tag>
<item>
- <p>if there is an error in <c>RegExp</c>.</p>
+ <p>if there is an error in <c><anno>RegExp</anno></c>.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>split(String, RegExp) -> SplitRes</name>
+ <name name="split" arity="2"/>
<fsummary>Split a string into fields</fsummary>
- <type>
- <v>String = RegExp = string()</v>
- <v>SubRes = {ok,FieldList} | {error,errordesc()}</v>
- <v>Fieldlist = [string()]</v>
- </type>
<desc>
- <p><c>String</c> is split into fields (sub-strings) by the
- regular expression <c>RegExp</c>.</p>
+ <p><c><anno>String</anno></c> is split into fields (sub-strings) by the
+ regular expression <c><anno>RegExp</anno></c>.</p>
<p>If the separator expression is <c>" "</c> (a single space),
then the fields are separated by blanks and/or tabs and
leading and trailing blanks and tabs are discarded. For all
other values of the separator, leading and trailing blanks
and tabs are not discarded. It returns:</p>
<taglist>
- <tag><c>{ok, FieldList}</c></tag>
+ <tag><c>{ok, <anno>FieldList</anno>}</c></tag>
<item>
<p>to indicate that the string has been split up into the fields of
- <c>FieldList</c>.</p>
+ <c><anno>FieldList</anno></c>.</p>
</item>
- <tag><c>{error, Error}</c></tag>
+ <tag><c>{error, <anno>Error</anno>}</c></tag>
<item>
- <p>if there is an error in <c>RegExp</c>.</p>
+ <p>if there is an error in <c><anno>RegExp</anno></c>.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>sh_to_awk(ShRegExp) -> AwkRegExp</name>
+ <name name="sh_to_awk" arity="1"/>
<fsummary>Convert an <c>sh</c>regular expression into an <c>AWK</c>one</fsummary>
- <type>
- <v>ShRegExp AwkRegExp = string()</v>
- <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v>
- <v>RepCount = integer()</v>
- </type>
<desc>
<p>Converts the <c>sh</c> type regular expression
- <c>ShRegExp</c> into a full <c>AWK</c> regular
+ <c><anno>ShRegExp</anno></c> into a full <c>AWK</c> regular
expression. Returns the converted regular expression
string. <c>sh</c> expressions are used in the shell for
matching file names and have the following special
@@ -236,40 +210,32 @@
</desc>
</func>
<func>
- <name>parse(RegExp) -> ParseRes</name>
+ <name name="parse" arity="1"/>
<fsummary>Parse a regular expression</fsummary>
- <type>
- <v>RegExp = string()</v>
- <v>ParseRes = {ok,RE} | {error,errordesc()}</v>
- </type>
<desc>
- <p>Parses the regular expression <c>RegExp</c> and builds the
+ <p>Parses the regular expression <c><anno>RegExp</anno></c> and builds the
internal representation used in the other regular expression
functions. Such representations can be used in all of the
other functions instead of a regular expression string. This
is more efficient when the same regular expression is used
in many strings. It returns:</p>
<taglist>
- <tag><c>{ok, RE}</c>if <c>RegExp</c>is correct and <c>RE</c>is the internal representation.</tag>
+ <tag><c>{ok, <anno>RE</anno>}</c></tag>
<item>
- <p></p>
+ <p>if <c>RegExp</c> is correct and <c><anno>RE</anno></c> is the internal representation.</p>
</item>
- <tag><c>{error, Error}</c>if there is an error in <c>RegExpString</c>.</tag>
+ <tag><c>{error, <anno>Error</anno>}</c></tag>
<item>
- <p></p>
+ <p>if there is an error in <c><anno>RegExp</anno></c>.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>format_error(ErrorDescriptor) -> Chars</name>
+ <name name="format_error" arity="1"/>
<fsummary>Format an error descriptor</fsummary>
- <type>
- <v>ErrorDescriptor = errordesc()</v>
- <v>Chars = [char() | Chars]</v>
- </type>
<desc>
- <p>Returns a string which describes the error <c>ErrorDescriptor</c>
+ <p>Returns a string which describes the error <c><anno>ErrorDescriptor</anno></c>
returned when there is an error in a regular expression.</p>
</desc>
</func>