PPATH(3) |
Library Functions Manual |
PPATH(3) |
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.
HISTORY
The ppath property container path library first appeared in NetBSD 6.0.
AUTHORS
David Young <dyoung@pobox.com>