only rdoxygen for merge

wactbprot · Oct 11, 2012 · 333d578 · 333d578
1 parent c6f2f90
commit 333d578
Show file tree

Hide file tree

Showing 14 changed files with 361 additions and 532 deletions.
diff --git a/R4CouchDB/R/cdbAddAttachment.R b/R4CouchDB/R/cdbAddAttachment.R
@@ -1,52 +1,43 @@
-cdbAddAttachment <- function( cdb){
-
-  if(cdb$serverName == ""){
-    cdb$error <- paste(cdb$error," no cdb$serverName given ")
-  }
-
-  if(cdb$DBName ==""){
-    cdb$error <- paste(cdb$error, " no cdb$DBName given ", sep=" ")
-  }
-
-  if( !(file.exists(cdb$fileName))){
-
-    cdb$error <- paste(cdb$error,
-                       " no cdb$fileName given or ",
-                       cdb$fileName,
-                       " does not exist",
-                       sep=" ")
-  }
-
-  if(cdb$error == ""){
-
-    tmpN <- length(tmpFn <- unlist(strsplit(cdb$fileName,"\\.")))
-
-    noOfBytes <- file.info(cdb$fileName)$size
-    con <- file(cdb$fileName, "rb")
-    data <- readBin(con,n=noOfBytes,raw())
-
-    close(con)
-
-    cdb$rev <- cdbGetDoc(cdb)$res$'_rev'
-
-    adrString <- paste(cdb$baseUrl(cdb),
-                       cdb$DBName,"/",
-                       cdb$id,"/",
-                       basename(cdb$fileName),"?rev=",
-                       cdb$rev,
-                       sep="")
-
-    res <- getURL(adrString,
-                  customrequest = "PUT",
-                  postfields = data,
-                  httpheader=c('Content-Type' =  paste("image/",tmpFn[tmpN],sep="")),
-                  curl=cdb$curl,
-                  .opts =cdb$opts(cdb)
-                  )
-
-    return(cdb$checkRes(cdb,res))
-
-  }else{
-    stop(cdb$error)
-  }
-}
+#' Add Attachments
+#' 
+#' This function adds attachments to a doc.
+#' 
+#' The function uses a simple call to \code{strsplit(fileName, ".")} and takes
+#' the last entry of the resulting vector as the \code{Content-Type} in the
+#' \code{httpheader}.
+#' 
+#' @usage cdbAddAttachment(cdb)
+#' @param cdb The list \code{cdb} has to contain
+#' \code{cdb$fileName},\code{cdb$serverName}, \code{cdb$DBName} and a
+#' \code{cdb$id}.
+#' @return \item{cdb}{The result is stored in \code{cdb$res} }
+#' @author wactbprot
+#' @export
+#' @keywords misc
+#' @examples
+#' 
+#' 
+#'# make a png (stolen from ?persp)
+#' x <- seq(-10, 10, length= 30)
+#'       y <- x
+#'       f <- function(x,y) { r <- sqrt(x^2+y^2); 10 * sin(r)/r }
+#'       z <- outer(x, y, f)
+#'       z[is.na(z)] <- 1
+#'       op <- par(bg = "white")
+#'
+#' cdb            <- cdbIni()
+#' cdb$serverName <- "localhost"
+#'
+#' cdb$DBName     <- "r4couchdb" ## should already exist
+#' cdb$fileName   <- paste("../",cdb$DBName,".test.png", sep="")
+#' cdb$dataList   <- list(data=list(x=x,y=y,z=z),
+#'                         date=cdb$date)
+#' cdb            <- cdbAddDoc(cdb)
+#' 
+#' png(filename=cdb$fileName)
+#'       persp(x, y, z, theta = 30, phi = 30, expand = 0.5, col = "lightblue")
+#' dev.off()
+#' 
+#' ## finaly the reason why we are here:
+#' cdb            <- cdbAddAttachment(cdb)
+#' 
diff --git a/R4CouchDB/R/cdbAddDoc.R b/R4CouchDB/R/cdbAddDoc.R
@@ -1,47 +1,28 @@
-cdbAddDoc <- function( cdb){
-
-  if(cdb$serverName == ""){
-    cdb$error <- paste(cdb$error," no cdb$serverName given")
-  }
-
-  if(cdb$DBName == ""){
-    cdb$error <- paste(cdb$error, " no cdb$DBName given ", sep=" ")
-  }
-
-  if( (length(cdb$dataList) < 1)){
-    cdb$error <- paste(cdb$error, " no cdb$dataList given ", sep=" ")
-  }
-
-  if(cdb$id == ""){
-    cdb <- cdbGetUuid(cdb)
-  }
-
-  if(cdb$error == ""){
-
-    adrString <- paste(cdb$baseUrl(cdb),
-                       cdb$DBName,"/",
-                       cdb$id,
-                       sep="")
-
-    res <- getURL(adrString,
-                  customrequest = "PUT",
-                  curl=cdb$curl,
-                  postfields = cdb$toJSON(cdb$dataList),
-                  httpheader=c('Content-Type: application/json'),
-                  .opts =cdb$opts(cdb))
-
-    res <- cdb$fromJSON( res )
-
-    if(length(res$ok) > 0){
-      cdb$dataList$'_id' <- res$id
-      cdb$dataList$'_rev' <- res$rev
-      cdb$res <- res
-      return( cdb )
-    }else{
-      cdb$error <- paste(cdb$error, res$error)
-    }
-  }
-  if(!(cdb$error == "")){
-    stop( cdb$error )
-  }
-}
+#' Generates a new document
+#' 
+#' This function adds a new document to an already existing database
+#' 
+#' This function is called addDoc (which means add a new document). Therefore
+#' the \code{cdb$id} is requested using \code{cdbGetUuid()} for every document
+#' to add if no \code{cdb$id} is provided. If a \code{cdb$id} is provided the
+#' function fails when a document with the given id already exists. In this
+#' case one should use \code{cdbUpdateDoc()}. Since version v0.6 the function
+#' writes the \code{_rev} and \code{_id} key to the top level of
+#' \code{cdb$dataList}.
+#' 
+#' @usage cdbAddDoc(cdb)
+#' @param cdb The list \code{cdb} only has to contain a \code{cdb$dataList}
+#' which is not an empty \code{list()}.
+#' @return \item{cdb}{The couchdb response is stored in \code{cdb$res} }
+#' @author wactbprot
+#' @export
+#' @seealso \code{cdbGetDoc()}
+#' @keywords misc
+#' @examples
+#' 
+#' ccc            <- cdbIni()
+#' ccc$DBName     <- "r4couchdb" ## should already exist
+#' ccc$dataList   <- list(normalDistRand =  rnorm(20))
+#' 
+#' cdbAddDoc(ccc)$res
+#' 
diff --git a/R4CouchDB/R/cdbDeleteDoc.R b/R4CouchDB/R/cdbDeleteDoc.R
@@ -1,32 +1,22 @@
-cdbDeleteDoc <- function( cdb ){
-  if(cdb$serverName == ""){
-    cdb$error <- paste(cdb$error," no cdb$serverName given")
-  }
-  if(cdb$DBName ==""){
-    cdb$error <- paste(cdb$error, " no cdb$DBName given ")
-  }
-  if(cdb$id ==""){
-    cdb$error <- paste(cdb$error, " no cdb$id given ")
-  }
-  if(cdb$error == ""){
-    cdb <- cdbGetDoc(cdb)
-    cdb$rev <- cdb$res$'_rev'
-
-    adrString <- paste(cdb$baseUrl(cdb),
-                       cdb$DBName,"/",
-                       cdb$id,
-                       "?rev=",
-                       cdb$rev,
-                       sep="")
-
-    res <- getURL(adrString,
-                  customrequest = "DELETE",
-                  curl = cdb$curl,
-                  .opts =cdb$opts(cdb))
-
-    return(cdb$checkRes(cdb,res))
-
-  }else{
-    stop(cdb$error)
-  }
-}
+#' Deletes a document from a database
+#' 
+#' With a given \code{cdb$id} this function sends a http \code{"DELETE"}
+#' request to the url \code{.../cdb$id?rev=cdb$rev}.
+#' 
+#' 
+#' @usage cdbDeleteDoc(cdb)
+#' @param cdb Beside \code{cdb$serverName}, \code{cdb$port} and
+#' \code{cdb$DBName} the \code{cdb$id} must be given. R errors are reported in
+#' \code{cdb$errors}
+#' @return
+#' 
+#' \item{cdb }{The result of the delete request is stored in
+#' \code{cdb$res}(whatever this means).  }
+#' @author wactbprot
+#' @export
+#' @seealso \code{cdbAddDoc()}
+#' @references
+#' 
+#' \url{ http://couchdb.apache.org/ } \url{ http://www.omegahat.org/ }
+#' @keywords misc
+#'
diff --git a/R4CouchDB/R/cdbGetConfig.R b/R4CouchDB/R/cdbGetConfig.R
@@ -1,18 +1,19 @@
-cdbGetConfig <- function(cdb){
-  if(cdb$serverName == ""){
-    cdb$error <- paste(cdb$error," no cdb$serverName given")
-  }
-  if (cdb$error ==""){
-    adrString <- paste(cdb$baseUrl(cdb),
-                       "_config",
-                       sep="")
-    res <- getURL(adrString,
-                  customrequest = "GET",
-                  curl=cdb$curl
-                  )
-
-    return(cdb$checkRes(cdb,res))
-  }else{
-    stop( cdb$error )
-  }
-}
+#' Request couchdb config
+#' 
+#' Function provides access to the \code{_config} api end point
+#' 
+#' 
+#' @param cdb Only the connection settings \code{cdb$port} and
+#' \code{cdb$serverName} is needed.
+#' @return
+#' 
+#' \item{cdb }{The result of the request is stored in \code{cdb$re} after
+#' converting the answer into a list using \code{fromJSON()}.  }
+#' @author wactbprot
+#' @export
+#' @seealso \code{cdbMakeDB}
+#' @references
+#' 
+#' \url{ http://www.omegahat.org/RCurl/ } \url{
+#' http://www.omegahat.org/RJSONIO/ } \url{ http://couchdb.apache.org/ }
+#' @keywords misc
diff --git a/R4CouchDB/R/cdbGetDoc.R b/R4CouchDB/R/cdbGetDoc.R
@@ -1,25 +1,31 @@
-cdbGetDoc <- function(cdb){
-
-  if(cdb$serverName == ""){
-    cdb$error <- paste(cdb$error," no cdb$serverName given")
-  }
-
-  if( cdb$id == ""){
-    cdb$error <- paste( cdb$error, " no cdb$id given ")
-  }
-
-  if(cdb$error == ""){
-    adrString <- paste(cdb$baseUrl(cdb),
-                       cdb$DBName,"/",
-                       cdb$id,
-                       sep="")
-
-    res <- getURL(adrString,
-                  customrequest = "GET")
-
-    return(cdb$checkRes(cdb,res))
-
-  }else{
-    stop(cdb$error)
-  }
-}
+#' Get a doc from CouchDB
+#' 
+#' With a given \code{cdb$id} this function requests the document.
+#' 
+#' 
+#' @usage cdbGetDoc(cdb)
+#' @param cdb Beside \code{cdb$serverName}, \code{cdb$port} and
+#' \code{cdb$DBName} the \code{cdb$id} must be given. R errors are reported
+#' 
+#' in cdb$errors
+#' @return
+#' 
+#' \item{cdb }{The result of the request is stored in \code{cdb$res} after
+#' converting the answer into a list using \code{fromJSON()}. If a list entry
+#' needed in \code{cdb} is not provided \code{cdb$error} gives some
+#' information.
+#' 
+#' }
+#' @author wactbprot
+#' @export
+#' @seealso \code{cdbAddDoc()}
+#' @references
+#' 
+#' \url{ http://couchdb.apache.org/ } \url{ http://www.omegahat.org/ }
+#' @keywords misc
+#' @examples
+#' 
+#' ccc          <- cdbIni()
+#' ccc$DBName   <- "r4couchdb" ## should already exist
+#' ccc$dataList <- list(normalDistRand =  rnorm(20))
+#' ccc          <- cdbAddDoc(ccc)