Update docs. Preparations for CRAN

.Rbuildignore

@@ -6,4 +6,7 @@
 ^LICENSE-yyjson.txt$
 ^.devcontainer$
 ^\.github$
-^pkgdown$
+^pkgdown$
+^LICENSE\.md$
+^doc$
+^Meta$

.gitignore

@@ -8,4 +8,6 @@ inst/doc
 doc
 Meta
 pkgdown
-working
+working
+/doc/
+/Meta/

DESCRIPTION

@@ -1,16 +1,24 @@
 Package: yyjsonr
 Type: Package
-Title: Fast JSON Parsing and Serialisation
+Title: A Fast JSON Parser and Generator 
 Version: 0.1.13
 Authors@R: c(
-    person("Mike", "FC", role = c("aut", "cre"), email = "[email protected]"),
+    person("Mike", "Cheng", role = c("aut", "cre", 'cph'), 
+    email = "[email protected]"),
     person("Yao", "Yuan", role = "cph", email = "[email protected]", 
-    comment="author of bundled yyjson"))
-Maintainer: mikefc <[email protected]>
-Description: Wrapper for yyjson - a JSON parsing and serialisation C library.
+    comment="Author of bundled yyjson"))
+Maintainer: Mike Cheng <[email protected]>
+Description: A fast JSON parser, generator and validator which converts JSON 
+    data to/from R objects.  The standard R data types are supported 
+    (e.g. logical, numeric, integer) with configurable handling of NULL and NA 
+    values. Data frames, atomic vectors and  lists are all supported as data 
+    containers translated to/from JSON.
+    This implementation is a wrapper around the 'yyjson' C library.  
 License: MIT + file LICENSE
+URL: https://github.com/coolbutuseless/yyjsonr, https://coolbutuseless.github.io/package/yyjsonr/
+BugReports: https://github.com/coolbutuseless/yyjsonr/issues
 Encoding: UTF-8
-LazyData: true
+Language: en-AU
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.2.3
 Suggests: 

LICENSE

@@ -1,21 +1,2 @@
-MIT License
-
-Copyright (c) 2023 [email protected]
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+YEAR: 2023,2024
+COPYRIGHT HOLDER: Mike FC

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023,2024 [email protected]
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

NAMESPACE

@@ -2,14 +2,14 @@
 
 export(opts_read_json)
 export(opts_write_json)
-export(read_flag)
 export(read_json_conn)
 export(read_json_file)
 export(read_json_raw)
 export(read_json_str)
 export(validate_json_file)
 export(validate_json_str)
-export(write_flag)
 export(write_json_file)
 export(write_json_str)
+export(yyjson_read_flag)
+export(yyjson_write_flag)
 useDynLib(yyjsonr, .registration=TRUE)

R/json-opts.R

@@ -9,7 +9,7 @@
 #' the translation of JSON values to R.
 #'
 #" Pass multiple options with 
-#' \code{opts_read_json(yyjson_read_flag = c(read_flag$x, read_flag$y, ...))}
+#' \code{opts_read_json(yyjson_read_flag = c(yyjson_read_flag$x, yyjson_read_flag$y, ...))}
 #' 
 #' \describe{
 #' \item{YYJSON_READ_NOFLAG}{
@@ -42,7 +42,7 @@
 #'
 #' \item{YYJSON_READ_ALLOW_TRAILING_COMMAS}{
 #' Allow single trailing comma at the end of an object or array,
-#' such as \code{"[1,2,3,]"},  "{"a":1,"b":2,}" (non-standard).
+#' such as \code{"[1,2,3,]"},  '{"a":1,"b":2,}' (non-standard).
 #' }
 #' 
 #' \item{YYJSON_READ_ALLOW_COMMENTS}{
@@ -76,16 +76,16 @@
 #' The flag will be overridden by "YYJSON_READ_NUMBER_AS_RAW" flag.
 #' }
 #' }
-#'
-#' @examples
-#' \dontrun{
-#' read_json_str(str, opts = opts_read_json(yyjson_read_flag = read_flag$YYJSON_READ_NUMBER_AS_RAW))
-#' }
 #' 
-#'
 #' @export
