submitted 1.5 to CRAN... will update when accepted

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).

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
 

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,

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>

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)