0.1.0 Release of 'envvar'

Not sure about the presence of the .Rd and .html files
but everything else seems to be properly handled by
hadley/devtools.  Pushing this to GitHub and will
see how well it installs using devtools::install_github(...)

.Rbuildignore

@@ -0,0 +1 @@
+^.*\.Rproj$

.gitignore

@@ -1,3 +1,4 @@
 .Rproj.user
 .Rhistory
 .RData
+inst/doc

DESCRIPTION

@@ -0,0 +1,12 @@
+Package: envvar
+Type: Package
+Title: Envrionment Variables Helper Functions
+Version: 0.1.0
+Date: 2015-02-24
+Author: David G. Johnston
+Maintainer: David G. Johnston <[email protected]>
+Description: Provides functions to semantically manipulate environment variables.
+License: Unlimited
+Suggests: knitr,
+    testthat
+VignetteBuilder: knitr

NAMESPACE

@@ -0,0 +1,3 @@
+# Generated by roxygen2 (4.1.0): do not edit by hand
+
+export(env_or_default)

R/envvar-internal.R

@@ -0,0 +1,126 @@
+.Random.seed <-
+c(403L, 10L, 528445139L, 1410403569L, -864925664L, 318320318L, 
+-1920251191L, -1675181957L, -1768849846L, 1002072748L, -1585750609L, 
+-2130039451L, 656128796L, -608592014L, 1749414893L, 899167271L, 
+-1799607218L, -1954590552L, 2054340267L, -1630626871L, 804779992L, 
+-388260218L, 1985210209L, -915612941L, 2009580898L, 1758024660L, 
+1999328983L, 43130061L, 1530723428L, -646147510L, 1049114549L, 
+-983020785L, -2135082986L, 1553482432L, -594373501L, 865075361L, 
+863676048L, -1180699282L, 390980377L, -1581455445L, 165168538L, 
+-1675697828L, -1284474785L, -402139083L, -180872244L, -337260766L, 
+-863497859L, -2044372361L, -398818402L, -1898835368L, 2021366715L, 
+1936026969L, -994973976L, -798550250L, 1290958993L, -343517885L, 
+1936199762L, 1675137764L, -281279193L, -674644611L, 483234932L, 
+1253277274L, 1909549733L, 1665667263L, -875629754L, 717300176L, 
+-1190935565L, 1136646929L, -1783149760L, -1929399522L, 1053932521L, 
+-1364274917L, -2085074134L, 1292553292L, -1877244913L, 1082404677L, 
+-1028404996L, -188795054L, 1430747341L, 1204627591L, 1100823406L, 
+1509698888L, 750074187L, 63040681L, -825537032L, -1084615386L, 
+-1412151743L, -152645677L, -1422768766L, -1430754892L, 1116615991L, 
+-1534066643L, -1840886460L, 1168001642L, -1001954091L, -1164782993L, 
+1287370614L, 2098927776L, -1680518813L, -1406795263L, 49222000L, 
+-241438450L, 166536057L, 1000270603L, -1129180102L, 1772778300L, 
+-2099533697L, -981677099L, -2100189716L, 1294346050L, -1749972835L, 
+1011339543L, 1856096382L, -491003848L, -1837132005L, -280980359L, 
+1160494280L, -704590602L, 1676029233L, 1096879459L, -1308438734L, 
+856598660L, -2122754873L, -167651427L, 400474900L, -1593298502L, 
+328419333L, 120856031L, 761811046L, 154230768L, 1489828115L, 
+454919857L, -1931267744L, 474162942L, 2042937993L, -732930629L, 
+1645070218L, -224145812L, -1795698705L, -446019547L, -773461796L, 
+-723202382L, 1463280045L, -1383479961L, -881569138L, -1403503768L, 
+-1927281813L, 1640226057L, -541969512L, 581206726L, -1060567007L, 
+1425972403L, -1554440670L, 1453686804L, 1167041687L, 1936559757L, 
+-1155547228L, 413860234L, -1683169803L, 2033971279L, -801519786L, 
+-2101314048L, -1561940157L, 579020513L, -1633622960L, 1878092974L, 
+914085977L, -1281173397L, 1555709402L, -2123913572L, 1433073823L, 
+-1701874955L, 1064972172L, 1335164514L, 1617551933L, 1254403255L, 
+795980638L, -1157458280L, 1261590011L, 472729497L, 38842408L, 
+-6129450L, 2014575953L, 483068931L, 1440568210L, -2046344924L, 
+620918759L, 1864993853L, 734837428L, -2103846630L, -882918811L, 
+873590527L, 1389081478L, 719639824L, 1126075827L, -736022959L, 
+-1815933440L, -1814476066L, 2074560809L, -1412606757L, 992506858L, 
+932815756L, -1648057137L, 48057477L, -1730296004L, -1208322542L, 
+2063062285L, -452755897L, -59931602L, -1562973816L, -319647605L, 
+-921539991L, 1305196088L, 1794821862L, -1617417599L, 289027603L, 
+-1004674622L, -1560769932L, 212986999L, -769731219L, -2064963068L, 
+596314410L, 1073110677L, -1016236753L, 1623429174L, 395887712L, 
+482880163L, 2092973505L, 1870043568L, -2076470640L, 394839842L, 
+674108936L, 249840396L, 2069306268L, -1571691502L, 2033431424L, 
+1347398420L, 136942888L, -907186118L, -2140040240L, -713434516L, 
+-371549132L, 1936677010L, 485007712L, -1735717556L, -1574056480L, 
+-1794886750L, -759297112L, -855290740L, -646323268L, -1717822350L, 
+-5507088L, 1655608388L, -806422440L, 1485422650L, -1387581328L, 
+-1505470916L, -1587161324L, -1101124926L, 384119520L, 1272638588L, 
+2006670544L, 625552290L, -1804890584L, -432260852L, -39258180L, 
+-1432516302L, -634609472L, -302833100L, 1002506952L, -1964959046L, 
+1091216528L, -1842456852L, 757546580L, -948681070L, 946009888L, 
+-1697273908L, -2104770336L, 783007426L, 1866466344L, -594097236L, 
+-1754793284L, -1376990734L, -1067067856L, 1207805860L, 1015763384L, 
+-1454886054L, -170330992L, 287128444L, -504391916L, 210832706L, 
+1738120960L, 1381094332L, 986115920L, 1202387234L, 895746632L, 
+-162451444L, -1163799460L, -232586798L, 2068028928L, 2130792788L, 
+1313616104L, 2114031866L, 1076709072L, -1010208468L, -1115221772L, 
+779275666L, -889976480L, 2004338700L, -1336769824L, 1823767138L, 
+1197404840L, -1471862196L, 1802821500L, -917879502L, 958617200L, 
+-112848060L, -227530792L, -428025990L, 1050682928L, 1753700284L, 
+1547245140L, -1933303742L, -1247137632L, 1310529212L, 980507088L, 
+-1941982366L, -400575768L, -1200463668L, -1898511876L, 1775673842L, 
+1058081408L, 1745960436L, 1863657096L, -1754489030L, 2072654672L, 
+214592620L, 462336404L, 1695028306L, -528285216L, -858321716L, 
+692126880L, -406166142L, -1951692568L, -636340500L, -1592720068L, 
+1042521202L, 834107504L, 961622052L, 429702200L, -2035781862L, 
+-2145850160L, -642941124L, -2055645292L, 764396418L, -713545280L, 
+1170169404L, -2074180208L, 1051680290L, 136471816L, 474209932L, 
+-451227876L, -980647790L, -1723573888L, -557115884L, 1989414696L, 
+-1665611206L, 1218551248L, -37918356L, -1676614732L, -2105182190L, 
+1111180768L, -1194395700L, 1709342944L, 1998141474L, 380449064L, 
+735940108L, 295618364L, 1497773042L, 928647920L, 2064715332L, 
+-811134376L, 74039098L, 344856048L, 1104533180L, 1880258836L, 
+371724994L, 1590420576L, -2083212420L, 41797584L, 389001506L, 
+1359297192L, 1246878604L, -313390916L, -176857294L, -159552960L, 
+-219702092L, -156708280L, -493406790L, -2010283504L, 478061292L, 
+-1936981676L, 449208594L, -231993952L, -1393093940L, -1180836256L, 
+1914451906L, -335636696L, -44101716L, -627535044L, 626125170L, 
+-386622672L, -596763356L, -536843464L, 1147260634L, -1511110768L, 
+-2109182212L, 1417411476L, 528158786L, -107375360L, 677553212L, 
+-796532400L, -2097954654L, 557125960L, -894597364L, -60718372L, 
+-1995891374L, -1168960384L, 972345428L, 1418964968L, 2012276986L, 
+1253268304L, -902815956L, -934082188L, -1036088430L, 1653315680L, 
+-2019295860L, 1899174752L, -1052182046L, -1991101528L, 1756820684L, 
+1991782396L, 105842098L, 756012528L, -2146268220L, -862972584L, 
+-622904966L, 364749744L, 1447229884L, -495081388L, -828356670L, 
+-769658848L, 794175676L, -1453964720L, 154264546L, -1352171416L, 
+-1810715118L, -1961199129L, 1963013553L, -1331301386L, 298556948L, 
+1828684069L, 107817519L, -1350897688L, 1896634566L, 743259507L, 
+-1514428971L, 1908533682L, -908335232L, -1706304663L, 1506471899L, 
+1756378924L, -985884358L, 1929807855L, -747793799L, 1528771854L, 
+-1763992356L, 73626445L, -1894327625L, -340330432L, -1703053026L, 
+-2072747029L, -1492299923L, 1900651994L, -1598056552L, 1993233921L, 
+858806195L, -712505644L, 1676763106L, -1040088457L, -405824575L, 
+979364166L, -690907004L, 428793397L, -1864661473L, 255451512L, 
+367624278L, 66497763L, 1136208549L, 487618370L, 1302431024L, 
+11588953L, 1379292875L, 1345621820L, -1535965334L, -381631073L, 
+906107945L, 683163326L, -912707668L, 588649725L, -354168761L, 
+-1125437648L, 802240590L, 822006907L, -281405475L, -1198365174L, 
+-1870922968L, -66321007L, 953162627L, -2059034492L, 1009110706L, 
+-253832697L, 483074641L, 1253013974L, -791550796L, 1947287749L, 
+151048719L, -792311160L, 347254694L, -1941723309L, 992524469L, 
+1256003090L, -2005416992L, -1998621111L, -381057925L, -1569708724L, 
+-1107554086L, -1848721201L, 1125276825L, 893214894L, 1847582140L, 
+416679469L, 441131479L, 2943008L, -1975874178L, 913273675L, 1091467597L, 
+-1988675718L, 231766456L, 2001013601L, -189789421L, -441892044L, 
+1680982338L, 1329370455L, -1597771615L, 1803360614L, -130299036L, 
+-1130241387L, 178127807L, -2124933288L, 1019293046L, 2130947971L, 
+709342661L, -1573025054L, 1051030352L, -1011724679L, -475393621L, 
+2078238492L, 362786890L, 2092045375L, -455814007L, 1578393758L, 
+-868086452L, -1401922275L, 520616103L, -1159686192L, 2047672174L, 
+250058267L, -1096016003L, 1515595114L, -407102456L, -1661533007L, 
+-982801629L, -199143388L, -479141166L, -2062620889L, 680860017L, 
+-973946954L, -1287523500L, 1508040165L, -496891921L, 1765271336L, 
+1950408582L, 1711377331L, 1488435989L, 1288689010L, -1254921792L, 
+310118953L, 39349915L, 1708939116L, 165130106L, -1484097361L, 
+466293689L, -1077332530L, 649863452L, -1836096371L, 854599927L, 
+-1394138112L, -974117282L, -1272973013L, 1888258605L, -2134353254L, 
+704743000L, -362354239L, 1774884467L, 198857620L, 103107106L, 
+-969411273L, 399111169L, -193955578L, -378172092L, 1997942901L, 
+-1188552225L, 1277988152L, -1635500266L, 1948267020L)

