zconfig(3)
==========

NAME
----
zconfig - work with config files written in rfc.zeromq.org/spec:4/ZPL.

SYNOPSIS
--------
----
//  This is a stable class, and may not change except for emergencies. It
//  is provided in stable builds.
// 
typedef int (zconfig_fct) (
    zconfig_t *self, void *arg, int level);

//  Create new config item
CZMQ_EXPORT zconfig_t *
    zconfig_new (const char *name, zconfig_t *parent);

//  Load a config tree from a specified ZPL text file; returns a zconfig_t  
//  reference for the root, if the file exists and is readable. Returns NULL
//  if the file does not exist.                                             
CZMQ_EXPORT zconfig_t *
    zconfig_load (const char *filename);

//  Equivalent to zconfig_load, taking a format string instead of a fixed
//  filename.                                                            
CZMQ_EXPORT zconfig_t *
    zconfig_loadf (const char *format, ...) CHECK_PRINTF (1);

//  Destroy a config item and all its children
CZMQ_EXPORT void
    zconfig_destroy (zconfig_t **self_p);

//  Return name of config item
CZMQ_EXPORT char *
    zconfig_name (zconfig_t *self);

//  Return value of config item
CZMQ_EXPORT char *
    zconfig_value (zconfig_t *self);

//  Insert or update configuration key with value
CZMQ_EXPORT void
    zconfig_put (zconfig_t *self, const char *path, const char *value);

//  Equivalent to zconfig_put, accepting a format specifier and variable
//  argument list, instead of a single string value.                    
CZMQ_EXPORT void
    zconfig_putf (zconfig_t *self, const char *path, const char *format, ...) CHECK_PRINTF (3);

//  Get value for config item into a string value; leading slash is optional
//  and ignored.                                                            
CZMQ_EXPORT char *
    zconfig_get (zconfig_t *self, const char *path, const char *default_value);

//  Set config item name, name may be NULL
CZMQ_EXPORT void
    zconfig_set_name (zconfig_t *self, const char *name);

//  Set new value for config item. The new value may be a string, a printf  
//  format, or NULL. Note that if string may possibly contain '%', or if it 
//  comes from an insecure source, you must use '%s' as the format, followed
//  by the string.                                                          
CZMQ_EXPORT void
    zconfig_set_value (zconfig_t *self, const char *format, ...) CHECK_PRINTF (2);

//  Find our first child, if any
CZMQ_EXPORT zconfig_t *
    zconfig_child (zconfig_t *self);

//  Find our first sibling, if any
CZMQ_EXPORT zconfig_t *
    zconfig_next (zconfig_t *self);

//  Find a config item along a path; leading slash is optional and ignored.
CZMQ_EXPORT zconfig_t *
    zconfig_locate (zconfig_t *self, const char *path);

//  Locate the last config item at a specified depth
CZMQ_EXPORT zconfig_t *
    zconfig_at_depth (zconfig_t *self, int level);

//  Execute a callback for each config item in the tree; returns zero if
//  successful, else -1.                                                
CZMQ_EXPORT int
    zconfig_execute (zconfig_t *self, zconfig_fct handler, void *arg);

//  Add comment to config item before saving to disk. You can add as many
//  comment lines as you like. If you use a null format, all comments are
//  deleted.                                                             
CZMQ_EXPORT void
    zconfig_set_comment (zconfig_t *self, const char *format, ...) CHECK_PRINTF (2);

//  Return comments of config item, as zlist.
CZMQ_EXPORT zlist_t *
    zconfig_comments (zconfig_t *self);

//  Save a config tree to a specified ZPL text file, where a filename
//  "-" means dump to standard output.                               
CZMQ_EXPORT int
    zconfig_save (zconfig_t *self, const char *filename);

//  Equivalent to zconfig_save, taking a format string instead of a fixed
//  filename.                                                            
CZMQ_EXPORT int
    zconfig_savef (zconfig_t *self, const char *format, ...) CHECK_PRINTF (2);

//  Report filename used during zconfig_load, or NULL if none
CZMQ_EXPORT const char *
    zconfig_filename (zconfig_t *self);

//  Reload config tree from same file that it was previously loaded from.
//  Returns 0 if OK, -1 if there was an error (and then does not change  
//  existing data).                                                      
CZMQ_EXPORT int
    zconfig_reload (zconfig_t **self_p);

//  Load a config tree from a memory chunk
CZMQ_EXPORT zconfig_t *
    zconfig_chunk_load (zchunk_t *chunk);

//  Save a config tree to a new memory chunk
CZMQ_EXPORT zchunk_t *
    zconfig_chunk_save (zconfig_t *self);

