diff --git a/.github/skills/document/SKILL.md b/.github/skills/document/SKILL.md index 9914cdd..07a3321 100644 --- a/.github/skills/document/SKILL.md +++ b/.github/skills/document/SKILL.md @@ -66,19 +66,19 @@ When a parameter takes one of a fixed set of values, document them with a bullet ## Returns -Use `@returns` (not `@return`). Include a type when it's informative: +Use `@returns` (not `@return`). Include a type or types: ```r -#' @returns A summary tibble. +#' @returns (`tibble`) A summary tibble. #' @returns (`logical(1)`) `TRUE` if `x` is a valid record. -#' @returns Either a tibble or a list, depending on the input. -#' @returns `NULL` (invisibly). +#' @returns (`tibble` or `list`) Either a tibble or a list, depending on the input. +#' @returns (`NULL`, invisibly) Called for warning side effect. ``` **Structured returns with columns:** ```r -#' @returns A [tibble::tibble()] with columns: +#' @returns (`tibble`) A [tibble::tibble()] with columns: #' - `name`: Record name. #' - `value`: Numeric value. #' - `status`: Status (`"active"` or `"inactive"`). @@ -94,7 +94,7 @@ Use `@returns` (not `@return`). Include a type when it's informative: #' @param param_name (`TYPE`) Description. #' @inheritParams .shared-params #' -#' @returns Description of return value. +#' @returns (`TYPE`) Description of return value. #' @seealso [related_function()] #' @export #' @@ -132,7 +132,7 @@ Use `@rdname` to group related functions under one help page. This applies to: #' #' @param x (`any`) The object to format. #' @param ... Additional arguments passed to methods. -#' @returns A formatted character string. +#' @returns (`character(1)`) A formatted summary string. #' @keywords internal .format_summary <- function(x, ...) { UseMethod(".format_summary") @@ -152,7 +152,7 @@ Use `@rdname` to group related functions under one help page. This applies to: #' #' @param x (`TYPE`) Description. #' @param ... Additional arguments (ignored). -#' @returns Description. +#' @returns (`TYPE`) Description. #' @exportS3Method pkg::generic method.class <- function(x, ...) { ... } ``` diff --git a/R/aaa-conditions.R b/R/aaa-conditions.R index 4ce7af5..9ae5645 100644 --- a/R/aaa-conditions.R +++ b/R/aaa-conditions.R @@ -2,7 +2,7 @@ #' #' @inheritParams .shared-params #' @inheritParams stbl::pkg_abort -#' @returns Does not return. +#' @returns (`NULL`) Does not return. #' @keywords internal .pkg_abort <- function( message, @@ -27,7 +27,7 @@ #' #' @inheritParams .shared-params #' @inheritParams stbl::pkg_warn -#' @returns `NULL`, invisibly (called for warning side effect). +#' @returns (`NULL`, invisibly) Called for warning side effect. #' @keywords internal .pkg_warn <- function( message, @@ -52,7 +52,7 @@ #' #' @inheritParams .shared-params #' @inheritParams stbl::pkg_inform -#' @returns `NULL`, invisibly (called for message side effect). +#' @returns (`NULL`, invisibly) Called for message side effect. #' @keywords internal .pkg_inform <- function( message, diff --git a/R/aaa-shared_params.R b/R/aaa-shared_params.R index 0ea641a..a3c0675 100644 --- a/R/aaa-shared_params.R +++ b/R/aaa-shared_params.R @@ -3,20 +3,86 @@ #' These parameters are used in multiple functions. They are defined here to #' make them easier to import and to find. #' +#' @param addition (`character`) Text to append when `test` is `TRUE`. +#' @param allow_empty (`logical`) Whether empty parameter values may be +#' represented as `NULL`. #' @param api_abbr (`character(1)`) A short (about 2-5 letter) abbreviation for #' the API, for use in function names and environment variables. #' @param api_definition (`rapid::class_rapid`) The API definition to generate #' package code from. #' @param api_title (`character(1)`) The API title used in generated package #' files. +#' @param base_path The root URL of the current project. +#' @param base_url (`character(1)`) The base URL used in generated test +#' helpers. #' @param call (`environment`) The caller environment for error messages. +#' @param config (`list`) Package-generation configuration data. #' @param config_file (`character(1)` or `fs_path`) The path to a beekeeper yaml #' config file. +#' @param data (`list`) Data passed to a template. +#' @param dir (`character(1)`) The directory where a generated file should be +#' written. +#' @param endpoint (`character(1)`) The operation endpoint. +#' @param endpoints (`character`) Endpoint paths paired with operations. +#' @param filter_in (`character(1)`) The parameter location to keep. +#' @param include_stbl (`logical(1)`) Whether to add `stbl` to Imports. +#' @param methods (`character`) HTTP methods paired with endpoints. +#' @param operation (`character(1)`) The HTTP method. +#' @param operation_description (`character(1)`) The operation description. +#' @param operation_descriptions (`character`) Operation descriptions from the +#' API definition. +#' @param operation_id (`character(1)`) The operation identifier used in +#' generated file names. +#' @param operation_ids (`character`) Operation identifiers from the API +#' definition. +#' @param operation_summaries (`character`) Operation summaries from the API +#' definition. +#' @param operation_summary (`character(1)`) The operation summary. +#' @param original (`character`) The original text. +#' @param pagination_data (`list`) Pagination metadata used while generating +#' path files. +#' @param parameters (`data.frame`) Operation parameters. +#' @param params (`list`) Parameter metadata for a single operation. +#' @param params_df (`data.frame`) Parameter metadata in tabular form. +#' @param params_schema (`data.frame`) Schema metadata for operation parameters. +#' @param path (`character(1)`) The path template. +#' @param path_operation (`list`) Template data for one operation. +#' @param paths (`rapid::class_paths`) API path definitions. +#' @param paths_by_operation (`list`) Template-ready operations keyed by +#' operation identifier. #' @param pkg_dir (`character(1)` or `fs_path`) The directory containing package #' files. #' @param rapid_file (`character(1)` or `fs_path`) The path to the R API #' definition (rapid) file. +#' @param required (`logical`) Whether each parameter is required. +#' @param security_arg_description (`character(1)`) The argument description. +#' @param security_arg_name (`character(1)`) The argument name. +#' @param security_arg_names (`character`) Security argument names to exclude +#' from generated operation signatures (because they are defined once, +#' separately). +#' @param security_args (`character`) Security argument names to remove from +#' operation parameters (because they are defined once, separately). +#' @param security_data (`list`) Generated security metadata. +#' @param security_scheme_collection (`list`) Collected security scheme +#' metadata. +#' @param security_scheme_description (`character(1)`) A security scheme +#' description from the API definition. +#' @param security_scheme_details (`rapid::class_security_scheme_details`) The +#' security scheme details. +#' @param security_scheme_name (`character(1)`) The security scheme name. +#' @param security_scheme_type (`character(1)`) The security scheme type. +#' @param security_schemes (`rapid::class_security_schemes`) Security schemes +#' from the API definition. +#' @param tag_operations (`list`) Operations grouped under one tag. +#' @param tag_name (`character(1)`) The tag name. +#' @param tags (`character` or `list`) Tags for all operations. +#' @param target (`character(1)`) The name of the generated file. +#' @param template (`character(1)`) The template file name to render. +#' @param test (`logical`) A condition for each element of `original`. #' @param to_collapse (`character`) The character vector to collapse. +#' @param type (`data.frame`) Joined parameter type metadata. +#' @param x (`any`) The object to check or coerce. +#' @param y (`any`) The default value. #' #' @name .shared-params #' @keywords internal diff --git a/R/as_bk_data.R b/R/as_bk_data.R index 44a10d2..f57223b 100644 --- a/R/as_bk_data.R +++ b/R/as_bk_data.R @@ -2,14 +2,15 @@ #' #' Convert `rapid` objects to lists of properties to use in beekeeper templates. #' +#' @inheritParams .shared-params #' @inheritParams rlang::args_dots_empty -#' @param x The object to coerce. -#' -#' @returns A list. +#' @returns (`list`) A list. #' @keywords internal as_bk_data <- S7::new_generic("as_bk_data", dispatch_args = "x") -S7::method(as_bk_data, class_any) <- function(x) { +#' @rdname as_bk_data +#' @keywords internal +S7::method(as_bk_data, class_any) <- function(x, ...) { cli::cli_warn("No method for as_bk_data() for class {.cls {class(x)}}.") return(list()) } diff --git a/R/generate_pkg-pagination.R b/R/generate_pkg-pagination.R index 8e70eaa..d24d681 100644 --- a/R/generate_pkg-pagination.R +++ b/R/generate_pkg-pagination.R @@ -1,3 +1,7 @@ +#' Generate pagination files +#' +#' @returns (`list`) Pagination metadata used while generating path files. +#' @keywords internal .generate_pagination <- function() { # TODO: Accept pagination config and generate 030-pagination.R (#63) list() diff --git a/R/generate_pkg-paths.R b/R/generate_pkg-paths.R index 8f816dc..d08c9af 100644 --- a/R/generate_pkg-paths.R +++ b/R/generate_pkg-paths.R @@ -1,3 +1,8 @@ +#' Generate files for API paths +#' +#' @inheritParams .shared-params +#' @returns (`character`) Generated file paths. +#' @keywords internal .generate_paths <- function( paths, api_abbr, @@ -26,7 +31,9 @@ # reshape data ----------------------------------------------------------------- -S7::method(as_bk_data, class_paths) <- function(x) { +#' @rdname as_bk_data +#' @keywords internal +S7::method(as_bk_data, class_paths) <- function(x, ...) { if (!length(x)) { return(list()) } @@ -36,6 +43,12 @@ S7::method(as_bk_data, class_paths) <- function(x) { result } +#' Convert API paths to an operations data frame +#' +#' @inheritParams .shared-params +#' @returns (`tibble`) A [tibble::tibble()] with one row per non-deprecated +#' operation. +#' @keywords internal .paths_to_clean_df <- function(paths) { operations_df <- tibble::as_tibble(paths) |> tidyr::unnest("operations") @@ -70,22 +83,42 @@ S7::method(as_bk_data, class_paths) <- function(x) { ### fill data ------------------------------------------------------------------ +#' Fill missing operation tags +#' +#' @inheritParams .shared-params +#' @returns (`character`) Snake-case tag names. +#' @keywords internal .paths_fill_tags <- function(tags) { tags[lengths(tags) == 0] <- "general" tags <- purrr::map_chr(tags, 1) return(.to_snake(tags)) } +#' Fill missing operation identifiers +#' +#' @inheritParams .shared-params +#' @returns (`character`) Operation identifiers. +#' @keywords internal .paths_fill_operation_id <- function(operation_ids, endpoints, methods) { .to_snake(operation_ids) %|% glue::glue("{methods}_{.to_snake(endpoints)}") } +#' Fill missing operation summaries +#' +#' @inheritParams .shared-params +#' @returns (`character`) Human-readable operation summaries. +#' @keywords internal .paths_fill_summary <- function(operation_summaries, endpoints, methods) { endpoints_spaced <- stringr::str_replace_all(.to_snake(endpoints), "_", " ") stringr::str_squish(operation_summaries) %|% stringr::str_to_sentence(glue::glue("{methods} {endpoints_spaced}")) } +#' Fill missing operation descriptions +#' +#' @inheritParams .shared-params +#' @returns (`character`) Operation descriptions. +#' @keywords internal .paths_fill_descriptions <- function( operation_descriptions, operation_summaries @@ -101,6 +134,12 @@ S7::method(as_bk_data, class_paths) <- function(x) { ### create template data ------------------------------------------------------- +#' Convert one operation row to template data +#' +#' @param ... Additional columns, ignored. +#' @inheritParams .shared-params +#' @returns (`list`) One operation description. +#' @keywords internal .path_row_to_list <- function( operation_id, endpoint, @@ -125,6 +164,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Prepare parameter metadata +#' +#' @inheritParams .shared-params +#' @returns (`data.frame`) Prepared parameter metadata. +#' @keywords internal .prepare_params_df <- function(params_df) { params_df <- .flatten_params_df(params_df) if (nrow(params_df)) { @@ -144,6 +188,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(params_df) } +#' Flatten parameter metadata +#' +#' @inheritParams .shared-params +#' @returns (`data.frame`) Flattened parameter metadata. +#' @keywords internal .flatten_params_df <- function(params_df) { params_df <- .flatten_df(params_df) if (nrow(params_df)) { @@ -152,6 +201,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(params_df) } +#' Convert parameter rows to a list +#' +#' @inheritParams .shared-params +#' @returns (`list`) Parameter metadata entries. +#' @keywords internal .params_to_list <- function(params_df) { if (!nrow(params_df)) { return(list()) @@ -169,6 +223,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Extract parameter names by location +#' +#' @inheritParams .shared-params +#' @returns (`character`) Parameter names for the requested location. +#' @keywords internal .extract_params_by_location <- function(params_df, filter_in) { if (!nrow(params_df)) { return(character()) @@ -176,6 +235,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(params_df$name[params_df$`in` == filter_in]) } +#' Describe parameter classes +#' +#' @inheritParams .shared-params +#' @returns (`character`) Display strings for parameter classes. +#' @keywords internal .describe_param_classes <- function(params_schema, allow_empty, required) { # TODO: Use enum and/or description when available. # @@ -197,6 +261,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(.compile_param_class_descriptions(type, allow_empty, required)) } +#' Map parameter schemas to `stbl` helpers +#' +#' @inheritParams .shared-params +#' @returns (`character`) Coercion helper names. +#' @keywords internal .param_schema_to_r <- function(params_schema) { type <- dplyr::left_join( dplyr::select(params_schema, "type", "format"), @@ -206,6 +275,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { type$to_r } +#' Compile parameter class descriptions +#' +#' @inheritParams .shared-params +#' @returns (`character`) Parameter class descriptions. +#' @keywords internal .compile_param_class_descriptions <- function(type, allow_empty, required) { r_class_descriptions <- glue::glue("length-1 `{type$r_class_name}`") |> .paste0_if( @@ -220,6 +294,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(r_class_descriptions) } +#' Convert a path to a request argument +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) Code for the request path argument. +#' @keywords internal .path_as_arg <- function(path, params_df) { if (!nrow(params_df) || !any(params_df$`in` == "path")) { return(glue::glue('"{path}"')) @@ -231,6 +310,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { # generate files --------------------------------------------------------------- +#' Generate files for all operations +#' +#' @inheritParams .shared-params +#' @returns (`character`) Generated file paths. +#' @keywords internal .generate_paths_files <- function( paths_by_operation, api_abbr, @@ -280,14 +364,29 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(c(r_files, test_files)) } +#' Convert parameters to a signature string +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A comma-separated parameter string. +#' @keywords internal .params_to_args <- function(params) { .collapse_comma(purrr::map_chr(params, "name")) %|a|% character() } +#' Convert parameters to named arguments +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A comma-separated named-argument string. +#' @keywords internal .params_to_named_args <- function(params) { .collapse_comma_self_equal(purrr::map_chr(params, "name")) %|a|% character() } +#' Remove security parameters +#' +#' @inheritParams .shared-params +#' @returns (`list`) Non-security parameters. +#' @keywords internal .remove_security_args <- function(params, security_args) { purrr::discard( params, @@ -297,10 +396,20 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Prepare parameter arguments +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A comma-separated named-argument string. +#' @keywords internal .prep_param_args <- function(params, security_args) { .collapse_comma_self_equal(setdiff(params, security_args)) %|a|% character() } +#' Convert parameters to validation metadata +#' +#' @inheritParams .shared-params +#' @returns (`list`) Validation metadata. +#' @keywords internal .params_to_validations <- function(params) { checks <- purrr::keep( params, @@ -318,6 +427,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Determine whether generated paths need `stbl` +#' +#' @inheritParams .shared-params +#' @returns (`logical(1)`) `TRUE` if any path needs `stbl`. +#' @keywords internal .paths_need_stbl <- function(paths, security_arg_names = character()) { ops <- as_bk_data(paths) if (!length(ops)) { @@ -329,6 +443,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { })) } +#' Generate one operation file +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated file path. +#' @keywords internal .generate_paths_file <- function( path_operation, operation_id, @@ -352,6 +471,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Generate one tag-level test file +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated test file path. +#' @keywords internal .generate_paths_test_file <- function(tag_operations, tag_name, api_abbr) { paths_list <- unname(purrr::imap(tag_operations, function(op, op_id) { list( diff --git a/R/generate_pkg-prepare.R b/R/generate_pkg-prepare.R index 8ad4e80..24dddb9 100644 --- a/R/generate_pkg-prepare.R +++ b/R/generate_pkg-prepare.R @@ -1,3 +1,8 @@ +#' Generate prepare files +#' +#' @inheritParams .shared-params +#' @returns (`character`) Generated file paths. +#' @keywords internal .generate_prepare <- function(config, api_definition, security_data) { c( .generate_prepare_r(config, api_definition, security_data), @@ -5,6 +10,11 @@ ) } +#' Generate the prepare helper +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated file path. +#' @keywords internal .generate_prepare_r <- function(config, api_definition, security_data) { .bk_use_template( template = "010-prepare.R", @@ -20,6 +30,11 @@ ) } +#' Generate prepare tests +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated test file path. +#' @keywords internal .generate_prepare_test <- function(api_abbr) { .bk_use_template( template = "test-010-prepare.R", diff --git a/R/generate_pkg-security.R b/R/generate_pkg-security.R index 6c960f7..c872edd 100644 --- a/R/generate_pkg-security.R +++ b/R/generate_pkg-security.R @@ -1,3 +1,8 @@ +#' Generate security files and metadata +#' +#' @inheritParams .shared-params +#' @returns (`list`) Generated security metadata. +#' @keywords internal .generate_security <- function(api_abbr, security_schemes) { security_data <- as_bk_data(security_schemes) if (length(security_data)) { @@ -13,6 +18,11 @@ return(security_data) } +#' Generate a security argument signature +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A function-signature fragment. +#' @keywords internal .generate_security_signature <- function(security_arg_names, api_abbr) { env_vars <- toupper(glue::glue("{api_abbr}_{security_arg_names}")) return( @@ -22,7 +32,9 @@ ) } -S7::method(as_bk_data, class_security_schemes) <- function(x) { +#' @rdname as_bk_data +#' @keywords internal +S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { if (!length(x)) { return(list()) } @@ -30,6 +42,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { return(.security_scheme_collection_finalize(security_scheme_collection)) } +#' Collect security scheme metadata +#' +#' @inheritParams .shared-params +#' @returns (`list`) Security scheme metadata. +#' @keywords internal .security_schemes_collect <- function(security_schemes) { purrr::pmap( list( @@ -42,6 +59,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { ) } +#' Convert one security scheme to a list +#' +#' @inheritParams .shared-params +#' @returns (`list`) One security scheme description. +#' @keywords internal .security_scheme_rotate <- function( security_scheme_name, security_scheme_details, @@ -61,6 +83,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { return(security_scheme_list) } +#' Fill a missing security scheme description +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A security scheme description. +#' @keywords internal .security_scheme_description_fill <- function( security_scheme_description, security_scheme_type @@ -83,6 +110,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { "Check the API documentation for details." ) +#' Finalize collected security scheme data +#' +#' @inheritParams .shared-params +#' @returns (`list`) Finalized security metadata. +#' @keywords internal .security_scheme_collection_finalize <- function(security_scheme_collection) { security_scheme_data <- c( list( @@ -94,6 +126,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { return(security_scheme_data) } +#' Compile security argument metadata +#' +#' @inheritParams .shared-params +#' @returns (`list`) Compiled security argument values. +#' @keywords internal .security_args_compile <- function(security_scheme_collection) { security_args <- sort(unique(purrr::map_chr( security_scheme_collection, @@ -112,6 +149,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { )) } +#' Build security argument help entries +#' +#' @inheritParams .shared-params +#' @returns (`list`) Template-ready parameter help entries. +#' @keywords internal .generate_security_arg_help <- function( security_scheme_collection, security_args @@ -130,6 +172,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { ) } +#' Format one security argument help entry +#' +#' @inheritParams .shared-params +#' @returns (`list`) A named list with `name` and `description`. +#' @keywords internal .security_arg_description_clean <- function( security_arg_description, security_arg_name @@ -137,11 +184,15 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { list(name = security_arg_name, description = security_arg_description) } -S7::method(as_bk_data, class_security_scheme_details) <- function(x) { +#' @rdname as_bk_data +#' @keywords internal +S7::method(as_bk_data, class_security_scheme_details) <- function(x, ...) { purrr::map(x, as_bk_data) } -S7::method(as_bk_data, class_api_key_security_scheme) <- function(x) { +#' @rdname as_bk_data +#' @keywords internal +S7::method(as_bk_data, class_api_key_security_scheme) <- function(x, ...) { if (length(x)) { return( list( diff --git a/R/generate_pkg-setup.R b/R/generate_pkg-setup.R index e5a4eee..f52873f 100644 --- a/R/generate_pkg-setup.R +++ b/R/generate_pkg-setup.R @@ -1,16 +1,15 @@ #' Error if not in package #' -#' @inheritParams .is_pkg -#' -#' @returns `NULL`, invisibly. +#' @inheritParams .shared-params +#' @returns (`NULL`, invisibly) Called for error side effect. #' @keywords internal -.assert_is_pkg <- function(base_path = usethis::proj_get()) { - if (.is_pkg(base_path)) { +.assert_is_pkg <- function(pkg_dir = usethis::proj_get()) { + if (.is_pkg(pkg_dir)) { return(invisible(NULL)) } cli::cli_abort(c( "Can't generate package files outside of a package.", - x = "{.path {base_path}} is not inside a package." + x = "{.path {pkg_dir}} is not inside a package." )) } @@ -18,80 +17,22 @@ #' #' Inspired by usethis:::is_package. #' -#' @param base_path The root URL of the current project. -#' -#' @returns `TRUE` if the project is a package, `FALSE` if not. +#' @inheritParams .shared-params +#' @returns (`logical(1)`) `TRUE` if the project is a package, `FALSE` if not. #' @keywords internal -.is_pkg <- function(base_path = usethis::proj_get()) { +.is_pkg <- function(pkg_dir = usethis::proj_get()) { root_file <- rlang::try_fetch( - rprojroot::find_package_root_file(path = base_path), + rprojroot::find_package_root_file(path = pkg_dir), error = function(cnd) NULL ) !is.null(root_file) } -#' Read a beekeeper config file -#' -#' Reads a YAML file (default name `_beekeeper.yml`) with configuration -#' information about the API and the package. This file is generated by -#' [use_beekeeper()], or can be created manually. -#' -#' The configuration information must contain these fields: -#' -#' - `api_title` (`character(1)`): The title of the API, used in documentation -#' and messages. -#' - `api_abbr` (`character(1)`): An abbreviation for the API, used in function -#' names and other identifiers. -#' - `api_version` (`character(1)`): The version of the API. -#' - `rapid_file` (`character(1)`): The name of the file (relative to the -#' package root) where the API definition is stored as an RDS file. By default, -#' this is `_beekeeper_rapid.rds`, and is generated by [use_beekeeper()] based -#' on an OpenAPI definition file. -#' - `updated_on` (`character(1)`): A timestamp of when the API definition was -#' last updated, in the format "YYYY-MM-DD HH:MM:SS" (UTC). -#' -#' @inheritParams .shared-params -#' @returns A `list` of configuration information, with elements `api_title`, -#' `api_abbr`, `api_version`, `rapid_file`, and `updated_on`. -#' @export -read_config <- function(pkg_dir = ".", config_file = "_beekeeper.yml") { - config <- yaml::read_yaml(fs::path(pkg_dir, config_file)) - return(.stabilize_config(config)) -} - -.stabilize_config <- function(config) { - config$api_title <- stbl::stabilize_character_scalar(config$api_title) - config$api_abbr <- stbl::stabilize_character_scalar(config$api_abbr) - config$api_version <- stbl::stabilize_character_scalar( - config$api_version, - allow_null = TRUE - ) - config$rapid_file <- stbl::stabilize_character_scalar(config$rapid_file) - config$updated_on <- config$updated_on %&&% - strptime( - config$updated_on, - format = "%Y-%m-%d %H:%M:%S", - tz = "UTC" - ) - return(config) -} - -#' Read an API definition file -#' -#' Reads an RDS file (default name `_beekeeper_rapid.rds`) with the API -#' definition stored as a [rapid::class_rapid()] object. This file is generated -#' by [use_beekeeper()] based on an OpenAPI definition file. +#' Set up package directories and dependencies #' #' @inheritParams .shared-params -#' @returns A [rapid::class_rapid()] with the definition of the API. -#' @export -read_api_definition <- function( - pkg_dir = ".", - rapid_file = "_beekeeper_rapid.rds" -) { - readRDS(fs::path(pkg_dir, rapid_file)) -} - +#' @returns (`NULL`, invisibly) Called for setup side effects. +#' @keywords internal .setup_r <- function(pkg_dir, include_stbl = FALSE) { if (as.character(pkg_dir) != ".") { usethis::local_project(pkg_dir, quiet = TRUE) # nocov diff --git a/R/generate_pkg-shared.R b/R/generate_pkg-shared.R index 7564df1..6d89be2 100644 --- a/R/generate_pkg-shared.R +++ b/R/generate_pkg-shared.R @@ -1,3 +1,8 @@ +#' Generate shared parameter docs +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated file path. +#' @keywords internal .generate_shared_params <- function(security_data) { shared_file_path <- .bk_use_template( template = "000-shared.R", diff --git a/R/generate_pkg-template.R b/R/generate_pkg-template.R index 023e557..bd6ace4 100644 --- a/R/generate_pkg-template.R +++ b/R/generate_pkg-template.R @@ -1,12 +1,9 @@ #' Use a template in this package #' +#' @inheritParams .shared-params #' @inheritParams rlang::args_dots_empty -#' @param template The name of the template. -#' @param data A list of variables to apply to the template. -#' @param target The name of the file to create. -#' @param dir The directory where the file should be created. -#' -#' @returns The path to the generated or updated file, invisibly. +#' @returns (`character(1)`, invisibly) The path to the generated or updated +#' file. #' @keywords internal .bk_use_template <- function( template, @@ -21,6 +18,11 @@ return(invisible(target)) } +#' Write a rendered template to disk +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated file path. +#' @keywords internal .bk_use_template_impl <- function(template, data, target, dir) { target <- usethis::proj_path(dir, target) save_as <- fs::path_rel(target, usethis::proj_path()) diff --git a/R/generate_pkg.R b/R/generate_pkg.R index e32a680..42ffb63 100644 --- a/R/generate_pkg.R +++ b/R/generate_pkg.R @@ -6,8 +6,7 @@ #' #' @inheritParams .shared-params #' -#' @returns A character vector of paths to files that were added or updated, -#' invisibly. +#' @returns (`character`, invisibly) Paths to files that were added or updated. #' @export generate_pkg <- function( api_abbr = NULL, @@ -41,6 +40,11 @@ generate_pkg <- function( return(invisible(touched_files)) } +#' Generate package files from prepared inputs +#' +#' @inheritParams .shared-params +#' @returns (`character`, invisibly) Generated file paths. +#' @keywords internal .generate_pkg_impl <- function(config, api_definition, security_data) { prep_files <- .generate_prepare(config, api_definition, security_data) pagination_data <- .generate_pagination() diff --git a/R/read_config.R b/R/read_config.R new file mode 100644 index 0000000..cd1874f --- /dev/null +++ b/R/read_config.R @@ -0,0 +1,66 @@ +#' Read a beekeeper config file +#' +#' Reads a YAML file (default name `_beekeeper.yml`) with configuration +#' information about the API and the package. This file is generated by +#' [use_beekeeper()], or can be created manually. +#' +#' The configuration information must contain these fields: +#' +#' - `api_title` (`character(1)`): The title of the API, used in documentation +#' and messages. +#' - `api_abbr` (`character(1)`): An abbreviation for the API, used in function +#' names and other identifiers. +#' - `api_version` (`character(1)`): The version of the API. +#' - `rapid_file` (`character(1)`): The name of the file (relative to the +#' package root) where the API definition is stored as an RDS file. By default, +#' this is `_beekeeper_rapid.rds`, and is generated by [use_beekeeper()] based +#' on an OpenAPI definition file. +#' - `updated_on` (`character(1)`): A timestamp of when the API definition was +#' last updated, in the format "YYYY-MM-DD HH:MM:SS" (UTC). +#' +#' @inheritParams .shared-params +#' @returns (`list`) Configuration information, with elements `api_title`, +#' `api_abbr`, `api_version`, `rapid_file`, and `updated_on`. +#' @export +read_config <- function(pkg_dir = ".", config_file = "_beekeeper.yml") { + config <- yaml::read_yaml(fs::path(pkg_dir, config_file)) + return(.stabilize_config(config)) +} + +#' Stabilize beekeeper config values +#' +#' @inheritParams .shared-params +#' @returns (`list`) A stabilized config list. +#' @keywords internal +.stabilize_config <- function(config) { + config$api_title <- stbl::stabilize_character_scalar(config$api_title) + config$api_abbr <- stbl::stabilize_character_scalar(config$api_abbr) + config$api_version <- stbl::stabilize_character_scalar( + config$api_version, + allow_null = TRUE + ) + config$rapid_file <- stbl::stabilize_character_scalar(config$rapid_file) + config$updated_on <- config$updated_on %&&% + strptime( + config$updated_on, + format = "%Y-%m-%d %H:%M:%S", + tz = "UTC" + ) + return(config) +} + +#' Read an API definition file +#' +#' Reads an RDS file (default name `_beekeeper_rapid.rds`) with the API +#' definition stored as a [rapid::class_rapid()] object. This file is generated +#' by [use_beekeeper()] based on an OpenAPI definition file. +#' +#' @inheritParams .shared-params +#' @returns (`rapid::class_rapid`) The definition of the API. +#' @export +read_api_definition <- function( + pkg_dir = ".", + rapid_file = "_beekeeper_rapid.rds" +) { + readRDS(fs::path(pkg_dir, rapid_file)) +} diff --git a/R/use_beekeeper.R b/R/use_beekeeper.R index ea8cdde..efecfe9 100644 --- a/R/use_beekeeper.R +++ b/R/use_beekeeper.R @@ -11,9 +11,9 @@ #' generated by reading such a document. #' @inheritParams .shared-params #' -#' @returns The path to the configuration file, invisibly. The config file is -#' written as a side effect of this function. The rapid object is also -#' written, and the path to that file is saved in the config file. +#' @returns (`character(1)`, invisibly) The path to the configuration file. The +#' config file is written as a side effect of this function. The rapid object +#' is also written, and the path to that file is saved in the config file. #' @export use_beekeeper <- function( x, @@ -34,6 +34,11 @@ use_beekeeper <- function( return(invisible(config_file)) } +#' Write the rapid definition file +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The written file path. +#' @keywords internal .write_rapid <- function(api_definition, rapid_file) { rapid_file <- stbl::stabilize_character_scalar(rapid_file) saveRDS(api_definition, rapid_file) @@ -41,6 +46,11 @@ use_beekeeper <- function( return(rapid_file) } +#' Write the beekeeper config file +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The written config file path. +#' @keywords internal .write_config <- function(api_definition, api_abbr, rapid_file, config_file) { config_file <- stbl::stabilize_character_scalar(config_file) update_time <- strptime(Sys.time(), format = "%Y-%m-%d %H:%M:%S", tz = "UTC") diff --git a/R/utils.R b/R/utils.R index 9f44022..df5ab67 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,8 +1,7 @@ #' Default value for `NULL` #' -#' @param x (`any`) Object to check. -#' @param y (`any`) Default value for `x`. -#' @returns If `x` is `NULL`, will return `y`; otherwise returns `x`. +#' @inheritParams .shared-params +#' @returns (`any`) If `x` is `NULL`, returns `y`; otherwise returns `x`. #' @name op-null-default #' @family empty operators #' @keywords internal @@ -17,9 +16,8 @@ if (exists("%||%", envir = baseenv())) { #' Default value for non-`NULL` #' -#' @param x (`any`) Object to check. -#' @param y (`any`) Default value for non-`NULL` `x`. -#' @returns If `x` is `NULL`, will return `x`; otherwise returns `y`. +#' @inheritParams .shared-params +#' @returns (`any`) If `x` is `NULL`, returns `x`; otherwise returns `y`. #' @name op-null-continuation #' @family empty operators #' @keywords internal @@ -29,9 +27,8 @@ if (exists("%||%", envir = baseenv())) { #' Default value for length 0 #' -#' @param x (`any`) Object to check. -#' @param y (`any`) Default value for `x`. -#' @returns If `!length(x)`, will return `x`; otherwise returns `y`. +#' @inheritParams .shared-params +#' @returns (`any`) If `!length(x)`, returns `x`; otherwise returns `y`. #' @keywords internal #' @name op-lengthless-default #' @family empty operators @@ -42,9 +39,9 @@ if (exists("%||%", envir = baseenv())) { #' Default value for empty strings #' -#' @param x (`any`) Object to check. -#' @param y (`character`) Default value for `x`. -#' @returns If `!nzchar(x)`, will return `y`; otherwise returns `x`. +#' @param y (`character`) The default value. +#' @inheritParams .shared-params +#' @returns (`character`) If `!nzchar(x)`, returns `y`; otherwise returns `x`. #' @keywords internal #' @name op-no-char-default #' @family empty operators @@ -59,11 +56,11 @@ if (exists("%||%", envir = baseenv())) { #' Default value for NA elements in vectors #' -#' @param x (`any`) A vector that may contain `NA` elements. #' @param y (`any`, coercible to the same class as `x`) A value or vector to #' replace `NA` elements in `x`. Will be recycled to the same length as `x`. -#' @returns A vector of the same length as `x`, where each `NA` element in `x` -#' is replaced by the corresponding element in `y`. +#' @inheritParams .shared-params +#' @returns (`vector`) A vector of the same length as `x`, where each `NA` +#' element in `x` is replaced by the corresponding element in `y`. #' @keywords internal #' @name op-na-coalesce #' @family empty operators @@ -75,7 +72,7 @@ if (exists("%||%", envir = baseenv())) { #' Collapse to a comma-separated string #' #' @inheritParams .shared-params -#' @returns A length-1, comma-separated glue object. +#' @returns (`glue`) A length-1, comma-separated glue object. #' @keywords internal .collapse_comma <- function(to_collapse) { glue::glue_collapse(to_collapse, sep = ", ") @@ -84,7 +81,7 @@ if (exists("%||%", envir = baseenv())) { #' Collapse to a comma-separated vertical string #' #' @inheritParams .shared-params -#' @returns A length-1, comma-separated glue object with newlines. +#' @returns (`glue`) A length-1, comma-separated glue object with newlines. #' @keywords internal .collapse_comma_newline <- function(to_collapse) { glue::glue_collapse(to_collapse, sep = ",\n") @@ -93,7 +90,7 @@ if (exists("%||%", envir = baseenv())) { #' Collapse to a comma-separated quoted string #' #' @inheritParams .shared-params -#' @returns A length-1, comma-separated glue object. +#' @returns (`glue`) A length-1, comma-separated glue object. #' @keywords internal .collapse_quote_comma <- function(to_collapse) { stringr::str_flatten_comma(paste0('"', to_collapse, '"')) @@ -102,20 +99,36 @@ if (exists("%||%", envir = baseenv())) { #' Collapse to a comma-separated x = x string #' #' @inheritParams .shared-params -#' @returns A length-1, comma-separated glue object. +#' @returns (`glue`) A length-1, comma-separated glue object. #' @keywords internal -.collapse_comma_self_equal <- function(x) { - .collapse_comma(glue::glue("{x} = {x}")) +.collapse_comma_self_equal <- function(to_collapse) { + .collapse_comma(glue::glue("{to_collapse} = {to_collapse}")) } +#' Append text conditionally +#' +#' @inheritParams .shared-params +#' @returns (`character`) The updated text. +#' @keywords internal .paste0_if <- function(original, test, addition) { ifelse(test, paste0(original, addition), original) } +#' Interpolate glue with pipe braces +#' +#' @param ... Expressions passed to [glue::glue()]. +#' @param .envir (`environment`) The environment in which to evaluate `...`. +#' @returns (`glue`) A glue object. +#' @keywords internal .glue_pipe_brace <- function(..., .envir = rlang::caller_env()) { glue::glue(..., .open = "|{", .close = "}|", .envir = .envir) } +#' Convert text to snake case +#' +#' @param x (`character`) Text to convert. +#' @returns (`character`) Snake-case text. +#' @keywords internal .to_snake <- function(x) { snakecase::to_snake_case(x, parsing_option = 3) } @@ -123,14 +136,19 @@ if (exists("%||%", envir = baseenv())) { #' Flatten a data frame or list of data frames #' #' @param x (`data.frame`, `list`, or `NULL`) The object to flatten. -#' @returns A single `data.frame`. Lists of data frames are flattened with -#' [purrr::list_rbind()], and `NULL` values are converted to empty data -#' frames. +#' @inheritParams rlang::args_dots_empty +#' @returns (`data.frame`) A single data frame. Lists of data frames are +#' flattened with [purrr::list_rbind()], and `NULL` values are converted to +#' empty data frames. #' @keywords internal .flatten_df <- S7::new_generic(".flatten_df", dispatch_args = "x") -S7::method(.flatten_df, class_data.frame) <- function(x) x +#' @rdname dot-flatten_df +#' @keywords internal +S7::method(.flatten_df, class_data.frame) <- function(x, ...) x -S7::method(.flatten_df, class_list) <- function(x) purrr::list_rbind(x) +#' @rdname dot-flatten_df +#' @keywords internal +S7::method(.flatten_df, class_list) <- function(x, ...) purrr::list_rbind(x) -S7::method(.flatten_df, NULL) <- function(x) data.frame() +S7::method(.flatten_df, NULL) <- function(x, ...) data.frame() diff --git a/inst/templates/paths.R b/inst/templates/paths.R index 5073515..ac06e06 100644 --- a/inst/templates/paths.R +++ b/inst/templates/paths.R @@ -22,7 +22,7 @@ } #' @rdname {{api_abbr}}_{{operation_id}} -#' @returns `req_{{api_abbr}}_{{operation_id}}()`: A `httr2_request` request object. +#' @returns `req_{{api_abbr}}_{{operation_id}}()`: (`httr2_request`) A [httr2::request()] object. req_{{api_abbr}}_{{operation_id}} <- function({{#args}}{{{args}}}{{/args}}{{#has_security}}{{#args}}, {{/args}}{{{security_signature}}}{{/has_security}}) { {{#validations}} {{name}} <- stbl::{{to_r}}({{name}}) diff --git a/man/as_bk_data.Rd b/man/as_bk_data.Rd index 17a1d1c..36a56bd 100644 --- a/man/as_bk_data.Rd +++ b/man/as_bk_data.Rd @@ -1,18 +1,39 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/as_bk_data.R +% Please edit documentation in R/as_bk_data.R, R/generate_pkg-paths.R, +% R/generate_pkg-security.R \name{as_bk_data} \alias{as_bk_data} +\alias{as_bk_data,any-method} +\alias{as_bk_data,rapid::paths-method} +\alias{as_bk_data,rapid::security_schemes-method} +\alias{as_bk_data,rapid::security_scheme_details-method} +\alias{as_bk_data,rapid::api_key_security_scheme-method} \title{Prepare rapid objects for beekeeper} \usage{ as_bk_data(x, ...) + +## S7 method for class +as_bk_data(x, ...) + +## S7 method for class +as_bk_data(x, ...) + +## S7 method for class +as_bk_data(x, ...) + +## S7 method for class +as_bk_data(x, ...) + +## S7 method for class +as_bk_data(x, ...) } \arguments{ -\item{x}{The object to coerce.} +\item{x}{(\code{any}) The object to check or coerce.} \item{...}{These dots are for future extensions and must be empty.} } \value{ -A list. +(\code{list}) A list. } \description{ Convert \code{rapid} objects to lists of properties to use in beekeeper templates. diff --git a/man/dot-assert_is_pkg.Rd b/man/dot-assert_is_pkg.Rd index 31c1b6c..e3c85ea 100644 --- a/man/dot-assert_is_pkg.Rd +++ b/man/dot-assert_is_pkg.Rd @@ -4,13 +4,14 @@ \alias{.assert_is_pkg} \title{Error if not in package} \usage{ -.assert_is_pkg(base_path = usethis::proj_get()) +.assert_is_pkg(pkg_dir = usethis::proj_get()) } \arguments{ -\item{base_path}{The root URL of the current project.} +\item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package +files.} } \value{ -\code{NULL}, invisibly. +(\code{NULL}, invisibly) Called for error side effect. } \description{ Error if not in package diff --git a/man/dot-bk_use_template.Rd b/man/dot-bk_use_template.Rd index 4ac8f9e..48bae24 100644 --- a/man/dot-bk_use_template.Rd +++ b/man/dot-bk_use_template.Rd @@ -13,18 +13,20 @@ ) } \arguments{ -\item{template}{The name of the template.} +\item{template}{(\code{character(1)}) The template file name to render.} -\item{data}{A list of variables to apply to the template.} +\item{data}{(\code{list}) Data passed to a template.} \item{...}{These dots are for future extensions and must be empty.} -\item{target}{The name of the file to create.} +\item{target}{(\code{character(1)}) The name of the generated file.} -\item{dir}{The directory where the file should be created.} +\item{dir}{(\code{character(1)}) The directory where a generated file should be +written.} } \value{ -The path to the generated or updated file, invisibly. +(\code{character(1)}, invisibly) The path to the generated or updated +file. } \description{ Use a template in this package diff --git a/man/dot-bk_use_template_impl.Rd b/man/dot-bk_use_template_impl.Rd new file mode 100644 index 0000000..4263323 --- /dev/null +++ b/man/dot-bk_use_template_impl.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-template.R +\name{.bk_use_template_impl} +\alias{.bk_use_template_impl} +\title{Write a rendered template to disk} +\usage{ +.bk_use_template_impl(template, data, target, dir) +} +\arguments{ +\item{template}{(\code{character(1)}) The template file name to render.} + +\item{data}{(\code{list}) Data passed to a template.} + +\item{target}{(\code{character(1)}) The name of the generated file.} + +\item{dir}{(\code{character(1)}) The directory where a generated file should be +written.} +} +\value{ +(\code{character(1)}) The generated file path. +} +\description{ +Write a rendered template to disk +} +\keyword{internal} diff --git a/man/dot-collapse_comma.Rd b/man/dot-collapse_comma.Rd index 4cfed87..dd0ef08 100644 --- a/man/dot-collapse_comma.Rd +++ b/man/dot-collapse_comma.Rd @@ -10,7 +10,7 @@ \item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ -A length-1, comma-separated glue object. +(\code{glue}) A length-1, comma-separated glue object. } \description{ Collapse to a comma-separated string diff --git a/man/dot-collapse_comma_newline.Rd b/man/dot-collapse_comma_newline.Rd index 88f9634..5c3a380 100644 --- a/man/dot-collapse_comma_newline.Rd +++ b/man/dot-collapse_comma_newline.Rd @@ -10,7 +10,7 @@ \item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ -A length-1, comma-separated glue object with newlines. +(\code{glue}) A length-1, comma-separated glue object with newlines. } \description{ Collapse to a comma-separated vertical string diff --git a/man/dot-collapse_comma_self_equal.Rd b/man/dot-collapse_comma_self_equal.Rd index 12748ed..063548c 100644 --- a/man/dot-collapse_comma_self_equal.Rd +++ b/man/dot-collapse_comma_self_equal.Rd @@ -4,10 +4,13 @@ \alias{.collapse_comma_self_equal} \title{Collapse to a comma-separated x = x string} \usage{ -.collapse_comma_self_equal(x) +.collapse_comma_self_equal(to_collapse) +} +\arguments{ +\item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ -A length-1, comma-separated glue object. +(\code{glue}) A length-1, comma-separated glue object. } \description{ Collapse to a comma-separated x = x string diff --git a/man/dot-collapse_quote_comma.Rd b/man/dot-collapse_quote_comma.Rd index 4a10e8c..e6aa0fb 100644 --- a/man/dot-collapse_quote_comma.Rd +++ b/man/dot-collapse_quote_comma.Rd @@ -10,7 +10,7 @@ \item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ -A length-1, comma-separated glue object. +(\code{glue}) A length-1, comma-separated glue object. } \description{ Collapse to a comma-separated quoted string diff --git a/man/dot-compile_param_class_descriptions.Rd b/man/dot-compile_param_class_descriptions.Rd new file mode 100644 index 0000000..cc3a760 --- /dev/null +++ b/man/dot-compile_param_class_descriptions.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.compile_param_class_descriptions} +\alias{.compile_param_class_descriptions} +\title{Compile parameter class descriptions} +\usage{ +.compile_param_class_descriptions(type, allow_empty, required) +} +\arguments{ +\item{type}{(\code{data.frame}) Joined parameter type metadata.} + +\item{allow_empty}{(\code{logical}) Whether empty parameter values may be +represented as \code{NULL}.} + +\item{required}{(\code{logical}) Whether each parameter is required.} +} +\value{ +(\code{character}) Parameter class descriptions. +} +\description{ +Compile parameter class descriptions +} +\keyword{internal} diff --git a/man/dot-describe_param_classes.Rd b/man/dot-describe_param_classes.Rd new file mode 100644 index 0000000..e94c684 --- /dev/null +++ b/man/dot-describe_param_classes.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.describe_param_classes} +\alias{.describe_param_classes} +\title{Describe parameter classes} +\usage{ +.describe_param_classes(params_schema, allow_empty, required) +} +\arguments{ +\item{params_schema}{(\code{data.frame}) Schema metadata for operation parameters.} + +\item{allow_empty}{(\code{logical}) Whether empty parameter values may be +represented as \code{NULL}.} + +\item{required}{(\code{logical}) Whether each parameter is required.} +} +\value{ +(\code{character}) Display strings for parameter classes. +} +\description{ +Describe parameter classes +} +\keyword{internal} diff --git a/man/dot-extract_params_by_location.Rd b/man/dot-extract_params_by_location.Rd new file mode 100644 index 0000000..ae912a3 --- /dev/null +++ b/man/dot-extract_params_by_location.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.extract_params_by_location} +\alias{.extract_params_by_location} +\title{Extract parameter names by location} +\usage{ +.extract_params_by_location(params_df, filter_in) +} +\arguments{ +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} + +\item{filter_in}{(\code{character(1)}) The parameter location to keep.} +} +\value{ +(\code{character}) Parameter names for the requested location. +} +\description{ +Extract parameter names by location +} +\keyword{internal} diff --git a/man/dot-flatten_df.Rd b/man/dot-flatten_df.Rd index 2d5ad8f..b05aa2a 100644 --- a/man/dot-flatten_df.Rd +++ b/man/dot-flatten_df.Rd @@ -2,17 +2,27 @@ % Please edit documentation in R/utils.R \name{.flatten_df} \alias{.flatten_df} +\alias{.flatten_df,data.frame-method} +\alias{.flatten_df,list-method} \title{Flatten a data frame or list of data frames} \usage{ .flatten_df(x, ...) + +## S7 method for class +.flatten_df(x, ...) + +## S7 method for class +.flatten_df(x, ...) } \arguments{ \item{x}{(\code{data.frame}, \code{list}, or \code{NULL}) The object to flatten.} + +\item{...}{These dots are for future extensions and must be empty.} } \value{ -A single \code{data.frame}. Lists of data frames are flattened with -\code{\link[purrr:list_rbind]{purrr::list_rbind()}}, and \code{NULL} values are converted to empty data -frames. +(\code{data.frame}) A single data frame. Lists of data frames are +flattened with \code{\link[purrr:list_rbind]{purrr::list_rbind()}}, and \code{NULL} values are converted to +empty data frames. } \description{ Flatten a data frame or list of data frames diff --git a/man/dot-flatten_params_df.Rd b/man/dot-flatten_params_df.Rd new file mode 100644 index 0000000..ba3583a --- /dev/null +++ b/man/dot-flatten_params_df.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.flatten_params_df} +\alias{.flatten_params_df} +\title{Flatten parameter metadata} +\usage{ +.flatten_params_df(params_df) +} +\arguments{ +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} +} +\value{ +(\code{data.frame}) Flattened parameter metadata. +} +\description{ +Flatten parameter metadata +} +\keyword{internal} diff --git a/man/dot-generate_pagination.Rd b/man/dot-generate_pagination.Rd new file mode 100644 index 0000000..5ec2cd6 --- /dev/null +++ b/man/dot-generate_pagination.Rd @@ -0,0 +1,15 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-pagination.R +\name{.generate_pagination} +\alias{.generate_pagination} +\title{Generate pagination files} +\usage{ +.generate_pagination() +} +\value{ +(\code{list}) Pagination metadata used while generating path files. +} +\description{ +Generate pagination files +} +\keyword{internal} diff --git a/man/dot-generate_paths.Rd b/man/dot-generate_paths.Rd new file mode 100644 index 0000000..eb528a1 --- /dev/null +++ b/man/dot-generate_paths.Rd @@ -0,0 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.generate_paths} +\alias{.generate_paths} +\title{Generate files for API paths} +\usage{ +.generate_paths( + paths, + api_abbr, + security_data, + pagination_data = list(), + base_url +) +} +\arguments{ +\item{paths}{(\code{rapid::class_paths}) API path definitions.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{security_data}{(\code{list}) Generated security metadata.} + +\item{pagination_data}{(\code{list}) Pagination metadata used while generating +path files.} + +\item{base_url}{(\code{character(1)}) The base URL used in generated test +helpers.} +} +\value{ +(\code{character}) Generated file paths. +} +\description{ +Generate files for API paths +} +\keyword{internal} diff --git a/man/dot-generate_paths_file.Rd b/man/dot-generate_paths_file.Rd new file mode 100644 index 0000000..d137dad --- /dev/null +++ b/man/dot-generate_paths_file.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.generate_paths_file} +\alias{.generate_paths_file} +\title{Generate one operation file} +\usage{ +.generate_paths_file(path_operation, operation_id, api_abbr, security_data) +} +\arguments{ +\item{path_operation}{(\code{list}) Template data for one operation.} + +\item{operation_id}{(\code{character(1)}) The operation identifier used in +generated file names.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +(\code{character(1)}) The generated file path. +} +\description{ +Generate one operation file +} +\keyword{internal} diff --git a/man/dot-generate_paths_files.Rd b/man/dot-generate_paths_files.Rd new file mode 100644 index 0000000..29e73d1 --- /dev/null +++ b/man/dot-generate_paths_files.Rd @@ -0,0 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.generate_paths_files} +\alias{.generate_paths_files} +\title{Generate files for all operations} +\usage{ +.generate_paths_files( + paths_by_operation, + api_abbr, + security_data, + pagination_data +) +} +\arguments{ +\item{paths_by_operation}{(\code{list}) Template-ready operations keyed by +operation identifier.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{security_data}{(\code{list}) Generated security metadata.} + +\item{pagination_data}{(\code{list}) Pagination metadata used while generating +path files.} +} +\value{ +(\code{character}) Generated file paths. +} +\description{ +Generate files for all operations +} +\keyword{internal} diff --git a/man/dot-generate_paths_test_file.Rd b/man/dot-generate_paths_test_file.Rd new file mode 100644 index 0000000..0efc832 --- /dev/null +++ b/man/dot-generate_paths_test_file.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.generate_paths_test_file} +\alias{.generate_paths_test_file} +\title{Generate one tag-level test file} +\usage{ +.generate_paths_test_file(tag_operations, tag_name, api_abbr) +} +\arguments{ +\item{tag_operations}{(\code{list}) Operations grouped under one tag.} + +\item{tag_name}{(\code{character(1)}) The tag name.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} +} +\value{ +(\code{character(1)}) The generated test file path. +} +\description{ +Generate one tag-level test file +} +\keyword{internal} diff --git a/man/dot-generate_pkg_impl.Rd b/man/dot-generate_pkg_impl.Rd new file mode 100644 index 0000000..90bae1b --- /dev/null +++ b/man/dot-generate_pkg_impl.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg.R +\name{.generate_pkg_impl} +\alias{.generate_pkg_impl} +\title{Generate package files from prepared inputs} +\usage{ +.generate_pkg_impl(config, api_definition, security_data) +} +\arguments{ +\item{config}{(\code{list}) Package-generation configuration data.} + +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +(\code{character}, invisibly) Generated file paths. +} +\description{ +Generate package files from prepared inputs +} +\keyword{internal} diff --git a/man/dot-generate_prepare.Rd b/man/dot-generate_prepare.Rd new file mode 100644 index 0000000..6270c9f --- /dev/null +++ b/man/dot-generate_prepare.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-prepare.R +\name{.generate_prepare} +\alias{.generate_prepare} +\title{Generate prepare files} +\usage{ +.generate_prepare(config, api_definition, security_data) +} +\arguments{ +\item{config}{(\code{list}) Package-generation configuration data.} + +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +(\code{character}) Generated file paths. +} +\description{ +Generate prepare files +} +\keyword{internal} diff --git a/man/dot-generate_prepare_r.Rd b/man/dot-generate_prepare_r.Rd new file mode 100644 index 0000000..7ab4510 --- /dev/null +++ b/man/dot-generate_prepare_r.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-prepare.R +\name{.generate_prepare_r} +\alias{.generate_prepare_r} +\title{Generate the prepare helper} +\usage{ +.generate_prepare_r(config, api_definition, security_data) +} +\arguments{ +\item{config}{(\code{list}) Package-generation configuration data.} + +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +(\code{character(1)}) The generated file path. +} +\description{ +Generate the prepare helper +} +\keyword{internal} diff --git a/man/dot-generate_prepare_test.Rd b/man/dot-generate_prepare_test.Rd new file mode 100644 index 0000000..55ba72f --- /dev/null +++ b/man/dot-generate_prepare_test.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-prepare.R +\name{.generate_prepare_test} +\alias{.generate_prepare_test} +\title{Generate prepare tests} +\usage{ +.generate_prepare_test(api_abbr) +} +\arguments{ +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} +} +\value{ +(\code{character(1)}) The generated test file path. +} +\description{ +Generate prepare tests +} +\keyword{internal} diff --git a/man/dot-generate_security.Rd b/man/dot-generate_security.Rd new file mode 100644 index 0000000..13480f5 --- /dev/null +++ b/man/dot-generate_security.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.generate_security} +\alias{.generate_security} +\title{Generate security files and metadata} +\usage{ +.generate_security(api_abbr, security_schemes) +} +\arguments{ +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{security_schemes}{(\code{rapid::class_security_schemes}) Security schemes +from the API definition.} +} +\value{ +(\code{list}) Generated security metadata. +} +\description{ +Generate security files and metadata +} +\keyword{internal} diff --git a/man/dot-generate_security_arg_help.Rd b/man/dot-generate_security_arg_help.Rd new file mode 100644 index 0000000..a9e3026 --- /dev/null +++ b/man/dot-generate_security_arg_help.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.generate_security_arg_help} +\alias{.generate_security_arg_help} +\title{Build security argument help entries} +\usage{ +.generate_security_arg_help(security_scheme_collection, security_args) +} +\arguments{ +\item{security_scheme_collection}{(\code{list}) Collected security scheme +metadata.} + +\item{security_args}{(\code{character}) Security argument names to remove from +operation parameters (because they are defined once, separately).} +} +\value{ +(\code{list}) Template-ready parameter help entries. +} +\description{ +Build security argument help entries +} +\keyword{internal} diff --git a/man/dot-generate_security_signature.Rd b/man/dot-generate_security_signature.Rd new file mode 100644 index 0000000..ec9fa1e --- /dev/null +++ b/man/dot-generate_security_signature.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.generate_security_signature} +\alias{.generate_security_signature} +\title{Generate a security argument signature} +\usage{ +.generate_security_signature(security_arg_names, api_abbr) +} +\arguments{ +\item{security_arg_names}{(\code{character}) Security argument names to exclude +from generated operation signatures (because they are defined once, +separately).} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} +} +\value{ +(\code{character(1)}) A function-signature fragment. +} +\description{ +Generate a security argument signature +} +\keyword{internal} diff --git a/man/dot-generate_shared_params.Rd b/man/dot-generate_shared_params.Rd new file mode 100644 index 0000000..27e35c7 --- /dev/null +++ b/man/dot-generate_shared_params.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-shared.R +\name{.generate_shared_params} +\alias{.generate_shared_params} +\title{Generate shared parameter docs} +\usage{ +.generate_shared_params(security_data) +} +\arguments{ +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +(\code{character(1)}) The generated file path. +} +\description{ +Generate shared parameter docs +} +\keyword{internal} diff --git a/man/dot-glue_pipe_brace.Rd b/man/dot-glue_pipe_brace.Rd new file mode 100644 index 0000000..de2a99a --- /dev/null +++ b/man/dot-glue_pipe_brace.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.glue_pipe_brace} +\alias{.glue_pipe_brace} +\title{Interpolate glue with pipe braces} +\usage{ +.glue_pipe_brace(..., .envir = rlang::caller_env()) +} +\arguments{ +\item{...}{Expressions passed to \code{\link[glue:glue]{glue::glue()}}.} + +\item{.envir}{(\code{environment}) The environment in which to evaluate \code{...}.} +} +\value{ +(\code{glue}) A glue object. +} +\description{ +Interpolate glue with pipe braces +} +\keyword{internal} diff --git a/man/dot-is_pkg.Rd b/man/dot-is_pkg.Rd index c9eaccc..ccd6dce 100644 --- a/man/dot-is_pkg.Rd +++ b/man/dot-is_pkg.Rd @@ -4,13 +4,14 @@ \alias{.is_pkg} \title{Check whether we're in a package} \usage{ -.is_pkg(base_path = usethis::proj_get()) +.is_pkg(pkg_dir = usethis::proj_get()) } \arguments{ -\item{base_path}{The root URL of the current project.} +\item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package +files.} } \value{ -\code{TRUE} if the project is a package, \code{FALSE} if not. +(\code{logical(1)}) \code{TRUE} if the project is a package, \code{FALSE} if not. } \description{ Inspired by usethis:::is_package. diff --git a/man/dot-param_schema_to_r.Rd b/man/dot-param_schema_to_r.Rd new file mode 100644 index 0000000..c76b4ec --- /dev/null +++ b/man/dot-param_schema_to_r.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.param_schema_to_r} +\alias{.param_schema_to_r} +\title{Map parameter schemas to \code{stbl} helpers} +\usage{ +.param_schema_to_r(params_schema) +} +\arguments{ +\item{params_schema}{(\code{data.frame}) Schema metadata for operation parameters.} +} +\value{ +(\code{character}) Coercion helper names. +} +\description{ +Map parameter schemas to \code{stbl} helpers +} +\keyword{internal} diff --git a/man/dot-params_to_args.Rd b/man/dot-params_to_args.Rd new file mode 100644 index 0000000..b27777c --- /dev/null +++ b/man/dot-params_to_args.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.params_to_args} +\alias{.params_to_args} +\title{Convert parameters to a signature string} +\usage{ +.params_to_args(params) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} +} +\value{ +(\code{character(1)}) A comma-separated parameter string. +} +\description{ +Convert parameters to a signature string +} +\keyword{internal} diff --git a/man/dot-params_to_list.Rd b/man/dot-params_to_list.Rd new file mode 100644 index 0000000..26d8e6e --- /dev/null +++ b/man/dot-params_to_list.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.params_to_list} +\alias{.params_to_list} +\title{Convert parameter rows to a list} +\usage{ +.params_to_list(params_df) +} +\arguments{ +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} +} +\value{ +(\code{list}) Parameter metadata entries. +} +\description{ +Convert parameter rows to a list +} +\keyword{internal} diff --git a/man/dot-params_to_named_args.Rd b/man/dot-params_to_named_args.Rd new file mode 100644 index 0000000..bf0003b --- /dev/null +++ b/man/dot-params_to_named_args.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.params_to_named_args} +\alias{.params_to_named_args} +\title{Convert parameters to named arguments} +\usage{ +.params_to_named_args(params) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} +} +\value{ +(\code{character(1)}) A comma-separated named-argument string. +} +\description{ +Convert parameters to named arguments +} +\keyword{internal} diff --git a/man/dot-params_to_validations.Rd b/man/dot-params_to_validations.Rd new file mode 100644 index 0000000..11a951e --- /dev/null +++ b/man/dot-params_to_validations.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.params_to_validations} +\alias{.params_to_validations} +\title{Convert parameters to validation metadata} +\usage{ +.params_to_validations(params) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} +} +\value{ +(\code{list}) Validation metadata. +} +\description{ +Convert parameters to validation metadata +} +\keyword{internal} diff --git a/man/dot-paste0_if.Rd b/man/dot-paste0_if.Rd new file mode 100644 index 0000000..cd0f731 --- /dev/null +++ b/man/dot-paste0_if.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.paste0_if} +\alias{.paste0_if} +\title{Append text conditionally} +\usage{ +.paste0_if(original, test, addition) +} +\arguments{ +\item{original}{(\code{character}) The original text.} + +\item{test}{(\code{logical}) A condition for each element of \code{original}.} + +\item{addition}{(\code{character}) Text to append when \code{test} is \code{TRUE}.} +} +\value{ +(\code{character}) The updated text. +} +\description{ +Append text conditionally +} +\keyword{internal} diff --git a/man/dot-path_as_arg.Rd b/man/dot-path_as_arg.Rd new file mode 100644 index 0000000..cd46314 --- /dev/null +++ b/man/dot-path_as_arg.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.path_as_arg} +\alias{.path_as_arg} +\title{Convert a path to a request argument} +\usage{ +.path_as_arg(path, params_df) +} +\arguments{ +\item{path}{(\code{character(1)}) The path template.} + +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} +} +\value{ +(\code{character(1)}) Code for the request path argument. +} +\description{ +Convert a path to a request argument +} +\keyword{internal} diff --git a/man/dot-path_row_to_list.Rd b/man/dot-path_row_to_list.Rd new file mode 100644 index 0000000..67cb21b --- /dev/null +++ b/man/dot-path_row_to_list.Rd @@ -0,0 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.path_row_to_list} +\alias{.path_row_to_list} +\title{Convert one operation row to template data} +\usage{ +.path_row_to_list( + operation_id, + endpoint, + operation, + operation_summary, + operation_description, + tags, + parameters, + ... +) +} +\arguments{ +\item{operation_id}{(\code{character(1)}) The operation identifier used in +generated file names.} + +\item{endpoint}{(\code{character(1)}) The operation endpoint.} + +\item{operation}{(\code{character(1)}) The HTTP method.} + +\item{operation_summary}{(\code{character(1)}) The operation summary.} + +\item{operation_description}{(\code{character(1)}) The operation description.} + +\item{tags}{(\code{character} or \code{list}) Tags for all operations.} + +\item{parameters}{(\code{data.frame}) Operation parameters.} + +\item{...}{Additional columns, ignored.} +} +\value{ +(\code{list}) One operation description. +} +\description{ +Convert one operation row to template data +} +\keyword{internal} diff --git a/man/dot-paths_fill_descriptions.Rd b/man/dot-paths_fill_descriptions.Rd new file mode 100644 index 0000000..b064906 --- /dev/null +++ b/man/dot-paths_fill_descriptions.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_fill_descriptions} +\alias{.paths_fill_descriptions} +\title{Fill missing operation descriptions} +\usage{ +.paths_fill_descriptions(operation_descriptions, operation_summaries) +} +\arguments{ +\item{operation_descriptions}{(\code{character}) Operation descriptions from the +API definition.} + +\item{operation_summaries}{(\code{character}) Operation summaries from the API +definition.} +} +\value{ +(\code{character}) Operation descriptions. +} +\description{ +Fill missing operation descriptions +} +\keyword{internal} diff --git a/man/dot-paths_fill_operation_id.Rd b/man/dot-paths_fill_operation_id.Rd new file mode 100644 index 0000000..8865fc6 --- /dev/null +++ b/man/dot-paths_fill_operation_id.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_fill_operation_id} +\alias{.paths_fill_operation_id} +\title{Fill missing operation identifiers} +\usage{ +.paths_fill_operation_id(operation_ids, endpoints, methods) +} +\arguments{ +\item{operation_ids}{(\code{character}) Operation identifiers from the API +definition.} + +\item{endpoints}{(\code{character}) Endpoint paths paired with operations.} + +\item{methods}{(\code{character}) HTTP methods paired with endpoints.} +} +\value{ +(\code{character}) Operation identifiers. +} +\description{ +Fill missing operation identifiers +} +\keyword{internal} diff --git a/man/dot-paths_fill_summary.Rd b/man/dot-paths_fill_summary.Rd new file mode 100644 index 0000000..aaf38f3 --- /dev/null +++ b/man/dot-paths_fill_summary.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_fill_summary} +\alias{.paths_fill_summary} +\title{Fill missing operation summaries} +\usage{ +.paths_fill_summary(operation_summaries, endpoints, methods) +} +\arguments{ +\item{operation_summaries}{(\code{character}) Operation summaries from the API +definition.} + +\item{endpoints}{(\code{character}) Endpoint paths paired with operations.} + +\item{methods}{(\code{character}) HTTP methods paired with endpoints.} +} +\value{ +(\code{character}) Human-readable operation summaries. +} +\description{ +Fill missing operation summaries +} +\keyword{internal} diff --git a/man/dot-paths_fill_tags.Rd b/man/dot-paths_fill_tags.Rd new file mode 100644 index 0000000..cb6a26f --- /dev/null +++ b/man/dot-paths_fill_tags.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_fill_tags} +\alias{.paths_fill_tags} +\title{Fill missing operation tags} +\usage{ +.paths_fill_tags(tags) +} +\arguments{ +\item{tags}{(\code{character} or \code{list}) Tags for all operations.} +} +\value{ +(\code{character}) Snake-case tag names. +} +\description{ +Fill missing operation tags +} +\keyword{internal} diff --git a/man/dot-paths_need_stbl.Rd b/man/dot-paths_need_stbl.Rd new file mode 100644 index 0000000..5d02c81 --- /dev/null +++ b/man/dot-paths_need_stbl.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_need_stbl} +\alias{.paths_need_stbl} +\title{Determine whether generated paths need \code{stbl}} +\usage{ +.paths_need_stbl(paths, security_arg_names = character()) +} +\arguments{ +\item{paths}{(\code{rapid::class_paths}) API path definitions.} + +\item{security_arg_names}{(\code{character}) Security argument names to exclude +from generated operation signatures (because they are defined once, +separately).} +} +\value{ +(\code{logical(1)}) \code{TRUE} if any path needs \code{stbl}. +} +\description{ +Determine whether generated paths need \code{stbl} +} +\keyword{internal} diff --git a/man/dot-paths_to_clean_df.Rd b/man/dot-paths_to_clean_df.Rd new file mode 100644 index 0000000..f03df01 --- /dev/null +++ b/man/dot-paths_to_clean_df.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_to_clean_df} +\alias{.paths_to_clean_df} +\title{Convert API paths to an operations data frame} +\usage{ +.paths_to_clean_df(paths) +} +\arguments{ +\item{paths}{(\code{rapid::class_paths}) API path definitions.} +} +\value{ +(\code{tibble}) A \code{\link[tibble:tibble]{tibble::tibble()}} with one row per non-deprecated +operation. +} +\description{ +Convert API paths to an operations data frame +} +\keyword{internal} diff --git a/man/dot-pkg_abort.Rd b/man/dot-pkg_abort.Rd index 47c00d4..4c9d03d 100644 --- a/man/dot-pkg_abort.Rd +++ b/man/dot-pkg_abort.Rd @@ -32,7 +32,7 @@ evaluate variables in error messages.} \code{\link[rlang:abort]{rlang::abort()}}.} } \value{ -Does not return. +(\code{NULL}) Does not return. } \description{ Signal a package-scoped error diff --git a/man/dot-pkg_inform.Rd b/man/dot-pkg_inform.Rd index 03836d8..ca339c9 100644 --- a/man/dot-pkg_inform.Rd +++ b/man/dot-pkg_inform.Rd @@ -32,7 +32,7 @@ evaluate variables in error messages.} \code{\link[rlang:abort]{rlang::inform()}}.} } \value{ -\code{NULL}, invisibly (called for message side effect). +(\code{NULL}, invisibly) Called for message side effect. } \description{ Signal a package-scoped message diff --git a/man/dot-pkg_warn.Rd b/man/dot-pkg_warn.Rd index 3e7a38d..6bc36ca 100644 --- a/man/dot-pkg_warn.Rd +++ b/man/dot-pkg_warn.Rd @@ -32,7 +32,7 @@ evaluate variables in error messages.} \code{\link[rlang:abort]{rlang::warn()}}.} } \value{ -\code{NULL}, invisibly (called for warning side effect). +(\code{NULL}, invisibly) Called for warning side effect. } \description{ Signal a package-scoped warning diff --git a/man/dot-prep_param_args.Rd b/man/dot-prep_param_args.Rd new file mode 100644 index 0000000..37a5660 --- /dev/null +++ b/man/dot-prep_param_args.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.prep_param_args} +\alias{.prep_param_args} +\title{Prepare parameter arguments} +\usage{ +.prep_param_args(params, security_args) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} + +\item{security_args}{(\code{character}) Security argument names to remove from +operation parameters (because they are defined once, separately).} +} +\value{ +(\code{character(1)}) A comma-separated named-argument string. +} +\description{ +Prepare parameter arguments +} +\keyword{internal} diff --git a/man/dot-prepare_params_df.Rd b/man/dot-prepare_params_df.Rd new file mode 100644 index 0000000..2d6923b --- /dev/null +++ b/man/dot-prepare_params_df.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.prepare_params_df} +\alias{.prepare_params_df} +\title{Prepare parameter metadata} +\usage{ +.prepare_params_df(params_df) +} +\arguments{ +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} +} +\value{ +(\code{data.frame}) Prepared parameter metadata. +} +\description{ +Prepare parameter metadata +} +\keyword{internal} diff --git a/man/dot-remove_security_args.Rd b/man/dot-remove_security_args.Rd new file mode 100644 index 0000000..232147f --- /dev/null +++ b/man/dot-remove_security_args.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.remove_security_args} +\alias{.remove_security_args} +\title{Remove security parameters} +\usage{ +.remove_security_args(params, security_args) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} + +\item{security_args}{(\code{character}) Security argument names to remove from +operation parameters (because they are defined once, separately).} +} +\value{ +(\code{list}) Non-security parameters. +} +\description{ +Remove security parameters +} +\keyword{internal} diff --git a/man/dot-security_arg_description_clean.Rd b/man/dot-security_arg_description_clean.Rd new file mode 100644 index 0000000..4eb9200 --- /dev/null +++ b/man/dot-security_arg_description_clean.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_arg_description_clean} +\alias{.security_arg_description_clean} +\title{Format one security argument help entry} +\usage{ +.security_arg_description_clean(security_arg_description, security_arg_name) +} +\arguments{ +\item{security_arg_description}{(\code{character(1)}) The argument description.} + +\item{security_arg_name}{(\code{character(1)}) The argument name.} +} +\value{ +(\code{list}) A named list with \code{name} and \code{description}. +} +\description{ +Format one security argument help entry +} +\keyword{internal} diff --git a/man/dot-security_args_compile.Rd b/man/dot-security_args_compile.Rd new file mode 100644 index 0000000..db82de3 --- /dev/null +++ b/man/dot-security_args_compile.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_args_compile} +\alias{.security_args_compile} +\title{Compile security argument metadata} +\usage{ +.security_args_compile(security_scheme_collection) +} +\arguments{ +\item{security_scheme_collection}{(\code{list}) Collected security scheme +metadata.} +} +\value{ +(\code{list}) Compiled security argument values. +} +\description{ +Compile security argument metadata +} +\keyword{internal} diff --git a/man/dot-security_scheme_collection_finalize.Rd b/man/dot-security_scheme_collection_finalize.Rd new file mode 100644 index 0000000..11d3cad --- /dev/null +++ b/man/dot-security_scheme_collection_finalize.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_scheme_collection_finalize} +\alias{.security_scheme_collection_finalize} +\title{Finalize collected security scheme data} +\usage{ +.security_scheme_collection_finalize(security_scheme_collection) +} +\arguments{ +\item{security_scheme_collection}{(\code{list}) Collected security scheme +metadata.} +} +\value{ +(\code{list}) Finalized security metadata. +} +\description{ +Finalize collected security scheme data +} +\keyword{internal} diff --git a/man/dot-security_scheme_description_fill.Rd b/man/dot-security_scheme_description_fill.Rd new file mode 100644 index 0000000..f93e9c7 --- /dev/null +++ b/man/dot-security_scheme_description_fill.Rd @@ -0,0 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_scheme_description_fill} +\alias{.security_scheme_description_fill} +\title{Fill a missing security scheme description} +\usage{ +.security_scheme_description_fill( + security_scheme_description, + security_scheme_type +) +} +\arguments{ +\item{security_scheme_description}{(\code{character(1)}) A security scheme +description from the API definition.} + +\item{security_scheme_type}{(\code{character(1)}) The security scheme type.} +} +\value{ +(\code{character(1)}) A security scheme description. +} +\description{ +Fill a missing security scheme description +} +\keyword{internal} diff --git a/man/dot-security_scheme_rotate.Rd b/man/dot-security_scheme_rotate.Rd new file mode 100644 index 0000000..5a825dc --- /dev/null +++ b/man/dot-security_scheme_rotate.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_scheme_rotate} +\alias{.security_scheme_rotate} +\title{Convert one security scheme to a list} +\usage{ +.security_scheme_rotate( + security_scheme_name, + security_scheme_details, + security_scheme_description +) +} +\arguments{ +\item{security_scheme_name}{(\code{character(1)}) The security scheme name.} + +\item{security_scheme_details}{(\code{rapid::class_security_scheme_details}) The +security scheme details.} + +\item{security_scheme_description}{(\code{character(1)}) A security scheme +description from the API definition.} +} +\value{ +(\code{list}) One security scheme description. +} +\description{ +Convert one security scheme to a list +} +\keyword{internal} diff --git a/man/dot-security_schemes_collect.Rd b/man/dot-security_schemes_collect.Rd new file mode 100644 index 0000000..7118e38 --- /dev/null +++ b/man/dot-security_schemes_collect.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_schemes_collect} +\alias{.security_schemes_collect} +\title{Collect security scheme metadata} +\usage{ +.security_schemes_collect(security_schemes) +} +\arguments{ +\item{security_schemes}{(\code{rapid::class_security_schemes}) Security schemes +from the API definition.} +} +\value{ +(\code{list}) Security scheme metadata. +} +\description{ +Collect security scheme metadata +} +\keyword{internal} diff --git a/man/dot-setup_r.Rd b/man/dot-setup_r.Rd new file mode 100644 index 0000000..2aba67e --- /dev/null +++ b/man/dot-setup_r.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-setup.R +\name{.setup_r} +\alias{.setup_r} +\title{Set up package directories and dependencies} +\usage{ +.setup_r(pkg_dir, include_stbl = FALSE) +} +\arguments{ +\item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package +files.} + +\item{include_stbl}{(\code{logical(1)}) Whether to add \code{stbl} to Imports.} +} +\value{ +(\code{NULL}, invisibly) Called for setup side effects. +} +\description{ +Set up package directories and dependencies +} +\keyword{internal} diff --git a/man/dot-shared-params.Rd b/man/dot-shared-params.Rd index ac04ee7..3193049 100644 --- a/man/dot-shared-params.Rd +++ b/man/dot-shared-params.Rd @@ -4,6 +4,11 @@ \alias{.shared-params} \title{Shared parameters} \arguments{ +\item{addition}{(\code{character}) Text to append when \code{test} is \code{TRUE}.} + +\item{allow_empty}{(\code{logical}) Whether empty parameter values may be +represented as \code{NULL}.} + \item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for the API, for use in function names and environment variables.} @@ -13,18 +18,129 @@ package code from.} \item{api_title}{(\code{character(1)}) The API title used in generated package files.} +\item{base_path}{The root URL of the current project.} + +\item{base_url}{(\code{character(1)}) The base URL used in generated test +helpers.} + \item{call}{(\code{environment}) The caller environment for error messages.} +\item{config}{(\code{list}) Package-generation configuration data.} + \item{config_file}{(\code{character(1)} or \code{fs_path}) The path to a beekeeper yaml config file.} +\item{data}{(\code{list}) Data passed to a template.} + +\item{dir}{(\code{character(1)}) The directory where a generated file should be +written.} + +\item{endpoint}{(\code{character(1)}) The operation endpoint.} + +\item{endpoints}{(\code{character}) Endpoint paths paired with operations.} + +\item{filter_in}{(\code{character(1)}) The parameter location to keep.} + +\item{include_stbl}{(\code{logical(1)}) Whether to add \code{stbl} to Imports.} + +\item{methods}{(\code{character}) HTTP methods paired with endpoints.} + +\item{operation}{(\code{character(1)}) The HTTP method.} + +\item{operation_description}{(\code{character(1)}) The operation description.} + +\item{operation_descriptions}{(\code{character}) Operation descriptions from the +API definition.} + +\item{operation_id}{(\code{character(1)}) The operation identifier used in +generated file names.} + +\item{operation_ids}{(\code{character}) Operation identifiers from the API +definition.} + +\item{operation_summaries}{(\code{character}) Operation summaries from the API +definition.} + +\item{operation_summary}{(\code{character(1)}) The operation summary.} + +\item{original}{(\code{character}) The original text.} + +\item{pagination_data}{(\code{list}) Pagination metadata used while generating +path files.} + +\item{parameters}{(\code{data.frame}) Operation parameters.} + +\item{params}{(\code{list}) Parameter metadata for a single operation.} + +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} + +\item{params_schema}{(\code{data.frame}) Schema metadata for operation parameters.} + +\item{path}{(\code{character(1)}) The path template.} + +\item{path_operation}{(\code{list}) Template data for one operation.} + +\item{paths}{(\code{rapid::class_paths}) API path definitions.} + +\item{paths_by_operation}{(\code{list}) Template-ready operations keyed by +operation identifier.} + \item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package files.} \item{rapid_file}{(\code{character(1)} or \code{fs_path}) The path to the R API definition (rapid) file.} +\item{required}{(\code{logical}) Whether each parameter is required.} + +\item{security_arg_description}{(\code{character(1)}) The argument description.} + +\item{security_arg_name}{(\code{character(1)}) The argument name.} + +\item{security_arg_names}{(\code{character}) Security argument names to exclude +from generated operation signatures (because they are defined once, +separately).} + +\item{security_args}{(\code{character}) Security argument names to remove from +operation parameters (because they are defined once, separately).} + +\item{security_data}{(\code{list}) Generated security metadata.} + +\item{security_scheme_collection}{(\code{list}) Collected security scheme +metadata.} + +\item{security_scheme_description}{(\code{character(1)}) A security scheme +description from the API definition.} + +\item{security_scheme_details}{(\code{rapid::class_security_scheme_details}) The +security scheme details.} + +\item{security_scheme_name}{(\code{character(1)}) The security scheme name.} + +\item{security_scheme_type}{(\code{character(1)}) The security scheme type.} + +\item{security_schemes}{(\code{rapid::class_security_schemes}) Security schemes +from the API definition.} + +\item{tag_operations}{(\code{list}) Operations grouped under one tag.} + +\item{tag_name}{(\code{character(1)}) The tag name.} + +\item{tags}{(\code{character} or \code{list}) Tags for all operations.} + +\item{target}{(\code{character(1)}) The name of the generated file.} + +\item{template}{(\code{character(1)}) The template file name to render.} + +\item{test}{(\code{logical}) A condition for each element of \code{original}.} + \item{to_collapse}{(\code{character}) The character vector to collapse.} + +\item{type}{(\code{data.frame}) Joined parameter type metadata.} + +\item{x}{(\code{any}) The object to check or coerce.} + +\item{y}{(\code{any}) The default value.} } \description{ These parameters are used in multiple functions. They are defined here to diff --git a/man/dot-stabilize_config.Rd b/man/dot-stabilize_config.Rd new file mode 100644 index 0000000..80b0b48 --- /dev/null +++ b/man/dot-stabilize_config.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_config.R +\name{.stabilize_config} +\alias{.stabilize_config} +\title{Stabilize beekeeper config values} +\usage{ +.stabilize_config(config) +} +\arguments{ +\item{config}{(\code{list}) Package-generation configuration data.} +} +\value{ +(\code{list}) A stabilized config list. +} +\description{ +Stabilize beekeeper config values +} +\keyword{internal} diff --git a/man/dot-to_snake.Rd b/man/dot-to_snake.Rd new file mode 100644 index 0000000..b0b5f1c --- /dev/null +++ b/man/dot-to_snake.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.to_snake} +\alias{.to_snake} +\title{Convert text to snake case} +\usage{ +.to_snake(x) +} +\arguments{ +\item{x}{(\code{character}) Text to convert.} +} +\value{ +(\code{character}) Snake-case text. +} +\description{ +Convert text to snake case +} +\keyword{internal} diff --git a/man/dot-write_config.Rd b/man/dot-write_config.Rd new file mode 100644 index 0000000..cd3ec2a --- /dev/null +++ b/man/dot-write_config.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/use_beekeeper.R +\name{.write_config} +\alias{.write_config} +\title{Write the beekeeper config file} +\usage{ +.write_config(api_definition, api_abbr, rapid_file, config_file) +} +\arguments{ +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{rapid_file}{(\code{character(1)} or \code{fs_path}) The path to the R API +definition (rapid) file.} + +\item{config_file}{(\code{character(1)} or \code{fs_path}) The path to a beekeeper yaml +config file.} +} +\value{ +(\code{character(1)}) The written config file path. +} +\description{ +Write the beekeeper config file +} +\keyword{internal} diff --git a/man/dot-write_rapid.Rd b/man/dot-write_rapid.Rd new file mode 100644 index 0000000..45c7333 --- /dev/null +++ b/man/dot-write_rapid.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/use_beekeeper.R +\name{.write_rapid} +\alias{.write_rapid} +\title{Write the rapid definition file} +\usage{ +.write_rapid(api_definition, rapid_file) +} +\arguments{ +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{rapid_file}{(\code{character(1)} or \code{fs_path}) The path to the R API +definition (rapid) file.} +} +\value{ +(\code{character(1)}) The written file path. +} +\description{ +Write the rapid definition file +} +\keyword{internal} diff --git a/man/generate_pkg.Rd b/man/generate_pkg.Rd index 295bae5..6e5607c 100644 --- a/man/generate_pkg.Rd +++ b/man/generate_pkg.Rd @@ -29,8 +29,7 @@ config file.} files.} } \value{ -A character vector of paths to files that were added or updated, -invisibly. +(\code{character}, invisibly) Paths to files that were added or updated. } \description{ Creates or updates package files based on the information in a beekeeper diff --git a/man/op-lengthless-default.Rd b/man/op-lengthless-default.Rd index 8091178..7d386fc 100644 --- a/man/op-lengthless-default.Rd +++ b/man/op-lengthless-default.Rd @@ -8,12 +8,12 @@ x \%|0|\% y } \arguments{ -\item{x}{(\code{any}) Object to check.} +\item{x}{(\code{any}) The object to check or coerce.} -\item{y}{(\code{any}) Default value for \code{x}.} +\item{y}{(\code{any}) The default value.} } \value{ -If \code{!length(x)}, will return \code{x}; otherwise returns \code{y}. +(\code{any}) If \code{!length(x)}, returns \code{x}; otherwise returns \code{y}. } \description{ Default value for length 0 diff --git a/man/op-na-coalesce.Rd b/man/op-na-coalesce.Rd index f64e065..d37b2b3 100644 --- a/man/op-na-coalesce.Rd +++ b/man/op-na-coalesce.Rd @@ -8,14 +8,14 @@ x \%|\% y } \arguments{ -\item{x}{(\code{any}) A vector that may contain \code{NA} elements.} +\item{x}{(\code{any}) The object to check or coerce.} \item{y}{(\code{any}, coercible to the same class as \code{x}) A value or vector to replace \code{NA} elements in \code{x}. Will be recycled to the same length as \code{x}.} } \value{ -A vector of the same length as \code{x}, where each \code{NA} element in \code{x} -is replaced by the corresponding element in \code{y}. +(\code{vector}) A vector of the same length as \code{x}, where each \code{NA} +element in \code{x} is replaced by the corresponding element in \code{y}. } \description{ Default value for NA elements in vectors diff --git a/man/op-no-char-default.Rd b/man/op-no-char-default.Rd index 03f015e..b0416ec 100644 --- a/man/op-no-char-default.Rd +++ b/man/op-no-char-default.Rd @@ -8,12 +8,12 @@ x \%|a|\% y } \arguments{ -\item{x}{(\code{any}) Object to check.} +\item{x}{(\code{any}) The object to check or coerce.} -\item{y}{(\code{character}) Default value for \code{x}.} +\item{y}{(\code{character}) The default value.} } \value{ -If \code{!nzchar(x)}, will return \code{y}; otherwise returns \code{x}. +(\code{character}) If \code{!nzchar(x)}, returns \code{y}; otherwise returns \code{x}. } \description{ Default value for empty strings diff --git a/man/op-null-continuation.Rd b/man/op-null-continuation.Rd index 1b1e0f0..8dd6281 100644 --- a/man/op-null-continuation.Rd +++ b/man/op-null-continuation.Rd @@ -8,12 +8,12 @@ x \%&&\% y } \arguments{ -\item{x}{(\code{any}) Object to check.} +\item{x}{(\code{any}) The object to check or coerce.} -\item{y}{(\code{any}) Default value for non-\code{NULL} \code{x}.} +\item{y}{(\code{any}) The default value.} } \value{ -If \code{x} is \code{NULL}, will return \code{x}; otherwise returns \code{y}. +(\code{any}) If \code{x} is \code{NULL}, returns \code{x}; otherwise returns \code{y}. } \description{ Default value for non-\code{NULL} diff --git a/man/op-null-default.Rd b/man/op-null-default.Rd index fea2a8c..84b01c3 100644 --- a/man/op-null-default.Rd +++ b/man/op-null-default.Rd @@ -8,12 +8,12 @@ x \%||\% y } \arguments{ -\item{x}{(\code{any}) Object to check.} +\item{x}{(\code{any}) The object to check or coerce.} -\item{y}{(\code{any}) Default value for \code{x}.} +\item{y}{(\code{any}) The default value.} } \value{ -If \code{x} is \code{NULL}, will return \code{y}; otherwise returns \code{x}. +(\code{any}) If \code{x} is \code{NULL}, returns \code{y}; otherwise returns \code{x}. } \description{ Default value for \code{NULL} diff --git a/man/read_api_definition.Rd b/man/read_api_definition.Rd index aa4ddf0..a043f2c 100644 --- a/man/read_api_definition.Rd +++ b/man/read_api_definition.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/generate_pkg-setup.R +% Please edit documentation in R/read_config.R \name{read_api_definition} \alias{read_api_definition} \title{Read an API definition file} @@ -14,7 +14,7 @@ files.} definition (rapid) file.} } \value{ -A \code{\link[rapid:class_rapid]{rapid::class_rapid()}} with the definition of the API. +(\code{rapid::class_rapid}) The definition of the API. } \description{ Reads an RDS file (default name \verb{_beekeeper_rapid.rds}) with the API diff --git a/man/read_config.Rd b/man/read_config.Rd index 1360857..9dadade 100644 --- a/man/read_config.Rd +++ b/man/read_config.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/generate_pkg-setup.R +% Please edit documentation in R/read_config.R \name{read_config} \alias{read_config} \title{Read a beekeeper config file} @@ -14,7 +14,7 @@ files.} config file.} } \value{ -A \code{list} of configuration information, with elements \code{api_title}, +(\code{list}) Configuration information, with elements \code{api_title}, \code{api_abbr}, \code{api_version}, \code{rapid_file}, and \code{updated_on}. } \description{ diff --git a/man/use_beekeeper.Rd b/man/use_beekeeper.Rd index 57461e5..2a6b33c 100644 --- a/man/use_beekeeper.Rd +++ b/man/use_beekeeper.Rd @@ -30,9 +30,9 @@ config file.} definition (rapid) file.} } \value{ -The path to the configuration file, invisibly. The config file is -written as a side effect of this function. The rapid object is also -written, and the path to that file is saved in the config file. +(\code{character(1)}, invisibly) The path to the configuration file. The +config file is written as a side effect of this function. The rapid object +is also written, and the path to that file is saved in the config file. } \description{ Create a configuration file for a package to use beekeeper. The configuration diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R b/tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R index df57209..e53dea6 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R @@ -85,7 +85,7 @@ fec_get_audit_case <- function( } #' @rdname fec_get_audit_case -#' @returns `req_fec_get_audit_case()`: A `httr2_request` request object. +#' @returns `req_fec_get_audit_case()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_audit_case <- function( audit_case_id, cycle, diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R b/tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R index f2c048d..a13b46e 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R @@ -52,7 +52,7 @@ fec_get_audit_category <- function( } #' @rdname fec_get_audit_category -#' @returns `req_fec_get_audit_category()`: A `httr2_request` request object. +#' @returns `req_fec_get_audit_category()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_audit_category <- function( sort_nulls_last, page, diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_audit_primary_category.R b/tests/testthat/_fixtures/fec/paths-audit-get_audit_primary_category.R index 4641347..beba2e2 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_audit_primary_category.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_audit_primary_category.R @@ -52,7 +52,7 @@ fec_get_audit_primary_category <- function( } #' @rdname fec_get_audit_primary_category -#' @returns `req_fec_get_audit_primary_category()`: A `httr2_request` request object. +#' @returns `req_fec_get_audit_primary_category()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_audit_primary_category <- function( sort_nulls_last, page, diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_candidates.R b/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_candidates.R index 76727c7..402df75 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_candidates.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_candidates.R @@ -23,7 +23,7 @@ fec_get_names_audit_candidates <- function(q, api_key = Sys.getenv("FEC_API_KEY" } #' @rdname fec_get_names_audit_candidates -#' @returns `req_fec_get_names_audit_candidates()`: A `httr2_request` request object. +#' @returns `req_fec_get_names_audit_candidates()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_names_audit_candidates <- function(q, api_key = Sys.getenv("FEC_API_KEY")) { fec_req_prepare( path = "/names/audit_candidates/", diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_committees.R b/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_committees.R index 9e6d5a5..43ee3cd 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_committees.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_committees.R @@ -29,7 +29,7 @@ fec_get_names_audit_committees <- function( } #' @rdname fec_get_names_audit_committees -#' @returns `req_fec_get_names_audit_committees()`: A `httr2_request` request object. +#' @returns `req_fec_get_names_audit_committees()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_names_audit_committees <- function( q, api_key = Sys.getenv("FEC_API_KEY") diff --git a/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d.R b/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d.R index 9e61f1b..80850c7 100644 --- a/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d.R +++ b/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d.R @@ -97,7 +97,7 @@ fec_get_schedules_schedule_d <- function( } #' @rdname fec_get_schedules_schedule_d -#' @returns `req_fec_get_schedules_schedule_d()`: A `httr2_request` request object. +#' @returns `req_fec_get_schedules_schedule_d()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_schedules_schedule_d <- function( creditor_debtor_name, max_image_number, diff --git a/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R b/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R index 0a2a9bf..6b78bef 100644 --- a/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R +++ b/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R @@ -49,7 +49,7 @@ fec_get_schedules_schedule_d_sub_id <- function( } #' @rdname fec_get_schedules_schedule_d_sub_id -#' @returns `req_fec_get_schedules_schedule_d_sub_id()`: A `httr2_request` request object. +#' @returns `req_fec_get_schedules_schedule_d_sub_id()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_schedules_schedule_d_sub_id <- function( sort_nulls_last, per_page, diff --git a/tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R b/tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R index e622c7f..1ebc4ac 100644 --- a/tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R +++ b/tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R @@ -154,7 +154,7 @@ fec_get_legal_search <- function( } #' @rdname fec_get_legal_search -#' @returns `req_fec_get_legal_search()`: A `httr2_request` request object. +#' @returns `req_fec_get_legal_search()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_legal_search <- function( hits_returned, af_report_year, diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_api.R b/tests/testthat/_fixtures/guru/paths-apis-get_api.R index 9139aaa..940925a 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_api.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_api.R @@ -23,7 +23,7 @@ guru_get_api <- function(provider, api, max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_api -#' @returns `req_guru_get_api()`: A `httr2_request` request object. +#' @returns `req_guru_get_api()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_api <- function(provider, api) { provider <- stbl::to_chr_scalar(provider) api <- stbl::to_chr_scalar(api) diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_metrics.R b/tests/testthat/_fixtures/guru/paths-apis-get_metrics.R index 04d2e6b..b4868f1 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_metrics.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_metrics.R @@ -21,7 +21,7 @@ guru_get_metrics <- function(max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_metrics -#' @returns `req_guru_get_metrics()`: A `httr2_request` request object. +#' @returns `req_guru_get_metrics()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_metrics <- function() { guru_req_prepare( path = "/metrics.json", diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_provider.R b/tests/testthat/_fixtures/guru/paths-apis-get_provider.R index 8efb4d5..078304a 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_provider.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_provider.R @@ -22,7 +22,7 @@ guru_get_provider <- function(provider, max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_provider -#' @returns `req_guru_get_provider()`: A `httr2_request` request object. +#' @returns `req_guru_get_provider()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_provider <- function(provider) { provider <- stbl::to_chr_scalar(provider) guru_req_prepare( diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_providers.R b/tests/testthat/_fixtures/guru/paths-apis-get_providers.R index ca20227..823d972 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_providers.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_providers.R @@ -21,7 +21,7 @@ guru_get_providers <- function(max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_providers -#' @returns `req_guru_get_providers()`: A `httr2_request` request object. +#' @returns `req_guru_get_providers()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_providers <- function() { guru_req_prepare( path = "/providers.json", diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_service_api.R b/tests/testthat/_fixtures/guru/paths-apis-get_service_api.R index 99a0df0..1343762 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_service_api.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_service_api.R @@ -24,7 +24,7 @@ guru_get_service_api <- function(provider, service, api, max_reqs = Inf, max_tri } #' @rdname guru_get_service_api -#' @returns `req_guru_get_service_api()`: A `httr2_request` request object. +#' @returns `req_guru_get_service_api()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_service_api <- function(provider, service, api) { provider <- stbl::to_chr_scalar(provider) service <- stbl::to_chr_scalar(service) diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_services.R b/tests/testthat/_fixtures/guru/paths-apis-get_services.R index 92f3245..45e8f43 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_services.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_services.R @@ -22,7 +22,7 @@ guru_get_services <- function(provider, max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_services -#' @returns `req_guru_get_services()`: A `httr2_request` request object. +#' @returns `req_guru_get_services()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_services <- function(provider) { provider <- stbl::to_chr_scalar(provider) guru_req_prepare( diff --git a/tests/testthat/_fixtures/guru/paths-apis-list_apis.R b/tests/testthat/_fixtures/guru/paths-apis-list_apis.R index d8a7e16..df70e2c 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-list_apis.R +++ b/tests/testthat/_fixtures/guru/paths-apis-list_apis.R @@ -21,7 +21,7 @@ guru_list_apis <- function(max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_list_apis -#' @returns `req_guru_list_apis()`: A `httr2_request` request object. +#' @returns `req_guru_list_apis()`: (`httr2_request`) A [httr2::request()] object. req_guru_list_apis <- function() { guru_req_prepare( path = "/list.json", diff --git a/tests/testthat/_fixtures/header_cookie/paths-things-search_things.R b/tests/testthat/_fixtures/header_cookie/paths-things-search_things.R index b8c3980..2140308 100644 --- a/tests/testthat/_fixtures/header_cookie/paths-things-search_things.R +++ b/tests/testthat/_fixtures/header_cookie/paths-things-search_things.R @@ -24,7 +24,7 @@ test_search_things <- function(x_auth_token, session_id, q, max_reqs = Inf, max_ } #' @rdname test_search_things -#' @returns `req_test_search_things()`: A `httr2_request` request object. +#' @returns `req_test_search_things()`: (`httr2_request`) A [httr2::request()] object. req_test_search_things <- function(x_auth_token, session_id, q) { x_auth_token <- stbl::to_chr_scalar(x_auth_token) session_id <- stbl::to_chr_scalar(session_id) diff --git a/tests/testthat/_fixtures/trello/paths-board-add_boards.R b/tests/testthat/_fixtures/trello/paths-board-add_boards.R index 26663e9..97e0c70 100644 --- a/tests/testthat/_fixtures/trello/paths-board-add_boards.R +++ b/tests/testthat/_fixtures/trello/paths-board-add_boards.R @@ -24,7 +24,7 @@ token = Sys.getenv("TRELLO_TOKEN"), max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname trello_add_boards -#' @returns `req_trello_add_boards()`: A `httr2_request` request object. +#' @returns `req_trello_add_boards()`: (`httr2_request`) A [httr2::request()] object. req_trello_add_boards <- function(key = Sys.getenv("TRELLO_KEY"), token = Sys.getenv("TRELLO_TOKEN")) { trello_req_prepare( diff --git a/tests/testthat/_snaps/generate_pkg-setup.md b/tests/testthat/_snaps/generate_pkg-setup.md index d0318ea..dd14438 100644 --- a/tests/testthat/_snaps/generate_pkg-setup.md +++ b/tests/testthat/_snaps/generate_pkg-setup.md @@ -7,24 +7,3 @@ ! Can't generate package files outside of a package. TMPDIR is not inside a package. -# read_config() reads configs - - Code - config - Output - $api_title - [1] "APIs.guru" - - $api_abbr - [1] "guru" - - $api_version - [1] "2.2.0" - - $rapid_file - [1] "_beekeeper_rapid.rds" - - $updated_on - [1] "2026-05-12 07:57:02 UTC" - - diff --git a/tests/testthat/_snaps/read_config.md b/tests/testthat/_snaps/read_config.md new file mode 100644 index 0000000..0a9e06d --- /dev/null +++ b/tests/testthat/_snaps/read_config.md @@ -0,0 +1,21 @@ +# read_config() reads configs + + Code + config + Output + $api_title + [1] "APIs.guru" + + $api_abbr + [1] "guru" + + $api_version + [1] "2.2.0" + + $rapid_file + [1] "_beekeeper_rapid.rds" + + $updated_on + [1] "2026-05-12 07:57:02 UTC" + + diff --git a/tests/testthat/test-generate_pkg-setup.R b/tests/testthat/test-generate_pkg-setup.R index 07c570a..cdd213a 100644 --- a/tests/testthat/test-generate_pkg-setup.R +++ b/tests/testthat/test-generate_pkg-setup.R @@ -13,21 +13,6 @@ test_that(".assert_is_pkg() isn't obtrusive for packages", { }) }) -test_that("read_config() reads configs", { - config <- read_config(pkg_dir = test_path("_fixtures", "guru")) - expect_s3_class(config$updated_on, c("POSIXlt", "POSIXt")) - expect_snapshot({ - config - }) -}) - -test_that("read_api_definition() reads api_definitions", { - api_definition <- read_api_definition( - pkg_dir = test_path("_fixtures", "guru") - ) - expect_s7_class(api_definition, rapid::class_rapid) -}) - test_that(".setup_r() sets up dependencies (#16)", { skip_on_cran() diff --git a/tests/testthat/test-read_config.R b/tests/testthat/test-read_config.R new file mode 100644 index 0000000..7a5a738 --- /dev/null +++ b/tests/testthat/test-read_config.R @@ -0,0 +1,14 @@ +test_that("read_config() reads configs", { + config <- read_config(pkg_dir = test_path("_fixtures", "guru")) + expect_s3_class(config$updated_on, c("POSIXlt", "POSIXt")) + expect_snapshot({ + config + }) +}) + +test_that("read_api_definition() reads api_definitions", { + api_definition <- read_api_definition( + pkg_dir = test_path("_fixtures", "guru") + ) + expect_s7_class(api_definition, rapid::class_rapid) +})