documentation

.gitignore

@@ -1,3 +1,4 @@
+inst/doc
 .Rproj.user
 .Rhistory
 .RData

.travis.yml

@@ -5,6 +5,11 @@ cache: packages
 r_packages:
   - covr
 
+before_install:
+  - sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable --yes
+  - sudo apt-get --yes --force-yes update -qq
+  - sudo apt-get install --yes libudunits2-dev libproj-dev libgeos-dev libgdal-dev
+
 after_success:
   - Rscript -e 'covr::codecov()'
 

DESCRIPTION

@@ -4,7 +4,13 @@ Version: 0.0.0.9010
 Authors@R: 
     person("Joe", "Thorley", role = c("aut", "cre"), email = "joe@poissonconsulting.ca", comment = c(ORCID = "0000-0002-7683-4592"))
 Description: 
-  Enhances reading and writing to and from SQLiteConnection objects.
+  readwritesqlite preserves meta data, logs changes and provides informative error messages.
+  readwritesqlite preserves the time zone for POSIXct columns, 
+  the projection for sfc columns, the units for unit columns, 
+  the class for logical and Date columns and 
+  the levels for factors and ordered factors.
+  readwritesqlite logs the date time, system user and 
+  number of rows deleted, or inserted by table.
 License: MIT + file LICENSE
 Depends: R (>= 3.4)
 Imports: 
@@ -18,9 +24,12 @@ Imports:
 Suggests: 
     covr,
     testthat,
-    tibble
+    tibble,
+    knitr,
+    rmarkdown
 Remotes:
     poissonconsulting/dttr
 Encoding: UTF-8
 LazyData: true
 RoxygenNote: 6.1.1
+VignetteBuilder: knitr

NAMESPACE

@@ -3,8 +3,10 @@
 S3method(rws_read_sqlite,SQLiteConnection)
 S3method(rws_read_sqlite,character)
 S3method(rws_write_sqlite,data.frame)
+S3method(rws_write_sqlite,environment)
 S3method(rws_write_sqlite,list)
 export(check_sqlite_connection)
+export(rws_list_tables)
 export(rws_read_sqlite)
 export(rws_read_sqlite_log)
 export(rws_read_sqlite_meta)

R/db.R

@@ -2,13 +2,6 @@ column_names <- function(table_name, conn) {
   DBI::dbListFields(conn, table_name)
 }
 
