From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/re.xml | 131 +++++++++++++++++----------------------------- 1 file changed, 48 insertions(+), 83 deletions(-) (limited to 'lib/stdlib/doc/src/re.xml') diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 9091035392..b8db55fc26 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -59,28 +59,24 @@ -
- DATA TYPES - - iodata() = iolist() | binary() - iolist() = [char() | binary() | iolist()] - - 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 a valid unicode codepoint - - chardata() = charlist() | unicode_binary() - - charlist() = [unicode_char() | unicode_binary() | charlist()] - - a unicode_binary is allowed as the tail of the list - - - mp() = Opaque datatype containing a compiled regular expression. - - The mp() is guaranteed to be a tuple() having the atom + + + + +

Opaque datatype containing a compiled regular expression. + The mp() is guaranteed to be a tuple() having the atom 're_pattern' as its first element, to allow for matching in guards. The arity of the tuple() or the content of the other fields - may change in future releases. -

+ may change in future releases.

+ + + + + + + + + compile(Regexp) -> {ok, MP} | {error, ErrSpec} @@ -96,14 +92,14 @@ compile(Regexp,Options) -> {ok, MP} | {error, ErrSpec} Compile a regular expression into a match program - Regexp = iodata() | charlist() + Regexp = iodata() | io:charlist() Options = [ Option ] Option = unicode | anchored | caseless | dollar_endonly | dotall | extended | firstline | multiline | no_auto_capture | dupnames | ungreedy | {newline, NLSpec}| bsr_anycrlf | bsr_unicode - NLSpec = cr | crlf | lf | anycrlf | any - MP = mp() + NLSpec = nl_spec() + MP = mp() ErrSpec = {ErrString, Position} ErrString = string() - Position = int() + Position = non_neg_integer()

This function compiles a regular expression with the syntax @@ -116,7 +112,7 @@ time one wants to match.

When the unicode option is given, the regular expression should be given as a valid unicode charlist(), otherwise as any valid iodata().

-

The options have the following meanings:

+

The options have the following meanings:

unicode The regular expression is given as a unicode charlist() and the resulting regular expression code is to be run against a valid unicode charlist() subject. @@ -173,10 +169,10 @@ This option makes it possible to include comments inside complicated patterns. N run(Subject,RE) -> {match, Captured} | nomatch Match a subject against regular expression and capture subpatterns - Subject = iodata() | charlist() - RE = mp() | iodata() | charlist() + Subject = iodata() | io:charlist() + RE = mp() | iodata() | io:charlist() Captured = [ CaptureData ] - CaptureData = {int(),int()} + CaptureData = {integer(),integer()}

The same as run(Subject,RE,[]).

@@ -186,18 +182,19 @@ This option makes it possible to include comments inside complicated patterns. N run(Subject,RE,Options) -> {match, Captured} | match | nomatch Match a subject against regular expression and capture subpatterns - Subject = iodata() | charlist() - RE = mp() | iodata() | charlist() + Subject = iodata() | io:charlist() + RE = mp() | iodata() | io:charlist() Options = [ Option ] - Option = anchored | global | notbol | noteol | notempty | {offset, int()} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {capture, ValueSpec} | {capture, ValueSpec, Type} | CompileOpt + Option = anchored | global | notbol | noteol | notempty | {offset, integer() >= 0} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {capture, ValueSpec} | {capture, ValueSpec, Type} | CompileOpt Type = index | list | binary ValueSpec = all | all_but_first | first | none | ValueList ValueList = [ ValueID ] - ValueID = int() | string() | atom() - CompileOpt = see compile/2 above - NLSpec = cr | crlf | lf | anycrlf | any + ValueID = integer() | string() | atom() + CompileOpt = compile_option() + See compile/2 above. + NLSpec = nl_spec() Captured = [ CaptureData ] | [ [ CaptureData ] ... ] - CaptureData = {int(),int()} | ListConversionData | binary() + CaptureData = {integer(),integer()} | ListConversionData | binary() ListConversionData = string() | {error, string(), binary()} | {incomplete, string(), binary()} @@ -217,7 +214,7 @@ This option makes it possible to include comments inside complicated patterns. N

