1.\" $NetBSD: ppath.3,v 1.3 2012/12/29 20:08:23 christos Exp $ 2.\" 3.\" Copyright (c) 2011 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by David Young <dyoung@NetBSD.org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS 19.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 20.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY 22.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 24.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 26.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 27.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 28.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd August 24, 2011 31.Dt PPATH 3 32.Os 33.Sh NAME 34.Nm ppath , 35.Nm ppath_idx , 36.Nm ppath_key , 37.\" , 38.Nm ppath_component_retain , 39.Nm ppath_component_release , 40.\" , 41.Nm ppath_create , 42.Nm ppath_length , 43.Nm ppath_component_idx , 44.Nm ppath_component_key , 45.Nm ppath_pop , 46.Nm ppath_push , 47.Nm ppath_component_at , 48.Nm ppath_subpath , 49.Nm ppath_push_idx , 50.Nm ppath_push_key , 51.Nm ppath_replace_idx , 52.Nm ppath_replace_key , 53.\" , 54.Nm ppath_copy , 55.Nm ppath_retain , 56.Nm ppath_release , 57.\" , 58.Nm ppath_lookup , 59.\" , 60.Nd property container path library 61.Sh LIBRARY 62.Lb libppath 63.Sh SYNOPSIS 64.In ppath/ppath.h 65.\" 66.Ft "ppath_component_t *" 67.Fn ppath_idx "unsigned int index" 68.Ft "ppath_component_t *" 69.Fn ppath_key "const char *key" 70.\" 71.Ft "ppath_component_t *" 72.Fn ppath_component_retain "ppath_component_t *pc" 73.Ft void 74.Fn ppath_component_release "ppath_component_t *pc" 75.\" 76.Ft "ppath_t *" 77.Fn ppath_create "void" 78.Ft "unsigned int" 79.Fn ppath_length "const ppath_t *p" 80.Ft int 81.Fn ppath_component_idx "const ppath_component_t *" 82.Ft const char * 83.Fn ppath_component_key "const ppath_component_t *" 84.Ft "ppath_t *" 85.Fn ppath_pop "ppath_t *" "ppath_component_t **" 86.Ft ppath_t * 87.Fn ppath_push "ppath_t *" "ppath_component_t *" 88.Ft ppath_component_t * 89.Fn ppath_component_at "const ppath_t *" "unsigned int" 90.Ft ppath_t * 91.Fn ppath_subpath "const ppath_t *" "unsigned int" "unsigned int" 92.Ft ppath_t * 93.Fn ppath_push_idx "ppath_t *" "unsigned int" 94.Ft ppath_t * 95.Fn ppath_push_key "ppath_t *" "const char *" 96.Ft ppath_t * 97.Fn ppath_replace_idx "ppath_t *" "unsigned int" 98.Ft ppath_t * 99.Fn ppath_replace_key "ppath_t *" "const char *" 100.\" 101.Ft ppath_t * 102.Fn ppath_copy "const ppath_t *" 103.Ft ppath_t * 104.Fn ppath_retain "ppath_t *" 105.Ft void 106.Fn ppath_release "ppath_t *" 107.\" 108.Ft prop_object_t 109.Fn ppath_lookup "prop_object_t" "const ppath_t *" 110.\" 111.Sh DESCRIPTION 112The 113.Nm 114library provides functions to read, write, or delete objects in a 115property list. 116A property-list 117.Dq path 118names the object in a property list to read, write, or delete. 119.Pp 120A property-list path is an ordered array of zero or more array 121indices and dictionary keys that names at most one 122.Vt prop_object_t 123in a property list. 124The abstract function 125.Fn E 126evaluates 127a property-list path against a 128.Vt prop_object_t , 129.Va o , 130to yield a 131.Vt prop_object_t 132result according to the following recursive definition, where 133.Fa empty 134indicates the empty 135.Pq zero-length 136path and the operator 137.Dq | 138indicates the concatenation of the path on the left-hand side with 139the key or index on the right-hand side: 140.Bl -tag -width "E(o, p | index)" 141.It Fn E "o" "empty" 142Evaluates to 143.Fa o . 144.It Fn E "o" "p | index" 145If 146.Fn E "o" "p" 147evaluates to a 148.Vt prop_array_t , 149then 150.Fn E "o" "p | index" 151evaluates to the 152.Fa index 'th 153element of that array. 154Otherwise, an error occurs. 155.It Fn E "o" "p | key" 156If 157.Fn E "o" "p" 158evaluates to a 159.Vt prop_dictionary_t , 160then 161.Fn E "o" "p | key" 162evaluates to the dictionary value stored under 163.Fa key . 164Otherwise, an error occurs. 165.El 166.Pp 167The programmer may think of property-list paths as working similarly 168to paths in a file system, where property arrays and dictionaries 169correspond to directories, and all other property types correspond 170to files. 171.Sh DATA TYPES 172.Nm 173provides two opaque types: 174.Bl -tag -width ppath_component 175.It Vt ppath_component_t 176A property-list path component: a single key or index. 177.Nm 178counts references to a 179.Vt ppath_component_t 180and reclaims its storage when there are no more references. 181.It Vt ppath_t 182An array of zero or more property-list path components. 183.Nm 184counts references to a 185.Vt ppath_t 186and reclaims its storage when there are no more references. 187.El 188.Sh FUNCTIONS 189.Nm 190provides these functions for manipulating property-list paths 191and their components: 192.Bl -tag -width ppath 193.It Fn ppath_idx "unsigned int index" 194Allocate a new 195.Vt ppath_component_t 196for the given array index and return it. 197Its reference count is initially one. 198.Pp 199If there is not sufficient memory to complete the request, return 200.Dv NULL . 201.It Fn ppath_key "const char *key" 202Allocate a new 203.Vt ppath_component_t 204for the given dictionary key and return it. 205Its reference count is initially one. 206.Pp 207If there is not sufficient memory to complete the request, return 208.Dv NULL . 209.\" 210.It Fn ppath_component_retain "ppath_component_t *pc" 211Increase the reference count on 212.Fa pc 213by one. 214.It Fn ppath_component_release "ppath_component_t *pc" 215Decrease the reference count on 216.Fa pc 217by one. 218If the reference count reaches zero, reclaim the storage 219for 220.Fa pc . 221.\" 222.It Fn ppath_create "void" 223Create a new property-list path and return it. 224Its reference count is initially one. 225The path's length is initially zero. 226.Pp 227If there is not sufficient memory to complete the request, return 228.Dv NULL . 229.It Fn ppath_length "const ppath_t *p" 230Return the number of components in path 231.Fa p . 232.It Fn ppath_component_idx "const ppath_component_t *pc" 233Return the array index represented by the component 234.Fa pc , 235or \-1 if 236.Fa pc 237does not represent an array index. 238.It Fn ppath_component_key "const ppath_component_t *pc" 239Return the dictionary key represented by the component 240.Fa pc , 241or 242.Dv NULL 243if 244.Fa pc 245does not represent a dictionary key. 246.It Fn ppath_pop "ppath_t *p" "ppath_component_t **pcp" 247If 248.Fa p 249is the empty path or 250.Dv NULL , 251return 252.Dv NULL . 253Otherwise, remove the last component from 254.Fa p 255and return 256.Fa p , 257and if 258.Fa pcp 259is not 260.Dv NULL , 261write the removed component to 262.Fa "*pcp" . 263.It Fn ppath_push "ppath_t *p" "ppath_component_t *pc" 264If 265either 266.Fa p 267is 268.Dv NULL 269or no more components can be added to 270.Fa p , 271return 272.Dv NULL . 273Otherwise, append 274.Fa pc 275to the end of the component array 276.Fa p 277and return 278.Fa p . 279.It Fn ppath_component_at "const ppath_t *p" "unsigned int i" 280If 281either 282.Fa p 283is 284.Dv NULL 285or there is no 286.Fa ith 287component to 288.Fa p , 289return 290.Dv NULL . 291Otherwise, return the 292.Fa ith 293component of 294.Fa p . 295Before returning a component, 296.Fn ppath_component_at 297increases its reference count. 298.Po 299The first component is 0. 300.Pc 301.It Fn ppath_subpath "const ppath_t *p" "unsigned int first" "unsigned int exclast" 302Create a new 303.Vt ppath_t 304and fill it with components 305.Fa first 306to 307.Fa exclast 308.Pq exclusive 309of 310.Fa p . 311If there are no such components as those in 312.Fa p , 313.Fn ppath_subpath 314returns an empty 315.Vt ppath_t . 316If there is insufficient memory to create the new path, or if 317.Fa p 318is 319.Dv NULL , 320return 321.Dv NULL . 322Otherwise, return the new path. 323.It Fn ppath_push_idx "ppath_t *p" "unsigned int idx" 324Append an array index, 325.Fa idx , 326to the end of path 327.Fa p . 328If 329.Fa p 330is 331.Dv NULL , 332or if there is insufficient memory to complete the operation, 333return 334.Dv NULL . 335Otherwise, return 336.Fa p . 337.It Fn ppath_push_key "ppath_t *" "const char *key" 338Append a dictionary key, 339.Fa key , 340to the end of path 341.Fa p . 342If 343.Fa p 344is 345.Dv NULL , 346or if there is insufficient memory to complete the operation, 347return 348.Dv NULL . 349Otherwise, return 350.Fa p . 351.It Fn ppath_replace_idx "ppath_t *p" "unsigned int idx" 352Replace the array index at the end of path 353.Fa p 354with the array index 355.Fa idx . 356If 357.Fa p 358is 359.Dv NULL , 360if the last component of 361.Fa p 362is not an array index, 363or if there is insufficient memory to complete the operation, 364return 365.Dv NULL . 366Otherwise, return 367.Fa p . 368.It Fn ppath_replace_key "ppath_t *p" "const char *key" 369Replace the dictionary key at the end of path 370.Fa p 371with the dictionary key 372.Fa idx . 373If 374.Fa p 375is 376.Dv NULL , 377if the last component of 378.Fa p 379is not a dictionary key, 380or if there is insufficient memory to complete the operation, 381return 382.Dv NULL . 383Otherwise, return 384.Fa p . 385.\" 386.It Fn ppath_copy "const ppath_t *p" 387Create a copy of path 388.Fa p . 389If 390.Fa p 391is 392.Dv NULL , 393or if there is insufficient memory to complete the operation, 394return 395.Dv NULL . 396Otherwise, return the copy, whose reference count will be one. 397.It Fn ppath_retain "ppath_t *p" 398Increase the reference count on 399.Fa p 400and return 401.Fa p . 402.It Fn ppath_release "ppath_t *p" 403Decrease the reference count on 404.Fa p . 405Reclaim the storage for 406.Fa p 407if the reference count reaches zero. 408.\" 409.It Fn ppath_lookup "prop_object_t o" "const ppath_t *p" 410Return the 411.Vt prop_object_t 412under 413.Fa o 414named by 415.Fa p , 416or return 417.Dv NULL 418if no such 419.Vt prop_object_t 420is under 421.Fa o . 422.El 423.Sh SEE ALSO 424.\" Cross-references should be ordered by section (low to high), then in 425.\" alphabetical order. 426.Xr ppath_bool 3 , 427.Xr ppath_data 3 , 428.Xr ppath_number 3 , 429.Xr ppath_object 3 , 430.Xr ppath_string 3 , 431.Xr proplib 3 432.Sh HISTORY 433The 434.Nm 435property container path library first appeared in 436.Nx 6.0 . 437.Sh AUTHORS 438.An David Young 439.Aq dyoung@pobox.com 440.\" .Sh CAVEATS 441.\" .Sh BUGS 442.\" .Sh SECURITY CONSIDERATIONS 443