Cran/resubmission 1.4.0

.github/workflows/reverse-dependency-check.yaml

@@ -0,0 +1,208 @@
+name: Reverse dependency checks
+
+on:
+  workflow_dispatch:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: reverse-deps-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  reverse-dependencies:
+    name: blotter and quantstrat
+    runs-on: ubuntu-latest
+
+    env:
+      _R_CHECK_FORCE_SUGGESTS_: false
+
+    steps:
+      - name: Check out FinancialInstrument
+        uses: actions/checkout@v4
+
+      - name: Set up R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: release
+          use-public-rspm: true
+
+      - name: Install FinancialInstrument dependencies
+        uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: |
+            any::rcmdcheck
+            any::tinytest
+            any::testthat
+            any::PerformanceAnalytics
+            any::foreach
+            any::iterators
+
+      - name: Install current FinancialInstrument
+        run: R CMD INSTALL .
+
+      - name: Clone downstream packages
+        run: |
+          mkdir -p revdeps
+
+          git clone --depth 1 \
+            https://github.com/braverock/blotter.git \
+            revdeps/blotter
+
+          git clone --depth 1 \
+            https://github.com/braverock/quantstrat.git \
+            revdeps/quantstrat
+
+      - name: Install remaining CRAN dependencies
+        shell: Rscript {0}
+        run: |
+          required <- c(
+            "quantmod",
+            "xts",
+            "zoo",
+            "TTR",
+            "PerformanceAnalytics",
+            "foreach",
+            "iterators",
+            "boot",
+            "tinytest",
+            "testthat"
+          )
+
+          missing <- required[
+            !vapply(
+              required,
+              requireNamespace,
+              logical(1),
+              quietly = TRUE
+            )
+          ]
+
+          if (length(missing)) {
+            install.packages(missing)
+          }
+
+      - name: Reinstall current FinancialInstrument
+        run: R CMD INSTALL .
+
+      - name: Install blotter
+        run: R CMD INSTALL revdeps/blotter
+
+      - name: Verify FinancialInstrument and blotter
+        shell: Rscript {0}
+        run: |
+          expected_fi <- package_version(
+            read.dcf(
+              "DESCRIPTION",
+              fields = "Version"
+            )[1, 1]
+          )
+
+          expected_blotter <- package_version(
+            read.dcf(
+              "revdeps/blotter/DESCRIPTION",
+              fields = "Version"
+            )[1, 1]
+          )
+
+          installed_fi <- packageVersion(
+            "FinancialInstrument"
+          )
+
+          installed_blotter <- packageVersion(
+            "blotter"
+          )
+
+          cat(
+            "FinancialInstrument:",
+            as.character(installed_fi),
+            "\n"
+          )
+
+          cat(
+            "blotter:",
+            as.character(installed_blotter),
+            "\n"
+          )
+
+          stopifnot(
+            installed_fi == expected_fi,
+            installed_blotter == expected_blotter
+          )
+
+      - name: Check blotter
+        shell: Rscript {0}
+        run: |
+          result <- rcmdcheck::rcmdcheck(
+            "revdeps/blotter",
+            args = c(
+              "--no-manual",
+              "--no-vignettes"
+            ),
+            build_args = "--no-build-vignettes",
+            error_on = "error"
+          )
+
+          print(result)
+
+      - name: Reinstall tested dependency chain
+        run: |
+          R CMD INSTALL .
+          R CMD INSTALL revdeps/blotter
+
+      - name: Install quantstrat
+        run: R CMD INSTALL revdeps/quantstrat
+
+      - name: Verify quantstrat dependency chain
+        shell: Rscript {0}
+        run: |
+          library(FinancialInstrument)
+          library(blotter)
+          library(quantstrat)
+
+          cat(
+            "FinancialInstrument:",
+            as.character(packageVersion("FinancialInstrument")),
+            "\n"
+          )
+
+          cat(
+            "blotter:",
+            as.character(packageVersion("blotter")),
+            "\n"
+          )
+
+          cat(
+            "quantstrat:",
+            as.character(packageVersion("quantstrat")),
+            "\n"
+          )
+
+      - name: Check quantstrat
+        continue-on-error: true
+        shell: Rscript {0}
+        run: |
+          result <- rcmdcheck::rcmdcheck(
+            "revdeps/quantstrat",
+            args = c(
+              "--no-manual",
+              "--no-vignettes"
+            ),
+            build_args = "--no-build-vignettes",
+            check_dir = "quantstrat-check",
+            error_on = "never"
+          )
+
+          print(result)
+
+      - name: Upload quantstrat check results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: quantstrat-check-results
+          path: quantstrat-check
+          if-no-files-found: warn
+

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: FinancialInstrument
 Type: Package
 Title: Financial Instrument Modeling Infrastructure