If the regular expression is previously compiled, the option list can only contain the options anchored, global, notbol, noteol, - notempty, {offset, int()}, {newline, + notempty, {offset, integer() >= 0}, {newline, NLSpec} and {capture, ValueSpec}/{capture, ValueSpec, Type}. Otherwise all options valid for the re:compile/2 function are allowed as well. Options @@ -360,7 +357,7 @@ This option makes it possible to include comments inside complicated patterns. N behavior of the dollar metacharacter. It does not affect \Z or \z. - {offset, int()} + {offset, integer() >= 0} Start matching at the offset (position) given in the subject string. The offset is zero-based, so that the default is @@ -503,42 +500,27 @@ This option makes it possible to include comments inside complicated patterns. N - replace(Subject,RE,Replacement) -> iodata() | charlist() + Match a subject against regular expression and replace matching elements with Replacement - - Subject = iodata() | charlist() - RE = mp() | iodata() - Replacement = iodata() | charlist() - -

The same as replace(Subject,RE,Replacement,[]).

+

The same as replace(Subject,RE,Replacement,[]).

 - replace(Subject,RE,Replacement,Options) -> iodata() | charlist() | binary() | list() + Match a subject against regular expression and replace matching elements with Replacement - - Subject = iodata() | charlist() - RE = mp() | iodata() | charlist() - Replacement = iodata() | charlist() - Options = [ Option ] - Option = anchored | global | notbol | noteol | notempty | {offset, int()} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {return, ReturnType} | CompileOpt - ReturnType = iodata | list | binary - CompileOpt = see compile/2 above - NLSpec = cr | crlf | lf | anycrlf | any - -

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

+

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 + 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}.

As in the re:run/3 function, an mp() compiled - with the unicode option requires the Subject to be + with the unicode option requires the Subject to be 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 + function, both the regular expression and the Subject should be given as valid Unicode charlist()s.

The replacement string can contain the special character @@ -565,34 +547,17 @@ This option makes it possible to include comments inside complicated patterns. N - split(Subject,RE) -> SplitList + Split a string by tokens specified as a regular expression - - Subject = iodata() | charlist() - RE = mp() | iodata() - SplitList = [ iodata() | charlist() ] - -

The same as split(Subject,RE,[]).

+

The same as split(Subject,RE,[]).

 - split(Subject,RE,Options) -> SplitList + Split a string by tokens specified as a regular expression - - Subject = iodata() | charlist() - RE = mp() | iodata() | charlist() - Options = [ Option ] - Option = anchored | global | notbol | noteol | notempty | {offset, int()} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {return, ReturnType} | {parts, NumParts} | group | trim | CompileOpt - NumParts = int() | infinity - ReturnType = iodata | list | binary - CompileOpt = see compile/2 above - NLSpec = cr | crlf | lf | anycrlf | any - SplitList = [ RetData ] | [ GroupedRetData ] - GroupedRetData = [ RetData ] - RetData = iodata() | charlist() | binary() | list() - + See compile/2 above.

This function splits the input into parts by finding tokens according to the regular expression supplied.

@@ -602,10 +567,10 @@ This option makes it possible to include comments inside complicated patterns. N of the string is removed from the output.

As in the re:run/3 function, an mp() compiled - with the unicode option requires the Subject to be + with the unicode option requires the Subject to be 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 + function, both the regular expression and the Subject should be given as valid Unicode charlist()s.

The result is given as a list of "strings", the @@ -722,7 +687,7 @@ This option makes it possible to include comments inside complicated patterns. N

Summary of options not previously described for the re:run/3 function:

- {return,ReturnType} + {return,ReturnType}

Specifies how the parts of the original string are presented in the result list. The possible types are:

iodata -- cgit v1.2.3