R package defineOptions

About defineOptions

This package enables users to define how to parse command line arguments and how to assign them to a list. Values to be assigned when the options is not specified can also be defined. Names to store values, their types, their long or short option names and callbacks for each definition are defined. Arguments other than options are stored as positional arguments.


parser_def = new_parser_def() |>
            def_name = "target_range",
            def_type = "integer",
            long_option = "--target-range",
            short_option = "-t",
            input_splitter = ",",
            callback = opt_optional_input_required( input_when_omitted = "70,180" )
    ) |>
            def_name = "exclude_weekend",
            def_type = "logical",
            long_option = "--exclude-weekend",
            callback = opt_optional_input_disallowed( input_when_specified = "TRUE",
                                                      input_when_omitted = "FALSE" )
    ) |>
            def_name = "exclude_holiday",
            def_type = "logical",
            long_option = "--exclude-holiday",
            callback = opt_optional_input_disallowed( input_when_specified = "TRUE",
                                                      input_when_omitted = "FALSE" )
    ) |>
            def_name = "output_path",
            def_type = "character",
            long_option = "--output",
            callback = opt_required_input_required()

command_arguments = commandArgs(trailingOnly = TRUE)
parsed_args = parse_with_defs( parser_def, command_arguments)
Rscript analyze_log.R input1.txt input2.txt --target-range 60,140 --exclude-weekend --output log.data
[1]  60 140

[1] TRUE


[1] "log.data"

[1] TRUE

[1] TRUE


[1] TRUE

[1] "input1.txt" "input2.txt"

[1] "parsed_result"

summary() function makes it easy to browse how values are assigned.

[1] "summary of parsed_result object"

$`assigned values`
             name opt_specified    value
1    target_range          TRUE       60
2    target_range          TRUE      140
3 exclude_weekend          TRUE        1
4 exclude_holiday         FALSE        0
5     output_path          TRUE log.data

$`positional arguments`
[1] "input1.txt" "input2.txt"

How arguments are defined

Definitions are consturcted by calling define_option() method for ParserDef object, which is instantiated by new_parser_def() function. The second argument of define_option() takes a list that consists of def_name, def_type, long_option, short_option, input_splitter and callback.

Setting name Description
def_name An identifier of this definition
Element name of the final parsing result
def_type Type into which each input is cast
long_option (e.g.) –output
short_option (e.g.) -o # Exactly one letter is allowed.
input_splitter Splitter
callback How to process input or define default input

How command line arguments are parsed

  1. Start parsing command line argumetns with definitions. parse_with_defs() method.
  2. If an option takes a value, its value is dealt as its input as characters.
  3. Callbacks of all the definitions are executed.
  4. Inputs can be splitted with a letter specified by input_splitter.
  5. Inputs are cast into the type specified as def_type.
  6. The results are returned in a list (S3 parsed_result class).

Built-in callbacks

The following functions return callbacks that can be assined to callback in define_option method. Each callback defines how to manage inputs, supply inputs and also raise an error when the input is inappropriately specified or is inappropriately unspecified,

Functions returning callbacks Option Value Option Example
opt_optional_input_required Optional Required –target-range 70,180 # or null
opt_optional_input_disallowed Optional No –wihtout-weekend # or null
opt_required_input_required Required Required –output log.data # never null

Each function takes the following paramters when definition.

Functions returning callbacks Parameters
opt_optional_input_required input_when_omitted
opt_optional_input_disallowed input_when_specified, input_when_omitted
opt_required_input_required NA

opt_optional_input_required function requires what input should be supplied when this option is omitted.

opt_optional_input_disallowed function requires what inputs should be supplied when then option is specified or is omitted. The option defined by this callback is called a flag.

opt_required_input_required function does not require any parameters, because it always require values to be supplied as command line options.




Your feedback is welcome.

Maintainer: Toshi Umehara toshi@niceume.com