{"Type":"Package","Package":"rotor","Title":"Log Rotation and Conditional Backups","Version":"0.3.4","Authors@R":"\nperson(given = \"Stefan\",\nfamily = \"Fleck\",\nrole = c(\"aut\", \"cre\"),\nemail = \"stefan.b.fleck@gmail.com\",\ncomment = c(ORCID = \"0000-0003-3344-9851\"))","Maintainer":"Stefan Fleck ","Description":"Conditionally rotate or back-up files based on\ntheir size or the date of the last backup; inspired by the 'Linux'\nutility 'logrotate'.","License":"MIT + file LICENSE","URL":"https://s-fleck.github.io/rotor/","BugReports":"https://github.com/s-fleck/rotor/issues","Imports":"dint, R6, tools","Suggests":"covr, crayon, data.table, digest, rmarkdown, testthat, uuid,\nulid, zip","Encoding":"UTF-8","LazyData":"true","RoxygenNote":"7.1.1.9000","NeedsCompilation":"no","Packaged":"2020-10-28 12:45:59 UTC; hoelk","Author":"Stefan Fleck [aut, cre] ()","Repository":"CRAN","Date/Publication":"2020-10-28 13:20:03 UTC","repoType":"cran","tarballUrl":"ftp://cran.r-project.org/pub/R/src/contrib/rotor_0.3.4.tar.gz","jsonAuthors":[{"name":"Stefan Fleck","email":"stefan.b.fleck@gmail.com","maintainer":true}],"readme":"\n\n\n# rotor\n\n\n\n[![Travis build\nstatus](https://travis-ci.com/s-fleck/rotor.svg?branch=master)](https://travis-ci.com/s-fleck/rotor)\n[![Lifecycle:\nmaturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing)\n[![Codecov test\ncoverage](https://codecov.io/gh/s-fleck/rotor/branch/master/graph/badge.svg)](https://codecov.io/gh/s-fleck/rotor?branch=master)\n[![CRAN\nstatus](https://www.r-pkg.org/badges/version/rotor)](https://cran.r-project.org/package=rotor)\n\n\n**rotor** provides a cross platform R reimagination of\n[logrotate](https://linux.die.net/man/8/logrotate). It is a companion\npackage to the logging package [lgr](https://github.com/s-fleck/lgr). In\ncontrast to logrotate, rotor relies solely on information encoded in a\nsuffixes of file names for conditionally creating backups (i.e. a\ntimestamp or index). It therefore also works with backups created by\nother tools, as long as the filename has a format that rotor can\nunderstand.\n\n`rotate()`, `rotate_date()`, and `rotate_time()` move a file and insert\na suffix (either an integer or a timestamp) into the filename. In\naddition, they create an empty file in place of the original one. This\nis useful for log rotation. `backup()`, `backup_date()` and\n`backup_time()` do the same but keep the original file.\n\nrotor also includes utility functions for finding and examining the\nbackups of a file: `list_backups()`, `backup_info()`, `n_backups`,\n`newest_backup()`, `oldest_backup()`. See the [function\nreference](https://s-fleck.github.io/rotor/reference/index.html) for\ndetails.\n\n## Installation\n\nYou can install the released version of rotor from\n[CRAN](https://CRAN.R-project.org) with:\n\n``` r\ninstall.packages(\"rotor\")\n```\n\nAnd the development version from [GitHub](https://github.com/) with:\n\n``` r\n# install.packages(\"remotes\")\nremotes::install_github(\"s-fleck/rotor\")\n```\n\n## Example\n\nFirst we create a temporary directory for the files created by the code\nexamples\n\n``` r\nlibrary(rotor)\n\n# create a directory\ntd <- file.path(tempdir(), \"rotor\")\ndir.create(td, recursive = TRUE)\n\n# create an example logfile\ntf <- file.path(td, \"mylogfile.log\")\nwriteLines(\"An important message\", tf)\n```\n\n### Indexed backups\n\n`backup()` makes a copy of a file and inserts an index between the\nfilename and the file extension. The file with the index `1` is always\nthe most recently made backup.\n\n``` r\nbackup(tf)\n\n# backup and rotate also support compression\nbackup(tf, compression = TRUE) \n\n# display backups of a file\nlist_backups(tf) \n#> [1] \"/tmp/Rtmpw73XUg/rotor/mylogfile.1.log.zip\"\n#> [2] \"/tmp/Rtmpw73XUg/rotor/mylogfile.2.log\"\n```\n\n`rotate()` also backs up a file, but replaces the original file with an\nempty one.\n\n``` r\nrotate(tf)\nlist_backups(tf)\n#> [1] \"/tmp/Rtmpw73XUg/rotor/mylogfile.1.log\" \n#> [2] \"/tmp/Rtmpw73XUg/rotor/mylogfile.2.log.zip\"\n#> [3] \"/tmp/Rtmpw73XUg/rotor/mylogfile.3.log\"\n\n# the original file is now empty\nreadLines(tf)\n#> character(0)\n\n# its content was moved to the first backup\nreadLines(list_backups(tf)[[1]])\n#> [1] \"An important message\"\n\n# we can now safely write to the original file\nwriteLines(\"another important message\", tf)\n```\n\nThe `max_backups` parameter limits the maximum number of backups rotor\nwill keep of a file. Notice how the zipped backup we created above moves\nto index 4 as we create two new backups.\n\n``` r\nbackup(tf, max_backups = 4)\nbackup(tf, max_backups = 4)\n\nlist_backups(tf)\n#> [1] \"/tmp/Rtmpw73XUg/rotor/mylogfile.1.log\" \n#> [2] \"/tmp/Rtmpw73XUg/rotor/mylogfile.2.log\" \n#> [3] \"/tmp/Rtmpw73XUg/rotor/mylogfile.3.log\" \n#> [4] \"/tmp/Rtmpw73XUg/rotor/mylogfile.4.log.zip\"\n```\n\nWe can also use `prune_backups()` to delete old backups. Other than\nensuring that no new backups is created, it works identically to using\n`backup()` with the `max_backups` parameter. By setting it to `0`, we\ndelete all backups.\n\n``` r\nprune_backups(tf, max_backups = 0)\n```\n\n## Timestamped backups\n\n**rotor** can also create timestamped backups. `backup_date()` creates\nuses a Date (`yyyy-mm-dd`) timestamp, `backup_time()` uses a full\ndatetime-stamp by default (`yyyy-mm-dd--hh-mm-ss`). The format of the\ntimestamp can be modified with a subset of the formatting tokens\nunderstood by `strftime()` (within certain restrictions). Backups\ncreated with both functions are compatible with each other (but not with\nthose created with `backup_index()`).\n\n``` r\n# be default backup_date() only makes a backup if the last backups is younger\n# than 1 day, so we set `age` to -1 for this example\nbackup_date(tf, age = -1) \nbackup_date(tf, format = \"%Y-%m\", age = -1)\nbackup_time(tf)\nbackup_time(tf, format = \"%Y-%m-%d_%H-%M-%S\") # Python logging\nbackup_time(tf, format = \"%Y%m%dT%H%M%S\") # ISO 8601 compatible\n\nbackup_info(tf)\n#> path name\n#> 1 /tmp/Rtmpw73XUg/rotor/mylogfile.2020-07-24_10-54-30.log mylogfile\n#> 2 /tmp/Rtmpw73XUg/rotor/mylogfile.2020-07-24--10-54-30.log mylogfile\n#> 5 /tmp/Rtmpw73XUg/rotor/mylogfile.20200724T105430.log mylogfile\n#> 3 /tmp/Rtmpw73XUg/rotor/mylogfile.2020-07-24.log mylogfile\n#> 4 /tmp/Rtmpw73XUg/rotor/mylogfile.2020-07.log mylogfile\n#> sfx ext size isdir mode mtime\n#> 1 2020-07-24_10-54-30 log 26 FALSE 664 2020-07-24 10:54:30\n#> 2 2020-07-24--10-54-30 log 26 FALSE 664 2020-07-24 10:54:30\n#> 5 20200724T105430 log 26 FALSE 664 2020-07-24 10:54:30\n#> 3 2020-07-24 log 26 FALSE 664 2020-07-24 10:54:30\n#> 4 2020-07 log 26 FALSE 664 2020-07-24 10:54:30\n#> ctime atime uid gid uname grname\n#> 1 2020-07-24 10:54:30 2020-07-24 10:54:30 11861 11861 fleck fleck\n#> 2 2020-07-24 10:54:30 2020-07-24 10:54:30 11861 11861 fleck fleck\n#> 5 2020-07-24 10:54:30 2020-07-24 10:54:30 11861 11861 fleck fleck\n#> 3 2020-07-24 10:54:30 2020-07-24 10:54:30 11861 11861 fleck fleck\n#> 4 2020-07-24 10:54:30 2020-07-24 10:54:30 11861 11861 fleck fleck\n#> timestamp\n#> 1 2020-07-24 10:54:30\n#> 2 2020-07-24 10:54:30\n#> 5 2020-07-24 10:54:30\n#> 3 2020-07-24 00:00:00\n#> 4 2020-07-01 00:00:00\n```\n\nIf we examine the “timestamp” column in the example above, we see that\nmissing date information is always interpreted as the start of the\nperiod; i.e. so `\"2019-01\"` is equivalent to `\"2019-01-01--00--00--00\"`\nfor all intents and purposes.\n\n``` r\nprune_backups(tf, max_backups = 0) # cleanup\nlist_backups(tf)\n#> character(0)\n```\n\nBesides passing a total number of backups to keep, `max_backups` can\nalso be a period or a date / datetime for timestamped backups.\n\n``` r\n# keep all backups younger than one year\nprune_backups(tf, \"1 year\") \n \n# keep all backups from April 4th, 2018 and onwards\nprune_backups(tf, \"2018-04-01\") \n```\n\n## Cache\n\nrotor also provides a simple on-disk key-value store that can be used as\na persistent cache.\n\n``` r\ncache <- Cache$new(file.path(tempdir(), \"cache-test\"), hashfun = digest::digest)\n#> creating directory '/tmp/Rtmpw73XUg/cache-test'\nkey1 <- cache$push(iris)\nkey2 <- cache$push(cars)\nkey3 <- cache$push(mtcars)\n\ncache$files$path\n#> [1] \"/tmp/Rtmpw73XUg/cache-test/d3c5d071001b61a9f6131d3004fd0988\"\n#> [2] \"/tmp/Rtmpw73XUg/cache-test/f98a59010652c8e1ee062ed4c43f648e\"\n#> [3] \"/tmp/Rtmpw73XUg/cache-test/a63c70e73b58d0823ab3bcbd3b543d6f\"\n\nhead(cache$read(key1))\n#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species\n#> 1 5.1 3.5 1.4 0.2 setosa\n#> 2 4.9 3.0 1.4 0.2 setosa\n#> 3 4.7 3.2 1.3 0.2 setosa\n#> 4 4.6 3.1 1.5 0.2 setosa\n#> 5 5.0 3.6 1.4 0.2 setosa\n#> 6 5.4 3.9 1.7 0.4 setosa\n\ncache$prune(max_files = 1)\ncache$files$path\n#> [1] \"/tmp/Rtmpw73XUg/cache-test/a63c70e73b58d0823ab3bcbd3b543d6f\"\ncache$purge() # deletes all cached files\ncache$destroy() # deletes the cache directory\n```\n\n# Dependencies\n\n**rotor**’s dependencies are intentionally kept slim. It only comes with\ntwo non-base dependencies:\n\n - [R6](https://github.com/r-lib/R6): A light weight system for\n encapsulated object-oriented programming.\n - [dint](https://github.com/s-fleck/dint): A toolkit for working\n year-quarter and year-month dates that I am also the author of. It\n is used by `rotate_date()` and `rotate_time()` to deal with calendar\n periods (such as weeks or months).\n\nBoth packages have no transitive dependencies (i.e they do not depend on\nanything outside of base R)\n\nOptional dependencies:\n\n - [digest](https://github.com/eddelbuettel/digest) or\n [uuid](https://CRAN.R-project.org/package=uuid) for generating\n hashes or UIDs when using Cache. Storage keys for cache files can\n also be set manually, in which case no external dependencies are\n required.\n - [zip](https://CRAN.R-project.org/package=zip) is supported as an\n alternative to the integrated zip function in R. Might work better\n on some systems and worse on others.","jobInfo":{"package":"rotor","version":"0.3.4","parsingStatus":"success","parserVersion":1,"parsedAt":"2020-12-13T16:29:48+0000"}}

Description

Arguments

See Also