optigrab (version 0.9.2.1)

opt_get: Get option's values from the command-line

Description

Returns value(s) from the command-line associated with the desired option.

Usage

opt_get(name, default, n, required = FALSE, description = NULL,
  opts = commandArgs(), style = getOption("optigrab")$style)
opt_get_gnu(flag, ...)
opt_get_ms(flag, ...)
opt_get_java(flag, ...)
opt_grab(flag, n = 1, opts = commandArgs())

Arguments

name

character; vector of possible synonymes for the "flag" that identifies the option.

default

any; the value(s) provided if the flag is not found (default: NA )

n

integer; number of values to retrieve. See Details. (default: determined by default, see Details below.)

required

logical; whether the value is required. If not found or an incorrect, number of values are found, an error is thrown. (default: FALSE)

description

(character) message to be printed with opt_help

opts

character; vector to parse for options (default: commandArgs())

style

list; list of functions that define the parsing style

flag

character; vector of possible synonyms for the "flag" that identifies the option. These should be given as they would exactly appear on the command line.

...

additional arguments passed to opt_grab

Value

opt_grab always returns a character; it is either the value for the flags or NA_character_ if if they cannot be parsed.

opt_get returns a value the command-line value as specified by the arguments or produces an error if the value could not be determined and required==TRUE.

Selecting <code>n</code>

Except in rare-caces, the user should not have to specify n. This is determined from the value of default.

If default is a logical value, i.e. TRUE or FALSE, n is assumed to take no arguments. Presents of the flag on the command line will return TRUE, absense of the flag returns false.

If default is another type than logical, n is selected as length(default).

If default is missing, n is 1.

automatic coercision

Command-line arguments are character vectors. If default is supplied then the opt_get attempts to coerce the values it returns to class(default). The user might wish to supply the correct methods to handle the conversions.

side-effects

opt_grab has the additional side-effect of keeping track of the arguments. This is useful for keeping track of

flag is used to identify the command line flag. It can include all synonyms for the flags.

n the number of value(s) to retrieve from the command line. If n=0, then a logical value is returned indicating whether the flag exists

required indicates if a value is required. If the the flag is not found and there is no default given or if there is not the correct number of value(s) an error is raised.

opts is the vector from which options are parsed. By default, this is commandArgs().

Details

These functions support parsing of command arguments work when using Rscript, a #! on linux systems or R CMD BATCH. By default, they closely follows the ubiquitous GNU standards for command-line interfaces. opt_grab is the workhorse that does the actual parsing. It returns the options values or NA if it cannot discern them. It is currently exported, but this may change in future version to be an internal function. Its interface is not guarantted. The user should use opt_get instead.

opt_get supports default values, automated guessing for n and (attempts a) coercion of the return values to the correct class.

References

GNU Command Line Standards

See Also

commandArgs()

Examples

# NOT RUN {
  opts <- c( '--foo', 'bar' )
 
  opt_get('foo')
  opt_get( c('foo'), opts=opts )    
  opt_grab( c('--foo'), opts=opts ) 
  
  opt_get_ms( c('foo'), opts=c('/foo', 'bar' ) )
  opt_get_java( c('foo'), opts=c('-foo', 'bar' ) )
  
  
  # Using pipes:
  
# }
# NOT RUN {
    c('foo', 'f') %>% opt_get('bar')
  
# }
# NOT RUN {
  
# }