R/envvar_utility_functions.R

@@ -0,0 +1,31 @@
+#' Return the value of the named environment variable(s), or a default value if NA
+#'
+#' The common use-case for this is when it is expected to setup execution-specific
+#' variable values from a calling environment but if the script is run in a
+#' standalone/testing mode that it can make use of the defaults to still
+#' operate in a controlled manner.
+#'
+#' While bulk lookups can be accomplished readability will be hampered if
+#' extremely long vectors are used.  In that situation multiple single-pair
+#' calls is recommended.  This also has the beneficial property of not attaching
+#' names to the resultant vector which makes variable assignment easier.
+#'
+#' Wraps a call to Sys.getenv
+#'
+#' @param envvar_names A vector of envrionment variable names to retrieve
+#' @param values_if_missing A vector of strings, matched by position, to use as defaults
+#' @return A vector (named if length > 1) of a matching length (> 0) with the conditioned values
+#' @examples
+#' env_or_default("UNKNOWN", "DEFAULT")
+#' env_or_default(c("HOME", "UNKNOWN"), c("/tmp", "DEFAULT"))
+#'
+#' @name env_or_default
+#' @export
+env_or_default <- function(envvar_names, values_if_missing) {
+  stopifnot(length(envvar_names) == length(values_if_missing),
+            length(envvar_names) > 0)
+
+  vals <- Sys.getenv(envvar_names, unset = NA)
+  results <- ifelse(is.na(vals), values_if_missing, vals)  
+  return(results)
+}

