diff -Nru r-cran-getopt-1.17/DESCRIPTION r-cran-getopt-1.19.1/DESCRIPTION --- r-cran-getopt-1.17/DESCRIPTION 2011-09-26 07:15:29.000000000 +0000 +++ r-cran-getopt-1.19.1/DESCRIPTION 2013-03-04 06:40:03.000000000 +0000 @@ -1,16 +1,21 @@ Package: getopt Type: Package Title: C-like getopt behavior. -Version: 1.17 -Date: 2011-09-14 -Author: Allen Day -Maintainer: Trevor Davis -Description: Use this with Rscript to write ``#!'' shebang scripts that - accept short and long flags/options. +Version: 1.19.1 +Author: Allen Day Contributions from Trevor L Davis +Maintainer: Trevor L Davis +Description: Package designed to be used with Rscript to write ``#!'' + shebang scripts that accept short and long flags/options. Many + users will prefer using instead the package optparse which adds + extra features (automatically generated help option and usage, + support for default values, basic positional argument support). License: GPL (>= 2) Suggests: testthat +Collate: 'getopt.R' Repository: CRAN Repository/R-Forge/Project: optparse -Repository/R-Forge/Revision: 86 -Date/Publication: 2011-09-26 07:15:29 -Packaged: 2011-09-15 21:04:45 UTC; rforge +Repository/R-Forge/Revision: 116 +Repository/R-Forge/DateTimeStamp: 2013-03-01 22:49:51 +Date/Publication: 2013-03-04 07:40:03 +Packaged: 2013-03-01 23:15:17 UTC; rforge +NeedsCompilation: no diff -Nru r-cran-getopt-1.17/MD5 r-cran-getopt-1.19.1/MD5 --- r-cran-getopt-1.17/MD5 2011-09-26 07:15:29.000000000 +0000 +++ r-cran-getopt-1.19.1/MD5 2013-03-04 06:40:04.000000000 +0000 @@ -1,5 +1,8 @@ -3e6ec74e8a96e2d6ca8191dd33873441 *DESCRIPTION -012592abf4b40a8d741b299df2ded05a *NAMESPACE -5a36925f55c6948029fb7a575a5b648d *R/getopt.R -59c436ffa106b3a3226bdae1a1663ed2 *man/getopt.package.Rd -9189748f22940388cd2c2db25a5751cd *tests/unit_tests.R +bf4ef0ccdbd56ea20320566ce81af357 *DESCRIPTION +aebacd1e62ffaff4ccc2243969fd06b0 *NAMESPACE +96424b4d8b4cc2bdeb2031a954658e77 *NEWS +30b673c833af7a333dab2354bba1ca38 *R/getopt.R +7118628e7508f453e19082f20ed4991e *inst/tests/test-getopt.R +f692f19f2e09013c3d075f6d322473c0 *man/get_Rscript_filename.Rd +7476469866359a385df8551bf79b1cce *man/getopt.Rd +71912d95683c1891b4523acbc554da5e *tests/run-all.R diff -Nru r-cran-getopt-1.17/NAMESPACE r-cran-getopt-1.19.1/NAMESPACE --- r-cran-getopt-1.17/NAMESPACE 2011-09-15 21:04:45.000000000 +0000 +++ r-cran-getopt-1.19.1/NAMESPACE 2012-11-12 21:52:48.000000000 +0000 @@ -1 +1,2 @@ -exportPattern("^[^\\.]") +export(get_Rscript_filename) +export(getopt) diff -Nru r-cran-getopt-1.17/NEWS r-cran-getopt-1.19.1/NEWS --- r-cran-getopt-1.17/NEWS 1970-01-01 00:00:00.000000000 +0000 +++ r-cran-getopt-1.19.1/NEWS 2013-03-01 22:49:51.000000000 +0000 @@ -0,0 +1,11 @@ +getopt 1.19.1 +============= +* If a passed in option matches multiple options in the getopt specification but matches one exactly + then `getopt` now uses that value instead of throwing a "long flag is ambiguous" error. + +getopt 1.19.0 +============= +* Exports new function `get_Rscript_filename` that returns name of calling script, + `getopt` now uses this function value as default for `command` argument +* Documentation improved and now highlights differences + between `getopt` and `optparse` packages for new undecided users diff -Nru r-cran-getopt-1.17/R/getopt.R r-cran-getopt-1.19.1/R/getopt.R --- r-cran-getopt-1.17/R/getopt.R 2011-09-15 21:04:45.000000000 +0000 +++ r-cran-getopt-1.19.1/R/getopt.R 2013-03-01 03:02:27.000000000 +0000 @@ -1,40 +1,167 @@ -getopt = function (spec=NULL,opt=commandArgs(TRUE),command=strsplit(commandArgs(FALSE)[4],"=")[[1]][2],usage=FALSE,debug=FALSE) { - - # notes on naming convention: - - # 1. an "option" is one of the shell-split input strings - - # 2. a "flag" is a subclass of "option". a "flag" can be defined as having - # no "argument" (see below), a required "argument", or an optional - # "argument". - - # 3. an "argument" is a subclass of "option", and is the value associated - # with a flag. - - # 4. a "long flag" is a subclass of flag, and begins with the string "--". - # if the "long flag" has an associated "argument", it may be delimited from - # the "long flag" by either an "=", or may be the subsequent "option". - - # 5. a "short flag" is a subclass of flag, and begins with the string "-". - # if a "short flag" has an associated "argument", it is the subsequent - # "option". "short flags" may be bundled together, sharing a single leading - # "-", but only the final "short flag" is able to have a corresponding - # "argument". - - #spec contains at least 4 columns, as many as 5 columns. - # - # column 1: long name of flag - # - # column 2: short name of flag - # - # column 3: argument flag. 0=no argument, 1=required argument, 2=optional - # argument - # - # column 4: mode of argument. one of "logical", "integer", "double", - # "complex", "character" - # - # column 5 (optional): description of option. - # +#' C-like getopt behavior +#' +#' getopt is primarily intended to be used with ``\link{Rscript}''. It +#' facilitates writing ``\#!'' shebang scripts that accept short and long +#' flags/options. It can also be used from ``R'' directly, but is probably less +#' useful in this context. +#' +#' getopt() returns a \link{list} data structure containing \link{names} of the +#' flags that were present in the \link{character} \link{vector} passed in under +#' the \emph{opt} argument. Each value of the \link{list} is coerced to the +#' data type specified according to the value of the \emph{spec} argument. See +#' below for details. +#' +#' Notes on naming convention: +#' +#' 1. An \emph{option} is one of the shell-split input strings. +#' +#' 2. A \emph{flag} is a type of \emph{option}. a \emph{flag} can be defined as +#' having no \emph{argument} (defined below), a required \emph{argument}, or an +#' optional \emph{argument}. +#' +#' 3. An \emph{argument} is a type of \emph{option}, and is the value associated +#' with a flag. +#' +#' 4. A \emph{long flag} is a type of \emph{flag}, and begins with the string +#' ``--''. If the \emph{long flag} has an associated \emph{argument}, it may be +#' delimited from the \emph{long flag} by either a trailing \emph{=}, or may be +#' the subsequent \emph{option}. +#' +#' 5. A \emph{short flag} is a type of \emph{flag}, and begins with the string +#' ``-''. If a \emph{short flag} has an associated \emph{argument}, it is the +#' subsequent \emph{option}. \emph{short flags} may be bundled together, +#' sharing a single leading ``-'', but only the final \emph{short flag} is able +#' to have a corresponding \emph{argument}. +#' +#' Many users wonder whether they should use the getopt package or optparse package +#' Here is some of the major differences: +#' +#' Features available in \code{getopt} unavailable in \code{optparse} +#' +#' 1. As well as allowing one to specify options that take either +#' no argument or a required argument, +#' \code{getopt} also allows one to specify option with an optional argument. +#' +#' Some features implemented in \code{optparse} package unavailable in \code{getopt} +#' +#' 1. Limited support for capturing positional arguments after the optional arguments +#' when \code{positional_arguments} set to TRUE in \code{parse_args} +#' +#' 2. Automatic generation of an help option and printing of help text when encounters an "-h" +#' +#' 3. Option to specify default arguments for options as well the +#' variable name to store option values +#' +#' There is also new package \code{argparse} which contains all the features +#' of both getopt and optparse but which has a dependency on Python (>= 2.7) +#' and has not been used in production for a few years +#' like the getopt and optparse packages. +#' +#' Some Features unlikely to be implemented in \code{getopt}: +#' +#' 1. Support for multiple, identical flags, e.g. for "-m 3 -v 5 -v", the +#' trailing "-v" overrides the preceding "-v 5", result is v=TRUE (or equivalent +#' typecast). +#' +#' 2. Support for multi-valued flags, e.g. "--libpath=/usr/local/lib +#' --libpath=/tmp/foo". +#' +#' 3. Support for lists, e.g. "--define os=linux --define os=redhat" would +#' set result$os$linux=TRUE and result$os$redhat=TRUE. +#' +#' 4. Support for incremental, argument-less flags, e.g. "/path/to/script +#' -vvv" should set v=3. +#' +#' 5. Support partial-but-unique string match on options, e.g. "--verb" and +#' "--verbose" both match long flag "--verbose". +#' +#' 6. No support for mixing in positional arguments or extra arguments that +#' don't match any options. For example, you can't do "my.R --arg1 1 foo bar +#' baz" and recover "foo", "bar", "baz" as a list. Likewise for "my.R foo +#' --arg1 1 bar baz". +#' +#' @aliases getopt getopt-package +#' @param spec The getopt specification, or spec of what options are considered +#' valid. The specification must be either a 4-5 column \link{matrix}, or a +#' \link{character} \link{vector} coercible into a 4 column \link{matrix} using +#' \link{matrix}(x,ncol=4,byrow=TRUE) command. The \link{matrix}/\link{vector} +#' contains: +#' +#' Column 1: the \emph{long flag} name. A multi-\link{character} string. +#' +#' Column 2: \emph{short flag} alias of Column 1. A single-\link{character} +#' string. +#' +#' Column 3: \emph{Argument} mask of the \emph{flag}. An \link{integer}. +#' Possible values: 0=no argument, 1=required argument, 2=optional argument. +#' +#' Column 4: Data type to which the \emph{flag}'s argument shall be cast using +#' \link{storage.mode}. A multi-\link{character} string. This only considered +#' for same-row Column 3 values of 1,2. Possible values: \link{logical}, +#' \link{integer}, \link{double}, \link{complex}, \link{character}. +#' +#' Column 5 (optional): A brief description of the purpose of the option. +#' +#' The terms \emph{option}, \emph{flag}, \emph{long flag}, \emph{short flag}, +#' and \emph{argument} have very specific meanings in the context of this +#' document. Read the ``Description'' section for definitions. +#' @param opt This defaults to the return value of \link{commandArgs}(TRUE). +#' +#' If R was invoked directly via the ``R'' command, this corresponds to all +#' arguments passed to R after the ``--args'' flag. +#' +#' If R was invoked via the ``\link{Rscript}'' command, this corresponds to all +#' arguments after the name of the R script file. +#' +#' Read about \link{commandArgs} and \link{Rscript} to learn more. +#' @param command The string to use in the usage message as the name of the +#' script. See argument \emph{usage}. +#' @param usage If TRUE, argument \emph{opt} will be ignored and a usage +#' statement (character string) will be generated and returned from \emph{spec}. +#' @param debug This is used internally to debug the getopt() function itself. +#' @author Allen Day +#' @seealso \code{\link{getopt}} +#' @keywords data +#' @export +#' @examples +#' +#' #!/path/to/Rscript +#' library('getopt'); +#' #get options, using the spec as defined by the enclosed list. +#' #we read the options from the default: commandArgs(TRUE). +#' spec = matrix(c( +#' 'verbose', 'v', 2, "integer", +#' 'help' , 'h', 0, "logical", +#' 'count' , 'c', 1, "integer", +#' 'mean' , 'm', 1, "double", +#' 'sd' , 's', 1, "double" +#' ), byrow=TRUE, ncol=4); +#' opt = getopt(spec); +#' +#' # if help was asked for print a friendly message +#' # and exit with a non-zero error code +#' if ( !is.null(opt$help) ) { +#' cat(getopt(spec, usage=TRUE)); +#' q(status=1); +#' } +#' +#' #set some reasonable defaults for the options that are needed, +#' #but were not specified. +#' if ( is.null(opt$mean ) ) { opt$mean = 0 } +#' if ( is.null(opt$sd ) ) { opt$sd = 1 } +#' if ( is.null(opt$count ) ) { opt$count = 10 } +#' if ( is.null(opt$verbose ) ) { opt$verbose = FALSE } +#' +#' #print some progress messages to stderr, if requested. +#' if ( opt$verbose ) { write("writing...",stderr()); } +#' +#' #do some operation based on user input. +#' cat(paste(rnorm(opt$count,mean=opt$mean,sd=opt$sd),collapse="\n")); +#' cat("\n"); +#' +#' #signal success and exit. +#' #q(status=0); +getopt = function (spec=NULL,opt=commandArgs(TRUE),command=get_Rscript_filename(),usage=FALSE,debug=FALSE) { # littler compatibility - map argv vector to opt if (exists("argv", where = .GlobalEnv, inherits = FALSE)) { @@ -155,7 +282,11 @@ #long flag is ambiguous, matches too many options } else if ( length(rowmatch) > 1 ) { - stop(paste('long flag "', this.flag, '" is ambiguous', sep='')); + # check if there is an exact match and use that + rowmatch = which(this.flag == spec[,col.long.name]) + if(length(rowmatch) == 0) { + stop(paste('long flag "', this.flag, '" is ambiguous', sep='')); + } } #if we have an argument @@ -284,7 +415,9 @@ storage.mode(x) = spec[current.flag, col.mode]; result[spec[current.flag, col.long.name]] = x; } else { - stop("this should never happen (1). please inform the author."); + stop(paste("This should never happen.", + "Is your spec argument correct? Maybe you forgot to set", + "ncol=4, byrow=TRUE in your matrix call?")); } } #trailing flag without required argument @@ -313,3 +446,18 @@ } return(result); } + +#' Returns file name of calling Rscript +#' +#' \code{get_Rscript_filename} returns the file name of calling Rscript +#' @return A string with the filename of the calling script. +#' If not found (i.e. you are in a interactive session) returns NA. +#' +#' @export +get_Rscript_filename <- function() { + prog <- sub("--file=", "", grep("--file=", commandArgs(), value=TRUE)[1]) + if( .Platform$OS.type == "windows") { + prog <- gsub("\\\\", "\\\\\\\\", prog) + } + prog +} diff -Nru r-cran-getopt-1.17/debian/changelog r-cran-getopt-1.19.1/debian/changelog --- r-cran-getopt-1.17/debian/changelog 2013-05-06 17:01:08.000000000 +0000 +++ r-cran-getopt-1.19.1/debian/changelog 2013-05-06 17:01:08.000000000 +0000 @@ -1,3 +1,35 @@ +r-cran-getopt (1.19.1-2precise0) precise; urgency=low + + * Compilation for Ubuntu 12.04.2 LTS + + -- Michael Rutter Mon, 06 May 2013 16:54:26 +0000 + +r-cran-getopt (1.19.1-2) unstable; urgency=low + + * debian/control: Set Build-Depends: to current R version + + * (Re-)building with R 3.0.0 (beta) + + -- Dirk Eddelbuettel Sat, 30 Mar 2013 17:50:57 -0500 + +r-cran-getopt (1.19.1-1) unstable; urgency=low + + * New upstream release + + * debian/control: Set Build-Depends: to current R version + + -- Dirk Eddelbuettel Mon, 04 Mar 2013 05:59:35 -0600 + +r-cran-getopt (1.19.0-1) unstable; urgency=low + + * New upstream release + + * debian/control: Set Build-Depends: to current R version + * debian/control: Change Depends to ${R:Depends} + * debian/control: Set Standards-Version: to current version + + -- Dirk Eddelbuettel Sun, 18 Nov 2012 14:19:59 -0600 + r-cran-getopt (1.17-1) unstable; urgency=low * New upstream release diff -Nru r-cran-getopt-1.17/debian/control r-cran-getopt-1.19.1/debian/control --- r-cran-getopt-1.17/debian/control 2013-05-06 17:01:08.000000000 +0000 +++ r-cran-getopt-1.19.1/debian/control 2013-05-06 17:01:08.000000000 +0000 @@ -2,12 +2,12 @@ Section: gnu-r Priority: optional Maintainer: Dirk Eddelbuettel -Build-Depends: debhelper (>= 7.0.0), r-base-dev (>= 2.13.1), cdbs -Standards-Version: 3.9.1 +Build-Depends: debhelper (>= 7.0.0), r-base-dev (>= 3.0.0~20130327), cdbs +Standards-Version: 3.9.4 Package: r-cran-getopt Architecture: any -Depends: ${shlibs:Depends}, r-base-core (>= 2.13.1) +Depends: ${shlibs:Depends}, ${R:Depends} Description: GNU R package providing command-line parsing functionality This package provides the getopt function which can be used with R's Rscript (or littler's r) to write ``#!'' shebang scripts that accept diff -Nru r-cran-getopt-1.17/inst/tests/test-getopt.R r-cran-getopt-1.19.1/inst/tests/test-getopt.R --- r-cran-getopt-1.17/inst/tests/test-getopt.R 1970-01-01 00:00:00.000000000 +0000 +++ r-cran-getopt-1.19.1/inst/tests/test-getopt.R 2013-03-01 03:02:27.000000000 +0000 @@ -0,0 +1,84 @@ +library("testthat") +library("getopt") +sort_list <- function(unsorted_list) { + for(ii in seq(along=unsorted_list)) { + if(is.list(unsorted_list[[ii]])) { + unsorted_list[[ii]] <- sort_list(unsorted_list[[ii]]) + } + } + unsorted_list[sort(names(unsorted_list))] +} + +context("Testing getopt") +test_that("getopt works as expected", { + spec = matrix(c( + 'verbose', 'v', 2, "integer", + 'help' , 'h', 0, "logical", + 'dummy1' , 'd', 0, "logical", + 'dummy2' , 'e', 2, "logical", + 'count' , 'c', 1, "integer", + 'mean' , 'm', 1, "double", + 'sd' , 's', 1, "double", + 'output' , 'O', 1, "character" + ), ncol=4, byrow=TRUE); + expect_equal(sort_list(getopt(spec, c('-c', '-1', '-m', '-1.2'))), + sort_list(list(ARGS=character(0), count=-1, mean=-1.2))); + expect_equal(sort_list(getopt(spec, c('-v', '-m', '3'))), + sort_list(list(ARGS=character(0), verbose=1, mean=3))); + expect_equal(sort_list(getopt(spec, c('-m', '3', '-v'))), + sort_list(list(ARGS=character(0), mean=3, verbose=1))); + expect_equal(sort_list(getopt(spec, c('-m', '3', '-v', '2', '-v'))), + sort_list(list(ARGS=character(0), mean=3, verbose=1))); + expect_equal(sort_list(getopt(spec, c('-O', '-', '-m', '3'))), + sort_list(list(ARGS=character(0), output="-", mean=3))); + expect_equal(sort_list(getopt(spec, c('-O', '-', '-m', '3'))), + sort_list(getopt(spec, c('-m', '3', '-O', '-')))); + expect_equal(sort_list(getopt(spec, c('-de'))), + sort_list(getopt(spec, c('-ed')))); + expect_equal(sort_list(getopt(spec, c('-de'))), + sort_list(list(ARGS=character(0), dummy1=TRUE, dummy2=TRUE))); + expect_equal(sort_list(getopt(spec, c('-de', '1'))), + sort_list(list(ARGS=character(0), dummy1=TRUE, dummy2=NA))); + expect_equal(sort_list(getopt(spec, c('--verbose'))), + sort_list(list(ARGS=character(0), verbose=1))); + expect_equal(sort_list(getopt(spec, c('--verbose', '--help'))), + sort_list(list(ARGS=character(0), verbose=1, help=TRUE))); + expect_equal(sort_list(getopt(spec, c('--verbose', '--mean', '5'))), + sort_list(list(ARGS=character(0), verbose=1, mean=5))); + expect_equal(sort_list(getopt(spec, c('--mean=5'))), + sort_list(list(ARGS=character(0), mean=5))); + expect_equal(sort_list(getopt(spec, c('--verbose', '--mean=5', '--sd', '5'))), + sort_list(list(ARGS=character(0), verbose=1, mean=5, sd=5))); + expect_equal(sort_list(getopt(spec, c('--verbose', '--mean=5', '--sd', '5'))), + sort_list(getopt(spec, c('--mean=5', '--sd', '5', '--verbose')))); + spec = c( + 'date' , 'd', 1, "character", + 'help' , 'h', 0, "logical", + 'getdata' , 'g', 0, "logical", + 'market' , 'm', 1, "character", + 'threshold', 't', 1, "double" + ); + # should give warning is spec is not matrix + expect_that(getopt(spec, c('--date','20080421','--market','YM','--getdata')), gives_warning()); + expect_equal(sort_list(getopt(spec, c('--date','20080421','--market','YM','--getdata'))), + sort_list(list(ARGS=character(0), date='20080421', market='YM', getdata=TRUE))) + expect_equal(sort_list(getopt(spec, c('--date','20080421','--market','YM','--getdata'))), + sort_list(getopt(spec, c('--date','20080421','--getdata','--market','YM')))); + expect_that(getopt(spec, c('--date','20080421','--getdata','--market','YM'),debug=TRUE), + prints_text("processing ")); + expect_that(print(getopt(spec, c('--date','20080421','--getdata','--market','YM'),usage=TRUE)), + prints_text("Usage: ")); +}) +test_that("don't throw error if multiple matches match one argument fully", { + # test if partial name matches fully, + # still throw error if multiple matches and doesn't match both fully + # feature request from Jonas Zimmermann + spec = c( + 'foo' , 'f', 0, "logical", + 'foobar' , 'b', 0, "logical", + 'biz' , 'z', 0, "logical" + ) + expect_that(getopt(spec, c('--fo')), throws_error()) + expect_equal(getopt(spec, c('--foo')), sort_list(list(ARGS=character(0), foo=TRUE))) +}) + diff -Nru r-cran-getopt-1.17/man/get_Rscript_filename.Rd r-cran-getopt-1.19.1/man/get_Rscript_filename.Rd --- r-cran-getopt-1.17/man/get_Rscript_filename.Rd 1970-01-01 00:00:00.000000000 +0000 +++ r-cran-getopt-1.19.1/man/get_Rscript_filename.Rd 2012-11-13 01:06:02.000000000 +0000 @@ -0,0 +1,15 @@ +\name{get_Rscript_filename} +\alias{get_Rscript_filename} +\title{Returns file name of calling Rscript} +\usage{ + get_Rscript_filename() +} +\value{ + A string with the filename of the calling script. If not + found (i.e. you are in a interactive session) returns NA. +} +\description{ + \code{get_Rscript_filename} returns the file name of + calling Rscript +} + diff -Nru r-cran-getopt-1.17/man/getopt.Rd r-cran-getopt-1.19.1/man/getopt.Rd --- r-cran-getopt-1.17/man/getopt.Rd 1970-01-01 00:00:00.000000000 +0000 +++ r-cran-getopt-1.19.1/man/getopt.Rd 2012-11-12 21:52:48.000000000 +0000 @@ -0,0 +1,213 @@ +\name{getopt} +\alias{getopt} +\alias{getopt-package} +\title{C-like getopt behavior} +\usage{ + getopt(spec = NULL, opt = commandArgs(TRUE), + command = get_Rscript_filename(), usage = FALSE, + debug = FALSE) +} +\arguments{ + \item{spec}{The getopt specification, or spec of what + options are considered valid. The specification must be + either a 4-5 column \link{matrix}, or a \link{character} + \link{vector} coercible into a 4 column \link{matrix} + using \link{matrix}(x,ncol=4,byrow=TRUE) command. The + \link{matrix}/\link{vector} contains: + + Column 1: the \emph{long flag} name. A + multi-\link{character} string. + + Column 2: \emph{short flag} alias of Column 1. A + single-\link{character} string. + + Column 3: \emph{Argument} mask of the \emph{flag}. An + \link{integer}. Possible values: 0=no argument, + 1=required argument, 2=optional argument. + + Column 4: Data type to which the \emph{flag}'s argument + shall be cast using \link{storage.mode}. A + multi-\link{character} string. This only considered for + same-row Column 3 values of 1,2. Possible values: + \link{logical}, \link{integer}, \link{double}, + \link{complex}, \link{character}. + + Column 5 (optional): A brief description of the purpose + of the option. + + The terms \emph{option}, \emph{flag}, \emph{long flag}, + \emph{short flag}, and \emph{argument} have very specific + meanings in the context of this document. Read the + ``Description'' section for definitions.} + + \item{opt}{This defaults to the return value of + \link{commandArgs}(TRUE). + + If R was invoked directly via the ``R'' command, this + corresponds to all arguments passed to R after the + ``--args'' flag. + + If R was invoked via the ``\link{Rscript}'' command, this + corresponds to all arguments after the name of the R + script file. + + Read about \link{commandArgs} and \link{Rscript} to learn + more.} + + \item{command}{The string to use in the usage message as + the name of the script. See argument \emph{usage}.} + + \item{usage}{If TRUE, argument \emph{opt} will be ignored + and a usage statement (character string) will be + generated and returned from \emph{spec}.} + + \item{debug}{This is used internally to debug the + getopt() function itself.} +} +\description{ + getopt is primarily intended to be used with + ``\link{Rscript}''. It facilitates writing ``\#!'' + shebang scripts that accept short and long flags/options. + It can also be used from ``R'' directly, but is probably + less useful in this context. +} +\details{ + getopt() returns a \link{list} data structure containing + \link{names} of the flags that were present in the + \link{character} \link{vector} passed in under the + \emph{opt} argument. Each value of the \link{list} is + coerced to the data type specified according to the value + of the \emph{spec} argument. See below for details. + + Notes on naming convention: + + 1. An \emph{option} is one of the shell-split input + strings. + + 2. A \emph{flag} is a type of \emph{option}. a + \emph{flag} can be defined as having no \emph{argument} + (defined below), a required \emph{argument}, or an + optional \emph{argument}. + + 3. An \emph{argument} is a type of \emph{option}, and is + the value associated with a flag. + + 4. A \emph{long flag} is a type of \emph{flag}, and + begins with the string ``--''. If the \emph{long flag} + has an associated \emph{argument}, it may be delimited + from the \emph{long flag} by either a trailing \emph{=}, + or may be the subsequent \emph{option}. + + 5. A \emph{short flag} is a type of \emph{flag}, and + begins with the string ``-''. If a \emph{short flag} has + an associated \emph{argument}, it is the subsequent + \emph{option}. \emph{short flags} may be bundled + together, sharing a single leading ``-'', but only the + final \emph{short flag} is able to have a corresponding + \emph{argument}. + + Many users wonder whether they should use the getopt + package or optparse package Here is some of the major + differences: + + Features available in \code{getopt} unavailable in + \code{optparse} + + 1. As well as allowing one to specify options that take + either no argument or a required argument, \code{getopt} + also allows one to specify option with an optional + argument. + + Some features implemented in \code{optparse} package + unavailable in \code{getopt} + + 1. Limited support for capturing positional arguments + after the optional arguments when + \code{positional_arguments} set to TRUE in + \code{parse_args} + + 2. Automatic generation of an help option and printing of + help text when encounters an "-h" + + 3. Option to specify default arguments for options as + well the variable name to store option values + + There is also new package \code{argparse} which contains + all the features of both getopt and optparse but which + has a dependency on Python (>= 2.7) and has not been used + in production for a few years like the getopt and + optparse packages. + + Some Features unlikely to be implemented in + \code{getopt}: + + 1. Support for multiple, identical flags, e.g. for "-m 3 + -v 5 -v", the trailing "-v" overrides the preceding "-v + 5", result is v=TRUE (or equivalent typecast). + + 2. Support for multi-valued flags, e.g. + "--libpath=/usr/local/lib --libpath=/tmp/foo". + + 3. Support for lists, e.g. "--define os=linux --define + os=redhat" would set result$os$linux=TRUE and + result$os$redhat=TRUE. + + 4. Support for incremental, argument-less flags, e.g. + "/path/to/script -vvv" should set v=3. + + 5. Support partial-but-unique string match on options, + e.g. "--verb" and "--verbose" both match long flag + "--verbose". + + 6. No support for mixing in positional arguments or extra + arguments that don't match any options. For example, you + can't do "my.R --arg1 1 foo bar baz" and recover "foo", + "bar", "baz" as a list. Likewise for "my.R foo --arg1 1 + bar baz". +} +\examples{ +#!/path/to/Rscript +library('getopt'); +#get options, using the spec as defined by the enclosed list. +#we read the options from the default: commandArgs(TRUE). +spec = matrix(c( + 'verbose', 'v', 2, "integer", + 'help' , 'h', 0, "logical", + 'count' , 'c', 1, "integer", + 'mean' , 'm', 1, "double", + 'sd' , 's', 1, "double" +), byrow=TRUE, ncol=4); +opt = getopt(spec); + +# if help was asked for print a friendly message +# and exit with a non-zero error code +if ( !is.null(opt$help) ) { + cat(getopt(spec, usage=TRUE)); + q(status=1); +} + +#set some reasonable defaults for the options that are needed, +#but were not specified. +if ( is.null(opt$mean ) ) { opt$mean = 0 } +if ( is.null(opt$sd ) ) { opt$sd = 1 } +if ( is.null(opt$count ) ) { opt$count = 10 } +if ( is.null(opt$verbose ) ) { opt$verbose = FALSE } + +#print some progress messages to stderr, if requested. +if ( opt$verbose ) { write("writing...",stderr()); } + +#do some operation based on user input. +cat(paste(rnorm(opt$count,mean=opt$mean,sd=opt$sd),collapse="\\n")); +cat("\\n"); + +#signal success and exit. +#q(status=0); +} +\author{ + Allen Day +} +\seealso{ + \code{\link{getopt}} +} +\keyword{data} + diff -Nru r-cran-getopt-1.17/man/getopt.package.Rd r-cran-getopt-1.19.1/man/getopt.package.Rd --- r-cran-getopt-1.17/man/getopt.package.Rd 2011-09-15 21:04:45.000000000 +0000 +++ r-cran-getopt-1.19.1/man/getopt.package.Rd 1970-01-01 00:00:00.000000000 +0000 @@ -1,203 +0,0 @@ -\name{getopt.package} -\alias{getopt} -%- Also NEED an '\alias' for EACH other topic documented here. -\title{ C-like getopt behavior } -\description{ -getopt is primarily intended to be used with ``\link{Rscript}''. It facilitates writing -``\#!'' shebang scripts that accept short and long flags/options. It can also -be used from ``R'' directly, but is probably less useful in this context. - -getopt() returns a \link{list} data structure containing \link{names} of the -flags that were present in the \link{character} \link{vector} passed in under -the \emph{opt} argument. Each value of the \link{list} is coerced to the data -type specified according to the value of the \emph{spec} argument. See below -for details. - -Notes on naming convention: - -1. An \emph{option} is one of the shell-split input strings. - -2. A \emph{flag} is a type of \emph{option}. a \emph{flag} can be defined -as having no \emph{argument} (defined below), a required \emph{argument}, or an -optional \emph{argument}. - -3. An \emph{argument} is a type of \emph{option}, and is the value associated -with a flag. - -4. A \emph{long flag} is a type of \emph{flag}, and begins with the string -``--''. If the \emph{long flag} has an associated \emph{argument}, it may be -delimited from the \emph{long flag} by either a trailing \emph{=}, or may be -the subsequent \emph{option}. - -5. A \emph{short flag} is a type of \emph{flag}, and begins with the string -``-''. If a \emph{short flag} has an associated \emph{argument}, it is the -subsequent \emph{option}. \emph{short flags} may be bundled together, sharing -a single leading ``-'', but only the final \emph{short flag} is able to have a -corresponding \emph{argument}. -} -\usage{getopt( spec=NULL, opt=commandArgs(TRUE), command=strsplit(commandArgs(FALSE)[4],"=")[[1]][2], usage=FALSE, debug=FALSE )} -%- maybe also 'usage' for other objects documented here. -\arguments{ - \item{spec}{ - The getopt specification, or spec of what options are considered valid. The - specification must be either a 4-5 column \link{matrix}, or a \link{character} - \link{vector} coercible into a 4 column \link{matrix} using - \link{matrix}(x,ncol=4,byrow=TRUE) command. The \link{matrix}/\link{vector} - contains: - - Column 1: the \emph{long flag} name. A multi-\link{character} string. - - Column 2: \emph{short flag} alias of Column 1. A single-\link{character} - string. - - Column 3: \emph{Argument} mask of the \emph{flag}. An \link{integer}. - Possible values: 0=no argument, 1=required argument, 2=optional argument. - - Column 4: Data type to which the \emph{flag}'s argument shall be cast using - \link{storage.mode}. A multi-\link{character} string. This only - considered for same-row Column 3 values of {1,2}. Possible values: - \link{logical}, \link{integer}, \link{double}, \link{complex}, - \link{character}. - - Column 5 (optional): A brief description of the purpose of the option. - - The terms \emph{option}, \emph{flag}, \emph{long flag}, \emph{short flag}, - and \emph{argument} have very specific meanings in the context of this - document. Read the ``Description'' section for definitions. - } - \item{opt}{ - This defaults to the return value of \link{commandArgs}(TRUE). - - If R was invoked directly via the ``R'' command, this corresponds - to all arguments passed to R after the ``--args'' flag. - - If R was invoked via the ``\link{Rscript}'' command, this corresponds to all - arguments after the name of the R script file. - - Read about \link{commandArgs} and \link{Rscript} to learn more. - } - \item{command}{ - The string to use in the usage message as the name of the script. See - argument \emph{usage}. - } - \item{usage}{ - If TRUE, argument \emph{opt} will be ignored and a usage statement (character - string) will be generated and returned from \emph{spec}. - } - \item{debug}{ - This is used internally to debug the getopt() function itself. - } -} -\details{ -Current issues: - -1. No support for multiple, identical flags, e.g. for "-m 3 -v 5 -v", the -trailing "-v" overrides the preceding "-v 5", result is v=TRUE (or equivalent -typecast). - -2. No support for multi-valued flags, e.g. -"--libpath=/usr/local/lib --libpath=/tmp/foo". - -3. No support for lists, e.g. "--define os=linux --define os=redhat" -would set result$os$linux=TRUE and result$os$redhat=TRUE. - -4. No support for incremental, argument-less flags, e.g. "/path/to/script -vvv" -should set v=3. - -5. Need more unit tests (see end of examples section). - -6. Support partial-but-unique string match on options, e.g. "--verb" and -"--verbose" both match long flag "--verbose". - -7. No support for mixing in positional arguments or extra arguments that don't -match any options. For example, you can't do "my.R --arg1 1 foo bar baz" and -recover "foo", "bar", "baz" as a list. Likewise for "my.R foo --arg1 1 bar baz". - -} -\author{ Allen Day } -\seealso{ \code{\link{getopt}} } -\examples{ -#!/path/to/Rscript -library('getopt'); -#get options, using the spec as defined by the enclosed list. -#we read the options from the default: commandArgs(TRUE). -opt = getopt(c( - 'verbose', 'v', 2, "integer", - 'help' , 'h', 0, "logical", - 'count' , 'c', 1, "integer", - 'mean' , 'm', 1, "double", - 'sd' , 's', 1, "double" -)); - -#help was asked for. -if ( !is.null(opt$help) ) { - #get the script name (only works when invoked with Rscript). - self = commandArgs()[1]; - #print a friendly message and exit with a non-zero error code - cat(paste("Usage: ",self," [-[vh]] [-[-mean|m] ] [-[-sd|s] ] [-[-count|c] ]\n",sep="")); - q(status=1); -} - -#set some reasonable defaults for the options that are needed, -#but were not specified. -if ( is.null(opt$mean ) ) { opt$mean = 0 } -if ( is.null(opt$sd ) ) { opt$sd = 1 } -if ( is.null(opt$count ) ) { opt$count = 10 } -if ( is.null(opt$verbose ) ) { opt$verbose = FALSE } - -#print some progress messages to stderr, if requested. -if ( opt$verbose ) { write("writing...",stderr()); } - -#do some operation based on user input. -cat(paste(rnorm(opt$count,mean=opt$mean,sd=opt$sd),collapse="\n")); -cat("\n"); - -#signal success and exit. -#q(status=0); - -### END ### -#regression tests follow. not part of the example. -spec = c( - 'verbose', 'v', 2, "integer", - 'help' , 'h', 0, "logical", - 'dummy1' , 'd', 0, "logical", - 'dummy2' , 'e', 2, "logical", - 'count' , 'c', 1, "integer", - 'mean' , 'm', 1, "double", - 'sd' , 's', 1, "double", - 'output' , 'O', 1, "character" -); -opt = getopt(spec, c('-c', '-1', '-m', '-1.2')); -opt = getopt(spec, c('-v', '-m', '3')); -opt = getopt(spec, c('-m', '3', '-v')); -opt = getopt(spec, c('-m', '3', '-v', '2', '-v')); -opt = getopt(spec, c('-O', '-', '-m', '3')); -opt = getopt(spec, c('-m', '3', '-O', '-')); -opt = getopt(spec, c('-de')); -opt = getopt(spec, c('-ed')); -opt = getopt(spec, c('-d')); -opt = getopt(spec, c('-e', '1')); -opt = getopt(spec, c('-de', '1')); -opt = getopt(spec, c('--verbose')); -opt = getopt(spec, c('--help')); -opt = getopt(spec, c('--verbose', '--help')); -opt = getopt(spec, c('--verbose', '--mean', '5')); -opt = getopt(spec, c('--mean=5')); -opt = getopt(spec, c('--verbose', '--mean=5')); -opt = getopt(spec, c('--verbose', '--mean=5', '--sd', '5')); -opt = getopt(spec, c('--mean=5', '--sd', '5', '--verbose')); -opt = getopt(spec, c('--mean=5', '--verbose', '--sd', '5')); - -spec = c( - 'date' , 'd', 1, "character", - 'help' , 'h', 0, "logical", - 'getdata' , 'g', 0, "logical", - 'market' , 'm', 1, "character", - 'threshold', 't', 1, "double" -); -opt = getopt(spec, c('--date','20080421','--market','YM','--getdata')); -opt = getopt(spec, c('--date','20080421','--getdata','--market','YM')); -opt = getopt(spec, c('--date','20080421','--getdata','--market','YM'),debug=TRUE); -print(getopt(spec, c('--date','20080421','--getdata','--market','YM'),usage=TRUE)); -} -\keyword{ data }% at least one, from doc/KEYWORDS diff -Nru r-cran-getopt-1.17/tests/run-all.R r-cran-getopt-1.19.1/tests/run-all.R --- r-cran-getopt-1.17/tests/run-all.R 1970-01-01 00:00:00.000000000 +0000 +++ r-cran-getopt-1.19.1/tests/run-all.R 2012-11-10 02:20:24.000000000 +0000 @@ -0,0 +1,4 @@ +library("testthat") +library("getopt") + +test_package("getopt") diff -Nru r-cran-getopt-1.17/tests/unit_tests.R r-cran-getopt-1.19.1/tests/unit_tests.R --- r-cran-getopt-1.17/tests/unit_tests.R 2011-09-15 21:04:45.000000000 +0000 +++ r-cran-getopt-1.19.1/tests/unit_tests.R 1970-01-01 00:00:00.000000000 +0000 @@ -1,72 +0,0 @@ -library("testthat") -library("getopt") - -context("Testing getopt") -test_that("getopt works as expected", { - spec = matrix(c( - 'verbose', 'v', 2, "integer", - 'help' , 'h', 0, "logical", - 'dummy1' , 'd', 0, "logical", - 'dummy2' , 'e', 2, "logical", - 'count' , 'c', 1, "integer", - 'mean' , 'm', 1, "double", - 'sd' , 's', 1, "double", - 'output' , 'O', 1, "character" - ), ncol=4, byrow=TRUE); - sort_list <- function(unsorted_list) { - for(ii in seq(along=unsorted_list)) { - if(is.list(unsorted_list[[ii]])) { - unsorted_list[[ii]] <- sort_list(unsorted_list[[ii]]) - } - } - unsorted_list[sort(names(unsorted_list))] - } - expect_equal(sort_list(getopt(spec, c('-c', '-1', '-m', '-1.2'))), - sort_list(list(ARGS=character(0), count=-1, mean=-1.2))); - expect_equal(sort_list(getopt(spec, c('-v', '-m', '3'))), - sort_list(list(ARGS=character(0), verbose=1, mean=3))); - expect_equal(sort_list(getopt(spec, c('-m', '3', '-v'))), - sort_list(list(ARGS=character(0), mean=3, verbose=1))); - expect_equal(sort_list(getopt(spec, c('-m', '3', '-v', '2', '-v'))), - sort_list(list(ARGS=character(0), mean=3, verbose=1))); - expect_equal(sort_list(getopt(spec, c('-O', '-', '-m', '3'))), - sort_list(list(ARGS=character(0), output="-", mean=3))); - expect_equal(sort_list(getopt(spec, c('-O', '-', '-m', '3'))), - sort_list(getopt(spec, c('-m', '3', '-O', '-')))); - expect_equal(sort_list(getopt(spec, c('-de'))), - sort_list(getopt(spec, c('-ed')))); - expect_equal(sort_list(getopt(spec, c('-de'))), - sort_list(list(ARGS=character(0), dummy1=TRUE, dummy2=TRUE))); - expect_equal(sort_list(getopt(spec, c('-de', '1'))), - sort_list(list(ARGS=character(0), dummy1=TRUE, dummy2=NA))); - expect_equal(sort_list(getopt(spec, c('--verbose'))), - sort_list(list(ARGS=character(0), verbose=1))); - expect_equal(sort_list(getopt(spec, c('--verbose', '--help'))), - sort_list(list(ARGS=character(0), verbose=1, help=TRUE))); - expect_equal(sort_list(getopt(spec, c('--verbose', '--mean', '5'))), - sort_list(list(ARGS=character(0), verbose=1, mean=5))); - expect_equal(sort_list(getopt(spec, c('--mean=5'))), - sort_list(list(ARGS=character(0), mean=5))); - expect_equal(sort_list(getopt(spec, c('--verbose', '--mean=5', '--sd', '5'))), - sort_list(list(ARGS=character(0), verbose=1, mean=5, sd=5))); - expect_equal(sort_list(getopt(spec, c('--verbose', '--mean=5', '--sd', '5'))), - sort_list(getopt(spec, c('--mean=5', '--sd', '5', '--verbose')))); - spec = c( - 'date' , 'd', 1, "character", - 'help' , 'h', 0, "logical", - 'getdata' , 'g', 0, "logical", - 'market' , 'm', 1, "character", - 'threshold', 't', 1, "double" - ); - # should give warning is spec is not matrix - expect_that(getopt(spec, c('--date','20080421','--market','YM','--getdata')), gives_warning()); - expect_equal(sort_list(getopt(spec, c('--date','20080421','--market','YM','--getdata'))), - sort_list(list(ARGS=character(0), date='20080421', market='YM', getdata=TRUE))) - expect_equal(sort_list(getopt(spec, c('--date','20080421','--market','YM','--getdata'))), - sort_list(getopt(spec, c('--date','20080421','--getdata','--market','YM')))); - expect_that(getopt(spec, c('--date','20080421','--getdata','--market','YM'),debug=TRUE), - prints_text("processing ")); - expect_that(print(getopt(spec, c('--date','20080421','--getdata','--market','YM'),usage=TRUE)), - prints_text("Usage: ")); -}) -