New quoted string handling and simple pattern matching.

[mLib] / man / str.3

diff --git a/man/str.3 b/man/str.3
index 1484fb5..e91fc13 100644 (file)
--- a/man/str.3
+++ b/man/str.3
@@ -14,15 +14,22 @@
 .TH str 3 "20 June 1999" mLib
 .SH NAME
 str \- small string utilities
 .TH str 3 "20 June 1999" mLib
 .SH NAME
 str \- small string utilities

+.\" @str_qword
+.\" @str_qsplit

 .\" @str_getword
 .\" @str_split
 .\" @str_getword
 .\" @str_split

+.\" @str_match

 .\" @str_sanitize
 .SH SYNOPSIS
 .nf
 .B "#include <mLib/str.h>"
 
 .\" @str_sanitize
 .SH SYNOPSIS
 .nf
 .B "#include <mLib/str.h>"
 

+.BI "char *str_qword(char **" pp ", unsigned " f );
+.BI "size_t str_qsplit(char *" p ", char *" v "[], size_t " c ,
+.BI "                  char **" rest ", unsigned " f );

 .BI "char *str_getword(char **" pp );
 .BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest );
 .BI "char *str_getword(char **" pp );
 .BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest );

+.BI "int str_match(const char *" p ", const char *" s );

 .BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz );
 .fi
 .SH DESCRIPTION
 .BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz );
 .fi
 .SH DESCRIPTION


@@ -32,21 +39,26 @@ contains a few small utility functions for manipulating null-terminated
 strings.  
 .PP
 The function
 strings.  
 .PP
 The function

-.B str_getword
+.B str_qword

 extracts the next whitespace-delimited word from a string.  The
 function's argument,
 .IR pp ,
 is the address of a pointer into the string: this pointer is updated by
 extracts the next whitespace-delimited word from a string.  The
 function's argument,
 .IR pp ,
 is the address of a pointer into the string: this pointer is updated by

-.B str_getword
+.B str_qword

 so that it can extract the following word on the next call and so on.
 The return value is the address of the next word, appropriately null
 terminated.  A null pointer is returned if the entire remainder of the
 string is whitespace.  Note that
 so that it can extract the following word on the next call and so on.
 The return value is the address of the next word, appropriately null
 terminated.  A null pointer is returned if the entire remainder of the
 string is whitespace.  Note that

-.B str_getword
+.B str_qword

 modifies the string as it goes, to null-terminate the individual words.
 modifies the string as it goes, to null-terminate the individual words.

+If the flag
+.B STRF_QUOTE
+is passed, the single- and double-quote characters may be used to quote
+whitespace within words, and the backslash can escape quote characters
+and whitespace.

 .PP
 The function
 .PP
 The function

-.B str_split
+.B str_qsplit

 divides a string into whitespace-separated words.  The arguments are as
 follows:
 .TP
 divides a string into whitespace-separated words.  The arguments are as
 follows:
 .TP


@@ -74,11 +86,56 @@ storing.  If the remainder string is empty, a null pointer is stored
 instead.  If
 .I rest
 is null, the remainder pointer is discarded.
 instead.  If
 .I rest
 is null, the remainder pointer is discarded.

+.TP
+.BI "unsigned " f
+Flags, as for
+.BR str_qsplit .

 .PP
 The return value of
 .PP
 The return value of

-.B str_split
+.B str_qsplit

 is the number of words extracted from the input string.
 .PP
 is the number of words extracted from the input string.
 .PP

+The functions
+.B str_getword
+and
+.B str_split
+are veneers over
+.B str_qword
+and
+.B str_qsplit
+respectively; they are equivalent to calls to the latter functions with
+flags words of zero.
+.PP
+The
+.B str_match
+function does simple wildcard matching.  The first argument is a
+pattern, which may contain metacharacters:
+.RB ` * '
+matches zero or more arbitrary characters;
+.RB ` ? '
+matches exactly one arbitrary characters; and
+.RB ` [ ... ] '
+matches one of the characters listed.  The backslash
+.RB ` \e '
+escapes the following character.  Within square brackets, the
+hyphen
+.RB ` \- '
+may be used to designate ranges of characters.  If the initial character
+is
+.RB ` ! '
+or
+.RB ` ^ '
+then the sense of the match is reversed.  To literally match a
+.RB ` ] '
+character, list it first; to literally match a
+.RB ` \- '
+character, list it immediately after a range, or at the beginning or end
+of the set.  The return value is nonzero if the pattern
+.I p
+matches the given string
+.IR s ,
+or zero if the pattern doesn't match.
+.PP

 The function
 .B str_sanitize
 copies at most
 The function
 .B str_sanitize
 copies at most