diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 71 |
1 files changed, 40 insertions, 31 deletions
@@ -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. |