PPATH(3)

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.

# SEE ALSO

ppath_bool(3), ppath_number(3), ppath_object(3), proplib(3)

# HISTORY

The `ppath` property container path library first appeared in NetBSD 6.0.

# AUTHORS

David Young ⟨dyoung@pobox.com⟩

August 24, 2011 | NetBSD 9.0