Wolfram Language Paclet Repository

Community-contributed installable additions to the Wolfram Language

Wolfram/ CommandLineParser

(1.0.0) current version: 1.0.2 »

Parser for command line arguments

Contributed by: Matteo Salvarezza

A small package to parse command line arguments in a Wolfram Language script.

Installation Instructions

To install this paclet in your Wolfram Language environment, evaluate this code:
PacletInstall["Wolfram/CommandLineParser"]


To load the code after installation, evaluate this code:
Needs["Wolfram`CommandLineParser`"]

Details

The functionality offered by this paclet can be divided in two parts:

A very flexible command line parsing logic that allows for arbitrary validation/transformation of provided data using low-level argument specifications
A set of high-level helpers to generate said low-level specifications for common use cases (numeric arguments, boolean arguments, ...)

Examples

Basic Examples (5) 

Specify a command line interface with a single numeric argument:

In[1]:=
argsSpec = {{"my-int-arg" -> NumericSpec["Integer", "An unbounded integer"]}, {}};

Parse settings according to the above specification:

In[2]:=
ParseCommandLine[argsSpec, {"42"}]
Out[2]=

ParseCommandLine is meant to be used in Wolfram Language scripts. In the above example command line arguments are explicitly provided as a list of strings, but it's not necessary to do so in a script. When ParseCommandLine is used in a script, its 1-argument form will automatically grab the arguments provided from the command line. When ran from a notebook interface the 1-argument form does not work:

In[3]:=
ParseCommandLine[argsSpec]
Out[3]=

The script equivalent to the above example is:

(* script.m *) Get[] argsSpec = {{"my-int-arg" -> NumericSpec["Integer", "An unbounded integer"]}, {}}; parsed = ParseCommandLine[argsSpec]; Print[parsed]

The script is called e.g. in this way:

$ math -script script.m 42 {<|"my-int-arg" → 42|>, <||>}

Scope (3) 

Specify a command line interface with three positional arguments (the last being variadic) and two optional arguments:

In[4]:=
posArgSpec = { "my-string-arg" -> StringSpec["A generic string argument"], "my-symbol-arg" -> EnumSpec[{None, Automatic, Inherited}, "A special symbol. Can be None, Automatic, Inherited or their lower-case equivalents"], "my-variadic-numeric-arg" -> NumericSpec["Integer", "Any sequence of positive integers, including none", "Interval" -> {0, Infinity}, "Variadic" -> True] };
In[5]:=
optArgSpec = { {"my-numeric-opt", "0.5"} -> NumericSpec["Real", "A real number between 0 and 1", "Interval" -> {0, 1}], {"my-boolean-opt", "false"} -> BooleanSpec["A boolean"] };
In[6]:=
argsSpec = {posArgSpec, optArgSpec};

Parse various inputs:

In[7]:=
ParseCommandLine[argsSpec, {"hello", "inherited", "3", "5", "67", "1"}]
Out[7]=
In[8]:=
ParseCommandLine[argsSpec, {"hello", "inherited", "3", "5", "67", "1", "--my-numeric-opt=0.2"}]
Out[8]=
In[9]:=
ParseCommandLine[argsSpec, {"hello", "inherited", "3", "5", "67", "1", "--my-numeric-opt=0.2", "--my-boolean-opt=true"}]
Out[9]=
In[10]:=
ParseCommandLine[argsSpec, {"hello", "inherited", "3", "5", "67", "1", "--my-numeric-opt=0.2", "--my-boolean-opt"}]
Out[10]=

If the special flag -- help is passed, an auto-generated help message is printed :

In[11]:=
ParseCommandLine[argsSpec, {"--help"}]
Out[11]=

See the Tech Notes for the full documentation

Compatibility

Wolfram Language Version 13.0

Version History

  • 1.0.2 – 19 March 2024
  • 1.0.1 – 18 March 2024
  • 1.0.0 – 18 March 2024

License Information

MIT License

Paclet Source

Source Metadata

  • Source: https://github.com/matteosal/commandlineparser