## ----include = FALSE----------------------------------------------------------
knitr::opts_chunk$set(collapse = FALSE, comment = "")
# Console colour carries no meaning on a rendered page. pkgdown turns it on for
# its own build, and the escape sequences then reach the reader as literal text,
# so colour is switched off here for a plain vignette render and a site build
# alike. The fixed width keeps tibbles inside the documentation column.
options(cli.num_colors = 1, cli.hyperlink = FALSE, crayon.enabled = FALSE,
        width = 80)
# Print data frames and tibbles as formatted tables.
local({
  kp <- function(x, ...) {
    if (any(vapply(x, is.list, logical(1)))) return(knitr::normal_print(x))
    knitr::knit_print(knitr::kable(x))
  }
  for (cls in c("data.frame", "tbl_df", "tbl")) {
    registerS3method("knit_print", cls, kp, envir = asNamespace("knitr"))
  }
})

## ----setup--------------------------------------------------------------------
library(scopusflow)

## -----------------------------------------------------------------------------
q <- scopus_query("language learning", "effect size", .field = "TITLE-ABS-KEY")
q

## -----------------------------------------------------------------------------
scopus_field_tags()

## -----------------------------------------------------------------------------
plan <- scopus_plan(q, years = 2010:2020, partition = "year")
plan

## -----------------------------------------------------------------------------
scopus_plan(q, view = "STANDARD")$page_size[1]
scopus_plan(q, view = "COMPLETE")$page_size[1]

## ----eval = FALSE-------------------------------------------------------------
# n <- scopus_count(q, years = 2010:2020)
# n
# attr(n, "quota")

## -----------------------------------------------------------------------------
resp <- httr2::response(
  status_code = 200,
  headers = list(
    `X-RateLimit-Limit`     = "20000",
    `X-RateLimit-Remaining` = "19987",
    `X-RateLimit-Reset`     = "1700000000"
  )
)
scopus_quota(resp)

## ----eval = FALSE-------------------------------------------------------------
# records <- scopus_fetch_plan(
#   plan,
#   cache_dir = scopus_cache_dir(),
#   resume = TRUE
# )
# records

## ----eval = FALSE-------------------------------------------------------------
# scopus_cache_dir()    # where completed cells are written
# scopus_cache_clear()  # remove them, so the next run re-fetches from scratch

## -----------------------------------------------------------------------------
head(example_records)

## ----eval = FALSE-------------------------------------------------------------
# records <- scopus_fetch_plan(
#   plan,
#   cache_dir = scopus_cache_dir(),
#   verbose = TRUE
# )

## -----------------------------------------------------------------------------
baseline <- example_records[example_records$year <= 2023, ]
combined <- scopus_combine(baseline, example_records, dedupe = TRUE)
nrow(combined)

## -----------------------------------------------------------------------------
graphene <- scopus_plan("graphene supercapacitor", years = 2015:2024,
                        field = "TITLE-ABS-KEY", partition = "year")
report <- scopus_search_report(graphene)
report

## -----------------------------------------------------------------------------
records <- example_records
attr(records, "plan") <- graphene
attr(records, "retrieved_at") <- as.POSIXct("2026-07-22 09:15:00", tz = "UTC")
attr(records, "scopusflow_version") <- "0.3.0"
attr(records, "paging") <- "offset"
per_year <- as.integer(table(example_records$year))
attr(records, "cell_totals") <- tibble::tibble(
  cell = 1:10, date = as.character(2015:2024),
  n_records = per_year, reported_total = as.numeric(per_year)
)

report <- scopus_search_report(records)
report

## -----------------------------------------------------------------------------
cat(format(report, style = "paragraph"))

## ----eval = FALSE-------------------------------------------------------------
# scopus_search_report(records, file = "search-record.md")

## ----eval = FALSE-------------------------------------------------------------
# result <- tryCatch(
#   scopus_fetch_plan(plan, cache_dir = scopus_cache_dir()),
#   scopus_error_rate_limit = function(e) {
#     message("Rate limited; the cached cells are safe. Try again later.")
#     NULL
#   }
# )