summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org>2019-07-10 06:54:32 (GMT)
committer Sergey Poznyakoff <gray@gnu.org>2019-07-10 06:54:32 (GMT)
commitd36275fe9adf1428fd2476defda9e1fcda56988a (patch) (side-by-side diff)
tree0d5c9b9aabac887a100934118955ed7736690a98
parent5742ab5a037160a115144b3bf45cf3349df24635 (diff)
downloadwordsplit-d36275fe9adf1428fd2476defda9e1fcda56988a.tar.gz
wordsplit-d36275fe9adf1428fd2476defda9e1fcda56988a.tar.bz2
Improve docs
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--README71
-rw-r--r--wordsplit.314
2 files changed, 47 insertions, 38 deletions
diff --git a/README b/README
index c08b680..59f3436 100644
--- a/README
+++ b/README
@@ -1,18 +1,21 @@
* Overview
-This package provides a set of C functions for splitting a string into
-words. The splitting process is highly configurable and allows for
-considerable flexibility. The default splitting rules are similar to
-those used in Bourne shell. The splitting process includes tilde
-expansion, variable expansion, quote removal, command substitution,
-and path expansion. Each of these phases can be turned off by the caller.
+This package provides a set of C functions for parsing input strings.
+Default parsing rules are are similar to those used in Bourne shell.
+This includes tilde expansion, variable expansion, quote removal, word
+splitting, command substitution, and path expansion. Parsing is
+controlled by a number of settings which allow the caller to alter
+processing at each of these phases or even to disable any of them.
+Thus, wordsplit can be used for parsing inputs in different formats,
+from simple character-delimited entries, as in /etc/passwd, and up to
+complex shell statements.
The following code fragment shows the basic usage:
- /* This variable controls the splitting */
+ /* This variable controls parsing */
wordsplit_t ws;
int rc;
/* Provide variable definitions */
ws.ws_env = (const char **) environ;
/* Provide a function for expanding commands */
@@ -28,13 +31,13 @@ The following code fragment shows the basic usage:
/* Success. The resulting words are returned in the NULL-terminated
array ws.ws_wordv. Number of words is in ws.ws_wordc */
}
/* Reclaim the allocated memory */
wordsplit_free(&ws);
-For a detailed discussion, please see the man page wordsplit.3 inluded
+For a detailed discussion, please see the man page wordsplit.3 included
in the package.
* Description
The package is designed as a drop-in facility for use in larger
programs. It consists of the following files:
@@ -48,26 +51,31 @@ are for building the autotest-based testsuite:
wsp.c - Auxiliary test program.
wordsplit.at - The source for the testsuite.
* Incorporating wordsplit into your project
-The project is designed to be used as a git submodule. First, select
-the location DIR for the wordsplit directory within your project. Then
-add the submodule:
+The project is designed to be used as a git submodule. To incorporate
+it into your project, first select the location for the wordsplit
+directory within your project. Then add the submodule at this
+location. The rest is quite straightforward: you need to add
+wordsplit.c to your sources and add both wordsplit.c and wordsplit.h
+to the distributed files.
+
+The following will describe each step in detail. For the rest of this
+discussion it is supposed that 'wordsplit' is the name of the location
+selected for the submodule. It is also supposed that your project
+uses GNU autotools framework. If you are using plain makefiles, these
+instructions are easy to convert to such use as well.
- git submodule add git://git.gnu.org.ua/wordsplit.git DIR
+To add the submodule do:
-The rest is quite straightforward: you need to add wordsplit.c to your
-sources and add both wordsplit.c and wordsplit.h to the distributed files.
+ git submodule add git://git.gnu.org.ua/wordsplit.git wordsplit
-There are two methods of doing so: direct incorporation and
-incorporation via VPATH. The discussion below will describe both
-methods based on the assumption that your project is using GNU
-autotools framework. If you are using plain makefiles, these
-instructions are easy to convert to such use as well.
+There are two methods of including the sources to the project: direct
+incorporation and incorporation via VPATH.
** Direct incorporation
Add the subdir-objects option to the invocation of AM_INIT_AUTOMAKE macro in
your configure.ac:
@@ -85,36 +93,36 @@ You can also put wordsplit.h in the noinst_HEADERS variable, if you like:
program_SOURCES = main.c \
wordsplit/wordsplit.c
noinst_HEADERS = wordsplit/wordsplit.h
AM_CPPFLAGS = -I$(srcdir)/wordsplit
-If you are building an installable library and wish to make wordsplit functions
-available, install wordsplit.h to $(pkgincludedir), e.g.
+If you are building an installable library and wish to export the
+wordsplit API, install wordsplit.h to $(pkgincludedir), e.g.
lib_LTLIBRARIES = libmy.la
libmy_la_SOURCES = main.c \
wordsplit/wordsplit.c
AM_CPPFLAGS = -I$(srcdir)/wordsplit
pkginclude_HEADERS = wordsplit/wordsplit.h
-** Vpath-based incorporation
+** VPATH-based incorporation
Modify the VPATH variable in your Makefile.am:
VPATH += $(srcdir)/wordsplit
Notice the use of "+=": it is necessary for the vpath builds to work.
-Define the nodist_program_SOURCES variable:
+Add wordsplit.c to the nodist_program_SOURCES variable:
nodist_program_SOURCES = wordsplit.c
The nodist_ prefix is necessary to prevent Make from trying to
distribute this file from the current directory (where it doesn't
-exist of course). It will find it using VPATH during compilation.
+exist of course). During compilation it will be located using VPATH.
Finally, add both wordsplit/wordsplit.c and wordsplit/wordsplit.h to
the EXTRA_DIST variable and modify AM_CPPFLAGS as shown in the
previous section.
An example Makefile.am:
@@ -193,13 +201,13 @@ Add the following lines to your configure.ac:
AC_CONFIG_TESTDIR([lib])
AC_CONFIG_FILES([lib/Makefile lib/atlocal])
** lib/Makefile.am
-The makefile in lib must be modified to build the auxiliary program
+The Makefile.am in lib must be modified to build the auxiliary program
wsp and create the testsuite script. This is done by the following
fragment:
EXTRA_DIST = testsuite wordsplit/wordsplit.at package.m4
DISTCLEANFILES = atconfig
MAINTAINERCLEANFILES = Makefile.in $(TESTSUITE)
@@ -225,23 +233,24 @@ fragment:
check-local: atconfig atlocal $(TESTSUITE)
@$(SHELL) $(TESTSUITE)
* History
First version of wordsplit appeared in March 2009 as a part of the
-Wydawca[1] project. Its main usage there was to assist in
-configuration file parsing. The parser subsystem proved to be quite
-useful and it soon forked into a separate project - Grecs[2]. This
-package had been since used (as a git submodule) in a number of other
-projects, such as GNU Dico[3] and Direvent[4], to name a few.
+Wydawca[1] project. Its main usage was to assist in configuration
+file parsing. The parser subsystem proved to be quite useful and
+soon evolved into a separate project - Grecs[2]. This package had been
+since used (as a git submodule) in a number of other projects, such as
+GNU Dico[3] and Direvent[4], to name a few.
In 2010 the wordsplit sources were incorporated to the GNU
Mailutils[5] package, where they replaced the obsolete argcv module.
Mailutils uses its own configuration package, which meant that using
Grecs was not expedient. Therefore the sources had been exported from
-Grecs and are kept in sync with the changes in it.
+Grecs. Since then both Mailutils and Grecs versions are periodically
+synchronized.
Several other projects, such as GNU Rush[6] and fileserv[7], followed
the suite. It was therefore decided that it would be advisable to
have wordsplit as a separate package which could be easily included in
another project without incurring unnecessary overhead.
diff --git a/wordsplit.3 b/wordsplit.3
index 139c73e..e742030 100644
--- a/wordsplit.3
+++ b/wordsplit.3
@@ -330,13 +330,13 @@ The sequence \fB\\0\fINNN\fR, where \fINNN\fR stands for a three-digit
octal number is replaced with ASCII character whose code is \fINNN\fR.
.PP
The \fBWRDSF_ESCAPE\fR flag allows the caller to customize escape
sequences. If it is set, the \fBws_escape\fR member must be
initialized. This member provides escape tables for unquoted words
(\fBws_escape[0]\fR) and quoted strings (\fBws_escape[1]\fR). Each
-table is a string consisting of an even number of charactes. In each
+table is a string consisting of an even number of characters. In each
pair of characters, the first one is a character that can appear after
backslash, and the following one is its translation. For example, the
above table of C escapes is represented as
\fB\(dq\\\\\\\\"\\"a\\ab\\bf\\fn\\nr\\rt\\tv\\v\(dq\fR.
.PP
It is valid to initialize \fBws_escape\fR elements to zero. In this
@@ -597,16 +597,16 @@ If initialized on input, the
flag must be set. By default, it's value is \fB\(dq#\(dq\fR.
.TP
.BI "const char *" ws_escape [2]
Escape tables for unquoted words (\fBws_escape[0]\fR) and quoted
strings (\fBws_escape[1]\fR). These are used to translate escape
sequences (\fB\\\fIC\fR) into characters. Each table is a string
-consisting of even number of charactes. In each pair of characters,
+consisting of even number of characters. In each pair of characters,
the first one is a character that can appear after backslash, and the
following one is its representation. For example, the string
-\fB\(dqt\\tn\\n\(dq\fR translates \fB\\t\fR into horisontal
+\fB\(dqt\\tn\\n\(dq\fR translates \fB\\t\fR into horizontal
tabulation character and \fB\\n\fR into newline.
.B WRDSF_ESCAPE
flag must be set if this member is initialized.
.TP
.BI "void (*" ws_alloc_die ") (wordsplit_t *)"
This function is called when
@@ -752,14 +752,14 @@ Default flags. This is a shortcut for:
\fB(WRDSF_NOVAR |\
WRDSF_NOCMD |\
WRDSF_QUOTE |\
WRDSF_SQUEEZE_DELIMS |\
WRDSF_CESCAPES)\fR,
-i.e.: disable variable expansion and quote substituton, perform quote
-removal, treat any number of consequtive delimiters as a single
+i.e.: disable variable expansion and quote substitution, perform quote
+removal, treat any number of consecutive delimiters as a single
delimiter, replace \fBC\fR escapes appearing in the input string with
the corresponding characters.
.TP
.B WRDSF_APPEND
Append the resulting words to the array left from a previous call to
\fBwordsplit\fR.
@@ -804,13 +804,13 @@ errors: the error is reported using \fIws_error\fR if the
.B WRDSF_SHOWERR
flag is set, and error code is returned. If this flag is set, the
.B ws_alloc_die
function is called instead. This function is not supposed to return.
.TP
.B WRDSF_WS
-Trim off any leading and trailind whitespace from the returned
+Trim off any leading and trailing whitespace from the returned
words. This flag is useful if the \fIws_delim\fR member does not
contain whitespace characters.
.TP
.B WRDSF_SQUOTE
Handle single quotes.
.TP
@@ -1004,13 +1004,13 @@ Unbalanced curly brace.
.TP
.B WRDSE_UNDEF
Undefined variable. This error is returned only if the
\fBWRDSF_UNDEF\fR flag is set.
.TP
.B WRDSE_NOINPUT
-Input exhausted. This is not acually an error. This code is returned
+Input exhausted. This is not actually an error. This code is returned
if \fBwordsplit\fR (or \fBwordsplit_len\fR) is invoked in incremental
mode and encounters end of input string. See the section
.BR "INCREMENTAL MODE" .
.TP
.B WRDSE_PAREN
Unbalanced parenthesis.

Return to:

Send suggestions and report system problems to the System administrator.