NAME
ppath,
ppath_idx,
ppath_key,
ppath_component_retain,
ppath_component_release,
ppath_create,
ppath_length,
ppath_component_idx,
ppath_component_key,
ppath_pop,
ppath_push,
ppath_component_at,
ppath_subpath,
ppath_push_idx,
ppath_push_key,
ppath_replace_idx,
ppath_replace_key,
ppath_copy,
ppath_retain,
ppath_release,
ppath_lookup, —
property container
path library
LIBRARY
Property-List Paths Library (libppath, -lppath)
SYNOPSIS
#include <ppath/ppath.h>
ppath_component_t *
ppath_idx(
unsigned
int index);
ppath_component_t *
ppath_key(
const
char *key);
ppath_component_t *
ppath_component_retain(
ppath_component_t
*pc);
void
ppath_component_release(
ppath_component_t
*pc);
ppath_t *
ppath_create(
void);
unsigned int
ppath_length(
const
ppath_t *p);
int
ppath_component_idx(
const
ppath_component_t *);
const char *
ppath_component_key(
const
ppath_component_t *);
ppath_t *
ppath_pop(
ppath_t
*,
ppath_component_t
**);
ppath_t *
ppath_push(
ppath_t
*,
ppath_component_t
*);
ppath_component_t *
ppath_component_at(
const
ppath_t *,
unsigned
int);
ppath_t *
ppath_subpath(
const
ppath_t *,
unsigned
int,
unsigned int);
ppath_t *
ppath_push_idx(
ppath_t
*,
unsigned int);
ppath_t *
ppath_push_key(
ppath_t
*,
const char *);
ppath_t *
ppath_replace_idx(
ppath_t
*,
unsigned int);
ppath_t *
ppath_replace_key(
ppath_t
*,
const char *);
ppath_t *
ppath_copy(
const
ppath_t *);
ppath_t *
ppath_retain(
ppath_t
*);
void
ppath_release(
ppath_t
*);
prop_object_t
ppath_lookup(
prop_object_t,
const ppath_t *);
DESCRIPTION
The
ppath library provides functions to read, write, or delete
objects in a property list. A property-list “path” names the
object in a property list to read, write, or delete.
A property-list path is an ordered array of zero or more array indices and
dictionary keys that names at most one
prop_object_t in
a property list. The abstract function
E() evaluates a
property-list path against a
prop_object_t,
o, to yield a
prop_object_t result
according to the following recursive definition, where
empty indicates the empty (zero-length) path and the
operator “|” indicates the concatenation of the path on the
left-hand side with the key or index on the right-hand side:
-
-
- E(o,
empty)
- Evaluates to o.
-
-
- E(o,
p | index)
- If E(o,
p) evaluates to a
prop_array_t, then
E(o, p |
index) evaluates to the index 'th element of
that array. Otherwise, an error occurs.
-
-
- E(o,
p | key)
- If E(o,
p) evaluates to a
prop_dictionary_t, then
E(o, p |
key) evaluates to the dictionary value stored under
key. Otherwise, an error occurs.
The programmer may think of property-list paths as working similarly to paths in
a file system, where property arrays and dictionaries correspond to
directories, and all other property types correspond to files.
DATA TYPES
ppath provides two opaque types:
-
-
- ppath_component_t
- A property-list path component: a single key or index.
ppath counts references to a
ppath_component_t and reclaims its storage when
there are no more references.
-
-
- ppath_t
- An array of zero or more property-list path components.
ppath counts references to a
ppath_t and reclaims its storage when there are no
more references.
FUNCTIONS
ppath provides these functions for manipulating property-list
paths and their components:
-
-
- ppath_idx(unsigned
int index)
- Allocate a new ppath_component_t for
the given array index and return it. Its reference count is initially one.
If there is not sufficient memory to complete the request, return
NULL
.
-
-
- ppath_key(const
char *key)
- Allocate a new ppath_component_t for
the given dictionary key and return it. Its reference count is initially
one.
If there is not sufficient memory to complete the request, return
NULL
.
-
-
- ppath_component_retain(ppath_component_t
*pc)
- Increase the reference count on pc by
one.
-
-
- ppath_component_release(ppath_component_t
*pc)
- Decrease the reference count on pc by
one. If the reference count reaches zero, reclaim the storage for
pc.
-
-
- ppath_create(void)
- Create a new property-list path and return it. Its
reference count is initially one. The path's length is initially zero.
If there is not sufficient memory to complete the request, return
NULL
.
-
-
- ppath_length(const
ppath_t *p)
- Return the number of components in path
p.
-
-
- ppath_component_idx(const
ppath_component_t *pc)
- Return the array index represented by the component
pc, or -1 if pc does not
represent an array index.
-
-
- ppath_component_key(const
ppath_component_t *pc)
- Return the dictionary key represented by the component
pc, or
NULL
if
pc does not represent a dictionary key.
-
-
- ppath_pop(ppath_t
*p, ppath_component_t **pcp)
- If p is the empty path or
NULL
, return NULL
.
Otherwise, remove the last component from p and
return p, and if pcp is not
NULL
, write the removed component to
*pcp.
-
-
- ppath_push(ppath_t
*p, ppath_component_t *pc)
- If either p is
NULL
or no more components can be added to
p, return NULL
. Otherwise,
append pc to the end of the component array
p and return p.
-
-
- ppath_component_at(const
ppath_t *p, unsigned int i)
- If either p is
NULL
or there is no ith
component to p, return NULL
.
Otherwise, return the ith component of
p. Before returning a component,
ppath_component_at() increases its reference count. (The
first component is 0.)
-
-
- ppath_subpath(const
ppath_t *p, unsigned int first,
unsigned int exclast)
- Create a new ppath_t and fill it with
components first to exclast
(exclusive) of p. If there are no such components as
those in p, ppath_subpath()
returns an empty ppath_t. If there is insufficient
memory to create the new path, or if p is
NULL
, return NULL
.
Otherwise, return the new path.
-
-
- ppath_push_idx(ppath_t
*p, unsigned int idx)
- Append an array index, idx, to the
end of path p. If p is
NULL
, or if there is insufficient memory to
complete the operation, return NULL
. Otherwise,
return p.
-
-
- ppath_push_key(ppath_t
*, const char *key)
- Append a dictionary key, key, to the
end of path p. If p is
NULL
, or if there is insufficient memory to
complete the operation, return NULL
. Otherwise,
return p.
-
-
- ppath_replace_idx(ppath_t
*p, unsigned int idx)
- Replace the array index at the end of path
p with the array index idx. If
p is
NULL
, if the last
component of p is not an array index, or if there is
insufficient memory to complete the operation, return
NULL
. Otherwise, return
p.
-
-
- ppath_replace_key(ppath_t
*p, const char *key)
- Replace the dictionary key at the end of path
p with the dictionary key idx.
If p is
NULL
, if the last
component of p is not a dictionary key, or if there
is insufficient memory to complete the operation, return
NULL
. Otherwise, return
p.
-
-
- ppath_copy(const
ppath_t *p)
- Create a copy of path p. If
p is
NULL
, or if there is
insufficient memory to complete the operation, return
NULL
. Otherwise, return the copy, whose reference
count will be one.
-
-
- ppath_retain(ppath_t
*p)
- Increase the reference count on p and
return p.
-
-
- ppath_release(ppath_t
*p)
- Decrease the reference count on p.
Reclaim the storage for p if the reference count
reaches zero.
-
-
- ppath_lookup(prop_object_t
o, const ppath_t *p)
- Return the prop_object_t under
o named by p, or return
NULL
if no such
prop_object_t is under o.
SEE ALSO
ppath_bool(3),
ppath_data(3),
ppath_number(3),
ppath_object(3),
ppath_string(3),
proplib(3)
HISTORY
The
ppath property container path library first appeared in
NetBSD 6.0.
AUTHORS
David Young ⟨dyoung@pobox.com⟩