Merge features of 9002 release into main.

This is a big commit. 150 commits were squashed into it. The history is detailed below. It integrates a lot of new features that are detailed in NEWS.md and marks the 9002 development release.

---

* Initial commit on class VectorBlueprint. Bundled doc in commit.

This is incomplete work. The class name is temporary (at least for now) and and tests are ongoing.

* Initial commit on class VectorBlueprints. Bundled doc in commit.

Just like class VectorBlueprint, this is incomplete work. The class name is temporary (at least for now) and and tests are ongoing.

* Change testthat for just tests in badges.

* Insert joke / easter egg related to the great song I'm blue from Eiffel 65. Who said this needed to be serious?

* Correct typos.

* Preliminary work to include a $field slot in VectorBlueprint. This is still work in progress.

  - Include $length in class.
  - Include length arg in $initialize().
  - Add a validation step for $length in
    $validate().
  - Modify $format() to include or not
    $length. TBD, I am not satisfied with
    current format.
  - Change $as.list and $as.character
    bindings to $as_list and $as_character
    for consistency.

* Latest improvements to VectorBlueprint.

  - Robustify $initialize() when length
    is ignored / NULL. Now favor NULL
    over missing.
  - $validate() now checks if $length < 0
    when it is not NULL.
  - $format() is now more consistent.

* Update collate field of DESCRIPTION and doc of Blueprint (updated @family Blueprint).

* Update side files after build with VectorBlueprint and VectorBlueprints classes.

* Add a Questions section.

* Change how Blueprint object are printed.

Result now includes package's version when $print() is called.

* New utility internal function inject().

Useful to inject new named values into an existing R structure. Read doc for more information.

* Update dependencies with packages yaml and jsonlite.

- These packages are required to print and write JSON and YAML strings / files. These allows us to convert Blueprints objects to these conveninent and popular formats.
- Also update URL and Contact fields, along with e-mail of author.

* Update email of author to jm@potvin.xyz. Shorter and nicer.

* Correct small typos.

Forgot to use new names VectorBlueprint and VectorBlueprints at some places... These replaces very old names stemming from first prototype (Field and Fields).

* Prepare terrain for inclusion of Github workflows.

This workflows will launch R CMD CHECK on three popular OS whenever a commit or a merge is done in 'main'. This is conveninent, because it runs all unit tests and check builds in one swoop.

Logos in README will change. Awaiting maturity of branch before changing this.

* Set of small changes to class Blueprint.

- Remove external constructor new_blueprint().
Will be replaced some day by a unified API; something like blueprint::new(mode).
- Add valid_blueprint(), an external validator that checks an object's class and then validates it.
- Changes unit tests accordingly.

* Rename function is_valid_r6_instance() to validate_blueprint().

* Very light changes to function quiet() used for unit testing.

* Remove VectorBlueprints class. Will be reintroduced later in dev cycle.

* Changes to doc.

* Rename class VectorBlueprint to Atomic.

I will try to favor shorter syntax from now on. VectorBlueprint was a cool name, but it is too long and it's already implied that if you call a class from the package's namespace, you WILL get a blueprint. This is its purpose.

* Reintroduce internal function valid_r6_instance(). Use simpler descriptions in unit tests.

* Explicit testthat namespace.

* Correct typo. Declare Imports in alphabetical order.

* Remove R CMD INSTALL args.

Don't keep source (this option sucks, let R reformat your code) and build for multiple architectures.

* Correct small typos.

* Introduce new function is_strict_atomic().

This function check if an object is a strict atomic: its class is itself derived from base types. This is safer.

* New Blueprinter %bp% operators.

Moved from class Atomic and generalized to all future classes of the package.

* New script to hold default options.

* Collection of small changes.

- Include options.R mechanisms.
- Rename as_list_utf8() to as_utf8_list().
- Correct typos.
- Rename arg atom to atomic.
- Move comments inside functions (when applicable). This follows the removal of stupid R CMD INSTALL keep.source option.
- Lightly change how Atomic objects are printed. This follows the change introduced in $print() method of class Blueprint.
- Light reformat of code.
- Remove %>>% operator. Replaced by %bp% defined in Blueprinter.R.
- Forgot to add argument validate in S3 dispatchers.