//  Load a config tree from a null-terminated string
//  Caller owns return value and must destroy it when done.
CZMQ_EXPORT zconfig_t *
    zconfig_str_load (const char *string);

//  Save a config tree to a new null terminated string
//  Caller owns return value and must destroy it when done.
CZMQ_EXPORT char *
    zconfig_str_save (zconfig_t *self);

//  Return true if a configuration tree was loaded from a file and that
//  file has changed in since the tree was loaded.                     
CZMQ_EXPORT bool
    zconfig_has_changed (zconfig_t *self);

//  Print the config file to open stream
CZMQ_EXPORT void
    zconfig_fprint (zconfig_t *self, FILE *file);

//  Print properties of object
CZMQ_EXPORT void
    zconfig_print (zconfig_t *self);

//  Self test of this class
CZMQ_EXPORT void
    zconfig_test (bool verbose);

----

DESCRIPTION
-----------

Lets applications load, work with, and save configuration files.
This implements rfc.zeromq.org/spec:4/ZPL, which is a simple structured
text format for configuration files.

Here is an example ZPL stream and corresponding config structure:

    context
        iothreads = 1
        verbose = 1      #   Ask for a trace
    main
        type = zqueue    #  ZMQ_DEVICE type
        frontend
            option
                hwm = 1000
                swap = 25000000     #  25MB
            bind = 'inproc://addr1'
            bind = 'ipc://addr2'
        backend
            bind = inproc://addr3

    root                    Down = child
    |                     Across = next
    v
    context-->main
    |         |
    |         v
    |       type=queue-->frontend-->backend
    |                      |          |
    |                      |          v
    |                      |        bind=inproc://addr3
    |                      v
    |                    option-->bind=inproc://addr1-->bind=ipc://addr2
    |                      |
    |                      v
    |                    hwm=1000-->swap=25000000
    v
    iothreads=1-->verbose=false

EXAMPLE
-------
.From zconfig_test method
----
//  Create temporary directory for test files
#   define TESTDIR ".test_zconfig"
zsys_dir_create (TESTDIR);

zconfig_t *root = zconfig_new ("root", NULL);
assert (root);
zconfig_t *section, *item;

section = zconfig_new ("headers", root);
assert (section);
item = zconfig_new ("email", section);
assert (item);
zconfig_set_value (item, "some@random.com");
item = zconfig_new ("name", section);
assert (item);
zconfig_set_value (item, "Justin Kayce");
zconfig_putf (root, "/curve/secret-key", "%s", "Top Secret");
zconfig_set_comment (root, "   CURVE certificate");
zconfig_set_comment (root, "   -----------------");
assert (zconfig_comments (root));
zconfig_save (root, TESTDIR "/test.cfg");
zconfig_destroy (&root);
root = zconfig_load (TESTDIR "/test.cfg");
if (verbose)
    zconfig_save (root, "-");
assert (streq (zconfig_filename (root), TESTDIR "/test.cfg"));

char *email = zconfig_get (root, "/headers/email", NULL);
assert (email);
assert (streq (email, "some@random.com"));
char *passwd = zconfig_get (root, "/curve/secret-key", NULL);
assert (passwd);
assert (streq (passwd, "Top Secret"));

zconfig_savef (root, "%s/%s", TESTDIR, "test.cfg");
assert (!zconfig_has_changed (root));
int rc = zconfig_reload (&root);
assert (rc == 0);
assert (!zconfig_has_changed (root));
zconfig_destroy (&root);

//  Test chunk load/save
root = zconfig_new ("root", NULL);
assert (root);
section = zconfig_new ("section", root);
assert (section);
item = zconfig_new ("value", section);
assert (item);
zconfig_set_value (item, "somevalue");
zconfig_t *search = zconfig_locate (root, "section/value");
assert (search == item);
zchunk_t *chunk = zconfig_chunk_save (root);
assert (strlen ((char *) zchunk_data (chunk)) == 32);
char *string = zconfig_str_save (root);
assert (string);
assert (streq (string, (char *) zchunk_data (chunk)));
free (string);
assert (chunk);
zconfig_destroy (&root);

root = zconfig_chunk_load (chunk);
assert (root);
char *value = zconfig_get (root, "/section/value", NULL);
assert (value);
assert (streq (value, "somevalue"));

//  Test config can't be saved to a file in a path that doesn't
//  exist or isn't writable
rc = zconfig_savef (root, "%s/path/that/doesnt/exist/%s", TESTDIR, "test.cfg");
assert (rc == -1);

zconfig_destroy (&root);
zchunk_destroy (&chunk);

//  Delete all test files
zdir_t *dir = zdir_new (TESTDIR, NULL);
assert (dir);
zdir_remove (dir, true);
zdir_destroy (&dir);
----
