nlib
nn::nlib::Nflags Class Reference

The class for parsing command line flags. More...

#include "nn/nlib/Nflags.h"

Static Public Member Functions

static errno_t Parse (int *argc, char ***argv) noexcept
 Parses command-line flags. More...
 
static errno_t Parse (int *argc, wchar_t ***argv) noexcept
 Parses command-line flags. More...
 
static void PrintHelp () noexcept
 Displays command-line Help. More...
 
static const char * GetErrorMessage () noexcept
 Gets the error message string. More...
 
static errno_t GetFileName (const char *path, char(&filename)[kMaxFileName]) noexcept
 Gets the filename from the path string specified by the command-line string. More...
 
static errno_t GetDirName (const char *path, char(&dirname)[kMaxDirName]) noexcept
 Gets the directory name from the path string specified by the command-line string. More...
 
static errno_t GetStringCommaList (char *arg, char **vec, size_t vec_count, size_t *written_count) noexcept
 Breaks up comma-delimited strings (of command line arguments) and stores them in an array. More...
 
template<size_t N>
static errno_t GetStringCommaList (char *arg, char *(&vec)[N], size_t *written_count) noexcept
 The function template version of GetStringCommaList.
 
static errno_t GetInt32CommaList (char *arg, int32_t *vec, size_t vec_count, size_t *written_count) noexcept
 Breaks up comma-delimited strings (of command-line arguments), converts them into integers, and stores them in an array. More...
 
template<size_t N>
static errno_t GetInt32CommaList (char *arg, int32_t(&vec)[N], size_t *written_count) noexcept
 The function template version of GetInt32CommaList.
 
static errno_t GetDoubleCommaList (char *arg, double *vec, size_t vec_count, size_t *written_count) noexcept
 Breaks up comma-delimited strings (of command-line arguments), converts them into double type, and stores them in an array. More...
 
template<size_t N>
static errno_t GetDoubleCommaList (char *arg, double(&vec)[N], size_t *written_count) noexcept
 The function template version of GetDoubleCommaList.
 
static bool GetBoolFromEnv (const char *varname, bool defval) noexcept
 Parses an environment variable value and returns a boolean value. Returns the default value if the environment variable does not exist or could not be parsed. More...
 
static int32_t GetInt32FromEnv (const char *varname, int32_t defval) noexcept
 Parses an environment variable value and returns an int32_t value. Returns the default value if the environment variable does not exist or could not be parsed. More...
 
static int64_t GetInt64FromEnv (const char *varname, int64_t defval) noexcept
 Parses an environment variable value and returns an int64_t value. Returns the default value if the environment variable does not exist or could not be parsed. More...
 
static double GetDoubleFromEnv (const char *varname, double defval) noexcept
 Parses an environment variable value and returns a double value. Returns the default value if the environment variable does not exist or could not be parsed. More...
 
static const char * GetStringFromEnv (UniquePtr< char[]> &buf, const char *varname, const char *defval) noexcept
 Returns an environment variable value as a string. The buffer allocated for storing the string is stored in buf. More...
 

Detailed Description

The class for parsing command line flags.

Description
With Nflags you can distribute the command line flag definitions to multiple files. Using this property, you can set command-line arguments in various libraries and modules, which makes it easy to customize how a program starts from the command line without recompiling.
Here is a typical example of command-line coding using Nflags. For more information, see the function and macro references.
#include "nn/nlib/Nflags.h"
int main(int argc, char* argv[]) {
errno_t e = Nflags::Parse(&argc, &argv);
if (nlib_is_error(e)) {
// Command-line string error.
return 1;
}
if (NLIB_FLAGS_help) {
// If the --help option has been specified, display the Help text and end.
return 0;
}
.... Below are the processes of the main function .....
}
......
// Command-line flag definitions.
// The definitions are distributed around in the various source files, so you can add more command-line switches without changing main.cpp.
NLIB_FLAGS_DEFINE_bool(myswitch, false, "My switch");
......
// Referencing command-line flags.
// Write something like the following to reference the command-line flag named 'NLIB_FLAGS_myswitch.'
See also
https://gflags.github.io/gflags/ (gflags)
Examples:
misc/nflags/nflags.cpp.