man/env_or_default.Rd

@@ -0,0 +1,35 @@
+% Generated by roxygen2 (4.1.0): do not edit by hand
+% Please edit documentation in R/envvar_utility_functions.R
+\name{env_or_default}
+\alias{env_or_default}
+\title{Return the value of the named environment variable(s), or a default value if NA}
+\usage{
+env_or_default(envvar_names, values_if_missing)
+}
+\arguments{
+\item{envvar_names}{A vector of envrionment variable names to retrieve}
+
+\item{values_if_missing}{A vector of strings, matched by position, to use as defaults}
+}
+\value{
+A vector (named if length > 1) of a matching length (> 0) with the conditioned values
+}
+\description{
+The common use-case for this is when it is expected to setup execution-specific
+variable values from a calling environment but if the script is run in a
+standalone/testing mode that it can make use of the defaults to still
+operate in a controlled manner.
+}
+\details{
+While bulk lookups can be accomplished readability will be hampered if
+extremely long vectors are used.  In that situation multiple single-pair
+calls is recommended.  This also has the beneficial property of not attaching
+names to the resultant vector which makes variable assignment easier.
+
+Wraps a call to Sys.getenv
+}
+\examples{
+env_or_default("UNKNOWN", "DEFAULT")
+env_or_default(c("HOME", "UNKNOWN"), c("/tmp", "DEFAULT"))
+}
+

