Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/mosherubin/getcmdopt

Simple, light, cross-platform C++ class for parsing command line options
https://github.com/mosherubin/getcmdopt
argument-parser argv argv-parser command-line command-line-parser cross-platform getopts parser
Last synced: 19 days ago
JSON representation
Simple, light, cross-platform C++ class for parsing command line options
Host: GitHub
URL: https://github.com/mosherubin/getcmdopt
Owner: mosherubin
License: mit
Created: 2018-04-28T20:50:27.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2020-03-07T18:27:39.000Z (almost 5 years ago)
Last Synced: 2024-10-27T13:10:47.628Z (2 months ago)
Topics: argument-parser, argv, argv-parser, command-line, command-line-parser, cross-platform, getopts, parser
Language: C++
Homepage:
Size: 27.3 KB
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        # GetCmdOpt

Simple, light, cross-platform C++ class for parsing command line options

# Quick start

This is a lightweight C++ option parser library, written in standard C++ to be used cross platform (avoiding the problem that GetOpts is not natively supported on Windows).  `GetCmdOpt` supports retrieving multiple values for a single option key.

Command line options have a mandatory `key` followed by zero or more optional `values`, all delimited by spaces.  Values can be integers, doubles, or strings.  Here are some examples of key/value pairs that can be parsed from the command line.  Here's what a real-life command line might look like:

```

--width 174 --days 3 4 7 8 --radius 3.1415 --distance 3.1415 7.2 -22 123.456 --folder foo/bar --dirs foo/bar baz\\wam "c:\\Program Files\\SuperApp" --enable-trace --somethingelse --flag-1 1 --flag-2 0 --flag-3 qwerty

```

Here is the same command line, parsed into key/value(s) pairs:

```

--width 174

--days 3 4 7 8

--radius 3.1415

--distance 3.1415 7.2 -22 123.456

--folder foo/bar

--dirs foo/bar baz\\wam "c:\\Program Files\\SuperApp"

--enable-trace

--somethingelse

--flag-1 1

--flag-2 0

--flag-3 qwerty

```

The key prefix, by default '--', can be modified by the developer (a default of '--' is preferred over '-' to allow negative numbers as values without mixing up the parser).

## Basics

    #include "GetCmdOpt.h"

Create a GetCmdOpt instance from the main() function's `argc` and `argv` arguments.

    int main(int argc, char *argv[])

    {

        GetCmdOpt *opt = new GetCmdOpt(argc, argv);

      ...

    }

At this point the command line has been parsed.  The application should now call the appropriate `GetCmdOpt` public functions to return the keys/values it needs.  See the section entitled "Parsing Functions Supported by GetCmdOpt" for the functions you can now call on `opt`.

By default, command-line options are declared by prefixing them with the string '--' followed by zero or more values.  Here is an example of a valid and complete command line:

    --rows 10 --fleet 1 2 3 --flag --verbose 0 --I ..\\foo\\bar \"c:\\Program Files\\blah\" --ratio 12.34 --height 1.2 3.4 777.888999

## GetCmdOpt Member Functions

`GetCmdOpts` supports the parsing of integer, double, string, and boolean command line values.  For the first three data types (i.e., integer, double, and string) it supports retrieving multiple values for a single key.  here is a table showing the functions:

| | Integer | Double | String | Boolean |

|:---:|:---:|:---:|:---:|:---:|

| **Single** | GetInt | GetDouble | GetString | GetBool |

| **Vector** | GetIntVector | GetDoubleVector | GetStringVector  | --- |

The following table shows what the command key/values would look like:

| Type | Option Form | Comment | Use Function ... |

|---|---|---|---|

| Integer | `--width 174` | Single integer value | GetInt |

| Integer Vector | `--days 3 4 7 8` | Multiple integer values | GetIntVector |

| Double | `--radius 3.1415` | Single double value | GetDouble |

| Double Vector | `--distance 3.1415 7.2 -22 123.456` | Multiple double values | GetDoubleVector |

| String | `--folder foo/bar` | Single string value | GetString |

| String Vector | `--dirs foo/bar baz\\wam "c:\\Program Files\\SuperApp"` | Multiple string values | GetStringVector |

| Bool | `--enable-trace --somethingelse` | true, `enable-trace` has no value | GetBool |

| Bool | `--flag-1 1` | true, `--enable-trace` value is not "0" | GetBool |

| Bool | `--flag-2 0` | false, `--enable-trace` value is "0" | GetBool |

| Bool | `--flag-3 qwerty` | true, `--enable-trace` value is not "0" | GetBool |

### Constructors

```

*GetCmdOpt (int argc, char *argv [], std::string keyPrefix = "--")*

```

**Description**

Use the `GetCmdOpt` constructor to create an object that can then be probed for command line options.  It accepts

**Parameters**

    argc       [in] The original `argc` passed by the operating system to the program

    argv       [in] The original `argv` passed by the operating system to the program

           

    keyPrefix  [in] An option string denoting the characters that are to prefix to all keys in the command line,

                identifying the command line token as a key string rather than a value string.  The default key

                prefix string is two successive hyphens ('--'), but this can be changed for a given program by

                specifying a different string.

    

### Single-Value Parse: GetInt, GetDouble, GetString, GetBool

```

*bool GetInt (const char *key, int& i)*  

*bool GetDouble (const char *key, double& d)*  

*bool GetString (const char *key, std::string &s)*  

*bool GetBool (const char *key, bool &b)*  

```

**Description**

Each of these functions takes a `key` and a reference to a variable of the desired data type (e.g., int, double, std::string, bool). If the function call succeeds, the parsed value will be returned in the out parameter.

If there are multiple occurrences of the key, only the first value will be returned.  Subsequence keys with the name will be ignored.

