Add new libraries/utilities for data throughput visualization.

dpv(3): dialog progress view library
dpv(1): stream data from stdin or multiple paths with dialog progress view
figpar(3): configuration file parsing library

Reviews:	D714
Reviewed by:	jelischer, shurd
Discussed at:	MeetBSD California 2014 Vendor/Dev Summit
Discussed on:	-current
MFC after:	21 days
X-MFC-to:	stable/10 stable/9

1 files changed, 251 insertions, 0 deletions

diff --git a/lib/libfigpar/figpar.3 b/lib/libfigpar/figpar.3
new file mode 100644
index 0000000..549808e
--- /dev/null
+++ b/lib/libfigpar/figpar.3
@@ -0,0 +1,251 @@
+.\" Copyright (c) 2013-2014 Devin Teske <dteske@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd Oct 24, 2014
+.Dt FIGPAR 3
+.Os
+.Sh NAME
+.Nm figpar ,
+.Nm parse_config ,
+.Nm get_config_option
+.Nd configuration file parsing library
+.Sh LIBRARY
+.Lb libfigpar
+.Sh SYNOPSIS
+.In figpar.h
+.Ft int
+.Fo parse_config
+.Fa "struct fp_config options[], const char *path"
+.Fa "int \*[lp]*unknown\*[rp]\*[lp]struct fp_config *option, uint32_t line"
+.Fa "char *directive, char *value\*[rp], uint8_t processing_options"
+.Fc
+.Ft "struct fp_config *"
+.Fo get_config_option
+.Fa "struct fp_config options[], const char *directive"
+.Fc
+.In string_m.h
+.Ft int
+.Fo replaceall
+.Fa "char *source, const char *find, const char *replace"
+.Fc
+.Ft unsigned int
+.Fo strcount
+.Fa "const char *source, const char *find"
+.Fc
+.Ft void
+.Fo strexpand
+.Fa "char *source"
+.Fc
+.Ft void
+.Fo strexpandnl
+.Fa "char *source"
+.Fc
+.Ft void
+.Fo strtolower
+.Fa "char *source"
+.Fc
+.Sh DESCRIPTION
+The
+.Nm
+library provides a light-weight, portable framework for parsing configuration
+files.
+The library uses
+.Xr open 2 ,
+.Xr read 2 ,
+and
+.Xr lseek 2
+within the file pointed to by
+.Fa path
+to find directives and values which are then made available to the application.
+.Pp
+Due to the fact that configuration files may have basic syntax differences,
+the library does not attempt to impose any structure on the data but instead
+provides raw data to a set of callback functions.
+These callback functions can in-turn initiate abort through their return value,
+allowing custom syntax validation during parsing.
+.Pp
+Configuration directives, types, and callback functions are provided through
+data structures defined in
+.In figpar.h :
+.Bd -literal -offset indent
+struct fp_config {
+    enum fp_cfgtype	type;		/* value type */
+    const char		*directive;	/* keyword */
+    union fp_cfgvalue	value;		/* value */
+
+    /* Pointer to function used when directive is found */
+    int (*action)(struct fp_config *option, uint32_t line,
+        char *directive, char *value);
+};
+
+enum fp_cfgtype {
+    FP_TYPE_NONE      = 0x0000, /* for directives with no value */
+    FP_TYPE_BOOL      = 0x0001, /* boolean */
+    FP_TYPE_INT       = 0x0002, /* signed 32 bit integer */
+    FP_TYPE_UINT      = 0x0004, /* unsigned 32 bit integer */
+    FP_TYPE_STR       = 0x0008, /* string pointer */
+    FP_TYPE_STRARRAY  = 0x0010, /* string array pointer */
+    FP_TYPE_DATA1     = 0x0020, /* void data type-1 (whatever) */
+    FP_TYPE_DATA2     = 0x0040, /* void data type-2 (whatever) */
+    FP_TYPE_DATA3     = 0x0080, /* void data type-3 (whatever) */
+    FP_TYPE_RESERVED1 = 0x0100, /* reserved data type-1 (future) */
+    FP_TYPE_RESERVED2 = 0x0200, /* reserved data type-2 (future) */
+    FP_TYPE_RESERVED3 = 0x0400, /* reserved data type-3 (future) */
+};
+
+union fp_cfgvalue {
+    void	*data;      /* Pointer to NUL-terminated string */
+    char	*str;       /* Pointer to NUL-terminated string */
+    char	**strarray; /* Pointer to an array of strings */
+    int32_t	num;        /* Signed 32-bit integer value */
+    uint32_t	u_num;      /* Unsigned 32-bit integer value */
+    uint32_t	boolean:1;  /* Boolean integer value (0 or 1) */
+};
+.Ed
+.Pp
+The
+.Fa processing_options
+argument to
+.Fn parse_config
+is a mask of bit fields which indicate various
+processing options.
+The possible flags are as follows:
+.Bl -tag -width FP_BREAK_ON_SEMICOLON
+.It Dv FP_BREAK_ON_EQUALS
+An equals sign
+.Pq Ql Li =
+is normally considered part of the directive.
+This flag enables terminating the directive at the equals sign.
+Also makes equals sign optional and transient.
+.It Dv FP_BREAK_ON_SEMICOLON
+A semicolon
+.Pq Ql Li \;
+is normally considered part of the value.
+This flag enables terminating the value at the semicolon.
+Also allows multiple statements on a single line separated by semicolon.
+.It Dv FP_CASE_SENSITIVE
+Normally directives are matched case insensitively using
+.Xr fnmatch 3 .
+This flag enables directive matching to be case sensitive.
+.It Dv FP_REQUIRE_EQUALS
+If a directive is not followed by an equals, processing is aborted.
+.It Dv FP_STRICT_EQUALS
+Equals must be part of the directive to be considered a delimiter between
+directive and value.
+.El
+.Pp
+The
+.Fa options
+struct array pointer can be NULL and every directive will invoke the
+.Fn unknown
+function argument.
+.Pp
+The directive for each fp_config item in the
+.Fn parse_config
+options argument is matched against each parsed directive using
+.Xr fnmatch 3
+until a match is found.
+If a match is found, the
+.Fn action
+function for that fp_config directive is invoked with the line number,
+directive, and value.
+Otherwise if no match, the
+.Fn unknown
+function is invoked
+.Pq with the same arguments .
+.Pp
+If either
+.Fa action
+or
+.Fa unknown
+return non-zero,
+.Fn parse_config
+aborts reading the file and returns the error value to its caller.
+.Pp
+.Fn get_config_option
+traverses the options-array and returns the option that matches via
+.Xr strcmp 3 ,
+or if no match a pointer to a static dummy struct is returned
+.Pq whose values are all zero or NULL .
+.Pp
+The use of
+.Fa "struct fp_config"
+is entirely optional as-is the use of
+.Fa "enum fp_cfgtype"
+or
+.Fa "union fp_cfgvalue" .
+For example, you could choose to pass a NULL pointer to
+.Fn parse_config
+for the first argument and then provide a simple
+.Fa unknown
+function based on
+.Xr queue 3
+that populates a singly-linked list of your own struct containing the
+.Fa directive
+and
+.Fa value .
+.Pp
+In addition, the following miscellaneous string manipulation routines are
+provided by
+.In string_m.h :
+.Bl -tag -width strexpandnl()
+.It Fn replaceall
+Replace all occurrences of
+.Fa find
+in
+.Fa source
+with
+.Fa replace .
+.It Fn strcount
+Count the number of occurrences of one string that appear in the
+.Fa source
+string.
+Return value is the total count.
+An example use would be if you need to know how large a block of memory needs
+to be for a
+.Fn replaceall
+series.
+.It Fn strexpand
+Expand escape sequences in a buffer pointed to by
+.Fa source .
+.It Fn strexpandnl
+Expand only the escaped newlines in a buffer pointed to by
+.Fa source .
+.It Fn strtolower
+Convert a string to lower case.
+.El
+.Sh SEE ALSO
+.Xr queue 3
+.Sh HISTORY
+The
+.Nm
+library first appeared in
+.Fx 11.0 .
+.Sh AUTHORS
+.An Devin Teske Aq dteske@FreeBSD.org
+.Sh BUGS
+This is the first implementation of the library,
+and the interface may be subject to refinement.