##
##  val - OSSP Value Library
##  Copyright (c) 2002 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2002 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
##
##  This file is part of OSSP val, a Value library which
##  can be found at http://www.ossp.org/pkg/val/.
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED 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 AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  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.
##
##  val.pod: library manual page
##

=pod

=head1 NAME

B<OSSP val> - Value Library

=head1 SYNOPSIS

=over 4

=item B<Constants>

C<VAL_MAXNAME>, 
C<VAL_TYPE_VAL>,
C<VAL_TYPE_PTR>,
C<VAL_TYPE_CHAR>,
C<VAL_TYPE_SHORT>,
C<VAL_TYPE_INT>,
C<VAL_TYPE_LONG>,
C<VAL_TYPE_FLOAT>,
C<VAL_TYPE_DOUBLE>
C<VAL_OK>,
C<VAL_ERR_ARG>,
C<VAL_ERR_USE>,
C<VAL_ERR_MEM>,
C<VAL_ERR_HSH>,
C<VAL_ERR_INT>,
C<VAL_ERR_SYS>.

=item B<Data Types>

C<val_t>,
C<val_cb_t>,
C<val_rc_t>.

=item B<Functions>

C<val_create>,
C<val_destroy>,
C<val_reg>,
C<val_unreg>,
C<val_query>,
C<val_set>,
C<val_get>,
C<val_vset>,
C<val_vget>,
C<val_apply>.

=back

=head1 DESCRIPTION

B<OSSP val> is a flexible name to value mapping library for C variables.
It allows one to access C variables through name strings, although
the C language does neither provide such a dedicated facility nor an
evaluation construct (which could be used to implement such a facility
easily). In general, it is interesting whenever you need access to C
variable symbols without having to know the actual address/reference.
The typical use cases are in combination with flexible configuration
parsing and supporting loosly-coupled DSO-based module architectures.

=head1 STRUCTURED NAMES

Whenever the APIs calls for a name it supports structured names where elements
are separated by a dot. It is assumed that the leading elements are references
to other C<val_t> structures and only the very last element is a reference to
an actual variable.

=head1 API CONSTANTS

=over 4

=item C<VAL_MAXNAME>

The maximum length of a variable name. For structured variables this includes
the concatenation of all elements within a path and their separating dots.

=item C<VAL_TYPE_>I<ID>

Type of value when registering a variable using B<val_reg>() or querying for
the type using B<val_query>(). Most are self-explanatory, C<VAL_TYPE_VAL> is
used to mount a C<val_t> structure into an existing C<val_t> structure to
support structured names.

C<VAL_TYPE_VAL>,
C<VAL_TYPE_PTR>,
C<VAL_TYPE_CHAR>,
C<VAL_TYPE_SHORT>,
C<VAL_TYPE_INT>,
C<VAL_TYPE_LONG>,
C<VAL_TYPE_FLOAT>,
C<VAL_TYPE_DOUBLE>

=item C<VAL_OK>, C<VAL_ERR_>I<ID>

Return codes for every API function. Signals success, invalid argument passed
to function, bad usage of a function, memoryusage reached C<VAL_MAXNAME>
limit, error in internal hash function to be examined through C<errno>,
internal error in storage as result from structure corruption, or system
errors including out of memory.

C<VAL_ERR_ARG>,
C<VAL_ERR_USE>,
C<VAL_ERR_MEM>,
C<VAL_ERR_HSH>,
C<VAL_ERR_INT>,
C<VAL_ERR_SYS>.

=back

=head1 API DATA TYPES

=over 4

=item C<val_t>

Handle created by B<val_create>() and passed to all other functions to reference
the the same group of variables.

=item C<val_cb_t>

Callback to be used B<var_apply>().

=item C<val_rc_t>

Code returned by every function. See C<API_CONSTANTS> C<VAL_OK> and
C<VAL_ERR_>I<ID>.

=back

=head1 API FUNCTIONS

=over 4

=item val_rc_t B<val_create>(val_t **I<pval>);

Creates an I<val> and updates the given pointer to reference it.

=item val_rc_t B<val_destroy>(val_t *I<val>);

Destroys an I<val>, freeing up memory.

=item val_rc_t B<val_reg>(val_t *I<val>, const char *I<name>, int I<type>, const char *I<desc>, void *I<storage>);

Registers a variable I<name> using I<type> in I<val>. An optional description
or NULL can be passed through I<desc> which can be queried through
B<val_query>() and is also passed to the callback of B<val_apply>(). The value
that belongs to the given I<name> is expected to be found at I<storage>.
Passing NULL as I<storage> will create an inline data store in I<val> so it
can only be access through B<val_get>(), B<val_set>() or after the actual
storage address was queried using B<val_query>().