-Version: 1.4.0
+Version: 1.4.1
 Authors@R: c(person(given = "Peter",
                       family = "Carl",
                       role = "aut"),

NEWS

@@ -1,3 +1,43 @@
+# FinancialInstrument 1.4.1
+
+## CRAN Compliance Fixes
+
+* **Console Output:** Added `verbose = FALSE` parameter to `alltick2sec()` at
+  the end of its signature. The unconditional `cat()` progress call is now
+  suppressible via `verbose = FALSE` (the default) and uses `message()` for
+  optional progress reporting, preserving all existing return values.
+
+* **Return-Value Documentation:** Added `@return` tags to all exported functions
+  that were previously missing `\value` sections, describing return class,
+  structure, and side-effects where applicable.
+
+* **Examples — Temporary Directories:** Replaced `dir.create("tmpdata")` with
+  `tempdir()` / `tempfile()` in the `saveInstruments`, `loadInstruments`,
+  `CompareInstrumentFiles`, `saveSymbols.common`, `saveSymbols.days`, and
+  `getSymbols.FI` examples. Cleanup is handled via `tryCatch(finally = ...)`.
+
+* **Examples — Internal Registry Access:** Removed `FinancialInstrument:::.instrument`
+  from all documentation examples and replaced backup/restore patterns with
+  exported `saveInstruments()` / `reloadInstruments()` calls.
+
+* **Examples — Unmatched Parenthesis:** Fixed the unmatched parenthesis in the
+  `ls_by_currency()` example.
+
+* **Examples — Commented-Out Code:** Removed commented-out executable
+  alternatives from examples.
+
+* **`\dontrun{}` vs `\donttest{}`:** Converted examples that can run in a
+  standard R session from `\dontrun{}` to either runnable or `\donttest{}`
+  blocks; retained `\dontrun{}` only for genuinely unrunnable code (e.g.,
+  examples requiring live network access or specific external files).
+
+* **Namespace:** Confirmed `expires()` is exported. Removed examples for
+  genuinely unexported helpers.
+
+* **`loadInstruments` compatibility:** Updated the header check in
+  `loadInstruments()` to recognise both the legacy `"#auto"` prefix and the
+  new `"# Auto"` prefix written by the refactored `saveInstruments()`.
+
 # FinancialInstrument 1.4.0
 
 ## New Maintainer

R/CompareInstrumentFiles.R

@@ -2,44 +2,70 @@
 #'
 #' Compare the .instrument environments of two files
 #'
-#' This will load two instrument files (created by 
-#' \code{\link{saveInstruments}}) and find the differences between them.  In 
-#' addition to returning a list of difference that are found, it will produce 
-#' messages indicating the number of instruments that were added, the number of 
-#' instruments that were removed, and the number of instruments that are 
+#' This will load two instrument files (created by
+#' \code{\link{saveInstruments}}) and find the differences between them.  In
+#' addition to returning a list of difference that are found, it will produce
+#' messages indicating the number of instruments that were added, the number of
+#' instruments that were removed, and the number of instruments that are
 #' different.
 #'
 #' @param file1 A file containing an instrument environment
-#' @param file2 Another file containing an instrument environment.  If not 
-#'   provided, \code{file1} will be compared against the currently loaded 
+#' @param file2 Another file containing an instrument environment.  If not
+#'   provided, \code{file1} will be compared against the currently loaded
 #'   instrument environment.
 #' @param ... Arguments to pass to \code{\link{all.equal.instrument}}
 #' @return A list that contains the names of all instruments that were added,
 #'   the names of all instruments that were removed, and the changes to all
 #'   instruments that were updated (per \code{\link{all.equal.instrument}}).
 #' @author Garrett See
 #' @seealso \code{\link{saveInstruments}}, \code{\link{all.equal.instrument}}
-#' @examples 
-#' \dontrun{
-#' #backup current .instrument environment
-#' bak <- as.list(FinancialInstrument:::.instrument, all.names=TRUE) 
-#' old.wd <- getwd()
-#' tmpdir <- tempdir()
-#' setwd(tmpdir)
-#' rm_instruments(keep=FALSE)
-#' # create some instruments and save
-#' stock(c("SPY", "DIA", "GLD"), currency("USD"))
-#' saveInstruments("MyInstruments1")
-#' # make some changes
-#' rm_stocks("GLD")
-#' stock("QQQ", "USD")
-#' instrument_attr("SPY", "description", "S&P ETF")
-#' saveInstruments("MyInstruments2")
-#' CompareInstrumentFiles("MyInstruments1", "MyInstruments2")
-#' #Clean up
-#' setwd(old.wd)
-#' reloadInstruments(bak)
-#' }
+#' @examples
+#' example_dir <- tempfile("fi-compare-")
+#' dir.create(example_dir)
+#'
+#' backup_name <- "backup.RData"
+#' file1_name <- "instruments1.RData"
+#' file2_name <- "instruments2.RData"
+#'
+#' backup_path <- file.path(example_dir, backup_name)
+#' file1_path <- file.path(example_dir, file1_name)
+#' file2_path <- file.path(example_dir, file2_name)
+#'
+#' saveInstruments(backup_name, dir = example_dir)
+#'
+#' tryCatch(
+#'   {
+#'     stopifnot(file.exists(backup_path))
+#'
+#'     rm_instruments(keep.currencies = FALSE)
+#'     currency("USD")
+#'     stock(c("SPY", "DIA", "GLD"), currency = "USD")
+#'     saveInstruments(file1_name, dir = example_dir)
+#'
+#'     stopifnot(file.exists(file1_path))
+#'
+#'     rm_stocks("GLD")
+#'     stock("QQQ", currency = "USD")
+#'     instrument_attr(
+#'       "SPY",
+#'       "description",
+#'       "S&P 500 ETF"
+#'     )
+#'     saveInstruments(file2_name, dir = example_dir)
+#'
+#'     stopifnot(file.exists(file2_path))
+#'
+#'     CompareInstrumentFiles(file1_path, file2_path)
+#'   },
+#'   finally = {
+#'     if (file.exists(backup_path)) {
+#'       reloadInstruments(backup_name, dir = example_dir)
+#'     }
+#'
+#'     unlink(example_dir, recursive = TRUE)
+#'   }
+#' )
+#'
 #' @export
 CompareInstrumentFiles <- function(file1, file2, ...) {
     force(file1)
@@ -83,7 +109,7 @@ CompareInstrumentFiles <- function(file1, file2, ...) {
     } else {
         message(paste(liu, "instruments updated."))
     }
-    out <- c(list(new.instruments=new.instruments, 
+    out <- c(list(new.instruments=new.instruments,
                   removed.instruments=removed.instruments),
              diffs)
     out <- Filter(function(x) length(x) > 0L, out)

R/FinancialInstrument-package.R

@@ -91,11 +91,11 @@ NULL
 #' where and how your market data are stored so that
 #' \code{\link[quantmod]{getSymbols}} will work for you.
 #'
-#' FinancialInstrument's functions build and manipulate objects that are stored
-#' in an environment named ".instrument" at the top level of the package
-#' (i.e. "FinancialInstrument:::.instrument") rather than the global
-#' environment, \code{.GlobalEnv}.  Objects may be listed using
-#' \code{ls_instruments()} (or many other ls_* functions).
+#' FinancialInstrument stores instrument definitions in an internal
+#' package-level environment named `.instrument`, rather than in
+#' `.GlobalEnv`. Users should access instrument definitions through exported
+#' functions such as `getInstrument()`, `ls_instruments()`,
+#' `saveInstruments()`, and `loadInstruments()`.
 #'
 #' We store instruments in their own environment for two reasons.  First, it
 #' keeps the user's workspace less cluttered and lowers the probability of