zargs(3)

zargs(3)

CZMQ Manual - CZMQ/2.2.1

Name

zargs - Class for Platform independent command line argument parsing helpers

Synopsis

//  This is a draft class, and may change without notice. It is disabled in
//  stable builds by default. If you use this in applications, please ask
//  for it to be pushed to stable state. Use --enable-drafts to enable.
#ifdef CZMQ_BUILD_DRAFT_API
//  *** Draft method, for development use, may change without warning ***
//  Create a new zargs from command line arguments.
CZMQ_EXPORT zargs_t *
    zargs_new (int argc, char **argv);

//  *** Draft method, for development use, may change without warning ***
//  Destroy zargs instance.
CZMQ_EXPORT void
    zargs_destroy (zargs_t **self_p);

//  *** Draft method, for development use, may change without warning ***
//  Return program name (argv[0])
CZMQ_EXPORT const char *
    zargs_progname (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Return number of positional arguments
CZMQ_EXPORT size_t
    zargs_arguments (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Return first positional argument or NULL
CZMQ_EXPORT const char *
    zargs_first (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Return next positional argument or NULL
CZMQ_EXPORT const char *
    zargs_next (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Return first named parameter value, or NULL if there are no named
//  parameters, or value for which zargs_param_empty (arg) returns true.
CZMQ_EXPORT const char *
    zargs_param_first (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Return next named parameter value, or NULL if there are no named
//  parameters, or value for which zargs_param_empty (arg) returns true.
CZMQ_EXPORT const char *
    zargs_param_next (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Return current parameter name, or NULL if there are no named
//  parameters.
CZMQ_EXPORT const char *
    zargs_param_name (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Return value of named parameter, NULL if no given parameter has
//  been specified, or special value for wich zargs_param_empty ()
//  returns true.
CZMQ_EXPORT const char *
    zargs_param_lookup (zargs_t *self, const char *keys);

//  *** Draft method, for development use, may change without warning ***
//  Return value of named parameter(s), NULL if no given parameter has
//  been specified, or special value for wich zargs_param_empty ()
//  returns true.
CZMQ_EXPORT const char *
    zargs_param_lookupx (zargs_t *self, const char *keys, ...);

//  *** Draft method, for development use, may change without warning ***
//  Returns true if there are --help -h arguments
CZMQ_EXPORT bool
    zargs_has_help (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Returns true if parameter did not have a value
CZMQ_EXPORT bool
    zargs_param_empty (const char *arg);

//  *** Draft method, for development use, may change without warning ***
//  Print an instance of zargs.
CZMQ_EXPORT void
    zargs_print (zargs_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Self test of this class.
CZMQ_EXPORT void
    zargs_test (bool verbose);

#endif // CZMQ_BUILD_DRAFT_API
Please add '@interface' section in './../src/zargs.c'.

Description

zargs - Platform independent command line argument parsing helpers

Platform independent command line argument parsing helpers

There are two kind of elements provided by this class foo —named-parameter —parameter with_value positional arguments -a gain-parameter zargs keeps poision only for arguments, parameters are to be accessed like hash.

It DOES: * provide easy to use CLASS compatible API for accessing argv * is platform independent * provide getopt_long style — argument, which delimits parameters from arguments * makes parameters positon independent

It does NOT * change argv * provide a "declarative" way to define command line interface

In future it SHALL * hide several formats of command line to one (-Idir, —include=dir, —include dir are the same from API pov)

Please add @discuss section in ./../src/zargs.c.

Example

From zargs_test method

// Simple create/destroy test

char *argv1[] = {"progname", "--named1", "-n1", "val1", "positional1", "--with", "value", "--with2=value2", "-W3value3", "--", "--thisis", "considered", "positional", NULL};

zargs_t *self = zargs_new (13, argv1);
assert (self);

assert (streq (zargs_progname (self), "progname"));
assert (streq (zargs_first (self), "positional1"));
assert (streq (zargs_next (self), "--thisis"));
assert (streq (zargs_next (self), "considered"));
assert (streq (zargs_next (self), "positional"));
assert (!zargs_next (self));

assert (zargs_param_empty (zargs_param_lookup (self, "--named1")));
assert (!zargs_param_empty (zargs_param_lookup (self, "-n1")));
assert (streq (zargs_param_lookupx (self, "--not at all", "-n1", NULL), "val1"));
// TODO: this does not look like an easy hack w/o allocating extra memory
// ???
//assert (streq (zargs_param_lookup (self, "--with", NULL), "value2"));
 zargs_destroy (&self);

Authors

The CZMQ manual was written by Pieter Hintjens<moc.xitami|hp#moc.xitami|hp>.

Resources

Main web site: http://czmq.zeromq.org/

Report bugs to the ØMQ development mailing list: <gro.qmorez.stsil|ved-qmorez#gro.qmorez.stsil|ved-qmorez>

Copyright

Copyright (c) 1991-2014 iMatix and Contributors. License LGPLv3+: GNU LGPL 3 or later <http://gnu.org/licenses/lgpl.html>. This is free software: you are free to change it and redistribute it. There is NO WARRANTY, to the extent permitted by law. For details see the files COPYING and COPYING.LESSER included with the CZMQ distribution.