From 3b7ee3aed26f3f35082b25dc279df8959ca3c089 Mon Sep 17 00:00:00 2001
From: Tony Fischetti <tony.fischetti@gmail.com>
Date: Fri, 23 Apr 2021 21:35:28 -0400
Subject: [PATCH] submitted 1.5 to CRAN... will update when accepted

---
 CRAN-RELEASE                         |   2 +
 NEWS.md                              |   2 +-
 R/worldcat-api.R                     |  95 +++++++++++++++++++++------
 README.md                            |  23 +++++--
 cran-comments.md                     |   4 +-
 data/books_serials_etc_sample.rda    | Bin 3390 -> 3389 bytes
 man/worldcat_api_bib_read_info_by.Rd |   4 +-
 man/worldcat_api_locations_by.Rd     |  11 ++--
 man/worldcat_api_search.Rd           |  78 ++++++++++++++++++----
 9 files changed, 173 insertions(+), 46 deletions(-)
 create mode 100644 CRAN-RELEASE

diff --git a/CRAN-RELEASE b/CRAN-RELEASE
new file mode 100644
index 0000000..daac877
--- /dev/null
+++ b/CRAN-RELEASE
@@ -0,0 +1,2 @@
+This package was submitted to CRAN on 2021-04-23.
+Once it is accepted, delete this file and tag the release (commit a33f9681e7a9a).
diff --git a/NEWS.md b/NEWS.md
index 3042e47..7af7aa2 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -3,7 +3,7 @@
 [latest news on GitHub](https://github.com/NYPL/libbib/blob/master/NEWS.md)
 where the formatting is better.**
 
-# libbib 2.0 (in development)
+# libbib 1.5
 
 ## new features
 
diff --git a/R/worldcat-api.R b/R/worldcat-api.R
index 47ce8d0..024540f 100755
--- a/R/worldcat-api.R
+++ b/R/worldcat-api.R
@@ -329,8 +329,8 @@ worldcat_api_bib_read_info_by_something <- function(x,
 #'          chosen accepts.
 #' @param wskey A WorldCat API key (default is \code{getOption("libbib.wskey")})
 #' @param more A logical indicating whether more infomation from the MARCXML
-#'             should be returned (publisher, etc....) In the interest of
-#'             memory consumption, the default is \code{FALSE}
+#'             should be returned (publisher, bib level etc....) In the
+#'             interest of memory consumption, the default is \code{FALSE}
 #' @param debug A logical indicating whether the HTTP and bib read API
 #'              responses should be printed (for debugging)
 #'              (default is \code{FALSE})
@@ -720,11 +720,12 @@ worldcat_api_locations_by_something <- function(x,
 #'                     an application where a user is not logged in to an
 #'                     institution, set this to "default". It is up to you
 #'                     to respect the WorldCat API's conditions.
-#' @param frbrGrouping With this parameter set to "on" (default), an attempt
-#'                     is made by the WorldCat API to group equivalent works
-#'                     (different editions, format, etc...) together. If not,
-#'                     only institutions holding the exact standard number
-#'                     specified will be returned.
+#' @param frbrGrouping With this parameter set to "on" (default),
+#'                     an attempt is made by the WorldCat API to group
+#'                     together similar editions and present only the top
+#'                     held record as the representative record for that group.
+#'                     If not, only institutions holding the exact standard
+#'                     number specified will be returned.
 #' @param libtype One of \code{NULL} (default), "academic", "public",
 #'                "government", or "other". \code{NULL} will return all
 #'                library subsets. The others will only search for holdings
@@ -864,7 +865,6 @@ worldcat_api_locations_by_issn <- function(x,
 construct_wcapi_search_url <- function(sru, max_records=100,
                                        frbrGrouping="on", start_at=1,
                                        wskey=getOption("libbib.wskey", "")){
-
   # error checking
   if(class(sru)!="character")
     stop("SRU search must be a string")
@@ -952,26 +952,81 @@ worldcat_api_search_helper <- function(sru, max_records=100,
 
 #' Use the WorldCat Search API
 #'
-#' STUB
+#' Searches WorldCat using a CQL query. Returns a \code{data.table}
+#' containing the bibliographic metadata of the results, along
+#' with the total number of results.
 #'
-#' @param sru STUB
-#' @param max_records STUB
-#' @param frbrGrouping STUB
-#' @param start_at STUB
-#' @param wskey STUB
-#' @param more STUB
-#' @param print.progress STUB
-#' @param debug STUB
+#' @param sru The search query (in CQL syntax). See \code{examples} section
+#'            for some examples.
+#' @param max_records The maximum number of search results to return.
+#'                    Must be a number between 0 and 100 or \code{Inf}.
+#'                    If \code{Inf} (default), the function will
+#'                    automatically make all follow-up requests to retrieve
+#'                    all search results. For safety, the default is 10.
+#' @param frbrGrouping With this parameter set to "on" (default),
+#'                     an attempt is made by the WorldCat API to group
+#'                     together similar editions and present only the top
+#'                     held record as the representative record for that group.
+#' @param start_at The search result to start at (default is 1)
+#' @param wskey A WorldCat API key (default is \code{getOption("libbib.wskey")})
+#' @param more A logical indicating whether more infomation from the MARCXML
+#'             search results should be returned (publisher, bib level, etc....).
+#'             (Default is \code{TRUE})
+#' @param print.progress A logical indicating whether a message should be
+#'                       displayed for each API request. If \code{max_records}
+#'                       is \code{TRUE} a message will be displayed for every
+#'                       group of 100 search results the function fetches.
+#'                       (default is \code{TRUE})
+#' @param debug A logical indicating whether the HTTP and API
+#'              responses should be printed (for debugging)
+#'              (default is \code{FALSE})
 #'
 #' @details
-#' STUB
 #'
-#' @return STUB
+#' As with all API access functions in this package, it's up to the
+#' user to limit their API usage so as to not get blocked. These
+#' functions are deliberately not vectorized for this reason; they
+#' only accept one standard number at a time.
+#'
+#' This (and other) WorldCat API communication functions require a
+#' WorldCat API key. The easiest way to use these functions is to
+#' set a global options with your key:
+#' \code{options("libbib.wskey"="YOUR KEY HERE")}
+#'
+#' @return A \code{data.table} containing the bibliographic metadata of the
+#'         results, along with the total number of results.
 #'
 #' @examples
 #'
-#' # STUB
+#' \dontrun{
+#'
+#' # A title search of "The Brothers Karamazov"
+#' worldcat_api_search('srw.ti="Brothers Karamazov"')
 #'
+#' # Search for title "Madame Bovary" by author "Gustave Flaubert"
+#' # in language Greek (all results)
+#' sru <- 'srw.au="Gustave Flaubert" and srw.ti="Madame Bovary" and srw.la=gre'
+#' worldcat_api_search(sru, max_records=Inf)
+#'
+#' # Hip Hop (subject) materials on Cassette, CD, or wax from years 1987 to 1990
+#' sru <- '((srw.mt=cas or srw.mt=cda or srw.mt=lps) and srw.su="Rap") and srw.yr="1987-1990"'
+#' worldcat_api_search(sru)
+#'
+#' # all materials with keyword "Common Lisp" at The New York Public Library
+#' sru <- 'srw.kw="common lisp" and srw.li=NYP'
+#' worldcat_api_search(sru, max_records=Inf)
+#'
+#' # 19th century materials on ethics (Dewey code 170s / LC Call prefix BJ)
+#' sru <- '(srw.dd="17*" or srw.lc="bj*") and srw.yr="18*"'
+#' worldcat_api_search(sru, max_records=Inf)
+#'
+#' # Music (Dewey 780s) materials that are only held by The New York Public
+#' # Library (a "cg" code of 11 means there is only one holding)
+#' # [searching with debugging]
+#' sru <- 'srw.dd="78*" and srw.li=NYP and srw.cg=11'
+#' worldcat_api_search(sru, debug=TRUE)
+#'
+#' }
 #' @export
 worldcat_api_search <- function(sru, max_records=10,
                                  frbrGrouping="on", start_at=1,
diff --git a/README.md b/README.md
index 6ed9b02..fe8521d 100755
--- a/README.md
+++ b/README.md
@@ -8,11 +8,12 @@ libbib <img src="http://statethatiamin.com/media/libbibsmall.png" align="right"
 
 
 ## Description
-An R package providing functions for for validating and normalizing
-bibliographic codes such as ISBN, ISSN, and LCCN. Includes functions to
-translate Call numbers (Library of Congress and Dewey Decimal) to their
-subject classifications or subclassifications. Also provides various
-loadable data files such call number / subject crosswalks and code
+An R package providing WorldCat API communication, functions for validating
+and normalizing bibliographic codes such as ISBN; ISSN; and LCCN, translation
+from call numbers (Library of Congress and Dewey Decimal) to their subject
+classifications or subclassifications, and other related utilities helpful
+for assessment librarians. Also provides various loadable data files such
+call number / subject crosswalks and code tables.
 
 Speed of execution and robustness are priorities in this package.
 To the end of optimizing speed and efficiency, careful consideration
@@ -53,6 +54,18 @@ automated tests, at time of writing
 > normalize_lccn(" 79139101 /AC/r932")
 [1] "79139101"
 
+> # Do a WorldCat APU search on 19th century materials on ethics
+> # (Dewey code 170s / LC Call prefix BJ)
+> results <- worldcat_api_search('(srw.dd="17*" or srw.lc="bj*") and srw.yr="18*"')
+> results[,.(oclc, title, result_number, num_results)][1:5]
+        oclc                                       title result_number num_results
+      <char>                                      <char>         <int>      <char>
+1:   8665856 The principles of moral and political ph...             1        1716
+2: 191264919                The economy of human life. /             2        1716
+3:  22571399                                   Solitude:             3        1716
+4:  65250134 The theory of moral sentiments, or, An e...             4        1716
+5:  13106952    Letters on the improvement of the mind :             5        1716 
+
 > worldcat_api_bib_read_info_by_isbn("9780984201006")
         oclc          isbn   issn                        title
       <char>        <char> <char>                       <char>
diff --git a/cran-comments.md b/cran-comments.md
index 807c405..e68f830 100644
--- a/cran-comments.md
+++ b/cran-comments.md
@@ -8,5 +8,7 @@
 
 When checked with --as-cran and --no-manual
 there were no ERRORs or WARNINGs but 1 NOTE related
-to being a new submission
+to "WorldCat" being a possibly mis-spelled word
+(but it's a valid term in the context of this
+package)
 
diff --git a/data/books_serials_etc_sample.rda b/data/books_serials_etc_sample.rda
index 983b368396a9ad9032f504587d41f603cfcc7f7a..005a7feebfb02581f8195090a34748db5d14fee4 100644
GIT binary patch
delta 3299
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

delta 3300
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

diff --git a/man/worldcat_api_bib_read_info_by.Rd b/man/worldcat_api_bib_read_info_by.Rd
index 64375c3..0a27b75 100644
--- a/man/worldcat_api_bib_read_info_by.Rd
+++ b/man/worldcat_api_bib_read_info_by.Rd
@@ -35,8 +35,8 @@ chosen accepts.}
 \item{wskey}{A WorldCat API key (default is \code{getOption("libbib.wskey")})}
 
 \item{more}{A logical indicating whether more infomation from the MARCXML
-should be returned (publisher, etc....) In the interest of
-memory consumption, the default is \code{FALSE}}
+should be returned (publisher, bib level etc....) In the
+interest of memory consumption, the default is \code{FALSE}}
 
 \item{debug}{A logical indicating whether the HTTP and bib read API
 responses should be printed (for debugging)
diff --git a/man/worldcat_api_locations_by.Rd b/man/worldcat_api_locations_by.Rd
index 795a9a5..e9cf5d9 100644
--- a/man/worldcat_api_locations_by.Rd
+++ b/man/worldcat_api_locations_by.Rd
@@ -85,11 +85,12 @@ an application where a user is not logged in to an
 institution, set this to "default". It is up to you
 to respect the WorldCat API's conditions.}
 
-\item{frbrGrouping}{With this parameter set to "on" (default), an attempt
-is made by the WorldCat API to group equivalent works
-(different editions, format, etc...) together. If not,
-only institutions holding the exact standard number
-specified will be returned.}
+\item{frbrGrouping}{With this parameter set to "on" (default),
+an attempt is made by the WorldCat API to group
+together similar editions and present only the top
+held record as the representative record for that group.
+If not, only institutions holding the exact standard
+number specified will be returned.}
 
 \item{libtype}{One of \code{NULL} (default), "academic", "public",
 "government", or "other". \code{NULL} will return all
diff --git a/man/worldcat_api_search.Rd b/man/worldcat_api_search.Rd
index ce69a6b..5ce2f29 100644
--- a/man/worldcat_api_search.Rd
+++ b/man/worldcat_api_search.Rd
@@ -16,33 +16,87 @@ worldcat_api_search(
 )
 }
 \arguments{
-\item{sru}{STUB}
+\item{sru}{The search query (in CQL syntax). See \code{examples} section
+for some examples.}
 
-\item{max_records}{STUB}
+\item{max_records}{The maximum number of search results to return.
+Must be a number between 0 and 100 or \code{Inf}.
+If \code{Inf} (default), the function will
+automatically make all follow-up requests to retrieve
+all search results. For safety, the default is 10.}
 
-\item{frbrGrouping}{STUB}
+\item{frbrGrouping}{With this parameter set to "on" (default),
+an attempt is made by the WorldCat API to group
+together similar editions and present only the top
+held record as the representative record for that group.}
 
-\item{start_at}{STUB}
+\item{start_at}{The search result to start at (default is 1)}
 
-\item{wskey}{STUB}
+\item{wskey}{A WorldCat API key (default is \code{getOption("libbib.wskey")})}
 
-\item{more}{STUB}
+\item{more}{A logical indicating whether more infomation from the MARCXML
+search results should be returned (publisher, bib level, etc....).
+(Default is \code{TRUE})}
 
-\item{print.progress}{STUB}
+\item{print.progress}{A logical indicating whether a message should be
+displayed for each API request. If \code{max_records}
+is \code{TRUE} a message will be displayed for every
+group of 100 search results the function fetches.
+(default is \code{TRUE})}
 
-\item{debug}{STUB}
+\item{debug}{A logical indicating whether the HTTP and API
+responses should be printed (for debugging)
+(default is \code{FALSE})}
 }
 \value{
-STUB
+A \code{data.table} containing the bibliographic metadata of the
+        results, along with the total number of results.
 }
 \description{
-STUB
+Searches WorldCat using a CQL query. Returns a \code{data.table}
+containing the bibliographic metadata of the results, along
+with the total number of results.
 }
 \details{
-STUB
+As with all API access functions in this package, it's up to the
+user to limit their API usage so as to not get blocked. These
+functions are deliberately not vectorized for this reason; they
+only accept one standard number at a time.
+
+This (and other) WorldCat API communication functions require a
+WorldCat API key. The easiest way to use these functions is to
+set a global options with your key:
+\code{options("libbib.wskey"="YOUR KEY HERE")}
 }
 \examples{
 
-# STUB
+\dontrun{
+
+# A title search of "The Brothers Karamazov"
+worldcat_api_search('srw.ti="Brothers Karamazov"')
+
+# Search for title "Madame Bovary" by author "Gustave Flaubert"
+# in language Greek (all results)
+sru <- 'srw.au="Gustave Flaubert" and srw.ti="Madame Bovary" and srw.la=gre'
+worldcat_api_search(sru, max_records=Inf)
+
+# Hip Hop (subject) materials on Cassette, CD, or wax from years 1987 to 1990
+sru <- '((srw.mt=cas or srw.mt=cda or srw.mt=lps) and srw.su="Rap") and srw.yr="1987-1990"'
+worldcat_api_search(sru)
 
+# all materials with keyword "Common Lisp" at The New York Public Library
+sru <- 'srw.kw="common lisp" and srw.li=NYP'
+worldcat_api_search(sru, max_records=Inf)
+
+# 19th century materials on ethics (Dewey code 170s / LC Call prefix BJ)
+sru <- '(srw.dd="17*" or srw.lc="bj*") and srw.yr="18*"'
+worldcat_api_search(sru, max_records=Inf)
+
+# Music (Dewey 780s) materials that are only held by The New York Public
+# Library (a "cg" code of 11 means there is only one holding)
+# [searching with debugging]
+sru <- 'srw.dd="78*" and srw.li=NYP and srw.cg=11'
+worldcat_api_search(sru, debug=TRUE)
+
+}
 }