mirrors/wordsplit
1
0
Fork 0
mirror of git://git.gnu.org.ua/wordsplit.git synced 2025-04-26 08:39:54 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Minor fixes in documentation

Browse source
This commit is contained in:
Sergey Poznyakoff 2014-12-03 16:01:16 +02:00
parent 3fca27c20b
commit 1939ae3326
1 changed files with 24 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

47
doc/wordsplit.3
View file

@ -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 "October 31, 2014" "GRECS" "Grecs User Reference"
.TH WORDSPLIT 3 "December 3, 2014" "GRECS" "Grecs User Reference"
.SH NAME
wordsplit \- split string into words
.SH SYNOPSIS
@ -43,12 +43,12 @@ wordsplit \- split string into words
.SH DESCRIPTION
The function \fBwordsplit\fR splits the string \fIs\fR into words
using a set of rules governed by \fIflags\fR. Depending on
\fIflags\fR, the function performs the following: whitespace trimming,
tilde expansion, variable expansion, quote removal, command
substitution, and path expansion. On success, the function returns 0
and stores the words found in the member \fBws_wordv\fR and the number
of words in the member \fBws_wordc\fR. On error, a non-zero error
code is returned.
\fIflags\fR, the function performs the following operations:
whitespace trimming, tilde expansion, variable expansion, quote
removal, command substitution, and path expansion. On success,
\fBwordsplit\fR returns 0 and stores the words found in the member
\fBws_wordv\fR and the number of words in the member \fBws_wordc\fR.
On error, a non-zero error code is returned.
.PP
The function \fBwordsplit_len\fR acts similarly, except that it
accesses only first \fBlen\fR bytes of the string \fIs\fR, which is
@ -108,8 +108,8 @@ The function
clears the error condition associated with \fIws\fR.
.SH INCREMENTAL MODE
In incremental mode \fBwordsplit\fR parses one word per invocation.
It returns \fBWRDSF_OK\fR on success and \fBWRDSF_NOINPUT\fR when it
has processed entire input string.
It returns \fBWRDSF_OK\fR on success and \fBWRDSF_NOINPUT\fR when
entire input string has been processed.
.PP
This mode is enabled if the flag \fBWRDSF_INCREMENTAL\fR is set in
the \fIflags\fR argument. Subsequent calls to \fBwordsplit\fR must
@ -179,24 +179,25 @@ An alternative format is enabled by the
flag. When it is set, each variable is described by two consecutive
elements in the array:
.IR ws_env [ n ]
contains variable name, and
containing the variable name, and
.IR ws_env [ "n+1" ]
contains its value.
containing its value.
.PP
More sophisticated variable tables can be implemented using
callback function. The \fIws_getvar\fR member should be set to point
to that function and \fBWRDSF_GETVAR\fR flag must be set. The
function itself should be defined as
function itself shall be defined as
.PP
.EX
int getvar (char **ret, const char *var, size_t len, void *clos);
.EE
.PP
The function should look up for the variable identified by the first
The function shall look up for the variable identified by the first
\fIlen\fR bytes of the string \fIvar\fR. If such variable is found,
th function stores a copy of its value (allocated using
the function shall store a copy of its value (allocated using
\fBmalloc\fR(3)) in the memory location pointed to by \fBret\fR, and
returns \fBWRDSE_OK\fR. If the variable is not found, the function
returns \fBWRDSE_UNDEF\fR. Otherwise, a non NULL error code is
return \fBWRDSE_OK\fR. If the variable is not found, the function shall
return \fBWRDSE_UNDEF\fR. Otherwise, a non-zero error code shall be
returned.
.PP
If \fIws_getvar\fR returns
@ -288,7 +289,7 @@ above table of C escapes is represented as
It is valid to initialize \fBws_escape\fR elements to zero. In this
case, no backslash translation occurs.
.PP
The handling if octal and hex escapes is controlled by the following
The handling of octal and hex escapes is controlled by the following
bits in \fBws_options\fR:
.TP
.B WRDSO_BSKEEP_WORD
@ -542,10 +543,11 @@ is called.
The name of the variable is specified by the first \fIlen\fR bytes of
the string \fIvar\fR. The \fIclos\fR parameter supplies the
user-specific data (see below the description of \fIws_closure\fR
member) and the \fBret\fR parameter points to the memory location used
for output data. On success, the function must store ther a pointer
to the string with the value of the variable and return 0. On error,
it must return one of the error codes described in the section
member) and the \fBret\fR parameter points to the memory location
where output data is to be stored. On success, the function must
store ther a pointer to the string with the value of the variable and
return 0. On error, it must return one of the error codes described
in the section
.BR "ERROR CODES" .
If \fIws_getvar\fR returns
.BR WRDSE_USERERR ,
@ -836,7 +838,7 @@ Unbalanced parenthesis.
An error occurred during pattern matching.
.TP
.B WRDSE_USERERR
User-defined error. Normally it is returned by \fBws_getvar\fR or
User-defined error. Normally this error is returned by \fBws_getvar\fR or
\fBws_command\fR. Use the function
.B wordsplit_strerror
to get textual description of the error.
@ -966,7 +968,6 @@ char **shell_parse(char *s)
return wv;
}
.EE
.SH "SEE ALSO"
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"