opts.h File Reference

Standard command-line options options and parsing. More...

#include <limits.h>
#include <getopt.h>
#include "rnr/rnrconfig.h"
#include "rnr/pkg.h"

Go to the source code of this file.

Classes
struct	OptsInfo_T
	Short and Long Options Info. More...
struct	OptsPgmInfo_T
	Program Description Strings Info Structure. More...

Macros
#define	OPTS_NO_SHORT   0
	no short option equivalent
#define	OPTS_RVAL_ERROR   '?'
	options error
#define	OPTS_RVAL_LOG   'l'
	-l, –log return value
#define	OPTS_RVAL_LONG   (CHAR_MAX + 1)
	long return value start
#define	OPTS_RVAL_HELP   (OPTS_RVAL_LONG)
	–help return value
#define	OPTS_RVAL_VERSION   (OPTS_RVAL_LONG + 1)
	–version return value
#define	OPTS_RVAL_LOGFILE   (OPTS_RVAL_LONG + 2)
	–logfile return value
#define	OPTS_RVAL_LOGNOCOLOR   (OPTS_RVAL_LONG + 3)
	–log-no-color rval
#define	OPTS_RVAL_LOGNOTIME   (OPTS_RVAL_LONG + 4)
	–log-no-timestamp rval
#define	OPTS_RVAL_USER   (OPTS_RVAL_LONG + 5)
	start of user available
#define	OPTSBADARG(argv0, opt, arg)   OptsInvalid(argv0, "Invalid '%s' argument to '%s' option.", arg, opt)
	Standard bad option error message reporter. More...

