Version 3.1.0
WT_CONFIG_PARSER Struct Reference

A handle that can be used to search and traverse configuration strings compatible with WiredTiger APIs. More...

Public Member Functions

int close (WT_CONFIG_PARSER *config_parser)
 Close the configuration scanner releasing any resources. More...
 
int next (WT_CONFIG_PARSER *config_parser, WT_CONFIG_ITEM *key, WT_CONFIG_ITEM *value)
 Return the next key/value pair. More...
 
int get (WT_CONFIG_PARSER *config_parser, const char *key, WT_CONFIG_ITEM *value)
 Return the value of an item in the configuration string. More...
 

Detailed Description

A handle that can be used to search and traverse configuration strings compatible with WiredTiger APIs.

To parse the contents of a list or nested configuration string use a new configuration parser handle based on the content of the WT_CONFIG_ITEM retrieved from the parent configuration string.

Configuration String Parsing examples

This could be used in C to create a configuration parser as follows:

const char *config_string =
"path=/dev/loop,page_size=1024,log=(archive=true,file_max=20MB)";
NULL, config_string, strlen(config_string), &parser));
error_check(parser->close(parser));

Once the parser has been created the content can be queried directly:

int64_t my_page_size;
/*
* Retrieve the value of the integer configuration string "page_size".
*/
error_check(parser->get(parser, "page_size", &v));
my_page_size = v.val;

Or the content can be traversed linearly:

/*
* Retrieve and print the values of the configuration strings.
*/
while ((ret = parser->next(parser, &k, &v)) == 0) {
printf("%.*s:", (int)k.len, k.str);
if (v.type == WT_CONFIG_ITEM_NUM)
printf("%" PRId64 "\n", v.val);
else
printf("%.*s\n", (int)v.len, v.str);
}
scan_end_check(ret == WT_NOTFOUND);

Nested configuration values can be queried using a shorthand notation:

/*
* Retrieve the value of the nested log file_max configuration string
* using dot shorthand. Utilize the configuration parsing automatic
* conversion of value strings into an integer.
*/
v.type = WT_CONFIG_ITEM_NUM;
error_check(parser->get(parser, "log.file_max", &v));
printf("log file max: %" PRId64 "\n", v.val);

Nested configuration values can be traversed using multiple WT_CONFIG_PARSER handles:

{
WT_CONFIG_PARSER *sub_parser;
while ((ret = parser->next(parser, &k, &v)) == 0) {
if (v.type == WT_CONFIG_ITEM_STRUCT) {
printf("Found nested configuration: %.*s\n",
(int)k.len, k.str);
NULL, v.str, v.len, &sub_parser));
while ((ret =
sub_parser->next(sub_parser, &k, &v)) == 0)
printf("\t%.*s\n", (int)k.len, k.str);
scan_end_check(ret == WT_NOTFOUND);
error_check(sub_parser->close(sub_parser));
}
}
scan_end_check(ret == WT_NOTFOUND);
Examples:
ex_file_system.c.

Member Function Documentation

◆ close()

int WT_CONFIG_PARSER::close ( WT_CONFIG_PARSER config_parser)

Close the configuration scanner releasing any resources.

Parameters
config_parserthe configuration parser handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples:
ex_file_system.c.

◆ get()

int WT_CONFIG_PARSER::get ( WT_CONFIG_PARSER config_parser,
const char *  key,
WT_CONFIG_ITEM value 
)

Return the value of an item in the configuration string.

Parameters
config_parserthe configuration parser handle
keyconfiguration key string
valuethe returned value
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ next()

int WT_CONFIG_PARSER::next ( WT_CONFIG_PARSER config_parser,
WT_CONFIG_ITEM key,
WT_CONFIG_ITEM value 
)

Return the next key/value pair.

If an item has no explicitly assigned value, the item will be returned in key and the value will be set to the boolean "true" value.

Parameters
config_parserthe configuration parser handle
keythe returned key
valuethe returned value
Returns
zero on success and a non-zero error code on failure. See Error handling for details. When iteration would pass the end of the configuration string WT_NOTFOUND will be returned.
Examples:
ex_file_system.c.