listToDepth: List Elements Recursively up to Depth

In KWB-R/kwb.utils: General Utility Functions Developed at KWB

List Elements Recursively up to Depth

Description

List Elements Recursively up to Depth

Usage

listToDepth(
  path,
  max_depth = 0L,
  full_info = FALSE,
  FUN = listFiles,
  ...,
  depth = 0,
  prob_mutate = 0,
  template = NULL
)

Arguments

path	path to the element at which to start listing
max_depth	maximal depth level of which to list elements. A value of 0 means non-recursive listing, a value of NA represents fully recursive listing.
full_info	return only path and isdir information or the full information provided by FUN(full_info = TRUE)?
FUN	function called to get the listing of the element given in path. The function must accept a path as its first argument and it must define the argument full_info second. It may accept further arguments. It must always return a data frame. For full_info = FALSE the data frame must have columns file and isdir (is the "file" a directory?). For full_info = TRUE the function may return further columns. The function must provide an empty data frame with the expected columns when being called with character() as the first argument. The function is expected to set the attribute "failed" to the given path in case that the path could not be accessed (e.g. because of a broken internet connection if the listing is done remotely). See kwb.utils:::listFiles for an example implementation that somehow simulates the behaviour of the dir function. See kwb.dwd::list_url() for a more advanced usage of this function in order to recursively list the files on an FTP server (FTP = file transfer protocol).
...	further arguments passed to FUN
depth	start depth of recursion if max_depth > 0. This argument is for internal use and not intended to be set by the user!
prob_mutate	probability to alter the path so that it becomes useless. This is zero by default. Set the value only if you want to test how the function behaves if the listing of a path fails.
template	empty data frame (zero rows) and with columns that are identical to the columns in the data frame returned by FUN. If not provided the function will call FUN once with a zero-length path argument expecting to retrieve the template that is expected here.

Value

data frame containing at least the columns file and isdir. If full_info = TRUE the result data frame may contain further columns, as provided by the function given in FUN for full_info = TRUE.

Examples

# Example list function provided in this package (file listing)
FUN <- kwb.utils:::listFiles

# The list function must provide empty records when no path is given. The 
# returned data frame must provide the columns "file" and "isdir" ...
FUN()
FUN(full_info = TRUE)

# ... even when being called with an empty character vector
FUN(character())
FUN(character(), full_info = TRUE)

# Call the function recursively up to the given depth level
kwb.utils:::listToDepth(".", max_depth = 1, FUN = FUN)

KWB-R/kwb.utils documentation built on April 1, 2024, 7:12 a.m.