* Update side-files.

* Favor is_strict_atomic() over is.atomic(). Correct typos.

* Correct typos in doc following R CMD CHECK results.

* Favor is_strict_atomic() over is.atomic().

* Include assertions.R. This is needed for is_strict_atomic().

* Remove explicit format.CLASS() functions. Let R6 handle S3 dispatch.

* New internal generic function as_utf8() to encode characters found in R structures to UTF-8.

This is required for YAML and JSON I/O. This function replaces old method as_utf8_list() of class Atomic.

* Total revamo of unit tests related to is_strict_atomic(). Now much more robust. Thoroughly documented.

* Correct typos and introduce small optimizations. Nothing fancy.

* New $generate() method. Useful to spawn vectors from Atomic blueprints.

* Remove space.

* Redesign function is_strict_atomic(). This version is work in progress and should flag pure vectors. See doc.

Add better documentation of what is an Atomic value.

* Correct typos in doc.

* New function is_single(). Add doc.

* New package doc file.

* Update package's description and shorten it. Add package doc to Collate order.

* Rename jsonlite_atomic_opts() to opts_jsonlite_atomic().

* Write NAs as NA, not null.

* Remove forgotten comment.

* Set of small changes. Moving to strict atomic types.

- Remove private field classes. Not needed anymore.
- Support of single values.
- Check for $type values.
- Revamp of $compare(). Much better now.
- Adjust $generate(). Should be good now.
- Correct typos.

* Favor stopifnot() in internal utility functions (when possible).

* New internal function add_headers().

* Robustify certain error checks. Nothing fancy.

* Change function name in tests following previous commit.

* Favor testthat::skip_() functions within tests.

* New private field: $valid_types. This is a constant character vector holding strict atomic types' names.

* Small adjustments to code.

* Add package utils to Imports.

* Bugfix in add_headers(). Force type to lower cases for match().

* Finalize methods $as_yaml() and $as_json(). Favor argument .validate over validate. We want this arg to be rather low-level, but still available to users.

* Simplify doc.

* Light change to syntax in add_headers().

* Partially re-arrange script.

* Major re-arrangement of unit tests.

- Better uniformity enforced.
- use smaller test chunks.
- Remove some useless comments.
- Split big contexts into smaller ones, whenever we feel it is necessary.
- Add some further small tests here and there for some specific edge cases.

* Use roxygen2 templates. Ignore them in builds.

* Various small improvements to doc. Now much more consistent.

* Major doc revamp. Should be pretty much final now.

* Small changes to doc. Now more precise.

* Bugfix. Export internal methods, even if they are tied to an unexported internal generic.

* Add arg ... to S3 methods to avoid R CMD CHECK errors. This argument is ignored.

* Update side-files following significant progress on doc.

* Use a NEWS file.

* Remove unecessary lines.

* Remove msg related to latest developments location (branch).

* Ignore tests/testthat/_snaps/ in builds.

This folder is created automatically by testthat.

* Robustify %bp%. Add argument checks.

* @symbol can now also be a scalar character.

* New unit tests for %bp% operator (Blueprinter).

* Add name of %bp% (Blueprinter).

* Bugfix. When length > 0L, Atomic$new() was not returning a proper prototype for single values.

* Major revamp of class Blueprint (again).

- Favor active fields over regular fields. Values that should not be changed are now protected by function scopes.
- Hide package version in private field pkg_ver. Make this value accessible through active field.
- Simplify validate() methods.
- Remove argument .validate everywhere. There is no field to validate now.
- New get() and set() low-level mechanisms.
- Change doc.
- Change unit tests.

* Small changes following revamp of super-class Blueprint. Correct small typos.

* Supress warnings stemming from internal coercion of 'length' to integer in $initialize().

* New objects used in unit tests of class Atomic.

* Add small comment in tests.

* Remove unecessary missing arg checks. R does it anyway.

* Bugfix. Functions used in tryCatch() loops needs to have an argument to properly work.

* Correct typos.

* Robustify tests following covr report.

* Correct small typos in code and doc.

* Standardization of unit tests structure.

* Change order of arguments of add_headers().

* Correct typo.

* Update side-files.

* Separate self$format() and cat() calls.

