From 436cee549f7410cccc9946eb11c50084dc43d995 Mon Sep 17 00:00:00 2001 From: Edwin de Jonge Date: Sun, 1 Oct 2023 15:57:24 +0200 Subject: [PATCH] updating readme.md --- .Rbuildignore | 1 + README.Rmd | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 63 +++++++++++++++------------ 3 files changed, 153 insertions(+), 28 deletions(-) create mode 100644 README.Rmd diff --git a/.Rbuildignore b/.Rbuildignore index 04c916d..34f2f1e 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -5,3 +5,4 @@ ^appveyor\.yml$ ^.RData ^\.github$ +^README\.Rmd$ diff --git a/README.Rmd b/README.Rmd new file mode 100644 index 0000000..c9fb69e --- /dev/null +++ b/README.Rmd @@ -0,0 +1,117 @@ +--- +output: github_document +--- + + + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + fig.path = "man/figures/README-", + out.width = "100%" +) +``` + + + +![version](http://www.r-pkg.org/badges/version/daff) +[![R-CMD-check](https://github.com/edwindj/daff/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/edwindj/daff/actions/workflows/R-CMD-check.yaml) +![downloads](http://cranlogs.r-pkg.org/badges/daff) + + + +# Daff: diff, patch and merge for data.frames + +daff is an R package that can find difference in values between +`data.frames`, store this difference, render it and apply this +difference to patch a `data.frame`. It can also merge two versions of a +`data.frame` having a common parent. It wraps the +[daff.js](http://paulfitz.github.io/daff/) library using the +[V8](https://github.com/jeroen/v8) package. + +The diff format is described in +. + + +Functions: + +- diff: `diff_data` +- patch: `patch_data` +- write/read diff: `read_diff` and `write_diff` +- render to html: `render_diff` +- merge two tables based on a same version: `merge_data` + + +## Installation + +You can install the development version of daff from [GitHub](https://github.com/) with: + +``` r +# install.packages("devtools") +devtools::install_github("edwindj/daff") +``` + +# Usage + +## diff_data + +Calculate the difference between a reference and a changed `data.frame` + +``` r +library(daff) +y <- iris[1:3,] +x <- y + +x <- head(x,2) # remove a row +x[1,1] <- 10 # change a value +x$hello <- "world" # add a column +x$Species <- NULL # remove a column + +patch <- diff_data(y, x) + +# write a patch to disk +write_diff(patch, "patch.csv") +``` + +`render_diff(patch)` will generate the following HTML page: + +
+render_diff + +
+ +## patch_data + +Patch a `data.frame` using a diff generated with `diff_data`. + +``` r +# read a diff from disk +patch <- read_diff("patch.csv") + +# apply patch +y_patched <- patch_data(y, patch) +``` + +## merge_data + +Merge two `data.frame`s that have diverged from a common parent +`data.frame`. + +``` r +parent <- a <- b <- iris[1:3,] +a[1,1] <- 10 +b[2,1] <- 11 +# succesful merge +merge_data(parent, a, b) + +parent <- a <- b <- iris[1:3,] +a[1,1] <- 10 +b[1,1] <- 11 +# conflicting merge (both a and b change same cell) +merged <- merge_data(parent, a, b) +merged #note the conflict + +#find out which rows contain a conflict +which_conflicts(merged) +``` diff --git a/README.md b/README.md index b378b2c..53162b4 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,26 @@ -# Daff: diff, patch and merge for data.frames - -daff is an R package that can find difference in values between `data.frames`, store this difference, render it and apply this difference to patch a `data.frame`. It can also merge two versions of a `data.frame` having a common parent. -It wraps the [daff.js](http://paulfitz.github.io/daff/) library using the [V8 ](https://github.com/jeroen/v8) package. - -The diff format is described in https://paulfitz.github.io/daff-doc/spec.html. + + ![version](http://www.r-pkg.org/badges/version/daff) [![R-CMD-check](https://github.com/edwindj/daff/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/edwindj/daff/actions/workflows/R-CMD-check.yaml) ![downloads](http://cranlogs.r-pkg.org/badges/daff) -/ci.appveyor.com/project/edwindj/daff) + -Working: +# Daff: diff, patch and merge for data.frames + +daff is an R package that can find difference in values between +`data.frames`, store this difference, render it and apply this +difference to patch a `data.frame`. It can also merge two versions of a +`data.frame` having a common parent. It wraps the +[daff.js](http://paulfitz.github.io/daff/) library using the +[V8](https://github.com/jeroen/v8) package. + +The diff format is described in +. + +Functions: - diff: `diff_data` - patch: `patch_data` @@ -20,22 +28,13 @@ Working: - render to html: `render_diff` - merge two tables based on a same version: `merge_data` -TODO: - -- add htmlwidgets -- implement extra parameters for `diff_data`: `ids`, `ignore` etc. -- make column type changes explicit (is now internally available) -- see if daff can be implemented in C++, using the Haxe C++ target of daff: this would remove the V8/jsonlite dependency +## Installation -# Install - -Install from CRAN -```R -install.packages('daff') -``` +You can install the development version of daff from +[GitHub](https://github.com/) with: -The latest version of `daff` can be installed with `devtools` -```S +``` r +# install.packages("devtools") devtools::install_github("edwindj/daff") ``` @@ -44,7 +43,8 @@ devtools::install_github("edwindj/daff") ## diff_data Calculate the difference between a reference and a changed `data.frame` -```R + +``` r library(daff) y <- iris[1:3,] x <- y @@ -62,13 +62,18 @@ write_diff(patch, "patch.csv") `render_diff(patch)` will generate the following HTML page: -![render_diff](man/render_diff.png "render_diff") - +
+render_diff + +
## patch_data Patch a `data.frame` using a diff generated with `diff_data`. -```R + +``` r # read a diff from disk patch <- read_diff("patch.csv") @@ -78,8 +83,10 @@ y_patched <- patch_data(y, patch) ## merge_data -Merge two `data.frame`s that have diverged from a common parent `data.frame`. -```R +Merge two `data.frame`s that have diverged from a common parent +`data.frame`. + +``` r parent <- a <- b <- iris[1:3,] a[1,1] <- 10 b[2,1] <- 11