=item val_rc_t B<val_unreg>(val_t *I<val>, const char *I<name>);

Unregisters a variable I<name> in I<val>.

=item val_rc_t B<val_query>(val_t *I<val>, const char *I<name>, int *I<ptype>, char **I<pdesc>, void **I<pstorage>);

Queries a variable I<name> in I<val> and returns it's type, description and
storage address. All of I<ptype>, I<pdesc> and I<pstorage> are optional and
NULL can be passed in if this information is not needed. Passing NULL to all
query result pointers just checks for existence of I<name>.

=item val_rc_t B<val_set>(val_t *I<val>, const char *I<name>, ...);

Sets the value of variable I<name> in I<val> to the data passed in as vararg.
Unless the actual storage address was queried using B<val_query>() this is
mandatory for inline data. Usually not the value but a pointer to it is stored
to the value can be modified without notice to the library.

=item val_rc_t B<val_get>(val_t *I<val>, const char *I<name>, ...);

Gets the value of variable I<name> in I<val> and stores it whereever the
passed vararg points to.

=item val_rc_t B<val_vset>(val_t *I<val>, const char *I<name>, va_list I<ap>);

Like B<val_set>() but takes a C<va_list> as input to allow recursive
execution. Acutally, B<val_set>() ist just a wrapper around
B<val_vset>().

=item val_rc_t B<val_vget>(val_t *I<val>, const char *I<name>, va_list I<ap>);

Like B<val_get>() but takes a C<va_list> as input to allow recursive
execution. Acutally, B<val_get>() ist just a wrapper around
B<val_vget>().

=item val_rc_t B<val_apply>(val_t *I<val>, const char *I<name>, int I<depth>, val_cb_t I<cb>, void *I<ctx>);

Iterates through all elements of I<val>, starting with I<name> which can be
either a data store or I<val> reference, down to a given recursion I<depth>.
When I<name> is set to the empty string the search starts immediately at
I<val>.  For every element, the callback I<cb>() is executed and a context
I<ctx> is passed to it along with other information described below.

=item val_rc_t (*)(void *I<ctx>, const char *I<name>, int I<type>, const char *I<desc>, void *I<data>)

Callback executed by B<val_apply>() for each element being processed. The
context I<ctx> input to B<val_apply>() is passed to the callback verbatim. The
I<name> is the structured name relative to the I<val> passed to
B<val_apply>(), I<type> signals the type of value I<data> points to and
I<desc> is a text which was optionally passed to B<val_reg>().

=back

=head1 SEE ALSO

OSSP var.

=head1 EXAMPLES

=over 4

=item simple create, reg, get, destroy

    #include <stdio.h>
    #include "val.h"

    int main(void)
    {
        val_rc_t rc;
        val_t *v;
        int example;
        int pullout;

        if ((rc = val_create(&v)) != VAL_OK) exit(-1);
        if ((rc = val_reg(v, "foo", VAL_TYPE_INT, "foo variable", (void *)&example)) != VAL_OK) exit(-1);
        example = 123;
        if ((rc = val_get(v, "foo", &pullout)) != VAL_OK) exit(-1);
        printf("pulled example and got %d\n", pullout);
        if ((rc = val_destroy(v)) != VAL_OK) exit(-1);
        return 0;
    }

=item reg inline data, structured name, set

    #include <stdio.h>
    #include "val.h"

    int main(void)
    {
        val_rc_t rc;
        val_t *v1, *v2;
        int pullout;

        if ((rc = val_create(&v1)) != VAL_OK) exit(-1);
        if ((rc = val_create(&v2)) != VAL_OK) exit(-1);
        if ((rc = val_reg(v1, "bar", VAL_TYPE_VAL, "child", (void *)&v2)) != VAL_OK) exit(-1);
        if ((rc = val_reg(v1, "bar.foo", VAL_TYPE_INT, "foo variable", NULL)) != VAL_OK) exit(-1);
        if ((rc = val_set(v2, "foo", 456)) != VAL_OK) exit(-1);
        if ((rc = val_get(v1, "bar.foo", &pullout)) != VAL_OK) exit(-1);
        printf("pulled example and got %d\n", pullout);
        if ((rc = val_destroy(v2)) != VAL_OK) exit(-1);
        if ((rc = val_destroy(v1)) != VAL_OK) exit(-1);
        return 0;
    }

=back

=head1 HISTORY

B<OSSP val> was invented in January 2002 by Thomas Lotterer and Ralf S.
Engelschall for use inside the OSSP lmtp2nntp project.

=head1 AUTHORS

 Thomas Lotterer
 Ralf S. Engelschall

=cut