352 lines
13 KiB
Groff
352 lines
13 KiB
Groff
.\" $XConsortium: nval.3 /main/2 1995/07/17 14:27:24 drk $
|
|
.TH NVAL 3 "12 Nov 1992"
|
|
.PP
|
|
\fBNAME\fP
|
|
.PP
|
|
\fBnval\fR \- a \f5ksh\fP name/value library
|
|
.PP
|
|
\fBSYNOPSIS\fP
|
|
.ta .8i 1.6i 2.4i 3.2i 4.0i 4.8i
|
|
.PP
|
|
.nf
|
|
.ft 5
|
|
#include <nval.h>
|
|
|
|
Namval_t *nv_namset(const char *\fIname\fP, Hashtab_t *\fItable\fP, int \fItype\fP);
|
|
Namval_t *nv_search(const char *\fIname\fP, Hashtab_t *\fItable\fP, int \fItype\fP);
|
|
void nv_free(Namval_t *\fInp\fP);
|
|
|
|
char *nv_name(Namval_t *\fInp\fP);
|
|
char *nv_getval(Namval_t *\fInp\fP);
|
|
double nv_getnum(Namval_t *\fInp\fP);
|
|
void nv_putval(Namval_t *\fInp\fP, const char *\fIval\fP, int \fItype\fP);
|
|
|
|
Namfun_t *nv_stack(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP);
|
|
char *nv_getv(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP);
|
|
double nv_getn(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP);
|
|
void nv_putv(Namval_t *\fInp\fP, const char *\fIval\fP, int \fItype\fP, Namfun_t *\fIfp\fP);
|
|
char *nv_settrap(Namval_t *\fInp\fP, const char *\fIe\fP, Namval_t *\fIa\fP, Namfun_t *\fIfp\fP);
|
|
Namval_t *nv_create(Namval_t *\fInp\fP, const char *\fIname\fP, Namfun_t *\fIfp\fP);
|
|
|
|
void nv_newtype(Namval_t *\fInp\fP, unsigned \fItype\fP, int \fIsize\fP);
|
|
unsigned nv_istype(Namval_t *\fInp\fP, unsigned \fItype\fP);
|
|
int nv_scan(Hashtab_t *\fItable\fP, void(*\fIfn\fP)(Namval_t*,int,int));
|
|
|
|
Namarr_t *nv_setarray(Namval_t *\fInp\fP,void*(*\fIfun\fP)(Namval_t*,const char*,int));
|
|
Namval_t *nv_putsub(Namval_t *\fInp\fP, char *\fIname\fP, long \fImode\fP);
|
|
char *nv_getsub(Namval_t *\fInp\fP);
|
|
int nv_nextsub(Namval_t *\fInp\fP);
|
|
int nv_aindex(Namval_t *\fInp\fP);
|
|
void nv_setref(Namval_t *\fInp\fP);
|
|
void nv_setvtree(Namval_t *\fInp\fP);
|
|
.fR
|
|
.fi
|
|
.PP
|
|
\fBDESCRIPTION\fP
|
|
.PP
|
|
\fINval\fP is a library of functions for interacting with name-value
|
|
pairs as used in \f5ksh\fP.
|
|
It is built on top an the extensible hashing library facility
|
|
in \f5libast\fP.
|
|
Each name-value pair is represented by a
|
|
type named \f5Namval_t\fP.
|
|
A \f5Namval_t\fP contains the name, value and
|
|
attributes of a variable.
|
|
The following attributes can be associated with a name-value pair:
|
|
.IP
|
|
\f5NV_EXPORT\fP:
|
|
The export attribute.
|
|
.IP
|
|
\f5NV_RDONLY\fP:
|
|
The readonly attribute.
|
|
.IP
|
|
\f5NV_LTOU\fP:
|
|
Lower case characters are converted to upper case characters.
|
|
.IP
|
|
\f5NV_UTOL\fP:
|
|
Upper case characters are converted to lower case characters.
|
|
.IP
|
|
\f5NV_RJUST\fP:
|
|
Right justify and blank fill.
|
|
This attribute has an associated size that defines the
|
|
string length of the value.
|
|
.IP
|
|
\f5NV_LJUST\fP:
|
|
Left justify and blank fill.
|
|
This attribute has an associated size that defines the
|
|
string length of the value.
|
|
.IP
|
|
\f5NV_ZFILL\fP:
|
|
Without \f5NV_LJUST\fP, right justifies and fills with leading zeros.
|
|
With \f5NV_LJUST\fP, left justify and strip leading zeros.
|
|
Left justify and blank fill.
|
|
This attribute has an associated size that defines the
|
|
string length of the value.
|
|
.IP
|
|
\f5NV_TAGGED\fP:
|
|
Indicates the tagged attribute.
|
|
.IP
|
|
\f5NV_INTEGER\fP:
|
|
Causes value to be represented by a number.
|
|
This attribute has an associated number that defines the
|
|
arithmetic base to be used when the value is expanded as a string.
|
|
.IP
|
|
\f5NV_DOUBLE\fP:
|
|
Used in conjunction with \f5NV_INTEGER\fP to cause value
|
|
to be stored as a double precision floating point number.
|
|
This attribute has an associated number that defines the
|
|
number of places after the decimal point to be used when
|
|
the value is expanded as a string.
|
|
.IP
|
|
\f5NV_EXPNOTE\fP:
|
|
Used in conjunction with \f5NV_INTEGER\fP and \f5NV_DOUBLE\fP to
|
|
cause the value to be represented in scientific notation when
|
|
expanded as a string.
|
|
This attribute has an associated number that defines the
|
|
the precision of the mantissa.
|
|
.IP
|
|
\f5NV_REF\fP:
|
|
The name-value pair is a name reference variable.
|
|
.PP
|
|
The function \f5nv_namset()\fP returns a pointer to a name-value
|
|
pair corresponding to the given \fIname\fP.
|
|
If a name-value pair by this name does not already exist, it is
|
|
created unless \fItype\fP contains the \f5NV_NOADD\fP flag.
|
|
If the first identifier in \fIname\fP is a reference and is not
|
|
preceded by a \fB.\fP,
|
|
it will be replaced by the value of the reference
|
|
to find the name of a variable.
|
|
Unless \fItype\fP contains the \f5NV_REF\fP flag,
|
|
if the name-value pair give by \fIname\fP has the \f5NV_REF\fP
|
|
attribute, it will be replaced by the variable whose name
|
|
is the value of this name-value pair.
|
|
Unless prohibited by the \fItype\fP argument,
|
|
the \f5name\fP variable can contain an \f5=\fP
|
|
and a value that will be assigned to the name-value pair.
|
|
The argument \fItable\fP defines the table to search.
|
|
A \f5NULL\fP value causes the shell variable table to be searched.
|
|
The \fItype\fP argument consists of the bitwise-or of zero or more
|
|
of the following and zero or more of the attributes listed above.
|
|
.IP
|
|
\f5NV_VARNAME\fP:
|
|
An invalid variable name causes an error.
|
|
.IP
|
|
\f5NV_IDENTIFIER\fP:
|
|
An variable name that is not an identifier causes an error.
|
|
.IP
|
|
\f5NV_NOASSIGN\fP:
|
|
The \f5name\fP argument cannot contain an assignment.
|
|
.IP
|
|
\f5NV_ARRAY\fP:
|
|
The \f5name\fP argument cannot contain a subscript.
|
|
.IP
|
|
\f5NV_REF\fP:
|
|
Do not follow references when finding the name-value pair.
|
|
.IP
|
|
\f5NV_NOADD\fP:
|
|
The name-value pair will not be added if it doesn't exist.
|
|
Instead a \f5NULL\fP pointer will be returned.
|
|
.IP
|
|
\f5NV_NOSCOPE\fP:
|
|
Only the top level scope is used.
|
|
.PP
|
|
The \f5nv_search()\fP function returns a pointer
|
|
pointer to the name-value pair corresponding to the given name.
|
|
The \fItable\fP argument must always be specified.
|
|
The \fItype\fP argument must either be \f50\fP or \f5NV_ADD\fP.
|
|
A value of \f50\fP causes a \f5NULL\fP pointer to be returned
|
|
if the name-value pair does not already exist, whereas the value
|
|
\f5NV_ADD\fP causes the name-value pair to be created if it
|
|
does not already exist.
|
|
There is no validity check performed on the \fIname\fP argument.
|
|
.PP
|
|
The \f5nv_name()\fP function returns the name of the given name-value
|
|
pair \fInp\fP.
|
|
The \f5nv_getval()\fP function returns the value of the given
|
|
name-value pair as a string. A \f5NULL\fP return value indicates
|
|
that the name-value pair is unset.
|
|
The \f5nv_getnum()\fP function returns the value of the given
|
|
name-value pair as a double precision number.
|
|
For name-value pairs without the \f5NV_INTEGER\fP attribute,
|
|
the string value is evaluated as an arithmetic expression to
|
|
arrive at a numerical value.
|
|
.PP
|
|
The \f5nv_putval()\fP function is used to assign a \fIvalue\fP to
|
|
the name-value pair \fInp\fP.
|
|
The \fItype\fP argument consists zero or more of the bitwise-or
|
|
of \f5NV_INTEGER\fP and \f5NV_RDONLY\fP.
|
|
The presence of \f5NV_RDONLY\fP allows the assignment to occur
|
|
even if the name-value pair has the \f5NV_RDONLY\fP attribute.
|
|
The presence of \f5NV_INTEGER\fP indicates that the \fIvalue\fP
|
|
argument is actually a pointer to a double precision number
|
|
containing the value for this name-value pair.
|
|
In all cases, a copy of the value is stored as the value for
|
|
\fInp\fP.
|
|
.PP
|
|
The \f5nv_istype()\fP function can test whether or not any of
|
|
the attributes given by \fItype\fP is set.
|
|
The attribute \f5NV_ARRAY\fP can be used to test whether
|
|
or not the given name-value pair is an array.
|
|
The \f5nv_newtype()\fP function can be used to change the
|
|
attributes of the given name-value pair.
|
|
The \fIsize\fP argument is needed for attributes that require
|
|
an additional argument.
|
|
Changing the attribute may require changing the value
|
|
to agree with the new type.
|
|
For an array variable, each of the values will be changed.
|
|
.PP
|
|
A user can intercept the lookup and assignment operations by
|
|
supplying their own discipline.
|
|
A discipline is a set of functions that override the getting
|
|
and putting of values to a name-value pair.
|
|
A discipline is defined by the type
|
|
\f5Namfun_t\fP which contains the following public fields:
|
|
.nf
|
|
\f5void (*putval)();\fP
|
|
\f5char *(*getval)();\fP
|
|
\f5double (*getnum)();\fP
|
|
\f5char (*settrap)();\fP
|
|
\f5Namval_t (*create)();\fP
|
|
.fi
|
|
To create a discipline, a user creates an instance of the type
|
|
\f5Namfun_t\fP and assigns functions to one or more of these
|
|
fields. The remaining fields must be \f50\fP.
|
|
The instance must be at the beginning of a structure that contains
|
|
additional fields that are used within the discipline functions.
|
|
The discipline is installed or removed with the
|
|
\f5nv_stack()\fP function.
|
|
The \fIgetval\fP\f5()\fP discipline function is called with a pointer
|
|
to the name-value pair, \fInp\fP, and a pointer to the discipline,
|
|
\fIfp\fP.
|
|
Inside the \fIgetval\fP\f5()\fP function, the \f5nv_get()\fP function
|
|
can be used to get the value of the name-value pair that
|
|
would have resulted if the discipline were not used.
|
|
The \fIgetnum()\fP discipline is called whenever a numerical
|
|
value is needed for the name-value pair \fInp\fP.
|
|
The \fIputval\fP\f5()\fP discipline function is used to
|
|
override the assignment of values
|
|
to a name-value pair. When a name-value pair is unset, \fIputval\fP\f5()\fP
|
|
is called with \fIvalue\fP set to \f5NULL\fP.
|
|
The \f5nv_putv()\fP function is used within the \fIputval\fP\f5()\fP
|
|
to perform the assignment that would have occurred
|
|
if the discipline has not been installed.
|
|
.PP
|
|
The \fIcreate\fP\f5()\fP discipline function is called from
|
|
\f5nv_namset\fP\f5()\fP when the name-value pair for name containing a
|
|
.B \s+2.\s-2
|
|
doesn't exist.
|
|
This function is passed the name-value pointer of the longest
|
|
parent name-value pair that exists, plus the remaining string.
|
|
The \fIcreate\fP\f5()\fP discipline function
|
|
must return the created name-value pair, otherwise the default action
|
|
will be taken.
|
|
The \f5nv_create()\fP function may be called within
|
|
the \fIcreate\fP\f5()\fP
|
|
discipline function
|
|
to perform the action that would have occurred
|
|
by an earlier discipline.
|
|
.PP
|
|
The \fIsettrap\fP\f5()\fP discipline function is used in conjunction with
|
|
user defined discipline shell functions whose are of the form
|
|
\fIvarname\fP\f5.\fP\fIevent\fP.
|
|
Whenever a function whose name is of the form \fIvarname\fP\f5.\fP\fIevent\fP,
|
|
is defined the \fIsettrap\fP\f5()\fP function is invoked with the same
|
|
argument format as \f5nv_settrap\fP\f5()\fP.
|
|
If the given event \fIe\fP is known by this discipline,
|
|
then the value of the action associated without the event should be returned.
|
|
Otherwise, this discipline function
|
|
should return the value of \f5nv_settrap()\fP. The \f5nv_settrap()\fP invokes
|
|
earlier disciplines to find the given event.
|
|
If the event \fIe\fP is NULL, the \fIsettrap\fP\f5()\fP must return the
|
|
name of the trap that follows the event name given by
|
|
\fIa\fP. If \fIa\fP is also NULL, the name of the first event
|
|
must be returned.
|
|
.PP
|
|
The \f5nv_scan()\fP function is used to walk through
|
|
all name-value pairs in the table given by \fItable\fP.
|
|
If \fIfn\fP is non-zero, then this function will be executed
|
|
for each name-value pair in the table.
|
|
The number of elements in the table will be returned.
|
|
.PP
|
|
The \f5nv_aindex()\fP function returns
|
|
the current index for
|
|
the indexed array given by the name-value pair pointer \fInp\fP.
|
|
The return value is negative if \fInp\fP refers to
|
|
an associative array.
|
|
.PP
|
|
The \f5nv_setarray()\fP function is used to create an associative array
|
|
from a name-value pair node.
|
|
The function \fIfun\fP defines the semantics of the associative
|
|
array.
|
|
Using \fIfun\fP equal to \f5nv_associative()\fP implements the default
|
|
associative array semantics
|
|
that is used with \f5typeset\ -A\fP.
|
|
This function \fIfun\fP will be called with third argument as follows:
|
|
.IP
|
|
\f5NV_AINIT\fP:
|
|
This will be called at initialization.
|
|
The function you supply must return a pointer to a structure
|
|
that contains the type \f5Namarr_t\fP as the first element.
|
|
All other calls receive this value as an argument.
|
|
.IP
|
|
\f5NV_AFREE\fP:
|
|
This will be called after all elements of the name-value pair have been
|
|
deleted and the array is to be freed.
|
|
.IP
|
|
\f5NV_ADELETE\fP:
|
|
The current element should be deleted.
|
|
.IP
|
|
\f5NV_ANEXT\fP:
|
|
This means that the array subscript should be advanced to the
|
|
next subscript. A \f5NULL\fP return indicates that there are
|
|
no more subscripts.
|
|
.IP
|
|
\f5NV_ANAME\fP:
|
|
The name of the current subscript must be returned.
|
|
.PP
|
|
If \fInp\fP refers to an array,
|
|
the \f5nv_getsub()\fP returns a pointer to
|
|
the name of the current subscript.
|
|
Otherwise, \f5nv_subscript()\fP
|
|
returns \f5NULL\fP.
|
|
.PP
|
|
The \f5nv_putsub()\fP function is used to
|
|
set the subscript for the next reference to \f5np\fP.
|
|
If the \f5name\fP argument is not \f5NULL\fP,
|
|
it defines the value of the next subscript.
|
|
The \f5mode\fP argument can contain one or more of the following flags:
|
|
.IP
|
|
\f5ARRAY_ADD\fP:
|
|
Add the subscript if not found.
|
|
Otherwise, \f5nv_putsub()\fP returns \f5NULL\fP if the
|
|
given subscript is not found.
|
|
.IP
|
|
\f5ARRAY_SCAN\fP:
|
|
Begin a walk through the subscripts starting at the subscript
|
|
given by \f5name\fP if given. Otherwise,
|
|
the walk is started from the beginning.
|
|
The \f5nv_nextsub()\fP function is used to advance to the
|
|
next subscript.
|
|
It returns 0 if there are no more subscripts or if called
|
|
when not in a scan.
|
|
.IP
|
|
\f5ARRAY_UNDEF\fP:
|
|
This causes any current scan to terminate and leaves the
|
|
subscript in an undefined state.
|
|
.PP
|
|
If \f5ARRAY_ADD\fP is not given and the subscript
|
|
does not exist, a \f5NULL\fP value is returned.
|
|
.PP
|
|
The \f5nv_setref()\fP function makes the name-value pair \f5np\fP
|
|
into a reference to the variable whose name is given by
|
|
the value of \f5np\fP.
|
|
.PP
|
|
The \f5nv_setvtree()\fP function makes the name-value pair \f5np\fP
|
|
into a tree structured variable so that \f5nv_getval()\fP
|
|
will return a string containing all the names and values of
|
|
children nodes in a format that can be used in
|
|
a shell compound assignment.
|
|
.PP
|
|
\fBAUTHOR\fP
|
|
David G. Korn (dgk@research.att.com).
|