-table_names <- function(conn) {
-  tables <- DBI::dbListTables(conn)
-  reserved <- to_upper(c(.log_table_name, .meta_table_name))
-  tables <- tables[!to_upper(tables) %in% reserved]
-  tables
-}
-
 tables_exists <- function(table_names, conn) {
   tables <- DBI::dbListTables(conn)
   to_upper(table_names) %in% to_upper(tables)

R/meta.R

@@ -9,7 +9,7 @@ meta_schema <- function () {
 }
 
 make_meta_data <- function(conn) {
-  table_names <- table_names(conn)
+  table_names <- rws_list_tables(conn)
   if(!length(table_names)) 
     return(data.frame(TableMeta = character(0), ColumnMeta = character(0),
                       stringsAsFactors = FALSE))

R/read.R

@@ -10,7 +10,7 @@ read_sqlite_data <- function(table_name, meta, conn) {
 #' @return A named list of data frames.
 #' @family rws_read_sqlite
 #' @export
-rws_read_sqlite <- function(x, ...) {
+rws_read_sqlite <- function(x, meta = TRUE, ...) {
   UseMethod("rws_read_sqlite")
 }
 
@@ -21,9 +21,9 @@ rws_read_sqlite <- function(x, ...) {
 #' @return A named list of the data frames.
 #' @family rws_read_sqlite
 #' @export
-rws_read_sqlite.character <- function(x,
-                                  conn = getOption("rws.conn", NULL),
-                                  meta = TRUE, ...) {
+rws_read_sqlite.character <- function(x, meta = TRUE,
+                                      conn = getOption("rws.conn", NULL),
+                                      ...) {
   check_sqlite_connection(conn, connected = TRUE)
   check_table_names(x, exists = TRUE, delete = FALSE, conn = conn)
   check_flag(meta)
@@ -46,7 +46,7 @@ rws_read_sqlite.SQLiteConnection <- function(x, meta = TRUE, ...) {
   check_flag(meta)
   check_unused(...)
 
-  table_names <- table_names(x)
+  table_names <- rws_list_tables(x)
   if(!length(table_names)) return(named_list())
   rws_read_sqlite(table_names, meta = meta, conn = x)
 }

R/readwritesqlite-package.R

@@ -0,0 +1,2 @@
+#' @keywords internal
+"_PACKAGE"

R/utils.R

@@ -0,0 +1,15 @@
+#' Table Names
+#' 
+#' Gets the table names excluding the names of the meta and log tables.
+#'
+#' @inheritParams rws_write_sqlite
+#'
+#' @return A character vector of table names.
+#' @export
+rws_list_tables <- function(conn = getOption("rws.conn", NULL)) {
+  check_sqlite_connection(conn, connected = TRUE)
+  tables <- DBI::dbListTables(conn)
+  reserved <- to_upper(c(.log_table_name, .meta_table_name))
+  tables <- tables[!to_upper(tables) %in% reserved]
+  tables
+}

R/write.R

@@ -12,7 +12,7 @@ write_sqlite_data <- function(data, table_name, exists, delete, meta,
 
 #' Write to a SQLite Database
 #'
-#' @param x The object to write.
+#' @param x The data frame, named list of data frames or environment with data frames to write.
 #' @param exists A flag specifying whether the table must already exist.
 #' @param delete A flag specifying whether to delete existing rows before 
 #' inserting data.
@@ -31,11 +31,6 @@ rws_write_sqlite <- function(x, exists = getOption("rws.exists", NA), delete = F
   UseMethod("rws_write_sqlite")
 }
 
-#' Write a data frame to a SQLite Database
-#'
-#' @inheritParams rws_write_sqlite
-#' @param table_name A string of the table name.
-#' @family rws_write_sqlite
 #' @export
 rws_write_sqlite.data.frame <- function(
   x, exists = getOption("rws.exists", NA), delete = FALSE, commit = TRUE,
@@ -71,11 +66,6 @@ rws_write_sqlite.data.frame <- function(
   invisible(table_name)
 }
 
-#' Write a list of data frames to a SQLite Database
-#'
-#' @param x A named list of data frames.
-#' @inheritParams rws_write_sqlite
-#' @family rws_write_sqlite
 #' @export
 rws_write_sqlite.list <- function(x,
                                   exists = getOption("rws.exists", NA),
@@ -117,3 +107,17 @@ rws_write_sqlite.list <- function(x,
   foreign_keys(foreign_keys, conn)
   invisible(invisible(names(x)))
 }
+
+#' @export
+rws_write_sqlite.environment <- function(x,
+                                         exists = getOption("rws.exists", NA),
+                                         delete = FALSE, commit = TRUE,
+                                         meta = TRUE, log = TRUE, 
+                                         conn = getOption("rws.conn", NULL), 
+                                         ...) {
+  x <- as.list(x)
+  check_unused(...)
+  invisible(
+    rws_write_sqlite(x, exists = exists, delete = delete, commit = commit,
+                     meta = meta, log = log, conn = conn))
+}

README.Rmd

@@ -30,7 +30,7 @@ However, current solutions do not preserve meta data, log changes or provide par
   - the projection for sfc columns
   - the units for unit columns
   - the class for logical and Date columns
-  - factor and ordered levels
+  - the levels for factors and ordered factors
 - logs 
     - the date time
     - system user
@@ -42,8 +42,8 @@ However, current solutions do not preserve meta data, log changes or provide par
 
 `readwritesqlite` also allows the user to 
 
-- read and write lists of data frames
-- rearrange and add factor and ordered levels
+- read and write named lists or environments of data frames
+- rearrange and add levels for factors and ordered factors
 - delete existing data (and meta data) before writing
 - confirm data can be written without commiting any changes
 
@@ -54,9 +54,8 @@ library(readwritesqlite)
 rws_data
 
 conn <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
-rws_write_sqlite(rws_data, conn = conn)
 
-rws_read_sqlite_log(conn)
+rws_write_sqlite(rws_data, conn = conn)
 
 rws_read_sqlite(conn)
 

README.md

@@ -25,7 +25,7 @@ provide particularly useful error messages.
       - the projection for sfc columns
       - the units for unit columns
       - the class for logical and Date columns
-      - factor and ordered levels
+      - the levels for factors and ordered factors
   - logs
       - the date time
       - system user
@@ -38,8 +38,8 @@ provide particularly useful error messages.
 
 `readwritesqlite` also allows the user to
 
-  - read and write lists of data frames
-  - rearrange and add factor and ordered levels
+  - read and write named lists or environments of data frames
+  - rearrange and add levels for factors and ordered factors
   - delete existing data (and meta data) before writing
   - confirm data can be written without commiting any changes
 
@@ -54,14 +54,8 @@ rws_data
 #> 3      NA       <NA>   <NA>    <NA>                <NA>    NA     1, 1
 
 conn <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
-rws_write_sqlite(rws_data, conn = conn)
 
-rws_read_sqlite_log(conn)
-#> # A tibble: 2 x 5
-#>   DateTimeUTCLog      UserLog TableLog CommandLog NRowLog
-#>   <dttm>              <chr>   <chr>    <chr>        <int>
-#> 1 2018-12-10 20:25:37 joe     RWS_DATA CREATE           0
-#> 2 2018-12-10 20:25:37 joe     RWS_DATA INSERT           3
+rws_write_sqlite(rws_data, conn = conn)
 
 rws_read_sqlite(conn)
 #> $rws_data