Definition at line 28 of file Nflags.h.

Member Function Documentation

◆ GetBoolFromEnv()

nn::nlib::Nflags::GetBoolFromEnv ( const char *  varname,
bool  defval 
)
staticnoexcept

Parses an environment variable value and returns a boolean value. Returns the default value if the environment variable does not exist or could not be parsed.

Parameters
[in]varnameThe name of the environment variable.
[in]defvalThe default return value.
Returns
The environment variable value.
Description
Returns true if the environment variable value is "1", "t", "true", "y", or "yes". Returns false if the value is "0", "f", "false", "n", or "no". Returns defval otherwise.

◆ GetDirName()

nn::nlib::Nflags::GetDirName ( const char *  path,
char(&)  dirname[kMaxDirName] 
)
staticnoexcept

Gets the directory name from the path string specified by the command-line string.

Parameters
[in]pathThe path string.
[out]dirnameThe directory name string.
Returns
Returns 0 on success.
Description
In the Windows version, the string set for path is converted to UTF-8 and stored in dirname.

◆ GetDoubleCommaList()

nn::nlib::Nflags::GetDoubleCommaList ( char *  arg,
double *  vec,
size_t  vec_count,
size_t *  written_count 
)
staticnoexcept

Breaks up comma-delimited strings (of command-line arguments), converts them into double type, and stores them in an array.

Template Parameters
NThe maximum number of numerical value lists stored.
Parameters
[in,out]argComma-delimited strings.
[out]vecThe array storing the numerical values.
[in]vec_countThe size of the vec array.
[out]written_countThe number of stored values.
Return values
0No error occurred.
EINVALNULL or 0 was passed to the argument.
ERANGEThe number of comma-delimited strings exceeds the number of elements of vec.
EILSEQThe comma-delimited string could be converted into numerical values.
Description
Note that after this function is executed, the content of the strings in arg may have been modified.

◆ GetDoubleFromEnv()

nn::nlib::Nflags::GetDoubleFromEnv ( const char *  varname,
double  defval 
)
staticnoexcept

Parses an environment variable value and returns a double value. Returns the default value if the environment variable does not exist or could not be parsed.

Parameters
[in]varnameThe name of the environment variable.
[in]defvalThe default return value.
Returns
The environment variable value.

◆ GetErrorMessage()

nn::nlib::Nflags::GetErrorMessage ( )
staticnoexcept

Gets the error message string.

Returns
Error message.
Description
An error message string is set if an error is generated by the Parse function. You can use this function to reference that string.

◆ GetFileName()

nn::nlib::Nflags::GetFileName ( const char *  path,
char(&)  filename[kMaxFileName] 
)
staticnoexcept

Gets the filename from the path string specified by the command-line string.

Parameters
[in]pathThe path string.
[out]filenameThe filename string.
Returns
Returns 0 on success.
Description
In the Windows version, the string set for path is converted to UTF-8 and stored in filename.

◆ GetInt32CommaList()

nn::nlib::Nflags::GetInt32CommaList ( char *  arg,
int32_t *  vec,
size_t  vec_count,
size_t *  written_count 
)
staticnoexcept

Breaks up comma-delimited strings (of command-line arguments), converts them into integers, and stores them in an array.

Template Parameters
NThe maximum number of integer lists stored.
Parameters
[in,out]argComma-delimited strings.
[out]vecAn array storing the integers.
[in]vec_countThe size of the vec array.
[out]written_countThe number of stored integers.
Return values
0No error occurred.
EINVALNULL or 0 was passed to the argument.
ERANGEThe number of comma-delimited strings exceeds the number of elements of vec.
EILSEQThe comma-delimited string could be converted into integers.
Description
Note that after this function is executed, the content of the strings in arg may have been modified.

◆ GetInt32FromEnv()

nn::nlib::Nflags::GetInt32FromEnv ( const char *  varname,
int32_t  defval 
)
staticnoexcept

