summaryrefslogtreecommitdiff
path: root/lib/regex/doc/myr-regex.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/regex/doc/myr-regex.3')
-rw-r--r--lib/regex/doc/myr-regex.3198
1 files changed, 198 insertions, 0 deletions
diff --git a/lib/regex/doc/myr-regex.3 b/lib/regex/doc/myr-regex.3
new file mode 100644
index 0000000..c0d0da0
--- /dev/null
+++ b/lib/regex/doc/myr-regex.3
@@ -0,0 +1,198 @@
+.TH MYR REGEX 1
+.SH NAME
+regex myr-regex
+.SH LIBRARY
+regex
+.SH SYNOPSIS
+.B use regex
+.I const compile : (re : byte[:] -> std.error(regex#, status))
+.I const dbgcompile : (re : byte[:] -> std.error(regex#, status))
+.I const free : (re : regex# -> void)
+.br
+.I const exec : (re : regex#, str : byte[:] -> bool)
+.I const search : (re : regex#, str : byte[:] -> bool)
+.SH DESCRIPTION
+.PP
+The regex library provides functions for compiling and evaluating regular
+expressions, as described later in this document, or in myr-regex(7).
+.PP
+.I regex.compile will take a string describing a regex, and will attempt
+to compile it, returing
+.I `std.Success regex#
+if the regex is valid, and there were no error conditions encountered during
+compilation. If the compilation failed,
+.I `std.Failure regex.status
+will be returned, where regex.status is a failure code.
+
+.PP
+.I regex.dbgcompile
+is identical to
+.I regex.compile,
+however, it will print debugging information as it compiles, and each
+time the regex is evaluated.
+
+.PP
+.I regex.exec
+will take the regex passed to it, and evaluate it over the text provided,
+returning the
+.I `std.Some matches,
+or
+.I `std.None
+if there were no matches found. The matches must span the whole string.
+
+.PP
+.I regex.search
+is similar to regex.exec, but it will attempt to find a match somewhere
+within the string, instead of attempting to find a match spanning the whole
+string.
+
+.SH REGEX SYNTAX
+.PP
+The grammar used by libregex is below:
+
+.EX
+ regex : altexpr
+ altexpr : catexpr ('|' altexpr)+
+ catexpr : repexpr (catexpr)+
+ repexpr : baseexpr[*+?]
+ baseexpr : literal
+ | charclass
+ | charrange
+ | escaped
+ | '.'
+ | '^'
+ | '$'
+ | '(' regex ')'
+ charclass : see below
+ charrange : '[' (literal('-' literal)?)+']'
+.EE
+
+The following metacharacters have the meanings listed below:
+.TP
+.
+Matches a single unicode character
+.TP
+^
+Matches the beginning of a line. Does not consume any characters.
+.TP
+$
+Matches the end of a line. Does not consume any characters.
+.TP
+*
+Matches any number of repetitions of the preceding regex fragment.
+.TP
+*?
+Reluctantly matches any number of repetitions of the preceding regex fragment.
+.TP
++
+Matches one or more repetitions of the preceding regex fragment.
+.TP
++?
+Reluctantly matches one or more repetitions of the preceding regex fragment.
+.TP
+?
+Matches zero or one of the preceding regex fragment.
+
+.PP
+In order to match a literal metacharacter, it needs to be preceded by
+a '\\' character.
+
+The following character classes are supported:
+.TP
+\\d
+ASCII digits
+.TP
+\\D
+Negation of ASCII digits
+.TP
+\\x
+ASCII Hex digits
+.TP
+\\X
+Negation of ASCII Hex digits
+.TP
+\\s
+ASCII spaces
+.TP
+\\S
+Negation of ASCII spaces
+.TP
+\\w
+ASCII word characters
+.TP
+\\W
+Negation of ASCII word characters
+.TP
+\\h
+ASCII whitespace characters
+.TP
+\\H
+Negation of ASCII whitespace characters
+.TP
+\\pX, \\p{X}
+Characters with unicode property 'X'
+.TP
+\\PX, \\P{X}
+Negation of characters with unicode property 'X'
+
+.PP
+Unicode properties that are supported are listed below:
+
+.TP
+L, Letter
+Unicode letter property
+.TP
+Lu, Uppercase_Letter
+Uppercase letter unicode property
+.TP
+Ll, Lowercase_Letter
+Lowercase letter unicode property
+.TP
+Lt, Titlecase_Letter
+Titlecase letter unicode property
+.TP
+N, Number
+Number unicode property
+.TP
+Z, Separator
+Any separator character unicode property
+.TP
+Zs, Space_Separator
+Space separator unicode property
+
+
+.SH EXAMPLE
+.EX
+ use std
+ use regex
+
+ const main = {
+ match regex.compile(pat)
+ var i
+ | `std.Success re:
+ match regex.exec(re, text)
+ | `std.Some matches:
+ for i = 0; i < matches.len; i++
+ std.put("Match %i: %s\n", i, match[i])
+ ;;
+ | `std.None: std.put("Text did not match\n")
+ ;;
+ | `std.Failure err:
+ std.put("failed to compile regex")
+ ;;
+ }
+.EE
+
+.SH FILES
+The source code for this compiler is available from
+.B git://git.eigenstate.org/git/ori/libregex.git
+
+.SH SEE ALSO
+.IR mc(1)
+
+.SH BUGS
+.PP
+This code is insufficiently tested.
+
+.PP
+This code does not support all of the regex features that one would expect.