* Small changes to doc of $get() and $set().

* Test if class name and pkg version are returned by $print().

* Snapshots are now used. Using testthat 3e. Using covr.

* Preparing terrain for merge into 'main'.

- Bump dev version.
- Bump test results.

* Various small improvement followjg test phase.

- Better doc.
- Small bugfixes.
- Add examples.
- New $set(). Supersedes Blueprint$set(). We needed a way to prevent users from changing $type.

* New low-level $get() and $set() methods. Small improvement to doc. Bugfixes.

* New default YAML handlers functions to be passed to yaml::as.yaml().

* Change order of args in vapply() wrappers. Put those 'names' args at the end.

* Improvements for function inject().

inject() is becoming essential to the pkg. Now, if the very first element passed to ... is either a list or a vector of length greater than 1, it is assumed that the child elements of ..1 should be used instead of ... Therefore, you can either pass args to inject() by parts (...) or as a whole (..1).

* Update doc side files following fixes and improvements.

* New roxygen2 templates for parameters field and value.

* Initial commit to unit testing framework of class Atomic.

This is a huge file because Atomic is an important class. It needs to be robust. We now uses snapshot tests introduced in testthat 3e. This is awesome for testing outputs.

* Collective changes to unit testing framework.

These changes were introduced at the same time the tests for class Atomic were written. This is because the framework needs to be as consistent as possible and thus, a lot of small changes here and there were introduced.

It would not be useful to list them all and justify them. They are simply maturing with the package.

* Bugfix. Ensure that a TRUE/FALSE value is returned. Change tests to reflect that.

* Favor hyphens over underscores in file names.

* Simplify script.

* Rename validate_blueprint() to report_errors(). Better name.

* Correct syntax typo.

* Prepare terrain ahead of merge and bump dev  version to 9002.

* Remove snapshots. They can be generated anytime from unit tests so we don't need to track them.

* Start ignoring testthat 3e snapshots.

* New assertion functions is_named_list() and is_named_vctr(). Now used in codebase.

* Correct various small typos.

* Rewrite function inject() as a more robust S3 generic function with dedicated method for lists and vectors (default).

* Add arg 'source_header' to add_headers(). New create_source_header() function that is called by add_headers().

Adding a 'source' header can now be deactivated. This will be useful in the future.

* Assertion is_*() functions gain a new function a new accept_na arg.

NA values can now be accepted/rejected as valid/invalid values in assertions.

* Specify default value for args of internal functions.

The behavior of those functions was lightly altered in order to handle these new default values. Specifying default args helps us specifying the contract, the interface.

* Revamp of internal function opts_json_atomic().

The function now have a similar behavior to opts_yaml_handlers. It has an argument ... that captures named arguments and inject them into a default list of values with inject(). Default values can be overridden. Moreover, by doing so, we completely hide inject() from users; this function won't appear directly in codebase of methods.

* New .source_header parameter template.

* Remove default value. This is explicited b y @Usage.

* Add snapshot test for $print() when length is ignored.

* Collective set of small changes.

- Add template parameter .source_header to $as_json() and $as_yaml().
- Add further details to arg ... of these two methods.
- Specify default values to args when appropriate.
- Change calls to add_headers() and opts_*() functions following their revamps.
- Correct typos.

* Specify default values of arguments when appropriate. Change behavior of methods to match that.

* Add some arguments checks to tests of Atomic and Blueprint.

* Update side files following changes.

* Change order of tests to match order of methods.

* Light rework of methods $as_yaml() and %as_json().

- Specify default values to args.
- source_header becomes a regular argument.
- Methods now return $self if output is written to file.

* Small changes to doc. Added some relevent details.

* Small changes in code order for consistency.

* Split tests of classes Blueprint and Atomic in multiple files.

- The main files holds all unit tests related to the machanisms.
- The files marked with a -outputs focuses on outputs printed to a console or a file.
- Add tests, robustify some others. Correct coverage to obtain 100% covr score. Remove temp notes related to covr in Atomic.
- Light reformat.

* Correct typo.

* Prepare terrain for 9002 dev release and merge into main.

* Small changes.

- Change error msgs to be consistent with other error msgs of the package.
- Arg 'name' must be a non-empty, non-NA scalar character.