+#'
+#' @examples
+#' read_json_str(
+#'    '[12.3]', 
+#'    opts = opts_read_json(yyjson_read_flag = yyjson_read_flag$YYJSON_READ_ALLOW_TRAILING_COMMAS)
+#'  )
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-read_flag <- list(
+yyjson_read_flag <- list(
   YYJSON_READ_NOFLAG                =   0L,
   YYJSON_READ_INSITU                =   1L,
   YYJSON_READ_STOP_WHEN_DONE        =   2L,
@@ -138,17 +138,14 @@ read_flag <- list(
 #' This flag will override `YYJSON_WRITE_PRETTY` flag.}
 #' }
 #' 
-#'
+#' @export
+#' 
 #' @examples
-#' \dontrun{
-#' write_json_str(str, opts = opts_write_json(
-#'   yyjson_write_flag = write_flag$YYJSON_WRITE_ESCAPE_SLASHES
+#' write_json_str("hello/there", opts = opts_write_json(
+#'   yyjson_write_flag = yyjson_write_flag$YYJSON_WRITE_ESCAPE_SLASHES
 #' ))
-#' }
-#' 
-#' @export
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-write_flag <- list(
+yyjson_write_flag <- list(
   YYJSON_WRITE_NOFLAG                  =  0L,
   YYJSON_WRITE_PRETTY                  =  1L,
   YYJSON_WRITE_ESCAPE_UNICODE          =  2L,
@@ -178,12 +175,12 @@ write_flag <- list(
 #'        a data.frame? Default: TRUE. If FALSE, then results will be read as a
 #'        list-of-lists.
 #' @param yyjson_read_flag integer vector of internal \code{yyjson}
-#'        options.  See \code{read_flag} in this package, and read
+#'        options.  See \code{yyjson_read_flag} in this package, and read
 #'        the yyjson API documentation for more information.  This is considered
 #'        an advanced option.
 #' @param str_specials Should \code{'NA'} in a JSON string be converted to the \code{'special'}
 #'        \code{NA} value in R, or left as a \code{'string'}.  Default: 'string'
-#' @param num_specials Should jsong strings 'NA'/'Inf'/'NaN' in a numeric context 
+#' @param num_specials Should JSON strings 'NA'/'Inf'/'NaN' in a numeric context 
 #'        be converted to the \code{'special'} R numeric values
 #'        \code{NA, Inf, NaN}, or left as a \code{'string'}. Default: 'special'
 #' @param promote_num_to_string Should numeric values be promoted to strings 
@@ -196,9 +193,12 @@ write_flag <- list(
 #' @param length1_array_asis logical. Should JSON arrays with length = 1 be 
 #'        marked with class \code{AsIs}.  Default: FALSE
 #'
-#' @seealso [read_flag()]
-#' @return Named list of options
+#' @seealso [yyjson_read_flag()]
+#' @return Named list of options for reading JSON
 #' @export
+#' 
+#' @examples
+#' opts_read_json()
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 opts_read_json <- function(
     int64                 = c('string', 'bit64'),
@@ -255,19 +255,16 @@ opts_read_json <- function(
 #'        converted to a JSON \code{null} value or converted to a string 
 #'        representation e.g. "NA"/"NaN" etc.   Default: 'null'
 #' @param yyjson_write_flag integer vector corresponding to internal \code{yyjson}
-#'        options.  See \code{write_flag} in this package, and read
+#'        options.  See \code{yyjson_write_flag} in this package, and read
 #'        the yyjson API documentation for more information.  This is considered
 #'        an advanced option.
 #' 
-#' @examples
-#' \dontrun{
-#' write_json_str(iris, opts = opts_write_json(factor = 'integer'))
-#' }
-#' 
-#' 
-#' @seealso [write_flag()]
-#' @return Named list of options
+#' @seealso [yyjson_write_flag()]
+#' @return Named list of options for writing JSON
 #' @export
+#' 
+#' @examples
+#' write_json_str(head(iris, 3), opts = opts_write_json(factor = 'integer'))
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 opts_write_json <- function( 
     digits            = -1,

R/json.R

@@ -8,15 +8,12 @@
 #' @param ... Other named options can be used to override any options in \code{opts}.
 #'        The valid named options are identical to arguments to [opts_read_json()]
 #'
-#'
-#' @examples
-#' \dontrun{
-#' read_json_str(str, opts = parse_opts(int64 = 'string'))
-#' }
-#' 
 #' @family JSON Parsers
 #' @return R object
 #' @export
+#'
+#' @examples
+#' read_json_str("4294967297", opts = opts_read_json(int64 = 'string'))
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 read_json_str <- function(str, opts = list(), ...) {
   .Call(
@@ -31,17 +28,14 @@ read_json_str <- function(str, opts = list(), ...) {
 #' 
 #' @inheritParams read_json_str
 #' @param raw_vec raw vector
-#'
-#'
-#' @examples
-#' \dontrun{
-#' a <- nanonext::ncurl("https://postman-echo.com/get", convert = FALSE)
-#' read_json_raw(a$raw)
-#' }
 #' 
 #' @family JSON Parsers
 #' @return R object
 #' @export
+#' 
+#' @examples
+#' raw_str <- as.raw(utf8ToInt('[1, 2, 3, "four"]'))
+#' read_json_raw(raw_str)
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 read_json_raw <- function(raw_vec, opts = list(), ...) {
   .Call(
@@ -58,15 +52,14 @@ read_json_raw <- function(raw_vec, opts = list(), ...) {
 #' @inheritParams read_json_str
 #' @param filename full path to text file containing JSON.
 #' 
-#' 
-#' @examples
-#' \dontrun{
-#' read_json_file("myfile.json")
-#' }
-#' 
 #' @family JSON Parsers
 #' @return R object
 #' @export
+#' 
+#' @examples
+#' tmp <- tempfile()
+#' write_json_file(head(iris, 3), tmp)
+#' read_json_file(tmp)
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 read_json_file <- function(filename, opts = list(), ...) {
   .Call(
@@ -80,7 +73,7 @@ read_json_file <- function(filename, opts = list(), ...) {
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #' Parse JSON from an R connection object.
 #' 
-#' Currently, this isn't very efficient as the entire contents of the connection are 
+#' Currently, this is not very efficient as the entire contents of the connection are 
 #' read into R as a string and then the JSON parsed from there.
 #' 
 #' For plain text files it is faster to use
@@ -92,7 +85,9 @@ read_json_file <- function(filename, opts = list(), ...) {
 #'
 #' @examples
 #' \dontrun{
-#' read_json_conn(url("https://api.github.com/users/hadley/repos"))
+#' if (interactive()) {
+#'   read_json_conn(url("https://api.github.com/users/hadley/repos"))
+#' }
 #' }
 #' 
 #' 
@@ -116,14 +111,11 @@ read_json_conn <- function(conn, opts = list(), ...) {
 #' 
 #' @return Character string
 #' 
-#' @examples
-#' \dontrun{
-#' write_json_str(iris, pretty = TRUE)
-#' write_json_str(iris, opts = opts_write_json(auto_unbox = FALSE))
-#' }
-#' 
 #' @family JSON Serializer
 #' @export
+#' 
+#' @examples
+#' write_json_str(head(iris, 3), pretty = TRUE)
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 write_json_str <- function(x, opts = list(), ...) {
   .Call(
@@ -140,13 +132,14 @@ write_json_str <- function(x, opts = list(), ...) {
 #' @inheritParams write_json_str
 #' @param filename filename
 #' 
-#' @examples
-#' \dontrun{
-#' write_json_str(iris, filename = "iris.json")
-#' }
-#' 
+#' @return NULL
 #' @family JSON Serializer
 #' @export
+#' 
+#' @examples
+#' tmp <- tempfile()
+#' write_json_file(head(iris, 3), tmp)
+#' read_json_file(tmp)
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 write_json_file <- function(x, filename, opts = list(), ...) {
   .Call(
@@ -171,6 +164,11 @@ write_json_file <- function(x, filename, opts = list(), ...) {
 #'
 #' @return Logical value. TRUE if JSON validates as OK, otherwise FALSE
 #' @export 
+#' 
+#' @examples
+#' tmp <- tempfile()
+#' write_json_file(head(iris, 3), tmp)
+#' validate_json_file(tmp)
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 validate_json_file <- function(filename, verbose = FALSE, opts = list(), ...) {
   opts <- modify_list(opts, list(...))
@@ -186,6 +184,10 @@ validate_json_file <- function(filename, verbose = FALSE, opts = list(), ...) {
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #' @rdname validate_json_file
 #' @export
+#' 
+#' @examples
+#' str <- write_json_str(iris)
+#' validate_json_str(str)
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 validate_json_str <- function(str, verbose = FALSE, opts = list(), ...) {
   opts <- modify_list(opts, list(...))

README.Rmd

@@ -152,9 +152,9 @@ yyjsonr::read_json_str(str)
     * GeoJSON support was removed for the initial CRAN release for the sake of my sanity.
     * See the `geojson` branch of this repository
 
-## Limitiations
+## Limitations
 
-* Some datatypes not currently supported. Please file an issue on github if
+* Some datatypes not currently supported. Please file an issue on GitHub if
   these types are critical for yoy:
     * Complex numbers
     * POSIXlt