Module Name: othersrc
Committed By: uwe
Date: Tue Oct 5 18:56:24 UTC 2021
Modified Files:
othersrc/external/bsd/agcre/dist: libagcre.3
Log Message:
Tweak markup.
To generate a diff of this commit:
cvs rdiff -u -r1.3 -r1.4 othersrc/external/bsd/agcre/dist/libagcre.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: othersrc/external/bsd/agcre/dist/libagcre.3
diff -u othersrc/external/bsd/agcre/dist/libagcre.3:1.3 othersrc/external/bsd/agcre/dist/libagcre.3:1.4
--- othersrc/external/bsd/agcre/dist/libagcre.3:1.3 Tue Oct 5 01:23:39 2021
+++ othersrc/external/bsd/agcre/dist/libagcre.3 Tue Oct 5 18:56:24 2021
@@ -1,4 +1,4 @@
-.\" $NetBSD: libagcre.3,v 1.3 2021/10/05 01:23:39 agc Exp $
+.\" $NetBSD: libagcre.3,v 1.4 2021/10/05 18:56:24 uwe Exp $
.\"
.\" Copyright (c) 2017,2020,2021 Alistair Crooks <a...@netbsd.org>
.\" All rights reserved.
@@ -24,46 +24,75 @@
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 1, 2021
-.Dt AGCRE-EMBED 3
+.Dt LIBAGCRE 3
.Os
.Sh NAME
.Nm agcre
.Nd regular expression library
.Sh LIBRARY
-.Lb agcre
+.\"Lb agcre
+agcre Regular Expression Library (libagcre, \-lagcre)
.Sh SYNOPSIS
.In agcre.h
+.\"
.Ft "agcre_regex_t *"
.Fo agcre_new
.Fa "void"
.Fc
-.Ft "int"
+.\"
+.Ft int
.Fo agcre_regcomp
-.Fa "agcre_regex_t *expression" "const void *pat" "uint32_t flags"
+.Fa "agcre_regex_t *expression"
+.Fa "const void *pat"
+.Fa "uint32_t flags"
.Fc
+.\"
.Ft int
.Fo agcre_regexec
-.Fa "agcre_regex_t *expression" "const void *input" "size_t nmatch" "agcre_regmatch_t *matches" "uint32_t flags"
+.Fa "agcre_regex_t *expression"
+.Fa "const void *input"
+.Fa "size_t nmatch"
+.Fa "agcre_regmatch_t *matches"
+.Fa "uint32_t flags"
.Fc
+.\"
.Ft int
.Fo agcre_rev_regexec
-.Fa "agcre_regex_t *expression" "const void *input" "size_t nmatch" "agcre_regmatch_t *matches" "uint32_t flags"
+.Fa "agcre_regex_t *expression"
+.Fa "const void *input"
+.Fa "size_t nmatch"
+.Fa "agcre_regmatch_t *matches"
+.Fa "uint32_t flags"
.Fc
+.\"
.Ft void
.Fo agcre_regfree
.Fa "agcre_regex_t *expression"
.Fc
+.\"
.Ft size_t
.Fo agcre_regerror
-.Fa "int errnum" "const agcre_regex_t *expression" "char *buf" "size_t size"
+.Fa "int errnum"
+.Fa "const agcre_regex_t *expression"
+.Fa "char *buf"
+.Fa "size_t size"
.Fc
+.\"
.Ft ssize_t
.Fo agcre_regnsub
-.Fa "char *buf" "size_t size" "const char *repl" "const agcre_regmatch_t *matches" "const char *str"
+.Fa "char *buf"
+.Fa "size_t size"
+.Fa "const char *repl"
+.Fa "const agcre_regmatch_t *matches"
+.Fa "const char *str"
.Fc
+.\"
.Ft ssize_t
.Fo agcre_regasub
-.Fa "char **buf" "const char *repl" "const agcre_regmatch_t *matches" "const char *str"
+.Fa "char **buf"
+.Fa "const char *repl"
+.Fa "const agcre_regmatch_t *matches"
+.Fa "const char *str"
.Fc
.Sh DESCRIPTION
The
@@ -74,7 +103,7 @@ It will compile expressions described in
.Xr agcre_format 7 ,
as well as some extensions.
.Pp
-A
+An
.Vt agcre_regex_t
structure can either be allocated on the stack, or
it can be allocated dynamically using
@@ -89,10 +118,10 @@ A regular expression is compiled using
Various flags can be specified during compilation, which will
alter the regular expression which is produced.
These flags are:
-.Bl -tag -width AGCRE_REG_EXTENDEDXXX
+.Bl -tag -width Dv
.It Dv AGCRE_REG_BASIC
Use basic regular expressions.
-These are prserved for legacy reasons; no new code should use basic
+These are preserved for legacy reasons; no new code should use basic
regular expressions.
For more information on regular expression formats, please refer to
.Xr agcre_format 7 .
@@ -100,25 +129,27 @@ For more information on regular expressi
Extended regular expressions are the standard form of searching,
and should be used.
.It Dv AGCRE_REG_NOSUB
-When searching through text, the standard searches are perfomed,
+When searching through text, the standard searches are performed,
but no subexpression information will be returned.
.It Dv AGCRE_REG_NEWLINE
Normally newline characters are treated as a standard character.
With this flag, the zero width match for
-.Dq ^
+.Ql \&^
before the newline character will match, as will the zero width string
after the
-.Dq $ .
+.Ql \&$ .
.It Dv AGCRE_REG_NOSPEC
A standard search text will be performed, and no special characters
will be recognised.
In the current implementation, this will be performed using
-a Horspool-modified Boyer-Moore search.
+a Horspool-modified Boyer\(enMoore search.
.It Dv AGCRE_REG_PEND
Normally, the end of the string to be compiled will be the
-first ASCII NUL character encountered.
+first
+.Tn ASCII NUL
+character encountered.
With this flag, the
-.Dv re_endp
+.Va re_endp
field in the
.Vt agcre_regex_t
structure will be used to point to the last position in
@@ -156,8 +187,8 @@ Traces execution of the regular expressi
A regular expression, once compiled,
can be executed on different input using
.Fn agcre_regexec .
-Various flags govern the matching behavior - these are:
-.Bl -tag -width AGCRE_REG_EXTENDEDXXX
+Various flags govern the matching behavior \(em these are:
+.Bl -tag -width Dv
.It Dv AGCRE_REG_ICASE
When searching through text, a case-insensitive search will be
performed.
@@ -168,7 +199,7 @@ only at expression execution time.
Normally, the sub-string passed to
.Fn agcre_regexec
is assumed to be the start of the whole string, and
-.Dq ^
+.Ql ^
matching will be performed in the standard way.
With this flag, beginning of line matching will
be suppressed.
@@ -176,7 +207,7 @@ be suppressed.
Normally, the sub-string passed to
.Fn agcre_regexec
is assumed to be the end of the whole string, and
-.Dq $
+.Ql $
matching will be performed in the standard way.
With this flag, end of line matching will
be suppressed.
@@ -184,13 +215,14 @@ be suppressed.
The string passed to
.Fn agcre_regexec
is normally assumed to start at the first character, and to
-complete at the first ASCII NUL
+complete at the first
+.Tn ASCII NUL
character.
With this flag, the start and end offsets to use
for string matching are taken from the
-.Dv rm_so
+.Va rm_so
and
-.Dv rm_eo
+.Va rm_eo
fields provided in the zero-th element of the
.Fa matchv
argument.
@@ -211,12 +243,12 @@ and/or at expression execution time.
.It Dv AGCRE_REG_ANCHOR
This is used where a regular expression pattern was generated by the
.Xr ctags 1
-program, since the syntax generated does not conform to a standard
+program, since the syntax generated does not conform to a standard
basic regular expression.
In particular,
.Xr ctags 1
outputs function location patterns which contain an unescaped
-.Dq *
+.Ql *
character, whereas basic regular expressions will only
recognise an asterisk as a standard character if it appears
at the start of an expression.
@@ -274,22 +306,30 @@ using
.Pp
The implementation is based around Rob Pike's
constant-time virtual machine implementation, released in 2008 by Russ Cox
-with a BSD license.
+with a
+.Tn BSD
+license.
That implementation has been augmented to support Unicode characters,
Perl escape sequences,
back references,
specifically-bounded repeat sequences
-and character sets, ranges and POSIX character classes.
+and character sets, ranges and
+.Tn POSIX
+character classes.
.Pp
Because a virtual machine is used,
there are no real limits top the size of regular expression
which can be compiled.
However, to avoid abuse, certain arbitrary limits are set:
-.Bl -tag -width characterXXX
-.It tokens
-the maximum number of tokens is set at compile-time to 65536
-.It sets
-the maximum number of sets is set at compile-time to 1024
+.Bl -bullet -offset indent -compact
+.It
+the maximum number of
+.Em tokens
+is set at compile-time to 65536
+.It
+the maximum number of
+.Em sets
+is set at compile-time to 1024
.El
.Pp
To show the value of constant-time execution, especially