Parses an environment variable value and returns an int32_t value. Returns the default value if the environment variable does not exist or could not be parsed.

Parameters
[in]varnameThe name of the environment variable.
[in]defvalThe default return value.
Returns
The environment variable value.

◆ GetInt64FromEnv()

nn::nlib::Nflags::GetInt64FromEnv ( const char *  varname,
int64_t  defval 
)
staticnoexcept

Parses an environment variable value and returns an int64_t value. Returns the default value if the environment variable does not exist or could not be parsed.

Parameters
[in]varnameThe name of the environment variable.
[in]defvalThe default return value.
Returns
The environment variable value.

◆ GetStringCommaList()

nn::nlib::Nflags::GetStringCommaList ( char *  arg,
char **  vec,
size_t  vec_count,
size_t *  written_count 
)
staticnoexcept

Breaks up comma-delimited strings (of command line arguments) and stores them in an array.

Template Parameters
NThe maximum number of string lists stored.
Parameters
[in,out]argComma-delimited strings.
[out]vecAn array storing pointers to the strings.
[in]vec_countThe size of the vec array.
[out]written_countThe number of stored strings.
Return values
0Success.
EINVALNULL or 0 was passed to the argument.
ERANGEThe number of comma-delimited strings exceeds the number of elements of vec.
Description
Use this option to process the --file=file1.txt,file2.txt,file3.txt command-line flag arguments.
// str = "text1,text2,text3" for example
char* x[3];
size_t len;
{
// Error handling.
....
}
for (size_t i = 0; i < len; ++i)
{
// Gets each string, using x[i].
....
}
Note that after this function is executed, the content of the strings in arg may have been modified. Also, in the Windows version, the strings set for arg are converted to UTF-8 and stored in vec.

◆ GetStringFromEnv()

const char * nn::nlib::Nflags::GetStringFromEnv ( UniquePtr< char[]> &  buf,
const char *  varname,
const char *  defval 
)
inlinestaticnoexcept

Returns an environment variable value as a string. The buffer allocated for storing the string is stored in buf.

Parameters
[in,out]bufDynamically allocated internal memory.
[in]varnameThe name of the environment variable.
[in]defvalThe default return value.
Returns
The environment variable value.
Description
Returns the default value if the environment variable does not exist or the memory allocation process failed. Do not attempt to reference the return value after freeing the buf buffer.

Definition at line 91 of file Nflags.h.

◆ Parse() [1/2]

nn::nlib::Nflags::Parse ( int *  argc,
char ***  argv 
)
staticnoexcept

Parses command-line flags.

Parameters
[in,out]argcPointers to the number of command-line flags.
[in,out]argvPointers to the command-line flags.
Return values
0Parsing was successful.
EILSEQInvalid format.
ENOENTThe specified option does not exist.
Description
The pointers to the argc and argv parameters that were passed to the main function are passed to the function. The parameters are parsed, the defined options are discovered, and the variables are set.
The parameters processed by this function are removed from argc and argv. (The number of parameters decreases.) This function does not process any parameters that are positioned after '--.'

◆ Parse() [2/2]

nn::nlib::Nflags::Parse ( int *  argc,
wchar_t ***  argv 
)
staticnoexcept

Parses command-line flags.

Parameters
[in,out]argcPointers to the number of command-line flags.
[in,out]argvPointers to the command-line flags.
Return values
0Parsing was successful.
EILSEQInvalid format.
ENOENTThe specified option does not exist.
Description
The pointers to the argc and argv parameters that were passed to the main function are passed to the function. The parameters are parsed, the defined options are discovered, and the variables are set.
The parameters processed by this function are removed from argc and argv. (The number of parameters decreases.) This function does not process any parameters that are positioned after '--.'

◆ PrintHelp()

nn::nlib::Nflags::PrintHelp ( )
staticnoexcept

Displays command-line Help.

Description
The normal way to use this function is to call it if NLIB_FLAGS_help is true after the command line has been parsed, and then end the program. If this function is not called, the command-line Help is not displayed even if the --help option has been specified.

The documentation for this class was generated from the following files: