A POSIX style commandline option/argument parser for CoolBasic.
Say that you call your program from the commandline like this: MyProgram.exe --output-file "C:\My output.txt" "a value" -c 1 -n --verbose -xyz -- get everything after two dashes into a single argument
This library helps you parse that string of options and arguments like so:
--output-file
is a long option (can have a short alias too, e.g.-o
) that takes an argument. The argument happens to contain a space, so it's enclosed in double quotes. CLA removes the double quotes at the end for you."a value"
is a non-option argument, meaning that it is not tied into any named option.-c
is a short option (can have a long alias too, e.g.--count
) and takes an argument. No quotes are needed for this particular argument.-n
is a short option without an argument.--verbose
is a long option without an argument.-xyz
are three short options joined together. It's the same as-x -y -z
, and the order does not matter, it could be e.g.-zxy
too. The last option can also have an argument assigned to it:-xyz some-argument
.-- get everything after two dashes into a single argument
The two dashes (without an option name, meaning separated by a space from whatever comes next) will terminate option parsing and include the rest of the command line into a single non-option argument.
While CoolBasic programs are designed for Windows only, this library is still designed not to use the Windows style command line options (e.g. MyProgram.exe /N
). I'm just more familiar with the POSIX style.
- CoolBasic development environment.
- GetWord2() & CountWords2() functions need to be included separately.
- Make sure that you have
GetWord2()
andCountWords2()
functions included in your program. Include "CommandLineArguments.cb"
in your program.
You do not need to include anything from the tests folder. It contains unit tests that only need to be used if you develop or debug this library.
Call DefineCommandLineOptions(options$)
which takes one mandatory parameter (see below for optional parameters). options$
is a string consisting of any of the following words:
--
denotes a long option name, e.g.--verbose
.-
denotes a short option name, e.g.-v
.:
denotes both a long and a short option name, e.g.--verbose:v
(also--verbose:-v
is valid)+
after a short/long option name tells that this option takes an argument and the argument is mandatory. E.g.--output-file+
or-o+
or--output-file:-o+
.- Each word must be separated by a space
- Complete example:
DefineCommandLineOptions("--verbose:-v -c+ -n")
options$
: Covered above.accept_non_option_arguments
: Boolean. Whether to accept the existence of non-option arguments in the command line string. Defaults to false. Non-option arguments: values in the commandline that do not have an option name assigned with them. For example executingMyProgram.exe output.txt
uses a non-option argument output.txt, whereasMyProgram.exe --output-file output.txt
uses an option which has output.txt as its argument. Depending on how you want to design your options, you can choose if you want to enable non-option arguments or not.accept_terminating_options
: Boolean. Denotes that it's allowed to use--
in the command line string to terminate option parsing, in which case the rest of the command line string will be read as a single argument into an option named--
. Defaults to false.
DefineCommandLineOptions(options$)
returns true if it was able to understand your option definitions, false otherwise. This phase is just a predefinition, and it does not yet parse the commandline string in any way.
Ensure that you call DefineCommandLineOptions() before trying to parse the commandline string!
Call ParseCommandLineOptions()
. It will read CoolBasic's CommandLine()
value and split it into parts. For an example of the format accepted by ParseCommandLineOptions()
, see the beginning of this readme.
The function returns true if the parsing succeeded or false if the program was executed with either undefined option names, non-option arguments (if those are disabled), or illegal format. You can then display your own error message that guides which options can be used. Even if the result is false, some options may be already parsed and usable, but not all.
If you want the function to use another source than CommandLine()
for the commandline string, just pass it a custom string as a parameter (optional). This is used at least for unit testing, but you do not need to do that.
- Call
isCommandLineOptionPresent(option_name$)
to see if a specific option was presented in the commandline. - Call
getCommandLineArgument(option_name$, if_not_present$="")
to get an argument related to a specific option. Use the optional second parameter to define what should be returned if the option was not present in the commandline.
To access non-option arguments, there is currently no function support for that (getCommandLineArgument()
will support it in the future), but you can iterate the CommandLineNonOptionArgument
type list.
Counts of options and non-option arguments can be read from:
CountCommandLineOptionsDefined
- How many options you have defined in the code.CountCommandLineOptionsPresent
- How many of them are present in the commanline string.CountCommandLineNonOptionArgumentsPresent
Currently there is no function support for getting all options that are present in the commandline with one function call.
Ideas, bug reports, and pull requests are all welcome. Use the GitHub issue tracker to get in touch! :)
This library is written by me, Jarkko Linnanvirta.