Merge pull request #84 from wibeasley/patch-1

README.Rmd

@@ -184,17 +184,20 @@ This package also provides generics, for which other packages may then implement
 ```{r extensibility}
 library(duckplyr)
 
+# Create a relational to be used by examples below
 new_dfrel <- function(x) {
   stopifnot(is.data.frame(x))
   new_relational(list(x), class = "dfrel")
 }
 mtcars_rel <- new_dfrel(mtcars[1:5, 1:4])
 
+# Example 1: return a data.frame
 rel_to_df.dfrel <- function(rel, ...) {
   unclass(rel)[[1]]
 }
 rel_to_df(mtcars_rel)
 
+# Example 2: A (random) filter
 rel_filter.dfrel <- function(rel, exprs, ...) {
   df <- unclass(rel)[[1]]
 
@@ -213,6 +216,7 @@ rel_filter(
   )
 )
 
+# Example 3: A custom projection
 rel_project.dfrel <- function(rel, exprs, ...) {
   df <- unclass(rel)[[1]]
 
@@ -226,6 +230,7 @@ rel_project(
   list(relexpr_reference("cyl"), relexpr_reference("disp"))
 )
 
+# Example 4: A custom ordering (eg, ascending by mpg)
 rel_order.dfrel <- function(rel, exprs, ...) {
   df <- unclass(rel)[[1]]
 
@@ -238,6 +243,8 @@ rel_order(
   mtcars_rel,
   list(relexpr_reference("mpg"))
 )
+
+# Example 5: A custom join
 rel_join.dfrel <- function(left, right, conds, join, ...) {
   left_df <- unclass(left)[[1]]
   right_df <- unclass(right)[[1]]
@@ -251,6 +258,7 @@ rel_join.dfrel <- function(left, right, conds, join, ...) {
 
 rel_join(new_dfrel(data.frame(mpg = 21)), mtcars_rel)
 
+# Example 6: Limit the maximum rows returned
 rel_limit.dfrel <- function(rel, n, ...) {
   df <- unclass(rel)[[1]]
 
@@ -259,6 +267,8 @@ rel_limit.dfrel <- function(rel, n, ...) {
 
 rel_limit(mtcars_rel, 3)
 
+# Example 7: Suppress duplicate rows
+#  (ignoring row names)
 rel_distinct.dfrel <- function(rel, ...) {
   df <- unclass(rel)[[1]]
 
@@ -267,6 +277,7 @@ rel_distinct.dfrel <- function(rel, ...) {
 
 rel_distinct(new_dfrel(mtcars[1:3, 1:4]))
 
+# Example 8: Return column names
 rel_names.dfrel <- function(rel, ...) {
   df <- unclass(rel)[[1]]
 

README.md

@@ -288,12 +288,14 @@ This package also provides generics, for which other packages may then implement
 <pre class='chroma'>
 <span><span class='kr'><a href='https://rdrr.io/r/base/library.html'>library</a></span><span class='o'>(</span><span class='nv'><a href='https://duckdblabs.github.io/duckplyr/'>duckplyr</a></span><span class='o'>)</span></span>
 <span></span>
+<span><span class='c'># Create a relational to be used by examples below</span></span>
 <span><span class='nv'>new_dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>x</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nf'><a href='https://rdrr.io/r/base/stopifnot.html'>stopifnot</a></span><span class='o'>(</span><span class='nf'><a href='https://rdrr.io/r/base/as.data.frame.html'>is.data.frame</a></span><span class='o'>(</span><span class='nv'>x</span><span class='o'>)</span><span class='o'>)</span></span>
 <span>  <span class='nf'><a href='https://duckdblabs.github.io/duckplyr/reference/new_relational.html'>new_relational</a></span><span class='o'>(</span><span class='nf'><a href='https://rdrr.io/r/base/list.html'>list</a></span><span class='o'>(</span><span class='nv'>x</span><span class='o'>)</span>, class <span class='o'>=</span> <span class='s'>"dfrel"</span><span class='o'>)</span></span>
 <span><span class='o'>}</span></span>
 <span><span class='nv'>mtcars_rel</span> <span class='o'>&lt;-</span> <span class='nf'>new_dfrel</span><span class='o'>(</span><span class='nv'>mtcars</span><span class='o'>[</span><span class='m'>1</span><span class='o'>:</span><span class='m'>5</span>, <span class='m'>1</span><span class='o'>:</span><span class='m'>4</span><span class='o'>]</span><span class='o'>)</span></span>
 <span></span>
+<span><span class='c'># Example 1: return a data.frame</span></span>
 <span><span class='nv'>rel_to_df.dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>rel</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>rel</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
 <span><span class='o'>}</span></span>
@@ -305,6 +307,7 @@ This package also provides generics, for which other packages may then implement
 <span><span class='c'>#&gt; Hornet 4 Drive    21.4   6  258 110</span></span>
 <span><span class='c'>#&gt; Hornet Sportabout 18.7   8  360 175</span></span>
 <span></span>
+<span><span class='c'># Example 2: A (random) filter</span></span>
 <span><span class='nv'>rel_filter.dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>rel</span>, <span class='nv'>exprs</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nv'>df</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>rel</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
 <span></span>
@@ -331,6 +334,7 @@ This package also provides generics, for which other packages may then implement
 <span><span class='c'>#&gt; attr(,"class")</span></span>
 <span><span class='c'>#&gt; [1] "dfrel"      "relational"</span></span>
 <span></span>
+<span><span class='c'># Example 3: A custom projection</span></span>
 <span><span class='nv'>rel_project.dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>rel</span>, <span class='nv'>exprs</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nv'>df</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>rel</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
 <span></span>
@@ -354,6 +358,7 @@ This package also provides generics, for which other packages may then implement
 <span><span class='c'>#&gt; attr(,"class")</span></span>
 <span><span class='c'>#&gt; [1] "dfrel"      "relational"</span></span>
 <span></span>
+<span><span class='c'># Example 4: A custom ordering (eg, ascending by mpg)</span></span>
 <span><span class='nv'>rel_order.dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>rel</span>, <span class='nv'>exprs</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nv'>df</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>rel</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
 <span></span>
@@ -376,6 +381,8 @@ This package also provides generics, for which other packages may then implement
 <span><span class='c'>#&gt; </span></span>
 <span><span class='c'>#&gt; attr(,"class")</span></span>
 <span><span class='c'>#&gt; [1] "dfrel"      "relational"</span></span>
+<span></span>
+<span><span class='c'># Example 5: A custom join</span></span>
 <span><span class='nv'>rel_join.dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>left</span>, <span class='nv'>right</span>, <span class='nv'>conds</span>, <span class='nv'>join</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nv'>left_df</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>left</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
 <span>  <span class='nv'>right_df</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>right</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
@@ -398,6 +405,7 @@ This package also provides generics, for which other packages may then implement
 <span><span class='c'>#&gt; attr(,"class")</span></span>
 <span><span class='c'>#&gt; [1] "dfrel"      "relational"</span></span>
 <span></span>
+<span><span class='c'># Example 6: Limit the maximum rows returned</span></span>
 <span><span class='nv'>rel_limit.dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>rel</span>, <span class='nv'>n</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nv'>df</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>rel</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
 <span></span>
@@ -414,6 +422,8 @@ This package also provides generics, for which other packages may then implement
 <span><span class='c'>#&gt; attr(,"class")</span></span>
 <span><span class='c'>#&gt; [1] "dfrel"      "relational"</span></span>
 <span></span>
+<span><span class='c'># Example 7: Suppress duplicate rows</span></span>
+<span><span class='c'>#  (ignoring row names)</span></span>
 <span><span class='nv'>rel_distinct.dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>rel</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nv'>df</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>rel</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
 <span></span>
@@ -429,6 +439,7 @@ This package also provides generics, for which other packages may then implement
 <span><span class='c'>#&gt; attr(,"class")</span></span>
 <span><span class='c'>#&gt; [1] "dfrel"      "relational"</span></span>
 <span></span>
+<span><span class='c'># Example 8: Return column names</span></span>
 <span><span class='nv'>rel_names.dfrel</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>rel</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
 <span>  <span class='nv'>df</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/class.html'>unclass</a></span><span class='o'>(</span><span class='nv'>rel</span><span class='o'>)</span><span class='o'>[[</span><span class='m'>1</span><span class='o'>]</span><span class='o'>]</span></span>
 <span></span>