* Restrict field $name to non-empty, non-NA scalar characters.

* New Atomic$bind() method. This is still an experimental feature.

* Update README prior to 9002 build release.

* Include testthat snapshots. They are stable now. Don't ignore them.

* Correct various very small typos following last revision before 9002 release.

* Run test of R 3.6.X, not R > 4.0. Transition to R4 will be done later in the year.

* Bugfix. In examples, write to tempfiles, not to files located in root.

Co-authored-by: Jean-Mathieu Potvin <jean-mathieu_potvin@cooperators.ca>
Co-authored-by: Jean-Mathieu Potvin <info@jeanmathieupotvin.com>

Author: 3 people

.Rbuildignore

@@ -2,3 +2,5 @@
 ^\.Rproj\.user$
 ^\.gitignore$
 ^\.dev$
+^\.github$
+^man-roxygen$

.Rproj

@@ -17,5 +17,4 @@ StripTrailingWhitespace: Yes
 
 BuildType: Package
 PackageUseDevtools: Yes
-PackageInstallArgs: --no-multiarch --with-keep.source
 PackageRoxygenize: rd,collate,namespace,vignette

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,86 @@
+# Github CI/CD workflow
+#
+# This workflows was generated automatically by
+# usethis::use_github_action_check_standard(). It runs R CMD CHECK
+# via the rcmdcheck package on three OS (Ubuntu, macOS and Windows)
+# that runs the latest release of R. This is appropriate for package
+# to be submitted to CRAN.
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+name: R-CMD-check
+
+jobs:
+  R-CMD-check:
+    runs-on: ${{ matrix.config.os }}
+
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {os: windows-latest, r: '3.6.3'}
+          - {os: macOS-latest, r: '3.6.3'}
+          - {os: ubuntu-20.04, r: '3.6.3', rspm: "https://packagemanager.rstudio.com/cran/__linux__/focal/latest"}
+
+    env:
+      R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
+      RSPM: ${{ matrix.config.rspm }}
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: r-lib/actions/setup-r@v1
+        with:
+          r-version: ${{ matrix.config.r }}
+
+      - uses: r-lib/actions/setup-pandoc@v1
+
+      - name: Query dependencies
+        run: |
+          install.packages('remotes')
+          saveRDS(remotes::dev_package_deps(dependencies = TRUE), ".github/depends.Rds", version = 2)
+          writeLines(sprintf("R-%i.%i", getRversion()$major, getRversion()$minor), ".github/R-version")
+        shell: Rscript {0}
+
+      - name: Cache R packages
+        if: runner.os != 'Windows'
+        uses: actions/cache@v2
+        with:
+          path: ${{ env.R_LIBS_USER }}
+          key: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-${{ hashFiles('.github/depends.Rds') }}
+          restore-keys: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-
+
+      - name: Install system dependencies
+        if: runner.os == 'Linux'
+        run: |
+          while read -r cmd
+          do
+            eval sudo $cmd
+          done < <(Rscript -e 'writeLines(remotes::system_requirements("ubuntu", "20.04"))')
+
+      - name: Install dependencies
+        run: |
+          remotes::install_deps(dependencies = TRUE)
+          remotes::install_cran("rcmdcheck")
+        shell: Rscript {0}
+
+      - name: Check
+        env:
+          _R_CHECK_CRAN_INCOMING_REMOTE_: false
+        run: rcmdcheck::rcmdcheck(args = c("--no-manual", "--as-cran"), error_on = "warning", check_dir = "check")
+        shell: Rscript {0}
+
+      - name: Upload check results
+        if: failure()
+        uses: actions/upload-artifact@main
+        with:
+          name: ${{ runner.os }}-r${{ matrix.config.r }}-results
+          path: check

.gitignore

