diff options
| -rw-r--r-- | README | 71 | ||||
| -rw-r--r-- | wordsplit.3 | 14 |
2 files changed, 47 insertions, 38 deletions
@@ -2,8 +2,11 @@ -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. @@ -11,3 +14,3 @@ The following code fragment shows the basic usage: - /* This variable controls the splitting */ + /* This variable controls parsing */ wordsplit_t ws; @@ -33,3 +36,3 @@ The following code fragment shows the basic usage: -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. @@ -53,16 +56,21 @@ are for building the autotest-based testsuite: -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. @@ -90,4 +98,4 @@ You can also put wordsplit.h in the noinst_HEADERS variable, if you like: -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. @@ -99,3 +107,3 @@ available, install wordsplit.h to $(pkgincludedir), e.g. -** Vpath-based incorporation +** VPATH-based incorporation @@ -107,3 +115,3 @@ 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: @@ -113,3 +121,3 @@ 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. @@ -198,3 +206,3 @@ Add the following lines to your configure.ac: -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 @@ -230,7 +238,7 @@ fragment: 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. @@ -240,3 +248,4 @@ 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. diff --git a/wordsplit.3 b/wordsplit.3 index 139c73e..e742030 100644 --- a/wordsplit.3 +++ b/wordsplit.3 @@ -335,3 +335,3 @@ 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 @@ -602,6 +602,6 @@ 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. @@ -757,4 +757,4 @@ Default flags. This is a shortcut for: -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 @@ -809,3 +809,3 @@ function is called instead. This function is not supposed to return. .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 @@ -1009,3 +1009,3 @@ Undefined variable. This error is returned only if the .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 |