diff options
Diffstat (limited to 'doc/wordsplit.3')
-rw-r--r-- | doc/wordsplit.3 | 59 |
1 files changed, 55 insertions, 4 deletions
diff --git a/doc/wordsplit.3 b/doc/wordsplit.3 index a391b81..c3149fe 100644 --- a/doc/wordsplit.3 +++ b/doc/wordsplit.3 @@ -1,5 +1,5 @@ .\" This file is part of grecs -*- nroff -*- -.\" Copyright (C) 2007-2016 Sergey Poznyakoff +.\" Copyright (C) 2007-2018 Sergey Poznyakoff .\" .\" Grecs is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by @@ -14,7 +14,7 @@ .\" You should have received a copy of the GNU General Public License .\" along with Grecs. If not, see <http://www.gnu.org/licenses/>. .\" -.TH WORDSPLIT 3 "February 20, 2018" "GRECS" "Grecs User Reference" +.TH WORDSPLIT 3 "May 22, 2018" "GRECS" "Grecs User Reference" .SH NAME wordsplit \- split string into words .SH SYNOPSIS @@ -133,6 +133,17 @@ if (rc != WRDSE_NOINPUT) wordsplit_free(&ws); .EE +.SH OPTIONS +The number of flags is limited to 32 (the width of \fBuint32_t\fR data +type) and each bit is occupied by a corresponding flag. However, the +number of features \fBwordsplit\fR provides required still +more. Additional features can be requested by setting a corresponding +\fIoption bit\fR in the \fBws_option\fR field of the \fBstruct +wordsplit\fR argument. To inform wordsplit functions that this field +is initialized the \fBWRDSF_OPTIONS\fR flag must be set. +.PP +Option symbolic names begin with \fBWRDSO_\fR. They are discussed in +detail in the subsequent chapters. .SH EXPANSION Expansion is performed on the input after it has been split into words. There are several kinds of expansion, which of them are @@ -392,7 +403,29 @@ for each such word using .PP When matching a pattern, the dot at the start of a name or immediately following a slash must be matched explicitly, unless -the \fBWRDSO_DOTGLOB\fR option is set, +the \fBWRDSO_DOTGLOB\fR option is set. +.SH LIMITING THE NUMBER OF WORDS +The maximum number of words to be returned can be limited by setting +the \fBws_maxwords\fR member to the desired count, and setting the +\fBWRDSO_MAXWORDS\fR option, e.g.: +.sp +.EX +struct wordsplit ws; +ws.ws_maxwords = 3; +ws.ws_options = WRDSO_MAXWORDS; +wordsplit(str, &ws, WRDSF_DEFFLAGS|WRDSF_OPTIONS); +.EE +.PP +If the actual number of words in the expanded input is greater than +the supplied limit, the trailing part of the input will be returned in +the last word. For example, if the input to the above fragment were +\fBNow is the time for all good men\fR, then the returned words would be: +.sp +.EX +"Now" +"is" +"the time for all good men" +.EE .SH WORDSPLIT_T STRUCTURE The data type \fBwordsplit_t\fR has three members that contain output data upon return from \fBwordsplit\fR or \fBwordsplit_len\fR, @@ -410,6 +443,12 @@ from \fBwordsplit\fR. Array of resulting words. Accessible upon successful return from \fBwordsplit\fR. .TP +.BI "size_t " ws_wordi +Total number of words processed. This field is intended for use with +.B WRDSF_INCREMENTAL +flag. If that flag is not set, the following relation holds: +.BR "ws_wordi == ws_wordc - ws_offs" . +.TP .BI "int " ws_errno Error code, if the invocation of \fBwordsplit\fR or \fBwordsplit_len\fR failed. This is the same value as returned from @@ -435,6 +474,12 @@ flag is set, this member specifies the number of initial elements in to fill with NULLs. These elements are not counted in the returned .IR ws_wordc . .TP +.BI "size_t " ws_maxwords +Maximum number of words to return. For this field to take effect, the +\fBWRDSO_MAXWORDS\fR option and \fBWRDSF_OPTIONS\fR flag must be set. +For a detailed discussion, see the chapter +.BR "LIMITING THE NUMBER OF WORDS" . +.TP .BI "int " ws_flags Contains flags passed to wordsplit on entry. Can be used as a read-only member when using \fBwordsplit\fR in incremental mode or @@ -804,6 +849,12 @@ Quote removal: handle octal escapes in doubly-quoted strings. .TP .B WRDSO_XESC_QUOTE Quote removal: handle hex escapes in doubly-quoted strings. +.TP +.B WRDSO_MAXWORDS +The \fBws_maxwords\fR member is initialized. This is used to control +the number of words returned by a call to \fBwordsplit\fR. For a +detailed discussion, refer to the chapter +.BR "LIMITING THE NUMBER OF WORDS" . .SH "ERROR CODES" .TP .BR WRDSE_OK ", " WRDSE_EOF @@ -974,7 +1025,7 @@ Sergey Poznyakoff .SH "BUG REPORTS" Report bugs to <gray+grecs@gnu.org.ua>. .SH COPYRIGHT -Copyright \(co 2009-2014 Sergey Poznyakoff +Copyright \(co 2009-2018 Sergey Poznyakoff .br .na License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> |