@@ -32,5 +32,8 @@ vignettes/*.pdf
 *.utf8.md
 *.knit.md
 
-# Files in development that should not be committed for a temporary period of time
+# Files in development
 .dev/
+
+# Github workflows outputs
+.github/*.html

DESCRIPTION

@@ -1,33 +1,41 @@
 Package: blueprint
 Title: Efficient data schemas generator for R
-Version: 0.0.0.9001
+Version: 0.0.0.9002
 Authors@R: 
     person(given = "Jean-Mathieu",
            family = "Potvin",
            role = c("aut", "cre"),
-           email = "info@potvin.xyz",
+           email = "jm@potvin.xyz",
            comment = c(ORCID = "0000-0002-8237-422X"))
-Description: An efficient and consistent interface to generate 
-    all sorts of data schemas in R. Schemas are objects that 
-    dictate what should be put in R data structures. Blueprint 
-    is neutral. It works with any kind of recursive structure. 
+Description: An unopinionated consistent interface to generate 
+    all sorts of data schemas in R. Data schemas are R objects
+    that dictate what should go in R data structures. 
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE, r6 = TRUE)
 RoxygenNote: 7.1.1
+Config/testthat/edition: 3
 Depends: 
     R (>= 3.5.0)
 Imports:
-    R6
+    R6, 
+    jsonlite, 
+    utils, 
+    yaml 
 Suggests: 
+    covr, 
     testthat
 ByteCompile: true
 NeedsCompilation: no 
-URL: https://github.com/jeanmathieupotvin/blueprint, https://blueprint.potvin.xyz
+URL: https://blueprint.potvin.xyz, https://github.com/jeanmathieupotvin/blueprint 
 BugReports: https://github.com/jeanmathieupotvin/blueprint/issues
-Contact: jean-mathieu_potvin@cooperators.ca
+Contact: info@blueprint.potvin.xyz
 Collate: 
     'assertions.R'
     'utilities.R'
     'Blueprint.R'
+    'options.R'
+    'Atomic.R'
+    'Blueprinter.R'
+    'blueprint-package.R'

NAMESPACE

@@ -1,10 +1,24 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method(format,Blueprint)
+S3method(as.character,Atomic)
+S3method(as.list,Atomic)
+S3method(as_utf8,character)
+S3method(as_utf8,default)
+S3method(as_utf8,list)
+S3method(inject,default)
+S3method(inject,list)
+export("%bp%")
+export(Atomic)
 export(Blueprint)
+export(is_atomic)
 export(is_blueprint)
+export(is_named_list)
+export(is_named_vctr)
 export(is_scalar_character)
 export(is_scalar_integer)
 export(is_scalar_logical)
 export(is_scalar_numeric)
-export(new_blueprint)
+export(is_single)
+export(is_strict_atomic)
+export(valid_atomic)
+export(valid_blueprint)

NEWS.md

@@ -0,0 +1,39 @@
+# blueprint 0.0.0.9002
+
+* **New concepts**
+    - *strict atomic types*
+        + Strict atomic are R types considered to be atomic objects in
+        the package: `NULL`, `logical`, `integer`, `single` (yes, `single`, see
+        documentation of the package for more information), `double`, `complex`,
+        `character` and `raw` vectors.
+        + These are the fundamental building blocks of R.
+* **New classes**
+    - `Atomic`
+        + A class to hold blueprints of *strict atomic vectors*. This is an
+        important class packed with a lot of features. Just like strict atomic
+        vectors are the building blocks of R, so is class `Atomic` for the
+        package. All other `blueprint`'s classes will reuse this class.
+* **New features**
+    - A new `%bp%` operator which can be used to construct blueprints in a
+    concise way. We call it the *Blueprinter*.
+    - New assertion functions: `is_single()`, `is_strict_atomic()`,
+    `is_named_vctr()` and `is_named_list()`. These are very useful.
+* **Important changes**
+    - Significant changes to class `Blueprint` to ensure consistency with class
+    `Atomic`.
+    - Package now imports packages `jsonlite` and `yaml` for I/O.
+* **Other important changes**
+    - Hundreds of new unit tests. We now use a consistent test structure derived
+    from `testthat` 3e edition.
+    - New internal mechanisms / utility functions. They are more robust and
+    better tested.
+    - New options system for I/O with packages `jsonlite` and `yaml`.
+    - New (experimental) Github workflows for future CI/CD pipeline.
+
+# blueprint 0.0.0.9001
+
+* **Package creation. Start tracking development process.**
+* **New features**
+    - Blueprint
+        + A super-class that all other classes inherit.
+        + Provides low-level mechanisms such as `$get()` and `$set()` methods.