The `GetBool` function differs from the other functions that the key can be followed by an optional value.  If there is no value, the boolean value for that key defaults to `true`.  If the value is a string of zeroes (i.e., it is a string whose characters are all '0') then the boolean value is set to `false`.  In all other cases it is set to `true`.  The following table summarizes the rules for `GetBool`:

| Type | Option Form | Comment | Use Function ... |

|---|---|---|---|

| bool | `--enable-trace --somethingelse` | true, `enable-trace` has no value | GetBool |

| bool | `--foo 1` | true, `--foo` value is not "0" | GetBool |

| bool | `--bar 0` | false, `--bar` value is "0" | GetBool |

| bool | `--baz qwerty` | true, `--baz` value is not "0" | GetBool |

**Parameters**

    key    [in] A string corresponding to a command line option key, without the leading key prefix.  For example, 

           if the command line has an option "--date", the `key` string would be "date".

           

    value  [out] A reference to the desired data type expected

    

**Return Value**

On success, the function returns a boolean value of `true`, and the out parameter `value` is set to the parsed value.

If the parsing operation failed, a boolean value of `false` is returned.

### Multiple-Value Parse: GetIntVector, GetDoubleVector, GetStringVector

```

*bool GetIntVector (const char *p, std::vector &vec)*

*bool GetDoubleVector (const char *p, std::vector &vec)*

*bool GetStringVector (const char *p, std::vector &vec)*

```

**Description**

Each of these functions takes a `key` and a reference to an `std::vector` variable of the desired data type.  If the function call succeeds, all values associated with the key will be returned in the out parameter.  If the key occurs more than once, all the values associated with all the key occurrences are returned.

**Parameters**

    key    [in] A string corresponding to a command line option key, without the leading key prefix.  For example, 

           if the command line has an option "--date", the `key` string would be "date".

           

    vec    [out] A reference to an `std::vector<>` matching the desired data type

    

**Return Value**

On success, the function returns a boolean value of `true`, and the out parameter `vec` contains all is set to the parsed value.

If the parsing operation failed, a boolean value of `false` is returned.

## Coding Example

```

#include "GetCmdOpt.h"

// Demoing GetCmdOpt with the command line:

//

//     --rows 10 --fleet 1 2 3 4 --cols 9 --enable-trace --foobar 1 --foo 0 

//     --day Tuesday --I ..\foo\bar c:\a\b\c\baz "c:\Program Files\blah" 

//     --ratio 12.34 --height 1.2 3.4 5.6 777.888999

void DisplayCommandLine(int argc, char *argv[])

{

    std::string cmdline;

    for (int i = 1; i < argc; ++i)

    {

        bool hasEmbeddedSpace = (strchr(argv[i], ' ') != 0);

        if (hasEmbeddedSpace) cmdline += "\"";

        cmdline += argv[i];

        if (hasEmbeddedSpace) cmdline += "\"";

        if (i < argc - 1)

            cmdline += " ";

    }

    printf("Command line:\n\n\t%s\n\n", cmdline.c_str());

}

int main(int argc, char *argv[])

{

    GetCmdOpt *opt = new GetCmdOpt(argc, argv);

    int i;

    int rows;

    int cols;

    std::vector vecFleet;

    std::string day;

    std::vector vecInclude;

    double ratio;

    std::vector vecHeights;

    DisplayCommandLine(argc, argv);

    opt->GetInt("rows", rows);

    opt->GetInt("cols", cols);

    opt->GetIntVector("fleet", vecFleet);

    opt->GetString("day", day);

    opt->GetStringVector("I", vecInclude);

    opt->GetDouble("ratio", ratio);

    opt->GetDoubleVector("height", vecHeights);

    printf ("rows = %d\n", rows);

    printf ("cols = %d\n", cols);

    printf ("vecFleet:\n");

    for (i = 0; i < (int) vecFleet.size(); ++i)

    {

        printf("\t[%d] %d\n", i, vecFleet[i]);

    }

    printf("enable-trace is %s\n", opt->GetBool("enable-trace") ? "TRUE" : "FALSE");

    printf("foobar is %s\n", opt->GetBool("foobar") ? "TRUE" : "FALSE");

    printf("foo is %s\n", opt->GetBool("foo") ? "TRUE" : "FALSE");

    printf("day is \"%s\"\n", day.c_str());

    printf("vecInclude:\n");

    for (i = 0; i < (int)vecInclude.size(); ++i)

    {

        printf("\t[%d] %s\n", i, vecInclude[i].c_str());

    }

    printf("ratio is \"%f\"\n", ratio);

    printf("vecHeights:\n");

    for (i = 0; i < (int)vecHeights.size(); ++i)

    {

        printf("\t[%d] %f\n", i, vecHeights[i]);

    }

}

```

Here is the expected output of the above program:

```

Command line:

        --rows 10 --fleet 1 2 3 4 --cols 9 --enable-trace --foobar 1 --foo 0 --day Tuesday --I ..\foo\bar c:\a\b\c\baz "c:\Program Files\blah" --ratio 12.34 --height 1.2 3.4 5.6 777.888999

rows = 10

cols = 9

vecFleet:

        [0] 1

        [1] 2

        [2] 3

        [3] 4

enable-trace is TRUE

foobar is TRUE

foo is FALSE

day is "Tuesday"

vecInclude:2^31

        [0] ..\foo\bar

        [1] c:\a\b\c\baz

        [2] c:\Program Files\blah

ratio is "12.340000"

vecHeights:

        [0] 1.200000

        [1] 3.400000

        [2] 5.600000

        [3] 777.888999

```

# Tips / Tricks / Caveats

* The largest integer that `GetInt` can parse is `2147483647` (max int = 2^31 - 1)

* If a key occurs more than once, a `Get*Vector` function call will return **all** values associated with the key.