Revise

DESCRIPTION

@@ -118,6 +118,7 @@ Collate:
     'expressions.R'
     'fill-variable.R'
     'filters.R'
+    'findVariables.R'
     'folders.R'
     'fork-and-merge.R'
     'formula.R'

NAMESPACE

@@ -191,6 +191,7 @@ export(exportDataset)
 export(exportDeck)
 export(extendDataset)
 export(filter)
+export(findVariables)
 export(flattenOrder)
 export(flipArrays)
 export(folder)

NEWS.md

@@ -1,5 +1,7 @@
 # crunch 1.30.4 (Development Version)
 
+* New function `findVariables` accepts a Crunch dataset or variable folder and returns a data.frame whose rows correspond to variables and their location (#640).
+
 # crunch 1.30.3
 * Fix typo which relied on partial argument matching when using the variable catalog cache
   (#625, thanks @rossellhayes)

R/findVariables.R

@@ -1,12 +1,19 @@
 #' Find variables and their paths in a Crunch dataset or folder
-#'
+#' 
+#' Returns a data.frame whose rows correspond to Crunch variables found in \code{x}.
+#' By default, only top-level, non-hidden, non-private variables in \code{x} are returned.
+#' 
 #' @param x Crunch dataset or variable folder
-#' @param deep FALSE (the default) or TRUE; should subfolders
-#' @param include.hidden FALSE (default) or TRUE, should hidden be included in the result?
+#' @param deep Defaults to \code{FALSE}, \code{TRUE} recursively examines any subfolders as well
+#' @param include.hidden Defaults to \code{FALSE}, \code{TRUE} finds any hidden variables as well
+#' @param include.private Defaults to \code{FALSE}, \code{TRUE} finds any private variables as well
 #'
-#' @return Data.frame with one row per Crunch variable and columns \code{alias}, \code{path}, \code{hidden}
+#' @return Data.frame with one row per Crunch variable and columns \code{alias} (Crunch variable alias),
+#' \code{path} (location of the variable, with " | " indicating nesting,
+#' e.g. "Foo | Bar" indicates that the variable can be found in the folder "Bar" and that "Bar" is located in folder "Foo"),
+#' \code{hidden} (\code{TRUE} or \code{FALSE}), \code{private} (\code{TRUE} or \code{FALSE})
 #' @export
-findVariables <- function(x, deep = FALSE, include.hidden = FALSE) {
+findVariables <- function(x, deep = FALSE, include.hidden = FALSE, include.private = FALSE) {
     if (is.dataset(x)) {
         x <- cd(x, ".")
         startpath <- ""
@@ -19,27 +26,41 @@ findVariables <- function(x, deep = FALSE, include.hidden = FALSE) {
         halt("`deep` should be TRUE or FALSE")
     }
     if (!isTRUE(include.hidden) && !isFALSE(include.hidden)) {
-        halt("`hidden` should be TRUE or FALSE")
+        halt("`include.hidden` should be TRUE or FALSE")
+    }
+    if (!isTRUE(include.private) && !isFALSE(include.private)) {
+        halt("`include.private` should be TRUE or FALSE")
     }
     if (!deep) {
         vars <- aliases(variables(x))
         nvars <- length(vars)
-        res <- data.frame(alias = vars, path = rep(startpath, nvars), hidden = rep(FALSE, nvars))
+        res <- data.frame(alias = vars, path = rep(startpath, nvars), hidden = rep(FALSE, nvars), private = rep(FALSE, nvars))
         return(res)
     }
     res <- .findVariables(x, startpath)
+    res <- do.call(rbind, res)
     res$hidden <- rep(FALSE, nrow(res))
+    res$private <- rep(FALSE, nrow(res))
     if (include.hidden) {
         hidden <- .findVariables(hiddenFolder(x), startpath)
+        hidden <- do.call(rbind, hidden)
         hidden$hidden <- rep(TRUE, nrow(hidden))
+        hidden$private <- rep(FALSE, nrow(hidden))
         res <- rbind(res, hidden)
     }
+    if (include.private) {
+        private <- .findVariables(privateFolder(x), startpath)
+        private <- do.call(rbind, private)
+        private$hidden <- rep(FALSE, nrow(private))
+        private$private <- rep(TRUE, nrow(private))
+        res <- rbind(res, private)
+    }
     res
 }
 
 .findVariables <- function(x, path) {
     vars <- variables(x)
-    res <- data.frame(alias = aliases(vars), path = rep(path, length(vars)))
+    res <- list(data.frame(alias = aliases(vars), path = rep(path, length(vars))))
     dirs <- x[types(x) %in% "folder"]
     if (length(dirs) == 0) {
         return(res)
@@ -53,5 +74,5 @@ findVariables <- function(x, deep = FALSE, include.hidden = FALSE) {
         }
         .findVariables(dirs[[i]], new_path)
     })
-    rbind(res, do.call(rbind, res2))
+    c(res, res2)
 }

R/folders.R

@@ -389,6 +389,7 @@ copyFolders <- function(source, target) {
 # Recursively get all variables below a folder
 # TODO: Use trampoline? https://community.rstudio.com/t/tidiest-way-to-do-recursion-safely-in-r/1408
 # My initial tests say it's slower, but is safer if we ever expect a large number of folders
+# NOTE: see ?findVariables for a similar exported function
 variablesBelowFolder <- function(folder) {
     vars <- variables(folder)
     dirs <- folder[types(folder) %in% "folder"]