Merge branch 'documentation'

Author: mtmorgan

.Rbuildignore

@@ -10,3 +10,4 @@
 ^scratch$
 ^CRAN-SUBMISSION$
 ^data$
+^vignettes/articles$

.github/workflows/pkgdown.yaml

@@ -32,7 +32,7 @@ jobs:
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::pkgdown, local::.
+          extra-packages: any::pkgdown, local::., tidyr
           needs: website
 
       - name: Build site

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: rjsoncons
 Title: 'C++' Header-Only 'jsoncons' Library for 'JSON' Queries
-Version: 1.1.0.9401
+Version: 1.1.0.9500
 Authors@R: c(
     person(
         "Martin", "Morgan", role = c("aut", "cre"),

NEWS.md

@@ -1,5 +1,7 @@
 # rjsoncons 1.2.0
 
+- (1.1.0.9500) update documentation, include NDJSON-specific, web-only
+  vignette
 - (1.1.0.9400) support NDJSON and file / url connections
 - (1.1.0.9300) implement `j_query()` (query without requiring path
   specification), `j_pivot()`, and `j_path_type()`. Remove

R/j_query.R

@@ -35,8 +35,10 @@
 #' j_query(json, "$.locations[*].name", as = "R") # JSONpath
 #' j_query(json, "locations[].state", as = "R")   # JMESpath
 #'
-#' ndjson_file <- system.file(package = "rjsoncons", "extdata", "example.ndjson")
-#' j_query(ndjson_file, "{name: name, state: state}")
+#' ## a few NDJSON records from <https://www.gharchive.org/>
+#' ndjson_file <-
+#'     system.file(package = "rjsoncons", "extdata", "2023-02-08-0.json")
+#' j_query(ndjson_file, "{id: id, type: type}")
 #'
 #' @export
 j_query <-
@@ -75,29 +77,39 @@ j_query <-
 #'
 #' @details
 #'
-#' `j_pivot()` transforms an 'array-of-objects' (typical when the
-#' JSON is a row-oriented representation of a table) to an
+#' `j_pivot()` transforms an 'array-of-objects' (typical when the JSON
+#' is a row-oriented representation of a table) to an
 #' 'object-of-arrays'. A simple example transforms an array of two
 #' objects each with three fields `'[{"a": 1, "b": 2, "c": 3}, {"a":
-#' 4, "b": 5, "c": 6}]'` to an object with with three fields, each a
-#' vector of length 2 `'{"a": [1, 4], "b": [2, 5], "c": [3, 6]}'`. The
+#' 4, "b": 5, "c": 6}]'` to an object with three fields, each a vector
+#' of length 2 `'{"a": [1, 4], "b": [2, 5], "c": [3, 6]}'`. The
 #' object-of-arrays representation corresponds closely to an _R_
 #' data.frame or tibble, as illustrated in the examples.
 #'
+#' `j_pivot()` with JMESpath paths are especially useful for
+#' transforming NDJSON to a `data.frame` or `tibble`
+#'
 #' @examples
 #' j_pivot(json, "$.locations[[email protected]=='WA']", as = "string")
 #' j_pivot(json, "locations[[email protected]=='WA']", as = "R")
 #' j_pivot(json, "locations[[email protected]=='WA']", as = "data.frame")
 #' j_pivot(json, "locations[[email protected]=='WA']", as = "tibble")
 #'
 #' ## use 'path' to pivot ndjson one record at at time
-#' j_pivot(ndjson_file, "{name: name, state: state}", as = "data.frame")
+#' j_pivot(ndjson_file, "{id: id, type: type}", as = "data.frame")
+#'
+#' ## 'org' is a nested element; extract it
+#' j_pivot(ndjson_file, "org", as = "data.frame")
 #'
-#' ## j_pivot discards arrays of size 0 '[]'
-#' path <- "[{name: name, state: state}][[email protected]=='WA']"
-#' j_query(ndjson_file, path)
+#' ## use j_pivot() to filter 'PushEvent' for organizations
+#' path <- "[{id: id, type: type, org: org}]
+#'              [[email protected] == 'PushEvent' && @.org != null]"
 #' j_pivot(ndjson_file, path, as = "data.frame")
 #'
+#' ## try also
+#' ##
+#' ##     j_pivot(ndjson_file, path, as = "tibble") |>
+#' ##         tidyr::unnest_wider("org", names_sep = ".")
 #' @export
 j_pivot <-
     function(

R/ndjson.R

@@ -122,7 +122,7 @@ ndjson_pivot <-
             do.call("c", lapply(pivot, `[[`, key))
         }, pivot)
     } else {
-        result <- pivot
+        result <- pivot[[1]]
     }
 
     switch(

inst/extdata/2023-02-08-0.json

@@ -0,0 +1,10 @@
+{"id":"26939254345","type":"DeleteEvent","actor":{"id":19908762,"login":"lucianHymer","display_login":"lucianHymer","gravatar_id":"","url":"https://api.github.com/users/lucianHymer","avatar_url":"https://avatars.githubusercontent.com/u/19908762?"},"repo":{"id":469847426,"name":"gitcoinco/passport","url":"https://api.github.com/repos/gitcoinco/passport"},"payload":{"ref":"format-alert-messages","ref_type":"branch","pusher_type":"user"},"public":true,"created_at":"2023-02-08T00:00:00Z","org":{"id":30044474,"login":"gitcoinco","gravatar_id":"","url":"https://api.github.com/orgs/gitcoinco","avatar_url":"https://avatars.githubusercontent.com/u/30044474?"}}
+{"id":"26939254358","type":"PushEvent","actor":{"id":7284629,"login":"johnbieren","display_login":"johnbieren","gravatar_id":"","url":"https://api.github.com/users/johnbieren","avatar_url":"https://avatars.githubusercontent.com/u/7284629?"},"repo":{"id":598619545,"name":"johnbieren-testing/simple-python-0BZGe-reflect-afford","url":"https://api.github.com/repos/johnbieren-testing/simple-python-0BZGe-reflect-afford"},"payload":{"repository_id":598619545,"push_id":12544374959,"size":1,"distinct_size":1,"ref":"refs/heads/main","head":"2813cdc5c70e8c99c7b57d7eea0a718a3f321cf8","before":"0598cb44f5bd9236b7c256450cd2ec152babac46","commits":[{"sha":"2813cdc5c70e8c99c7b57d7eea0a718a3f321cf8","author":{"email":"[email protected]","name":"AppData Robot"},"message":"Generating Tekton resources","distinct":true,"url":"https://api.github.com/repos/johnbieren-testing/simple-python-0BZGe-reflect-afford/commits/2813cdc5c70e8c99c7b57d7eea0a718a3f321cf8"}]},"public":true,"created_at":"2023-02-08T00:00:00Z","org":{"id":123667276,"login":"johnbieren-testing","gravatar_id":"","url":"https://api.github.com/orgs/johnbieren-testing","avatar_url":"https://avatars.githubusercontent.com/u/123667276?"}}
+{"id":"26939254361","type":"CreateEvent","actor":{"id":2826376,"login":"QAInsights","display_login":"QAInsights","gravatar_id":"","url":"https://api.github.com/users/QAInsights","avatar_url":"https://avatars.githubusercontent.com/u/2826376?"},"repo":{"id":596227788,"name":"QAInsights/perfGPT","url":"https://api.github.com/repos/QAInsights/perfGPT"},"payload":{"ref":"feature-detailed","ref_type":"branch","master_branch":"main","description":"PerfGPT helps you to analyze your performance test results using OpenAI.","pusher_type":"user"},"public":true,"created_at":"2023-02-08T00:00:00Z"}
+{"id":"26939254365","type":"CreateEvent","actor":{"id":185919,"login":"bhelx","display_login":"bhelx","gravatar_id":"","url":"https://api.github.com/users/bhelx","avatar_url":"https://avatars.githubusercontent.com/u/185919?"},"repo":{"id":598856142,"name":"bhelx/below-c-level","url":"https://api.github.com/repos/bhelx/below-c-level"},"payload":{"ref":null,"ref_type":"repository","master_branch":"main","description":"Below-C-Level Meetup Site","pusher_type":"user"},"public":true,"created_at":"2023-02-08T00:00:00Z"}
+{"id":"26939254366","type":"PushEvent","actor":{"id":124742879,"login":"akhanmalik786","display_login":"akhanmalik786","gravatar_id":"","url":"https://api.github.com/users/akhanmalik786","avatar_url":"https://avatars.githubusercontent.com/u/124742879?"},"repo":{"id":598846050,"name":"akhanmalik786/Seattle-Real-Estate-2022","url":"https://api.github.com/repos/akhanmalik786/Seattle-Real-Estate-2022"},"payload":{"repository_id":598846050,"push_id":12544374988,"size":1,"distinct_size":1,"ref":"refs/heads/main","head":"d0408abe4c6d3a6af2c781469ff9de91a44b044f","before":"2c0c4b22c39739f869a6ed4a6aad02178813346f","commits":[{"sha":"d0408abe4c6d3a6af2c781469ff9de91a44b044f","author":{"email":"[email protected]","name":"akhanmalik786"},"message":"Update README.md","distinct":true,"url":"https://api.github.com/repos/akhanmalik786/Seattle-Real-Estate-2022/commits/d0408abe4c6d3a6af2c781469ff9de91a44b044f"}]},"public":true,"created_at":"2023-02-08T00:00:00Z"}
+{"id":"26939254367","type":"PushEvent","actor":{"id":41898282,"login":"github-actions[bot]","display_login":"github-actions","gravatar_id":"","url":"https://api.github.com/users/github-actions[bot]","avatar_url":"https://avatars.githubusercontent.com/u/41898282?"},"repo":{"id":505266582,"name":"kherrick/slashdot","url":"https://api.github.com/repos/kherrick/slashdot"},"payload":{"repository_id":505266582,"push_id":12544374978,"size":1,"distinct_size":1,"ref":"refs/heads/gh-pages","head":"e3db491a9f26826ff20eb0af0b0d0d88d561c601","before":"b3e2715f9530cbe9031173a9c38ba3429caba397","commits":[{"sha":"e3db491a9f26826ff20eb0af0b0d0d88d561c601","author":{"email":"[email protected]","name":"Karl Herrick"},"message":"Build gh-pages: Tue Feb  7 23:59:58 UTC 2023","distinct":true,"url":"https://api.github.com/repos/kherrick/slashdot/commits/e3db491a9f26826ff20eb0af0b0d0d88d561c601"}]},"public":true,"created_at":"2023-02-08T00:00:00Z"}
+{"id":"26939254379","type":"PushEvent","actor":{"id":85432009,"login":"herokutests","display_login":"herokutests","gravatar_id":"","url":"https://api.github.com/users/herokutests","avatar_url":"https://avatars.githubusercontent.com/u/85432009?"},"repo":{"id":380776959,"name":"herokutests/provideip","url":"https://api.github.com/repos/herokutests/provideip"},"payload":{"repository_id":380776959,"push_id":12544374986,"size":1,"distinct_size":1,"ref":"refs/heads/main","head":"d6075ee54e2c10699764329dfb88c0c5504d8171","before":"bc306246d630b556450ebd804554f88468312e52","commits":[{"sha":"d6075ee54e2c10699764329dfb88c0c5504d8171","author":{"email":"[email protected]","name":"herokutests"},"message":"commitmessage","distinct":true,"url":"https://api.github.com/repos/herokutests/provideip/commits/d6075ee54e2c10699764329dfb88c0c5504d8171"}]},"public":true,"created_at":"2023-02-08T00:00:00Z"}
+{"id":"26939254380","type":"IssuesEvent","actor":{"id":20648179,"login":"whqkdhfh13","display_login":"whqkdhfh13","gravatar_id":"","url":"https://api.github.com/users/whqkdhfh13","avatar_url":"https://avatars.githubusercontent.com/u/20648179?"},"repo":{"id":591814884,"name":"CMPUT404-W23/project","url":"https://api.github.com/repos/CMPUT404-W23/project"},"payload":{"action":"opened","issue":{"url":"https://api.github.com/repos/CMPUT404-W23/project/issues/23","repository_url":"https://api.github.com/repos/CMPUT404-W23/project","labels_url":"https://api.github.com/repos/CMPUT404-W23/project/issues/23/labels{/name}","comments_url":"https://api.github.com/repos/CMPUT404-W23/project/issues/23/comments","events_url":"https://api.github.com/repos/CMPUT404-W23/project/issues/23/events","html_url":"https://github.com/CMPUT404-W23/project/issues/23","id":1575218964,"node_id":"I_kwDOI0Zg5M5d4-8U","number":23,"title":"[User Stories]20: As an author, when someone sends me a friends only-post I want to see the likes.","user":{"login":"whqkdhfh13","id":20648179,"node_id":"MDQ6VXNlcjIwNjQ4MTc5","avatar_url":"https://avatars.githubusercontent.com/u/20648179?v=4","gravatar_id":"","url":"https://api.github.com/users/whqkdhfh13","html_url":"https://github.com/whqkdhfh13","followers_url":"https://api.github.com/users/whqkdhfh13/followers","following_url":"https://api.github.com/users/whqkdhfh13/following{/other_user}","gists_url":"https://api.github.com/users/whqkdhfh13/gists{/gist_id}","starred_url":"https://api.github.com/users/whqkdhfh13/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/whqkdhfh13/subscriptions","organizations_url":"https://api.github.com/users/whqkdhfh13/orgs","repos_url":"https://api.github.com/users/whqkdhfh13/repos","events_url":"https://api.github.com/users/whqkdhfh13/events{/privacy}","received_events_url":"https://api.github.com/users/whqkdhfh13/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2023-02-07T23:59:59Z","updated_at":"2023-02-07T23:59:59Z","closed_at":null,"author_association":"NONE","active_lock_reason":null,"body":"As an author, when someone sends me a friends only-post I want to see the likes.","reactions":{"url":"https://api.github.com/repos/CMPUT404-W23/project/issues/23/reactions","total_count":0,"+1":0,"-1":0,"laugh":0,"hooray":0,"confused":0,"heart":0,"rocket":0,"eyes":0},"timeline_url":"https://api.github.com/repos/CMPUT404-W23/project/issues/23/timeline","performed_via_github_app":null,"state_reason":null}},"public":true,"created_at":"2023-02-08T00:00:00Z","org":{"id":123277977,"login":"CMPUT404-W23","gravatar_id":"","url":"https://api.github.com/orgs/CMPUT404-W23","avatar_url":"https://avatars.githubusercontent.com/u/123277977?"}}
+{"id":"26939254382","type":"PushEvent","actor":{"id":41898282,"login":"github-actions[bot]","display_login":"github-actions","gravatar_id":"","url":"https://api.github.com/users/github-actions[bot]","avatar_url":"https://avatars.githubusercontent.com/u/41898282?"},"repo":{"id":576765934,"name":"mornystannit/mornystannit.github.io","url":"https://api.github.com/repos/mornystannit/mornystannit.github.io"},"payload":{"repository_id":576765934,"push_id":12544374992,"size":1,"distinct_size":1,"ref":"refs/heads/main","head":"6e0919b2bc25ebe255533ad04c55ad1c07a0cd40","before":"38df98e75964df867a997633fb6d05abe333069e","commits":[{"sha":"6e0919b2bc25ebe255533ad04c55ad1c07a0cd40","author":{"email":"[email protected]","name":"GitHub Actions"},"message":"Update assets from pipeline script","distinct":true,"url":"https://api.github.com/repos/mornystannit/mornystannit.github.io/commits/6e0919b2bc25ebe255533ad04c55ad1c07a0cd40"}]},"public":true,"created_at":"2023-02-08T00:00:00Z","org":{"id":120284018,"login":"mornystannit","gravatar_id":"","url":"https://api.github.com/orgs/mornystannit","avatar_url":"https://avatars.githubusercontent.com/u/120284018?"}}
+{"id":"26939254383","type":"PushEvent","actor":{"id":97608502,"login":"mhutchinson-witness","display_login":"mhutchinson-witness","gravatar_id":"","url":"https://api.github.com/users/mhutchinson-witness","avatar_url":"https://avatars.githubusercontent.com/u/97608502?"},"repo":{"id":447228996,"name":"mhutchinson-witness/mhutchinson-distributor","url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor"},"payload":{"repository_id":447228996,"push_id":12544375001,"size":9,"distinct_size":9,"ref":"refs/heads/witness_mhutchinson_witness_50ed07082843287df5342353a4084563e6eaeb7bbaaa961d45400dde004c1186","head":"644c6005eedc825b7634dfe34cc07987570f857f","before":"6a3aa516362f36d21b57e8cb94f47bbdd911cdc2","commits":[{"sha":"1a9b69bea138052699765eb533987f744fcec713","author":{"email":"[email protected]","name":"Serverless Bot"},"message":"Automatically merge witness signatures","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/1a9b69bea138052699765eb533987f744fcec713"},{"sha":"0f226cebc930769d2bbe4d472349a3a527300bba","author":{"email":"[email protected]","name":"mhutchinson-witness"},"message":"Witness checkpoint@8691564","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/0f226cebc930769d2bbe4d472349a3a527300bba"},{"sha":"0dee17e2b9f16ff4e462ca7e1f3b7fcc063ca8b1","author":{"email":"[email protected]","name":"mhutchinson-witness"},"message":"Witness checkpoint@4163431","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/0dee17e2b9f16ff4e462ca7e1f3b7fcc063ca8b1"},{"sha":"4b75218f70581c0cff84cf1c1a7a8068339a560b","author":{"email":"[email protected]","name":"Serverless Bot"},"message":"Automatically merge witness signatures","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/4b75218f70581c0cff84cf1c1a7a8068339a560b"},{"sha":"ef62bbf45bf6dba8d76a7e4460e3c3f3374e986e","author":{"email":"[email protected]","name":"René Mayrhofer"},"message":"Witness checkpoint@8692086","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/ef62bbf45bf6dba8d76a7e4460e3c3f3374e986e"},{"sha":"41a275219aee610cd5dac13643d5aef3624b4197","author":{"email":"[email protected]","name":"René Mayrhofer"},"message":"Witness checkpoint@4163431","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/41a275219aee610cd5dac13643d5aef3624b4197"},{"sha":"bae247a2bcc2bbb60b92d06f0a884af3eb10be88","author":{"email":"[email protected]","name":"Serverless Bot"},"message":"Automatically merge witness signatures","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/bae247a2bcc2bbb60b92d06f0a884af3eb10be88"},{"sha":"f11750011603e352409743d7126d802667f6b375","author":{"email":"[email protected]","name":"Wolsey Bank Witness"},"message":"Witness checkpoint@8692208","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/f11750011603e352409743d7126d802667f6b375"},{"sha":"644c6005eedc825b7634dfe34cc07987570f857f","author":{"email":"[email protected]","name":"Wolsey Bank Witness"},"message":"Witness checkpoint@15489897","distinct":true,"url":"https://api.github.com/repos/mhutchinson-witness/mhutchinson-distributor/commits/644c6005eedc825b7634dfe34cc07987570f857f"}]},"public":true,"created_at":"2023-02-08T00:00:00Z"}