vpJsonArgumentParser Class Reference

#include <visp3/io/vpJsonArgumentParser.h>

Public Types
enum	vpJsonArgumentType { WITH_FIELD = 0 , FLAG = 1 }

Public Member Functions
	vpJsonArgumentParser (const std::string &description, const std::string &jsonFileArgumentName, const std::string &nestSeparator)
std::string	help () const
template<typename T >
vpJsonArgumentParser &	addArgument (const std::string &name, T &parameter, const bool required=true, const std::string &help="No description")
vpJsonArgumentParser &	addFlag (const std::string &name, bool &parameter, const std::string &help="No description")
void	parse (int argc, const char *argv[])

Detailed Description

Command line argument parsing with support for JSON files. If a JSON file is supplied, it is parsed and command line arguments take precedence over values given in the file.

Warning

To be used, this class requires the 3rd party JSON library to be installed and enabled when installing ViSP.

This argument parser can take any number and type of arguments, as long they can be serialized to and from JSON.

A very basic program that uses both a JSON file and command line arguments can be found below:

#include <visp3/io/vpJsonArgumentParser.h>
#include <iostream>
int main(int argc, char* argv[])
{
  double d = 1.0;
  std::string s = "Default";
 
  vpJsonArgumentParser parser("Example program for arguments with vpJsonArgumentParser", "config", "/");
 
  parser.add_argument("scalar", d, true, "An important value: must be defined by the user")
        .add_argument("string", s, false, "An optional value: if left unspecified, will default to its initialized value (\"Default\")")
        .parse(argc, argv);
 
  std::cout << "Scalar = " << d << std::endl;
  std::cout << "String = " << s << std::endl;
}

Compiling this sample and calling the program with the arguments from the command line would yield:

$ ./program scalar 2.0 string "A new value"
Scalar = 2.0
String = a new value
$ ./program scalar 2.0
Scalar = 2.0
String = default

Here the arguments are specified from the command line. Since the "string" argument is optional, it does not have to be specified.

For programs with more arguments it is helpful to use a JSON file that contains a base configuration. For the program above, a JSON file could look like:

{
  "scalar": 3.0,
  "string": "Some base value"
}

we could then call the program with:

$ ./program config my_settings.json
Scalar = 3.0
String = Some base value

The values contained in the JSON file can be overridden with command line arguments

$ ./program config my_settings.json scalar 5
Scalar = 5.0
String = Some base value

The program can also be called with the "-h" or "--help" argument to display the help associated to the arguments, as well as an example json configuration file

Examples

servoAfma6MegaposePBVS.cpp, and tutorial-megapose-live-single-object-tracking.cpp.

Definition at line 137 of file vpJsonArgumentParser.h.

Member Enumeration Documentation

vpJsonArgumentType

enum vpJsonArgumentParser::vpJsonArgumentType

Enumerator
WITH_FIELD
FLAG

Definition at line 141 of file vpJsonArgumentParser.h.

Constructor & Destructor Documentation

vpJsonArgumentParser()

vpJsonArgumentParser::vpJsonArgumentParser	(	const std::string &	description,
		const std::string &	jsonFileArgumentName,
		const std::string &	nestSeparator
	)

Create a new argument parser, that can take into account both a JSON configuration file and command line arguments.

json namespace shortcut

Parameters

description	Description of the program tied to this parser
jsonFileArgumentName	Name of the argument that points to the JSON file to load
nestSeparator	Delimiter that is used map a nested json object to a command line argument. For example, with a delimiter set to "/", the command line argument "a/b" will map to the json key "b" in the following json document: { "a": { "b": 10.0 }, "otherArgument": false }

Definition at line 41 of file vpJsonArgumentParser.cpp.

References vpException::badValue.

Member Function Documentation

addArgument()

template<typename T >

vpJsonArgumentParser& vpJsonArgumentParser::addArgument ( const std::string &  name, T &  parameter, const bool  required = true, const std::string &  help = "No description"  )

inline

Add an argument that can be provided by the user, either via command line or through the json file.

Template Parameters

T	Type of the argument to pass. The methods from_json(const nlohmann::json&, T&) and to_json(nlohmann::json&, const T&) must be defined. This is the case for most basic types or stl containers. For your own types, you should define the method.

Parameters

name	Name of the parameter that will be used to look up the argument values when parsing command line arguments or the json file. This name may contain the nestSeparator, in which case the look up in the JSON file will seek a nested object to parse.
parameter	Reference where the parsed value will be stored. It is modified when calling parse.
required	Whether this argument is required. If it is, it should be specified either through command line or through the json file. If not, then you should take special care to initialize parameter with a sensible value.
help	The description of the argument.

Returns

vpJsonArgumentParser& returns self, allowing argument definition chaining

Definition at line 189 of file vpJsonArgumentParser.h.

References vpException::badValue.

addFlag()

vpJsonArgumentParser & vpJsonArgumentParser::addFlag	(	const std::string &	name,
		bool &	parameter,
		const std::string &	help = "No description"
	)

Add an argument that acts as a flag when specified on the command line. When this flag is specified, the boolean passed in argument will be inverted.

Parameters

name	Name of the flag.
parameter	The boolean to modify when the flag is specified
help	The description of the argument.

Returns

vpJsonArgumentParser& returns self, allowing argument definition chaining

Definition at line 97 of file vpJsonArgumentParser.cpp.

References FLAG, and help().

help()

std::string vpJsonArgumentParser::help

(

)

const

Generate a help message, containing the description of the arguments, their default value and whether they are required or not. This message also contains an example json file, generated from the default values of the arguments. This method is called when running the program with the "-h" or "--help" arguments.

Returns

The help message

Definition at line 60 of file vpJsonArgumentParser.cpp.

Referenced by addFlag(), and parse().

parse()

void vpJsonArgumentParser::parse	(	int	argc,
		const char *	argv[]
	)

Parse the arguments.

Parameters

argc	Number of arguments (including program name)
argv	Arguments

Definition at line 154 of file vpJsonArgumentParser.cpp.

References FLAG, help(), vpException::ioError, and WITH_FIELD.