Cache {fscache} | R Documentation |
A cache class for handling caching on the file system.
A cache class for handling caching on the file system.
The purpose of this class is to help managing a user cache folder for an application. Files can be copied or moved into the cache folder. Character values can be saved into files and loaded from files. Sub-folders can be defined. Folders can be listed to see the existing files. Files can be deleted individually or by batch, Whole folders can be deleted, including the main cache folder.
new()
New instance initializer.
Initializes a Cache
instance, using a specified folder.
Path to the folder can be absolute or relative.
When relative, the absolute root folder is either the standard user cache
folder or the current working directory, depending on user
parameter.
Cache$new(folder, user = TRUE, force = FALSE, create = TRUE)
folder
The path to the wanted cache folder. Either an absolute path, or a relative path that will be resolved immediately into an absolute path.
user
If set to TRUE and the folder path is a relative path, then
the path is resolved relatively to the standard user cache
folder (i.e.: we call tools::R_user_dir(folder,
which = 'cache')
). A good and standard practice is to set
the folder
parameter to your package name,
using.
force
If the folder exists, is not empty and is not an fscache
folder, fails if force is FALSE
, and use folder
anyway if force is TRUE
.
create
If FALSE
, does not create the cache folder if does
not exist already. Used for testing purposes only.
Nothing.
# Create a new cache instance. # Note for the sake of the example we use a temporary directory specified # as an absolute path, however the usual way to use the cache system is # to provide a relative path, that will be placed inside the standard # user cache folder defined by the OS. cache <- Cache$new(tempdir()) # Erase cache cache$erase()
isReadable()
Tests if the cache system is readable.
Cache reading may be disabled and re-enabled with setReadable()
,
Mainly used for debug purposes.
Cache$isReadable()
TRUE
if the cache system is readable, FALSE
otherwise.
# Create a new cache instance cache <- Cache$new(tempdir()) # Tests if readable (TRUE by default) if (cache$isReadable()) { print("Cache is readable") } # Erase cache cache$erase()
isWritable()
Tests if the cache system is writable.
Cache reading may be disabled and re-enabled with setWritable()
.
Mainly used for debug purposes.
Cache$isWritable()
TRUE
if the cache system is writable, FALSE
otherwise.
# Create a new cache instance cache <- Cache$new(tempdir()) # Tests if writeable (TRUE by default) if (cache$isWritable()) { print("Cache is writeable") } # Erase cache cache$erase()
setReadable()
Disables or enable cache reading.
Allows or disallows reading to the cache folder.
Cache$setReadable(readable)
readable
Set to FALSE
to disallow reading and to
TRUE
to allow it.
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Disallow reading cache$setReadable(FALSE) # Erase cache cache$erase()
setWritable()
Disables or enable cache writing.
Allows or disallows writing to the cache folder.
Cache$setWritable(writable)
writable
Set to FALSE
to disallow writing and to
TRUE
to allow it.
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Disallow writing cache$setWritable(FALSE) # Erase cache cache$erase()
getFolder()
Gets the path to the main cache folder or a sub-folder.
Returns the absolute path to the main cache folder or a cache sub-folder. By default, the folder is created if it does not exist.
Cache$getFolder( sub_folder = NULL, create = TRUE, fail = FALSE, sub.folder = NULL )
The path to the cache folder as a character value.
# Create a new cache instance cache <- Cache$new(tempdir()) # Get the absolute path to the cache folder folder <- cache$getFolder() # Get the absolute path to a cache sub-folder sub_folder <- cache$getFolder('my_sub_folder') # Erase cache cache$erase()
hasFolder()
Tests if the cache main folder or a cache sub-folder exists.
Cache$hasFolder(sub_folder = NULL, sub.folder = NULL)
TRUE if the folder exists. FALSE otherwise.
# Create a new cache instance cache <- Cache$new(tempdir()) # Test if a sub-folder exists if (cache$hasFolder("my_sub_folder")) { print("Sub-folder exists.") } # Erase cache cache$erase()
getPaths()
Computes paths in the cache folder or a cache sub-folder.
Takes a list of relative paths and resolves them using the cache folder path to a list of absolute paths.
Cache$getPaths(paths, suffix = NULL, sub_folder = NULL, sub.folder = NULL)
A character vector, the same size as paths
,
containing the absolute paths.
# Create a new cache instance cache <- Cache$new(tempdir()) # Get the paths a list of filenames should have in the cache folder paths <- cache$getPaths(c("a.csv", "b.txt")) # Get paths using a common extension for filenames paths <- cache$getPaths(c("a", "b"), suffix = ".csv") # Get paths of files inside a sub-folder paths <- cache$getPaths(c("a.csv", "b.txt"), sub_folder = "foo") # Erase cache cache$erase()
globPaths()
Search for files inside the cache folder or one of its subfolders.
Cache$globPaths( suffix = NULL, sub_folder = NULL, tag_files = FALSE, folders = FALSE, tag.files = NULL, sub.folder = NULL )
suffix
The suffix files must have.
sub_folder
A sub-folder where to search.
tag_files
If set to FALSE
(default), exclude the tag files.
Otherwise include them in the output.
folders
If set to FALSE
(default), exclude the folders.
Otherwise include them in the output.
tag.files
sub.folder
A character vector containing paths to existing file matching the criteria.
# Create a new cache instance cache <- Cache$new(tempdir()) # Get all existing files inside sub-folder foo paths <- cache$globPaths(sub_folder = "foo") # Get all existing files with extension ".txt" inside main folder paths <- cache$globPaths(suffix = ".txt") # Erase cache cache$erase()
getNbItems()
Gets the number of items contained inside a cache folder.
Counts the number of items (files or folders) contained inside a cache folder. This method does not explore the file system recursively, but only look at the files inside the folder.
Cache$getNbItems( sub_folder = NULL, tag_files = FALSE, folders = FALSE, tag.files = NULL, sub.folder = NULL )
The number of items.
# Create a new cache instance cache <- Cache$new(tempdir()) # Get the number of files inside sub-folder "foo" n <- cache$getNbItems("foo") # Erase cache cache$erase()
pathsExist()
Tests if paths exist inside a cache folder.
Takes a list of relative paths and resolves them using the cache folder path to a list of absolute paths. Tests then if each path points to real object on the file system.
Cache$pathsExist(paths, suffix = NULL, sub_folder = NULL, sub.folder = NULL)
A logical vector, the same size as paths
, with TRUE
value if the file exists in the cache, or FALSE
otherwise.
# Create a new cache instance cache <- Cache$new(tempdir()) # Test if some files exist in the cache exits <- cache$pathsExist(c("a", "b"), suffix = ".txt") # Erase cache cache$erase()
tagExists()
Tests if a tag exists in the cache.
Tags are empty files, without extension, whose name starts and ends with
"__"
.
This method tests if some tag file already exist in a cache folder.
Cache$tagExists(name, sub_folder = NULL, sub.folder = NULL)
TRUE
if the tag exists in the cache. FALSE
otherwise.
# Create a new cache instance cache <- Cache$new(tempdir()) # Test if tag file "downloaded" exists in sub-folder "hmdb" if (cache$tagExists("downloaded", sub_folder = "hmdb")) { print("Tag exists") } # Erase cache cache$erase()
writeTag()
Sets a tag into the cache.
Cache$writeTag(name, sub_folder = NULL, sub.folder = NULL)
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Create tag file "downloaded" in sub-folder "hmdb" cache$writeTag("downloaded", sub_folder = "hmdb") # Erase cache cache$erase()
getTmp()
Gets path to the cache system temporary folder.
This temporary folder located inside the cache folder is needed in order to be able to move/rename files into the right cache location. When creating files in the system temporary folder, which may reside on a different partition, moving a file could fail as in the following error: cannot rename file "/tmp/Rtmpld18y7/10182e3a086e7b8a7.tsv" to "/home/pr228844/dev/biodb/cache/comp.csv.file-58e...c4/2e3...a7.tsv", reason "Invalid cross-device link".
When you download a file directly to the disk using for instance
download.file()
, write the destination into this destination
folder. When downloaded is complete, move the file using the method
importFiles()
.
Cache$getTmp()
A string containing the path to the folder.
# Create a new cache instance cache <- Cache$new(tempdir()) # Get the cache temporary folder tmp <- cache$getTmp() # Erase cache cache$erase()
getSubFolders()
Returns all existing sub-folders.
Cache$getSubFolders()
A character vector containing all the sub-folders.
# Create a new cache instance cache <- Cache$new(tempdir()) # Get the list of sub-folders sub.folders <- cache$getSubFolders() # Erase cache cache$erase()
importFiles()
Imports existing files into the cache.
Cache$importFiles( src, dst = NULL, suffix = NULL, sub_folder = NULL, action = c("copy", "move"), sub.folder = NULL )
src
A character vector containing paths to files to import.
dst
A character vector containing destination filenames. The
vector must have the length as the src
vector. If
NULL
, the filenames in src
will be used.
suffix
A suffix to add to all destination paths.
sub_folder
A sub-folder. All files will copied or moved to this sub-folder.
action
Specifies if files have to be moved or copied into the cache.
sub.folder
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Create some files for the example files <- c("k.txt", "u.csv") file.create(files) # Move those files into the cache cache$importFiles(files, sub_folder = "foo", action = "copy") # Remove original files unlink(files) # Erase cache cache$erase()
saveContents()
Saves contents to files into the cache.
Saves character values into files inside a cache folder.
Cache$saveContents( contents, dst, suffix = NULL, sub_folder = NULL, sub.folder = NULL )
contents
A character vector containing the contents to write.
dst
A character vector containing destination filenames. The
vector must have the length as the contents
vector.
suffix
A suffix to add to all destination paths.
sub_folder
A sub-folder. All files will copied or moved to this sub-folder.
sub.folder
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Create some contents for the example contents <- c("a", "b", "c") # Save contents cache$saveContents(contents, c("a.txt", "b.txt", "c.txt")) # Erase cache cache$erase()
loadContents()
Loads contents from files stored into the cache.
Loads character values from cache files.
Cache$loadContents(paths, suffix = NULL, sub_folder = NULL, sub.folder = NULL)
A character vector , the same size as paths
, containing
the contents of the files. If some file does not exist, a NA
value
is returned.
# Create a new cache instance cache <- Cache$new(tempdir()) # Create some contents for the example contents <- c("1", "2", "3") # Save contents cache$saveContents(contents, c("a", "b", "c"), suffix = ".txt", sub_folder = "ex2") # Load contents contents <- cache$loadContents(c("a", "b", "c"), suffix = ".txt", sub_folder = "ex2") # Erase cache cache$erase()
delPaths()
Deletes a list of paths inside the cache system.
Takes a list of relative paths, resolves them using the cache folder path to a list of absolute paths, and deletes the corresponding files.
Cache$delPaths( paths = NULL, suffix = NULL, sub_folder = NULL, sub.folder = NULL )
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Delete some cache files cache$delPaths(c("a.txt", "b.txt")) # Erase cache cache$erase()
delFolder()
Deletes all files in a sub-folder.
Deletes a sub-folder and all its content.
Cache$delFolder(sub_folder, sub.folder = NULL)
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Delete sub-folder cache$delFolder("my_sub_folder") # Erase cache cache$erase()
listFolder()
Lists files present inside a cache folder.
Lists files that exist inside a cache folder. Returns by default the full paths of the found files. It is possible to filter on files suffix, and to extract the basename.
Cache$listFolder( sub_folder = NULL, suffix = NULL, extract_name = FALSE, remove_suffix = FALSE, tag_files = FALSE, folders = FALSE, extract.name = NULL, remove.suffix = NULL, tag.files = NULL, sub.folder = NULL )
sub_folder
A sub-folder, or NULL
for the main folder.
suffix
A file suffix on which to filter.
extract_name
If set to TRUE
, instead of returning the full
paths of the files, returns their basenames.
remove_suffix
When set to TRUE
and extract.name
is
TRUE
and suffix
is not NULL
,
remove the suffix from the returned basenames.
tag_files
If set to FALSE
(default), exclude the tag files.
Otherwise include them in the output.
folders
If set to FALSE
(default), exclude the folders.
Otherwise include them in the output.
extract.name
remove.suffix
tag.files
sub.folder
The paths to the found files, or the names of the files if
extract.name
is set to TRUE
.
# Create a new cache instance cache <- Cache$new("my_cache_folder") # List files in sub-folder files <- cache$listFolder("my_sub_folder") # Remove cache folder cache$erase()
print()
Displays information about this object.
Cache$print()
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Print information print(cache) # Erase cache cache$erase()
erase()
Erases the whole cache folder.
Deletes the main cache folder and all its files and sub-folders.
Cache$erase()
Nothing.
# Create a new cache instance cache <- Cache$new(tempdir()) # Deletes the whole cache content cache$erase() # Erase cache cache$erase()
clone()
The objects of this class are cloneable with this method.
Cache$clone(deep = FALSE)
deep
Whether to make a deep clone.
# Create a new cache instance inside a custom folder
cache <- Cache$new(tempdir())
# Create some contents for the example
contents <- c("a", "b", "c")
# Save contents
cache$saveContents(contents, c("a.txt", "b.txt", "c.txt"),
sub_folder = "sub1")
# Get list of files inside folder
files <- cache$listFolder("sub1")
# Delete files
cache$delPaths(c("a.txt", "c.txt"), sub_folder = "sub1")
# Delete whole sub-folder
cache$delFolder("sub1")
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$new`
## ------------------------------------------------
# Create a new cache instance.
# Note for the sake of the example we use a temporary directory specified
# as an absolute path, however the usual way to use the cache system is
# to provide a relative path, that will be placed inside the standard
# user cache folder defined by the OS.
cache <- Cache$new(tempdir())
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$isReadable`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Tests if readable (TRUE by default)
if (cache$isReadable()) {
print("Cache is readable")
}
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$isWritable`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Tests if writeable (TRUE by default)
if (cache$isWritable()) {
print("Cache is writeable")
}
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$setReadable`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Disallow reading
cache$setReadable(FALSE)
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$setWritable`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Disallow writing
cache$setWritable(FALSE)
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$getFolder`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Get the absolute path to the cache folder
folder <- cache$getFolder()
# Get the absolute path to a cache sub-folder
sub_folder <- cache$getFolder('my_sub_folder')
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$hasFolder`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Test if a sub-folder exists
if (cache$hasFolder("my_sub_folder")) {
print("Sub-folder exists.")
}
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$getPaths`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Get the paths a list of filenames should have in the cache folder
paths <- cache$getPaths(c("a.csv", "b.txt"))
# Get paths using a common extension for filenames
paths <- cache$getPaths(c("a", "b"), suffix = ".csv")
# Get paths of files inside a sub-folder
paths <- cache$getPaths(c("a.csv", "b.txt"), sub_folder = "foo")
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$globPaths`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Get all existing files inside sub-folder foo
paths <- cache$globPaths(sub_folder = "foo")
# Get all existing files with extension ".txt" inside main folder
paths <- cache$globPaths(suffix = ".txt")
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$getNbItems`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Get the number of files inside sub-folder "foo"
n <- cache$getNbItems("foo")
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$pathsExist`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Test if some files exist in the cache
exits <- cache$pathsExist(c("a", "b"), suffix = ".txt")
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$tagExists`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Test if tag file "downloaded" exists in sub-folder "hmdb"
if (cache$tagExists("downloaded", sub_folder = "hmdb")) {
print("Tag exists")
}
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$writeTag`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Create tag file "downloaded" in sub-folder "hmdb"
cache$writeTag("downloaded", sub_folder = "hmdb")
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$getTmp`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Get the cache temporary folder
tmp <- cache$getTmp()
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$getSubFolders`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Get the list of sub-folders
sub.folders <- cache$getSubFolders()
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$importFiles`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Create some files for the example
files <- c("k.txt", "u.csv")
file.create(files)
# Move those files into the cache
cache$importFiles(files, sub_folder = "foo", action = "copy")
# Remove original files
unlink(files)
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$saveContents`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Create some contents for the example
contents <- c("a", "b", "c")
# Save contents
cache$saveContents(contents, c("a.txt", "b.txt", "c.txt"))
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$loadContents`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Create some contents for the example
contents <- c("1", "2", "3")
# Save contents
cache$saveContents(contents, c("a", "b", "c"), suffix = ".txt",
sub_folder = "ex2")
# Load contents
contents <- cache$loadContents(c("a", "b", "c"), suffix = ".txt",
sub_folder = "ex2")
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$delPaths`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Delete some cache files
cache$delPaths(c("a.txt", "b.txt"))
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$delFolder`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Delete sub-folder
cache$delFolder("my_sub_folder")
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$listFolder`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new("my_cache_folder")
# List files in sub-folder
files <- cache$listFolder("my_sub_folder")
# Remove cache folder
cache$erase()
## ------------------------------------------------
## Method `Cache$print`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Print information
print(cache)
# Erase cache
cache$erase()
## ------------------------------------------------
## Method `Cache$erase`
## ------------------------------------------------
# Create a new cache instance
cache <- Cache$new(tempdir())
# Deletes the whole cache content
cache$erase()
# Erase cache
cache$erase()