man/envvar-package.Rd

@@ -0,0 +1,30 @@
+\name{envvar-package}
+\alias{envvar-package}
+\alias{envvar}
+\docType{package}
+\title{
+Envrionment Variables Helper Functions
+}
+\description{
+Provides functions to semantically manipulate environment variables.
+}
+\details{
+\tabular{ll}{
+Package: \tab envvar\cr
+Type: \tab Package\cr
+Version: \tab 0.1.0\cr
+Date: \tab 2015-02-24\cr
+License: \tab Unlimited\cr
+}
+Each provided function has its own instructions for use.
+Pick the one that fulfills your requirements.
+}
+\author{
+David G. Johnston
+
+Maintainer: David G. Johnston <polobo@yahoo.com>
+}
+\keyword{ package }
+\examples{
+env_or_default(c("HOME","UNKNOWN"), c("/tmp", "DEFAULT"))
+}

tests/testthat.R

@@ -0,0 +1,4 @@
+library(testthat)
+library(envvar)
+
+test_check("envvar")

tests/testthat/test_utilities.R

@@ -0,0 +1,41 @@
+library(testthat)
+library(envvar)
+context("Utility Tests")
+
+# We need to have a known environment variable with which to test affirmative lookups
+Sys.setenv("KNOWN_VAR" = "VALUE")
+Sys.setenv("EMPTY_VAR" = "")
+
+test_that("env_or_default can resolve single envvars", {
+  expect_equal("VALUE", env_or_default("KNOWN_VAR", "DEFAULT"))
+  expect_equal("DEFAULT", env_or_default("UNKNOWN", "DEFAULT"))
+})
+
+test_that("nv_or_default can resolve multiple envvars", {
+  expect_equal(c("KNOWN_VAR" = "VALUE", "UNKNOWN" = "DEFAULT"),
+               env_or_default(c("KNOWN_VAR", "UNKNOWN"), c("DEFAULT", "DEFAULT")))
+})
+
+test_that("env_or_default requires matching lengths, no repetition allowed", {
+  expect_error(env_or_default(c("KNOWN_VAR", "UNKNOWN"), c("DEFAULT")))
+})
+
+test_that("env_or_default distinguishs between empty and missing", {
+  expect_equal("", env_or_default("EMPTY_VAR", "DEFAULT"))
+})
+
+test_that("env_or_default requires at least one pair", {
+ expect_error(env_or_default())
+ expect_error(env_or_default(c(), c()))
+})
+
+test_that("env_or_default result is not a named vector for single-pair", {
+  result <- env_or_default("KNOWN_VAR", "DEFAULT")
+  expect_named(result, NULL)
+})
+
+test_that("env_or_default result is a named vector for multi-pair", {
+  result <- env_or_default(c("KNOWN_VAR","UNKNOWN"), c("DEFAULT","DEFAULT"))
+  expect_named(result, c("KNOWN_VAR", "UNKNOWN"))
+  expect_equal("DEFAULT", result[["UNKNOWN"]])
+})

vignettes/envvar-vignette.Rmd

@@ -0,0 +1,16 @@
+---
+title: "EnvVar Vignette"
+author: "David G. Johnston"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Vignette Title}
+  %\VignetteEngine{knitr::rmarkdown}
+  \usepackage[utf8]{inputenc}
+---
+
+If this package, and its sole function `env_or_default` was difficult
+to use there would be more stuff here.  As it stands, please just
+read the documentation for that function.
+
+David G. Johnston