[med-svn] [r-cran-futile.options] 05/10: New upstream version 1.0.0
Andreas Tille
tille at debian.org
Thu Sep 28 16:07:39 UTC 2017
This is an automated email from the git hooks/post-receive script.
tille pushed a commit to branch master
in repository r-cran-futile.options.
commit c9a4a61297a340771fdd5abbda1017517b4c26a0
Author: Andreas Tille <tille at debian.org>
Date: Thu Sep 28 19:57:00 2017 +0200
New upstream version 1.0.0
---
DESCRIPTION | 14 ++++++
NAMESPACE | 1 +
R/deprecated.R | 9 ++++
R/options.R | 102 ++++++++++++++++++++++++++++++++++++++++++
debian/changelog | 12 -----
debian/compat | 1 -
debian/control | 21 ---------
debian/copyright | 27 -----------
debian/rules | 3 --
debian/source/format | 1 -
debian/watch | 2 -
man/OptionsManager.Rd | 85 +++++++++++++++++++++++++++++++++++
man/futile.options-package.Rd | 46 +++++++++++++++++++
13 files changed, 257 insertions(+), 67 deletions(-)
diff --git a/DESCRIPTION b/DESCRIPTION
new file mode 100644
index 0000000..0179698
--- /dev/null
+++ b/DESCRIPTION
@@ -0,0 +1,14 @@
+Package: futile.options
+Type: Package
+Title: Futile options management
+Version: 1.0.0
+Date: 2010-04-05
+Author: Brian Lee Yung Rowe
+Maintainer: Brian Lee Yung Rowe <r at nurometic.com>
+Depends: R (>= 2.8.0)
+Description: A scoped options management framework
+License: LGPL-3
+LazyLoad: yes
+Packaged: Mon Apr 5 21:09:07 2010; brian
+Repository: CRAN
+Date/Publication: 2010-04-06 08:57:40
diff --git a/NAMESPACE b/NAMESPACE
new file mode 100644
index 0000000..9c9f9ac
--- /dev/null
+++ b/NAMESPACE
@@ -0,0 +1 @@
+exportPattern("^[^\\.]")
diff --git a/R/deprecated.R b/R/deprecated.R
new file mode 100644
index 0000000..7ce293a
--- /dev/null
+++ b/R/deprecated.R
@@ -0,0 +1,9 @@
+# This is here for backwards compatibility
+options.manager <- function(option.name, defaults=NULL)
+{
+ OptionsManager(option.name, defaults)
+}
+
+# This is here for backwards compatibility
+reset.options <- function(option.name, ...) resetOptions(option.name, ...)
+
diff --git a/R/options.R b/R/options.R
new file mode 100644
index 0000000..46f70ce
--- /dev/null
+++ b/R/options.R
@@ -0,0 +1,102 @@
+# Passing the update argument to the resulting options manager will update
+# the provided keys and values. Note that update[[1]] are the keys and
+# update[[2]] are the values.
+# Examples of using options.manager
+# log.options <- options.manager('log.options', defaults=list(logger='ROOT'))
+# log.options(a=123, b=6234)
+# log.options()
+# log.options(a=123, b=6234)
+# resetOptions(log.options, c=29)
+# log.options()
+# Generates a function to retrieve options for a given name
+OptionsManager <- function(option.name, defaults=list())
+{
+ # Define a function to update options
+ up <- function(os)
+ {
+ my.options <- list()
+ my.options[[option.name]] <- os
+ options(my.options)
+ }
+
+ up(list())
+
+ function(..., simplify=FALSE, update=list())
+ {
+ os <- getOption(option.name)
+ if (length(os) < 1)
+ {
+ os <- defaults
+ up(os)
+ }
+
+ args <- list(...)
+ if (length(update) > 0)
+ invisible(updateOptions(option.name, update[[1]], update[[2]]))
+ if (length(args) == 0) return(os)
+
+ # Getter
+ if (any(is.null(names(args))))
+ {
+ ns <- sapply(args, '[')
+ ns <- ns[ns %in% names(os)]
+ if (length(ns) == 0) return(NULL)
+ if (length(ns) == 1) return(os[[ns]])
+ return(sapply(os[ns], '[', simplify=simplify))
+ }
+
+ # Setter
+ for (x in names(args)) os[[x]] <- args[[x]]
+ up(os)
+ invisible()
+ }
+}
+
+# Reset options for a given option set
+resetOptions <- function(option.name, ...) UseMethod('resetOptions')
+resetOptions.default <- function(option.name, ...)
+ resetOptions.character(deparse(substitute(option.name)), ...)
+
+resetOptions.character <- function(option.name, ...)
+{
+ my.options <- list()
+ my.options[[option.name]] <- NA
+ options(my.options)
+
+ args <- list(...)
+ if (length(args) > 0)
+ {
+ ks <- names(args)
+ vs <- sapply(args, '[')
+ kvs <- paste(ks,vs, sep='=')
+ line <- paste(kvs, collapse=',')
+
+ exp <- parse(text=paste('new.options <- ',option.name,'(',line,')',sep=''))
+ eval(exp)
+ }
+ invisible()
+}
+
+# Update a specific option in an option set (a generated function)
+# This is primarily used when dynamic creation of options variables are needed.
+updateOptions <- function(option.name, ...) UseMethod('updateOptions')
+updateOptions.default <- function(option.name, ...)
+ updateOptions.character(deparse(substitute(option.name)), ...)
+
+updateOptions.character <- function(option.name, key, value, ...)
+{
+ os <- getOption(option.name)
+ if (is.null(os))
+ stop(paste("Cannot update non-existent options:",option.name))
+
+ if (length(key) == 1)
+ os[[key]] <- value
+ else
+ for (idx in 1:length(key)) os[[key[idx]]] <- value[idx]
+ my.options <- list()
+ my.options[[option.name]] <- os
+ options(my.options)
+
+ invisible()
+}
+
diff --git a/debian/changelog b/debian/changelog
deleted file mode 100644
index 507b235..0000000
--- a/debian/changelog
+++ /dev/null
@@ -1,12 +0,0 @@
-r-cran-futile.options (1.0.0-2) unstable; urgency=medium
-
- * Mention location of license as comment in d/copyright
- * Architecture all rather than any
-
- -- Andreas Tille <tille at debian.org> Thu, 28 May 2015 15:36:38 +0200
-
-r-cran-futile.options (1.0.0-1) unstable; urgency=medium
-
- * Initial upload (Closes: #784872)
-
- -- Andreas Tille <tille at debian.org> Sat, 09 May 2015 08:52:18 +0200
diff --git a/debian/compat b/debian/compat
deleted file mode 100644
index ec63514..0000000
--- a/debian/compat
+++ /dev/null
@@ -1 +0,0 @@
-9
diff --git a/debian/control b/debian/control
deleted file mode 100644
index 2643a7d..0000000
--- a/debian/control
+++ /dev/null
@@ -1,21 +0,0 @@
-Source: r-cran-futile.options
-Maintainer: Debian Med Packaging Team <debian-med-packaging at lists.alioth.debian.org>
-Uploaders: Andreas Tille <tille at debian.org>
-Section: gnu-r
-Priority: optional
-Build-Depends: debhelper (>= 9),
- r-base-dev,
- cdbs
-Standards-Version: 3.9.6
-Vcs-Browser: http://anonscm.debian.org/viewvc/debian-med/trunk/packages/R/r-cran-futile.options/
-Vcs-Svn: svn://anonscm.debian.org/debian-med/trunk/packages/R/r-cran-futile.options/
-Homepage: http://cran.r-project.org/web/packages/futile.options
-
-Package: r-cran-futile.options
-Architecture: all
-Depends: ${shlibs:Depends},
- ${misc:Depends},
- ${R:Depends}
-Description: GNU R futile options management
- This GNU R package provides a scoped options management framework.
-
diff --git a/debian/copyright b/debian/copyright
deleted file mode 100644
index a9ed4cf..0000000
--- a/debian/copyright
+++ /dev/null
@@ -1,27 +0,0 @@
-Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-Upstream-Contact: Brian Lee Yung Rowe <r at zatonovo.com>
-Upstream-Name: futile.options
-Source: http://cran.r-project.org/web/packages/futile.options/
-
-Files: *
-Copyright: 2010 Brian Lee Yung Rowe <r at zatonovo.com>
-License: LGPL-3
-Comment: License is mentioned in the metadata of the file DESCRIPTION
- and at the download page mentioned above.
-
-Files: debian/*
-Copyright: 2015 Andreas Tille <tille at debian.org>
-License: LGPL-3
-
-License: LGPL-3
- This program is free software: you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation, either version 3 of the License.
- .
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU Lesser General Public License for more details.
- .
- On Debian systems, the complete text of the GNU Lesser General Public
- License version 3 can be found in ‘/usr/share/common-licenses/LGPL-3’.
diff --git a/debian/rules b/debian/rules
deleted file mode 100755
index 2fbba2d..0000000
--- a/debian/rules
+++ /dev/null
@@ -1,3 +0,0 @@
-#!/usr/bin/make -f
-
-include /usr/share/R/debian/r-cran.mk
diff --git a/debian/source/format b/debian/source/format
deleted file mode 100644
index 163aaf8..0000000
--- a/debian/source/format
+++ /dev/null
@@ -1 +0,0 @@
-3.0 (quilt)
diff --git a/debian/watch b/debian/watch
deleted file mode 100644
index f135bd2..0000000
--- a/debian/watch
+++ /dev/null
@@ -1,2 +0,0 @@
-version=3
-http://cran.r-project.org/src/contrib/futile.options_([\d.-]*)\.tar.gz
diff --git a/man/OptionsManager.Rd b/man/OptionsManager.Rd
new file mode 100644
index 0000000..e2ce224
--- /dev/null
+++ b/man/OptionsManager.Rd
@@ -0,0 +1,85 @@
+\name{OptionsManager}
+\alias{OptionsManager}
+\alias{resetOptions}
+\alias{resetOptions.default}
+\alias{resetOptions.character}
+\alias{updateOptions}
+\alias{updateOptions.default}
+\alias{updateOptions.character}
+\alias{options.manager}
+\alias{reset.options}
+\title{ Futile options management }
+\description{
+ Included as part of futile is an options subsystem that facilitates the
+ management of options for a particular application. The options.manager
+ function produces a scoped options set within the environment, to protect
+ against collisions with other libraries or applications. The options subsystem
+ also provides default settings that can be restored by calling reset.options.
+}
+\usage{
+OptionsManager(option.name, defaults = list())
+\method{resetOptions}{default}(option.name, ...)
+\method{resetOptions}{character}(option.name, ...)
+\method{updateOptions}{default}(option.name, ...)
+\method{updateOptions}{character}(option.name, key, value, ...)
+options.manager(option.name, defaults = NULL)
+reset.options(option.name, ...)
+}
+\arguments{
+ \item{option.name}{ The namespace of the options set }
+ \item{defaults}{ A list of default values to use for the new options manager }
+ \item{key}{ A vector of keys in the options that need to be updated }
+ \item{value}{ A vector of values that correspond to the keys above }
+ \item{\dots}{ Option values to set after resetting }
+}
+\details{
+ Using the options subsystem is simple. The first step is to create a specific
+ options manager for a given namespace by using the 'OptionsManager' function.
+ It is possible to specify some default values by passing a list to the default
+ argument. This function returns a specialized function for managing options in
+ the given namespace.
+
+ With the new function, options can be set and accessed in an isolated
+ namespace. The options can also be reset using 'resetOptions' to the default
+ values.
+
+ Note that if multiple values are accessed, to support lists and other complex
+ data structures, the output is a list. If a vector is preferred, pass
+ simplify=TRUE as an argument to the user-defined options management function.
+
+ Another arugment available in the resulting function is 'update', which allows
+ specific values to be updated dynamically rather than via named key=value
+ pairs. This is useful in certain situations but can be safely ignored for
+ most situations.
+
+ To reset options back to default settings, use the 'reset.options' function.
+
+ In certain cases, stored options may need to be set programattically, i.e.
+ their name is constructed dynamically. When this occurs, use update.options to
+ set the values.
+
+ NOTE: The functions 'options.manager' and 'reset.options' are deprecated but
+ still extant to maintain backwards compatibility. All futile libraries are
+ renamed to avoid naming collisions with S3 generics. Furthermore, any futile
+ function that returns a function will be PascalCased, whereas all others will
+ be camelCased. The dot notation is reserved strictly for S3 generics.
+}
+\value{
+ The 'OptionsManager' function produces a custom function to manage options
+ for the specified namespace. Use this function to access and set options in
+ your code.
+}
+\author{ Brian Lee Yung Rowe }
+\examples{
+ my.options <- OptionsManager('my.options', default=list(a=2,b=3))
+ my.options(c=4,d='hello')
+ my.options('b')
+ my.options('c')
+
+ resetOptions(my.options)
+ my.options('c')
+
+ updateOptions(my.options, paste('key',1,sep='.'), 10)
+ my.options('key.1')
+}
+\keyword{ array }
diff --git a/man/futile.options-package.Rd b/man/futile.options-package.Rd
new file mode 100644
index 0000000..27eb999
--- /dev/null
+++ b/man/futile.options-package.Rd
@@ -0,0 +1,46 @@
+\name{futile.options-package}
+\alias{futile.options-package}
+\alias{futile.options}
+\docType{package}
+\title{
+ A scoped options management framework
+}
+\description{
+ The 'futile.options' subsystem provides an easy user-defined options
+ management system that is properly scoped. This means that options created
+ via 'futile.options' are fully self-contained and will not collide with
+ options defined in other packages. This package is a self-contained package
+ within the futile suite of libraries.
+}
+\details{
+\tabular{ll}{
+Package: \tab futile.options\cr
+Type: \tab Package\cr
+Version: \tab 1.0.0\cr
+Date: \tab 2010-04-05\cr
+License: \tab LGPL-3\cr
+LazyLoad: \tab yes\cr
+}
+ While R provides a useful mechanism for storing and retrieving options, there
+ is a danger that variable names collide with names defined by a package that
+ a user's code depends. These types of errors are difficult to detect and
+ should be avoided. Using 'futile.options' addresses this problem by properly
+ scoping variables within its own custom 'namespace'. This is handled by the
+ 'OptionsManager', which acts as a generator for functions that manage user-
+ defined options.
+
+ An added benefit to the package is that default values are automatically
+ supported in the creation of the bespoke options manager.
+}
+\author{
+Brian Lee Yung Rowe <r at nurometic.com>
+}
+\keyword{ package }
+\keyword{ attribute }
+\keyword{ logic }
+\seealso{ \code{\link{OptionsManager}} }
+\examples{
+ my.options <- OptionsManager('my.options', defaults=list(a=1,b=2))
+ my.options(a=5, c=3)
+ my.options('a')
+}
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/r-cran-futile.options.git
More information about the debian-med-commit
mailing list