Typedefs
typedef int(*	OptsCvtFunc_T) (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Option Argument Conversion Function Type.
typedef char *(*	OptsFmtFunc_T) (char *buf, size_t buflen, void *pOptVal)
	Option Value String Formatter Type.

Functions
char **	OptsGet (const char *argv0, const PkgInfo_T *pPkgInfo, OptsPgmInfo_T *pPgmInfo, OptsInfo_T *pOptsInfo, bool_t bHasLogging, int *pargc, char *argv[])
	Gets, validates, and sets all command line options. More...
int	OptsCvtArgStr (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options string argument to string. More...
int	OptsCvtArgBool (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options boolean argument to bool_t. More...
int	OptsCvtArgInt (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options integer argument to integer. More...
int	OptsCvtArgFloat (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options float argument to double. More...
int	OptsCvtArgLogLevel (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options string argument to log threshold level. More...
char *	OptsFmtStr (char *buf, size_t buflen, void *pOptVal)
	String option value string formatter. More...
char *	OptsFmtInt (char *buf, size_t buflen, void *pOptVal)
	Integer option value string formatter. More...
char *	OptsFmtFloat (char *buf, size_t buflen, void *pOptVal)
	Float option value string formatter. More...
char *	OptsFmtBool (char *buf, size_t buflen, void *pOptVal)
	Boolean option value string formatter. More...
char *	OptsFmtChar (char *buf, size_t buflen, void *pOptVal)
	Character option value string formatter. More...
char *	OptsFmtLogLevel (char *buf, size_t buflen, void *pOptVal)
	Log Level option value string formatter. More...
void	OptsInvalid (const char *argv0, const char *sFmt,...)
	Invalid option or option argument print and exit. More...

Detailed Description

Standard command-line options options and parsing.

Every application that uses librnr options facilities are provided with a set of built-in options (described below) to standardize RoadNarrows application interfaces.

Built-In Options

-l, –log=level

Set logging threshold level. All logging events with priority ≤ level will be logged. All others will be ignored. The level argument is one of:

'off' or 0	Disable all logging.
'error' or 1	Enable error and warning logging.
'diag1' or 2	Enable diagnostics 1 logging.
'diag2' or 3	Enable diagnostics 2 logging.
'diag3' or 4	Enable diagnostics 3 logging.
'diag4' or 5	Enable diagnostics 4 logging.
'diag5' or 6	Enable diagnostics 5 logging.
> 6	Enable user-defined logging.

DEFAULT: off

–logfile=file

Set log file file. Special file names:

'stderr'	log to standard error.
'stdout'	log to standard output.

DEFAULT: stderr

–log-no-color

Disable logging with compiled ANSI color strings.
DEFAULT: false

–log-no-timestamp

Disable logging with timestamps.
DEFAULT: false

–help

Display this help and exit.

–version

Output version information and exit.

See also

Page example_log under "Related Pages" for an example usage of options.

Package

RoadNarrows Robotics Common Library 1

Library

librnr

File

rnr/opts.h

Author

Robin Knight (robin.nosp@m..kni.nosp@m.ght@r.nosp@m.oadn.nosp@m.arrow.nosp@m.s.co.nosp@m.m)

Copyright

© 2005-2018. RoadNarrows LLC..
http://www.roadnarrows.com
All Rights Reserved

License

MIT

EULA

See the README and EULA files for any copyright and licensing information.

—

Definition in file opts.h.

Macro Definition Documentation

#define OPTSBADARG	(		argv0,
			opt,
			arg
	)		OptsInvalid(argv0, "Invalid '%s' argument to '%s' option.", arg, opt)

Standard bad option error message reporter.

Parameters

argv0	Command name string.
opt	Option name string.
arg	Option argument name string.

Definition at line 263 of file opts.h.

Referenced by OptsCvtArgBool(), OptsCvtArgFloat(), and OptsCvtArgInt().

Function Documentation

int OptsCvtArgBool	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options boolean argument to bool_t.

1 or "true" converts to true.
0 or "false" converts to false.

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

true

Exceptions

OPTSBADARG()

Returns

If returns, then returns OK.

Definition at line 1018 of file opts.c.

References OK, and OPTSBADARG.

{
  if( optarg )
  {
    if( !strcmp(optarg, "true") || !strcmp(optarg, "1") )
    {
      *((bool_t *)pOptVal) = true;
    }
    else if( !strcmp(optarg, "false") || !strcmp(optarg, "0") )
    {
      *((bool_t *)pOptVal) = false;
    }
    else
    {
      OPTSBADARG(argv0, sOptName, optarg);
    }
  }
  // optional argument default
  else
  {
    *((bool_t *)pOptVal) = true;
  }

  return OK;
}

int OptsCvtArgFloat	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options float argument to double.

Accepted format: optionally signed floating-point number.

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

1.0

Exceptions

OPTSBADARG()

Returns

If returns, then returns OK.

Definition at line 1109 of file opts.c.

References OK, and OPTSBADARG.

{
  double  optargFloat;

  if( optarg )
  {
    if( sscanf(optarg, "%lf", &optargFloat) != 1 )
    {
      OPTSBADARG(argv0, sOptName, optarg);
    }
    *((double *)pOptVal) = optargFloat;
  }
  // optional argument default
  else
  {
    *((double *)pOptVal) = 1.0;
  }

  return OK;
}

int OptsCvtArgInt	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options integer argument to integer.

Accepted formats: decimal hexidecimal(0x<hexdigits>) octal(0<octaldigits>).

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

1

Exceptions

OPTSBADARG()

Returns

If returns, then returns OK.

Definition at line 1065 of file opts.c.

References OK, and OPTSBADARG.

Referenced by OptsCvtArgLogLevel().

{
  int   optargInt;
  char  *optargEnd;

  if( optarg )
  {
    optargInt = (int)strtol(optarg, &optargEnd, 0);
    if( *optargEnd != 0 )
    {
      OPTSBADARG(argv0, sOptName, optarg);
    }
    *((int *)pOptVal) = optargInt;
  }
  // optional argument default
  else
  {
    *((int *)pOptVal) = 1;
  }

  return OK;
}

int OptsCvtArgLogLevel	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options string argument to log threshold level.

Format: "off", "error", "diag1", "diag2", "diag3", "diag4", "diag5", or >= 0

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

LOG_LEVEL_DFT

Exceptions

OPTSBADARG()

Returns

If returns, then returns OK.

Definition at line 1151 of file opts.c.

References arraysize, LOG_LEVEL_DFT, LOG_LEVEL_OFF, NvpName2Val(), OK, and OptsCvtArgInt().

Referenced by OptsLogSetLevel().

{
  int logLevel;

  if( optarg )
  {
    logLevel = NvpName2Val(OptsLogLevelTbl, arraysize(OptsLogLevelTbl), optarg);

    // assume integer format
    if( logLevel < LOG_LEVEL_OFF )
    {
      OptsCvtArgInt(argv0, sOptName, optarg, &logLevel);
    }
  }
  // optional argument default
  else
  {
    logLevel = LOG_LEVEL_DFT;
  }

  if( logLevel < LOG_LEVEL_OFF )
  {
    logLevel = LOG_LEVEL_OFF;
  }

  *((int *)pOptVal) = logLevel;

  return OK;
}

int OptsCvtArgStr	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options string argument to string.

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

"" (zero-length string)

Returns

If returns, then returns OK.

Definition at line 987 of file opts.c.

References new_strdup(), and OK.

Referenced by OptsGet(), and OptsLogSetFile().

{
  *((char **)pOptVal) = new_strdup(optarg);
  return OK;
}

char* OptsFmtBool	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Boolean option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1247 of file opts.c.

{
  char  *s;

  if( *((int *)pOptVal) == true )
  {
    s = "true";
  }
  else
  {
    s = "false";
  }
  strncpy(buf, s, buflen);
  buf[buflen-1] = 0;
  return buf;
}

char* OptsFmtChar	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Character option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1273 of file opts.c.

{
  buf[0] = *((char *)pOptVal);
  buf[1] = 0;
  return buf;
}

char* OptsFmtFloat	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Float option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1231 of file opts.c.

{
  snprintf(buf, buflen, "%f", *((double *)pOptVal));
  buf[buflen-1] = 0;
  return buf;
}

char* OptsFmtInt	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Integer option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1215 of file opts.c.

Referenced by OptsFmtLogLevel().

{
  snprintf(buf, buflen, "%d", *((int *)pOptVal));
  buf[buflen-1] = 0;
  return buf;
}

char* OptsFmtLogLevel	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Log Level option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1289 of file opts.c.

References LOG_LEVEL_OFF, OptsFmtInt(), and OptsFmtStr().

{
  int   level = *((int *)pOptVal);
  char *off   = "off";

  if( level == LOG_LEVEL_OFF )
  {
    return OptsFmtStr(buf, buflen, &off);
  }
  else
  {
    return OptsFmtInt(buf, buflen, pOptVal);
  }
}

char* OptsFmtStr	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

String option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1191 of file opts.c.

References NULL.

Referenced by OptsFmtLogLevel().

{
  
  if( (pOptVal == NULL) || (*((char **)pOptVal) == NULL) )
  {
    buf[0] = 0;
  }
  else
  {
    strncpy(buf, *((char **)pOptVal), buflen);
    buf[buflen-1] = 0;
  }
  return buf;
}

char** OptsGet	(	const char *	argv0,
		const PkgInfo_T *	pPkgInfo,
		OptsPgmInfo_T *	pPgmInfo,
		OptsInfo_T *	pOptsInfo,
		bool_t	bHasLogging,
		int *	pargc,
		char *	argv[]
	)

Gets, validates, and sets all command line options.

Parameters

	argv0	(Massaged) program name.
	pPkgInfo	Package info.
	pPgmInfo	Program info.
	pOptsInfo	Program options info.
	bHasLogging	Do [not] include logging options.
[out]	pargc	New non-option argument count.
	argv	Command-line options and arguments. arguments.

Returns

Reposition command-line arguments to start of first non-option comand argument.

Definition at line 861 of file opts.c.

References EC_BAD_OPT, OptsInfo_T::fn_cvt, OptsInfo_T::has_arg, OptsInfo_T::long_opt, OptsCtl_T::m_pLongOpts, OptsCtl_T::m_sShortOpts, NULL, OK, OptsInfo_T::opt_addr, OPTS_LONGOPT_LOG, OPTS_LONGOPT_LOGFILE, OPTS_RESET_ARGCV, OPTS_RVAL_ERROR, OPTS_RVAL_HELP, OPTS_RVAL_LOG, OPTS_RVAL_LOGFILE, OPTS_RVAL_LOGNOCOLOR, OPTS_RVAL_LOGNOTIME, OPTS_RVAL_VERSION, OptsCvtArgStr(), OptsDelete(), OptsHelp(), OptsInvalid(), OptsLogDisableColor(), OptsLogDisableTimestamp(), OptsLogSetFile(), OptsLogSetLevel(), OptsNew(), OptsVersion(), and OptsInfo_T::pvt_retval.

Referenced by init().

{
  OptsCtl_T     *pOptsCtl;
  OptsInfo_T    *p;
  int           argc = *pargc;
  int           c;
  int           option_index;
  bool_t        bHasOpt;

  //
  // Set external getopt_long() variables. N.B. makes OptsGet() non-reentrant.
  //
  optarg  = NULL; // current argument to option
  optind  = 0;    // next index in argv to look for options
  opterr  = 1;    // allow getopt_long() to print error messages
  optopt  = 0;    // current parsed option character

  // build option arguments from info
  pOptsCtl = OptsNew(pOptsInfo, bHasLogging);

  // parse and convert options
  while(true)
  {
    option_index = 0;

    // parse next long/short option
    c = getopt_long(argc, argv, pOptsCtl->m_sShortOpts, pOptsCtl->m_pLongOpts,
                    &option_index);

    // end of option list
    if( c == -1 )
    {
      break;
    }

    // process option
    switch(c)
    {
      case OPTS_RVAL_ERROR:         // -? options error
        OptsInvalid(argv0, "");
        break;
      case OPTS_RVAL_HELP:          // --help
        OptsHelp(argv0, pOptsInfo, pPgmInfo, bHasLogging);
        exit(OK);
        break;
      case OPTS_RVAL_VERSION:       // --version
        OptsVersion(argv0, pPkgInfo);
        exit(OK);
        break;
      case OPTS_RVAL_LOG:           // -l, --log <level>
        OptsLogSetLevel(argv0, OPTS_LONGOPT_LOG, optarg);
        break;
      case OPTS_RVAL_LOGFILE:       // --logfile <file>
        OptsLogSetFile(argv0, OPTS_LONGOPT_LOGFILE, optarg);
        break;
      case OPTS_RVAL_LOGNOCOLOR:    // --log-no-color
        OptsLogDisableColor(argv0, OPTS_LONGOPT_LOG, optarg);
        break;
      case OPTS_RVAL_LOGNOTIME:     // --log-no-timestamp
        OptsLogDisableTimestamp(argv0, OPTS_LONGOPT_LOG, optarg);
        break;
      default:                      // user application option
        bHasOpt = false;
        for(p=pOptsInfo; (p!=NULL) && (p->long_opt!=NULL); ++p)
        {
          if( p->pvt_retval == c )
          {
            bHasOpt = true;

            // user supplied option conversion function
            if( p->fn_cvt != NULL )
            {
              p->fn_cvt(argv0, p->long_opt, optarg, p->opt_addr);
            }
            // default for option w/o argument is boolean true value
            else if( p->has_arg == no_argument )
            {
              *((int *)p->opt_addr) = true;
            }
            // default for option w/ argument is string value
            else
            {
              OptsCvtArgStr(argv0, p->long_opt, optarg, p->opt_addr);
            }
          }
        }
        if( !bHasOpt )
        {
          fprintf(stderr, "Warning: getopt_long() return character code 0x%x\n",
                            c);
          exit(EC_BAD_OPT);
        }
        break;
    }
  }

  OptsDelete(pOptsCtl);

  OPTS_RESET_ARGCV(optind, argc, argv);

  *pargc = argc;

  return argv;
}

void OptsInvalid	(	const char *	argv0,
		const char *	sFmt,
			...
	)

Invalid option or option argument print and exit.

Parameters

argv0	Program name.
sFmt	Error format string.
...	Variable arguments to format string.

Note

The function terminates process with exit status EC_BAD_OPT(2).

Definition at line 1313 of file opts.c.

References EC_BAD_OPT, MAX_FMT_BUF, and NULL.

Referenced by OptsGet().

{
  va_list ap;
  char    fmtbuf[MAX_FMT_BUF];

  if( (sFmt != NULL) && (*sFmt != 0) )
  {
    snprintf(fmtbuf, MAX_FMT_BUF, "%s: %s\n", argv0, sFmt);
    fmtbuf[MAX_FMT_BUF-1] = 0;
    va_start(ap, sFmt);
    vfprintf(stderr, fmtbuf, ap); 
    va_end(ap);
  }
  fprintf(stderr, "Try '%s --help' for more information.\n", argv0);
  exit(EC_BAD_OPT);
}