README.md
In defineOptions: Define and Parse Command Line Options

R package 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.

analyze_log.R

library(defineOptions)
parser_def = new_parser_def() |>
    define_option(
        list(
            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" )
        )
    ) |>
    define_option(
        list(
            def_name = "exclude_weekend",
            def_type = "logical",
            long_option = "--exclude-weekend",
            callback = opt_optional_input_disallowed( input_when_specified = "TRUE",
                                                      input_when_omitted = "FALSE" )
        )
    ) |>
    define_option(
        list(
            def_name = "exclude_holiday",
            def_type = "logical",
            long_option = "--exclude-holiday",
            callback = opt_optional_input_disallowed( input_when_specified = "TRUE",
                                                      input_when_omitted = "FALSE" )
        )
    ) |>
    define_option(
        list(
            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)
print(parsed_args)
print(summary(parsed_args))

Run the example with command line arguments

Rscript analyze_log.R input1.txt input2.txt --target-range 60,140 --exclude-weekend --output log.data

Output

$values
$values$target_range
[1]  60 140

$values$exclude_weekend
[1] TRUE

$values$exclude_holiday
[1] FALSE

$values$output_path
[1] "log.data"


$opt_specified
$opt_specified$target_range
[1] TRUE

$opt_specified$exclude_weekend
[1] TRUE

$opt_specified$exclude_holiday
[1] FALSE

$opt_specified$output_path
[1] TRUE


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

attr(,"class")
[1] "parsed_result"

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

$message
[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"

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 |

def_name and def_type are required.
long_option or short_option is required.
input_splitter is optional.
callback is required.

Start parsing command line argumetns with definitions. parse_with_defs() method.
If an option takes a value, its value is dealt as its input as characters.
Callbacks of all the definitions are executed.
- Callback function takes four arguments, which take the following values.
  - name: def_name value is supplied
  - specified: TRUE if option is specified in command line arguments. Otherwise FALSE.
  - input: input value from command line arguments. If not provided, NA is passed here.
  - optoins: concatenation of long_option and short_option
- Each Callback returns a new input as a chracter object or raise an error when its input is inappropriate.
Inputs can be splitted with a letter specified by input_splitter.
Inputs are cast into the type specified as def_type.
- as() function is used for this process.
The results are returned in a list (S3 parsed_result class).
- values: A list of vlues, and each element name is specified by def_name.
- opt_specified: A list of boolean vlues of whether its options were specified in command line arguments or not, and each element name is specified by def_name.
- positoinal: a vector of positional arguments. If there are no positoinal arguments, NA is assigned.

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.

https://github.com/niceume/defineOptions

Your feedback is welcome.

Maintainer: Toshi Umehara toshi@niceume.com