| libucl.3 (268831) | libucl.3 (279549) |
|---|---|
| 1.TH "LIBUCL" "3" "July 26, 2014" "Libucl manual" "" | 1.TH "LIBUCL" "3" "27 December, 2014" "Libucl manual" "" |
| 2.SH NAME 3.PP 4\f[B]ucl_parser_new\f[], \f[B]ucl_parser_register_macro\f[], 5\f[B]ucl_parser_register_variable\f[], \f[B]ucl_parser_add_chunk\f[], 6\f[B]ucl_parser_add_string\f[], \f[B]ucl_parser_add_file\f[], 7\f[B]ucl_parser_get_object\f[], \f[B]ucl_parser_get_error\f[], 8\f[B]ucl_parser_free\f[], \f[B]ucl_pubkey_add\f[], 9\f[B]ucl_parser_set_filevars\f[] \- universal configuration library --- 513 unchanged lines hidden (view full) --- 523A caller should always check the type of the returned object and release 524it after using. 525.SH ITERATION FUNCTIONS 526.PP 527Iteration are used to iterate over UCL compound types: arrays and 528objects. 529Moreover, iterations could be performed over the keys with multiple 530values (implicit arrays). | 2.SH NAME 3.PP 4\f[B]ucl_parser_new\f[], \f[B]ucl_parser_register_macro\f[], 5\f[B]ucl_parser_register_variable\f[], \f[B]ucl_parser_add_chunk\f[], 6\f[B]ucl_parser_add_string\f[], \f[B]ucl_parser_add_file\f[], 7\f[B]ucl_parser_get_object\f[], \f[B]ucl_parser_get_error\f[], 8\f[B]ucl_parser_free\f[], \f[B]ucl_pubkey_add\f[], 9\f[B]ucl_parser_set_filevars\f[] \- universal configuration library --- 513 unchanged lines hidden (view full) --- 523A caller should always check the type of the returned object and release 524it after using. 525.SH ITERATION FUNCTIONS 526.PP 527Iteration are used to iterate over UCL compound types: arrays and 528objects. 529Moreover, iterations could be performed over the keys with multiple 530values (implicit arrays). |
| 531To iterate over an object, an array or a key with multiple values there 532is a function \f[C]ucl_iterate_object\f[]. | 531There are two types of iterators API: old and unsafe one via 532\f[C]ucl_iterate_object\f[] and the proposed interface of safe 533iterators. |
| 533.SS ucl_iterate_object 534.IP 535.nf 536\f[C] 537const\ ucl_object_t*\ ucl_iterate_object\ (const\ ucl_object_t\ *obj,\ 538\ \ \ \ ucl_object_iter_t\ *iter,\ bool\ expand_values); 539\f[] 540.fi --- 32 unchanged lines hidden (view full) --- 573\ \ \ \ /*\ Iterate\ over\ the\ values\ of\ a\ key\ */ 574\ \ \ \ while\ ((cur\ =\ ucl_iterate_object\ (obj,\ &it_obj,\ false)))\ { 575\ \ \ \ \ \ \ \ printf\ ("value:\ \\"%s\\"\\n",\ 576\ \ \ \ \ \ \ \ \ \ \ \ ucl_object_tostring_forced\ (cur)); 577\ \ \ \ } 578} 579\f[] 580.fi | 534.SS ucl_iterate_object 535.IP 536.nf 537\f[C] 538const\ ucl_object_t*\ ucl_iterate_object\ (const\ ucl_object_t\ *obj,\ 539\ \ \ \ ucl_object_iter_t\ *iter,\ bool\ expand_values); 540\f[] 541.fi --- 32 unchanged lines hidden (view full) --- 574\ \ \ \ /*\ Iterate\ over\ the\ values\ of\ a\ key\ */ 575\ \ \ \ while\ ((cur\ =\ ucl_iterate_object\ (obj,\ &it_obj,\ false)))\ { 576\ \ \ \ \ \ \ \ printf\ ("value:\ \\"%s\\"\\n",\ 577\ \ \ \ \ \ \ \ \ \ \ \ ucl_object_tostring_forced\ (cur)); 578\ \ \ \ } 579} 580\f[] 581.fi |
| 582.SS Safe iterators API 583.PP 584Safe iterators are defined to clarify iterating over UCL objects and 585simplify flattening of UCL objects in non\-trivial cases. 586For example, if there is an implicit array that contains another array 587and a boolean value it is extremely unclear how to iterate over such an 588object. 589Safe iterators are desinged to define two sorts of iteration: 590.IP "1." 3 591Iteration over complex objects with expanding all values 592.IP "2." 3 593Iteration over complex objects without expanding of values 594.PP 595The following example demonstrates the difference between these two 596types of iteration: 597.IP 598.nf 599\f[C] 600key\ =\ 1; 601key\ =\ [2,\ 3,\ 4]; 602 603Iteration\ with\ expansion: 604 6051,\ 2,\ 3,\ 4 606 607Iteration\ without\ expansion: 608 6091,\ [2,\ 3,\ 4] 610\f[] 611.fi 612.PP 613UCL defines the following functions to manage safe iterators: 614.IP \[bu] 2 615\f[C]ucl_object_iterate_new\f[] \- creates new safe iterator 616.IP \[bu] 2 617\f[C]ucl_object_iterate_reset\f[] \- resets iterator to a new object 618.IP \[bu] 2 619\f[C]ucl_object_iterate_safe\f[] \- safely iterate the object inside 620iterator 621.IP \[bu] 2 622\f[C]ucl_object_iterate_free\f[] \- free memory associated with the safe 623iterator 624.PP 625Please note that unlike unsafe iterators, safe iterators \f[I]must\f[] 626be explicitly initialized and freed. 627An assert is likely generated if you use uninitialized or \f[C]NULL\f[] 628iterator in all safe iterators functions. 629.IP 630.nf 631\f[C] 632ucl_object_iter_t\ it; 633const\ ucl_object_t\ *cur; 634 635it\ =\ ucl_object_iterate_new\ (obj); 636 637while\ ((cur\ =\ ucl_object_iterate_safe\ (it,\ true))\ !=\ NULL)\ { 638\ \ \ \ /*\ Do\ something\ */ 639} 640 641/*\ Switch\ to\ another\ object\ */ 642it\ =\ ucl_object_iterate_reset\ (it,\ another_obj); 643 644while\ ((cur\ =\ ucl_object_iterate_safe\ (it,\ true))\ !=\ NULL)\ { 645\ \ \ \ /*\ Do\ something\ else\ */ 646} 647 648ucl_object_iterate_free\ (it); 649\f[] 650.fi |
|
| 581.SH VALIDATION FUNCTIONS 582.PP 583Currently, there is only one validation function called 584\f[C]ucl_object_validate\f[]. 585It performs validation of object using the specified schema. 586This function is defined as following: 587.SS ucl_object_validate 588.IP --- 50 unchanged lines hidden --- | 651.SH VALIDATION FUNCTIONS 652.PP 653Currently, there is only one validation function called 654\f[C]ucl_object_validate\f[]. 655It performs validation of object using the specified schema. 656This function is defined as following: 657.SS ucl_object_validate 658.IP --- 50 unchanged lines hidden --- |