Package 'beekeeper'

Use a beekeeper config file to generate code

Description

Creates or updates package files based on the information in a beekeeper config file (generated by use_beekeeper() or manually). The files enforce an opinionated framework for API packages.

Usage

generate_pkg(
  api_abbr = read_api_abbr(pkg_dir, config_filename),
  api_definition = read_api_definition(pkg_dir, read_rapid_filename(pkg_dir,
    config_filename)),
  api_title = read_api_title(pkg_dir, config_filename),
  config_filename = "_beekeeper.yml",
  pkg_dir = "."
)

Arguments

api_abbr	(character(1)) A short (about 2-5 letter) abbreviation for the API, for use in function names and environment variables.
api_definition	(rapid::class_rapid) The API definition to generate package code from.
api_title	(character(1)) The API title used in generated package files.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).
pkg_dir	(character(1) or fs_path) The directory containing package files.

Value

(character, invisibly) Paths to files that were added or updated.

See Also

Other package generation functions: generate_pkg_auth(), generate_pkg_paths(), generate_pkg_req_prepare(), generate_pkg_shared_params()

Examples

# Set up an empty package.
pkg_dir <- unclass(fs::path_norm(withr::local_tempdir()))
usethis::create_package(pkg_dir, open = FALSE, check_name = FALSE)
bk_files <- c("_beekeeper.yml", "_beekeeper_rapid.rds")
fs::file_copy(
  fs::path_package("beekeeper", "guru", bk_files),
  fs::path(pkg_dir, bk_files)
)
usethis::local_project(pkg_dir)

# Generate a package.
generate_pkg()
fs::dir_ls("R")
fs::dir_ls("tests/testthat")

# Clean up.
withr::deferred_run()

---

Generate authentication helpers

Description

Generate the authentication helper file for a package under development from the API security schemes stored in the OpenAPI definition. This supports incremental package scaffolding when you want to review or customize auth handling before generating the rest of the package files.

Usage

generate_pkg_auth(
  api_abbr = read_api_abbr(pkg_dir, config_filename),
  security_schemes = read_security_schemes(pkg_dir, read_rapid_filename(pkg_dir,
    config_filename)),
  save_security_data = TRUE,
  security_data_filename = "_beekeeper_security.yml",
  config_filename = "_beekeeper.yml",
  pkg_dir = "."
)

Arguments

api_abbr	(character(1)) A short (about 2-5 letter) abbreviation for the API, for use in function names and environment variables.
security_schemes	(rapid::class_security_schemes) Security schemes from the API definition.
save_security_data	(logical(1)) Whether to save generated security metadata to a file and record that file in the beekeeper config.
security_data_filename	(character(1) or fs_path) The path to the saved security metadata file (relative to the package root).
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).
pkg_dir	(character(1) or fs_path) The directory containing package files.

Value

(list) Generated security metadata. R/020-auth.R is generated as a side effect. When save_security_data is TRUE (strongly recommended when calling this function as a stand-alone), the file designated by security_data_filename, and the security_data_filename field in the file designated by config_filename are generated as side effects.

See Also

Other package generation functions: generate_pkg(), generate_pkg_paths(), generate_pkg_req_prepare(), generate_pkg_shared_params()

Examples

# Set up an empty package.
pkg_dir <- unclass(fs::path_norm(withr::local_tempdir()))
usethis::create_package(pkg_dir, open = FALSE, check_name = FALSE)
bk_files <- c("_beekeeper.yml", "_beekeeper_rapid.rds")
fs::file_copy(
  fs::path_package("beekeeper", "trello", bk_files),
  fs::path(pkg_dir, bk_files)
)
usethis::local_project(pkg_dir)

# Generate package authentication functions.
generate_pkg_auth()
fs::dir_ls("R")

# Clean up.
withr::deferred_run()

---

Generate files for API paths

Description

Generate operation functions and their tests from the API paths stored in the OpenAPI definition. This supports incremental package scaffolding when you want to review or customize endpoint wrappers separately from other package components.

Usage

generate_pkg_paths(
  api_abbr = read_api_abbr(pkg_dir, config_filename),
  api_definition = read_api_definition(pkg_dir, read_rapid_filename(pkg_dir,
    config_filename)),
  security_data = read_security_data(pkg_dir, config_filename),
  config_filename = "_beekeeper.yml",
  pkg_dir = "."
)

Arguments

api_abbr	(character(1)) A short (about 2-5 letter) abbreviation for the API, for use in function names and environment variables.
api_definition	(rapid::class_rapid) The API definition to generate package code from.
security_data	(list) Generated security metadata.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).
pkg_dir	(character(1) or fs_path) The directory containing package files.

Value

(character) Generated file paths. As a side effect, zero or more ⁠R/paths-*.R⁠ files are generated from the paths in the api_definition, as well as the associated test files as ⁠tests/testthat/test-paths-*.R⁠.

See Also

Other package generation functions: generate_pkg(), generate_pkg_auth(), generate_pkg_req_prepare(), generate_pkg_shared_params()

Examples

# Set up an empty package.
pkg_dir <- unclass(fs::path_norm(withr::local_tempdir()))
usethis::create_package(pkg_dir, open = FALSE, check_name = FALSE)
bk_files <- c("_beekeeper.yml", "_beekeeper_rapid.rds")
fs::file_copy(
  fs::path_package("beekeeper", "guru", bk_files),
  fs::path(pkg_dir, bk_files)
)
usethis::local_project(pkg_dir)

# Generate functions and tests for API paths.
generate_pkg_paths()
fs::dir_ls("R")
fs::dir_ls("tests/testthat")

# Clean up.
withr::deferred_run()

---

Generate request-prepare helpers

Description

Generate the core request helper and its initial test file for a package under development. This supports incremental package scaffolding when you want to review or customize the central request-construction helper used by generated endpoint wrappers separately from other package components.

Usage

generate_pkg_req_prepare(
  api_abbr = read_api_abbr(pkg_dir, config_filename),
  api_definition = read_api_definition(pkg_dir, read_rapid_filename(pkg_dir,
    config_filename)),
  api_title = read_api_title(pkg_dir, config_filename),
  security_data = read_security_data(pkg_dir, config_filename),
  config_filename = "_beekeeper.yml",
  pkg_dir = "."
)

Arguments

api_abbr	(character(1)) A short (about 2-5 letter) abbreviation for the API, for use in function names and environment variables.
api_definition	(rapid::class_rapid) The API definition to generate package code from.
api_title	(character(1)) The API title used in generated package files.
security_data	(list) Generated security metadata.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).
pkg_dir	(character(1) or fs_path) The directory containing package files.

Value

(character) Generated file paths. As a side effect, R/010-prepare.R and tests/testthat/test-010-prepare.R are generated.

See Also

Other package generation functions: generate_pkg(), generate_pkg_auth(), generate_pkg_paths(), generate_pkg_shared_params()

Examples

# Set up an empty package.
pkg_dir <- unclass(fs::path_norm(withr::local_tempdir()))
usethis::create_package(pkg_dir, open = FALSE, check_name = FALSE)
bk_files <- c("_beekeeper.yml", "_beekeeper_rapid.rds")
fs::file_copy(
  fs::path_package("beekeeper", "guru", bk_files),
  fs::path(pkg_dir, bk_files)
)
usethis::local_project(pkg_dir)

# Generate functions and tests for request preparation.
generate_pkg_req_prepare()
fs::dir_ls("R")
fs::dir_ls("tests/testthat")

# Clean up.
withr::deferred_run()

---

Generate shared parameter docs

Description

Generate the shared roxygen parameter definitions used across scaffolded functions. This supports incremental package scaffolding when you want to review or customize the shared parameter topic independently while iterating on the rest of the generated package files.

Usage

generate_pkg_shared_params(
  security_data = read_security_data(pkg_dir, "_beekeeper.yml"),
  pkg_dir = "."
)

Arguments

security_data	(list) Generated security metadata.
pkg_dir	(character(1) or fs_path) The directory containing package files.

Value

(character(1)) The generated file path. As a side effect, R/000-shared.R is generated.

See Also

Other package generation functions: generate_pkg(), generate_pkg_auth(), generate_pkg_paths(), generate_pkg_req_prepare()

Examples

# Set up an empty package.
pkg_dir <- unclass(fs::path_norm(withr::local_tempdir()))
usethis::create_package(pkg_dir, open = FALSE, check_name = FALSE)
bk_files <- c("_beekeeper.yml", "_beekeeper_rapid.rds")
fs::file_copy(
  fs::path_package("beekeeper", "trello", bk_files),
  fs::path(pkg_dir, bk_files)
)
usethis::local_project(pkg_dir)

# Generate shared parameters.
generate_pkg_shared_params()
fs::dir_ls("R")

# Clean up.
withr::deferred_run()

---

Read api_abbr config field

Description

Read the api_abbr field from a beekeeper config file.

Usage

read_api_abbr(pkg_dir = ".", config_filename = "_beekeeper.yml")

Arguments

pkg_dir	(character(1) or fs_path) The directory containing package files.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).

Value

(character(1)) The api_abbr field from the beekeeper config file.

See Also

Other config readers: read_api_definition(), read_api_title(), read_config(), read_rapid_filename(), read_security_data(), read_security_data_filename(), read_security_schemes()

Examples

read_api_abbr(pkg_dir = fs::path_package("beekeeper", "guru"))

---

Read an API definition file

Description

Read 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.

Usage

read_api_definition(
  pkg_dir = ".",
  rapid_filename = read_rapid_filename(pkg_dir)
)

Arguments

pkg_dir	(character(1) or fs_path) The directory containing package files.
rapid_filename	(character(1) or fs_path) The path to the R API definition (rapid) file (relative to the package root).

Value

(rapid::class_rapid) The definition of the API.

See Also

Other config readers: read_api_abbr(), read_api_title(), read_config(), read_rapid_filename(), read_security_data(), read_security_data_filename(), read_security_schemes()

Examples

api_definition <- read_api_definition(fs::path_package("beekeeper", "guru"))
class(api_definition)
api_definition@info@origin@url

---

Read api_title config field

Description

Read the api_title field from a beekeeper config file.

Usage

read_api_title(pkg_dir = ".", config_filename = "_beekeeper.yml")

Arguments

pkg_dir	(character(1) or fs_path) The directory containing package files.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).

Value

(character(1)) The api_title field from the beekeeper config file.

See Also

Other config readers: read_api_abbr(), read_api_definition(), read_config(), read_rapid_filename(), read_security_data(), read_security_data_filename(), read_security_schemes()

Examples

read_api_title(pkg_dir = fs::path_package("beekeeper", "guru"))

---

Read a beekeeper config file

Description

Read 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.

Usage

read_config(pkg_dir = ".", config_filename = "_beekeeper.yml")

Arguments

pkg_dir	(character(1) or fs_path) The directory containing package files.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).

Details

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_filename (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).

• security_data_filename (character(1)): Optionally, the path (relative to the package root) where generated security metadata is stored.

Value

(list) Configuration information, with elements api_title, api_abbr, api_version, rapid_filename, and updated_on, plus security_data_filename when present.

See Also

Other config readers: read_api_abbr(), read_api_definition(), read_api_title(), read_rapid_filename(), read_security_data(), read_security_data_filename(), read_security_schemes()

Examples

read_config(pkg_dir = fs::path_package("beekeeper", "guru"))

---

Read rapid_filename config field

Description

Read the rapid_filename field from a beekeeper config file.

Usage

read_rapid_filename(pkg_dir = ".", config_filename = "_beekeeper.yml")

Arguments

pkg_dir	(character(1) or fs_path) The directory containing package files.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).

Value

(character(1)) The rapid_filename field from the beekeeper config file.

See Also

Other config readers: read_api_abbr(), read_api_definition(), read_api_title(), read_config(), read_security_data(), read_security_data_filename(), read_security_schemes()

Examples

read_rapid_filename(pkg_dir = fs::path_package("beekeeper", "guru"))

---

Read saved security metadata

Description

Read prepared security metadata from a YAML file (default name ⁠_beekeeper_security.yml⁠) generated via generate_pkg_auth().

Usage

read_security_data(
  pkg_dir = ".",
  config_filename = "_beekeeper.yml",
  security_data_filename = read_security_data_filename(pkg_dir, config_filename)
)

Arguments

pkg_dir	(character(1) or fs_path) The directory containing package files.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).
security_data_filename	(character(1) or fs_path) The path to the saved security metadata file (relative to the package root).

Value

(list) Saved security metadata.

See Also

Other config readers: read_api_abbr(), read_api_definition(), read_api_title(), read_config(), read_rapid_filename(), read_security_data_filename(), read_security_schemes()

Examples

read_security_data(pkg_dir = fs::path_package("beekeeper", "trello"))

---

Read saved security metadata filename

Description

Read the security_data_filename field from a beekeeper config file.

Usage

read_security_data_filename(pkg_dir = ".", config_filename = "_beekeeper.yml")

Arguments

pkg_dir	(character(1) or fs_path) The directory containing package files.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).

Value

(character(1)) The configured security metadata file path.

See Also

Other config readers: read_api_abbr(), read_api_definition(), read_api_title(), read_config(), read_rapid_filename(), read_security_data(), read_security_schemes()

Examples

read_security_data_filename(
  pkg_dir = fs::path_package("beekeeper", "trello")
)

---

Read security schemes from an API definition

Description

Read the security schemes from an API definition stored as a rapid::class_rapid() object.

Usage

read_security_schemes(
  pkg_dir = ".",
  rapid_filename = read_rapid_filename(pkg_dir)
)

Arguments

pkg_dir	(character(1) or fs_path) The directory containing package files.
rapid_filename	(character(1) or fs_path) The path to the R API definition (rapid) file (relative to the package root).

Value

(rapid::class_security_schemes) Security schemes from the API definition.

See Also

Other config readers: read_api_abbr(), read_api_definition(), read_api_title(), read_config(), read_rapid_filename(), read_security_data(), read_security_data_filename()

---

Configure a package to use beekeeper

Description

Create a configuration file for a package to use beekeeper. The configuration file tracks information that will be used for generation of other functions, and the timestamp when the configuration was last updated or used.

Usage

use_beekeeper(
  x,
  api_abbr,
  ...,
  pkg_dir = ".",
  config_filename = "_beekeeper.yml",
  rapid_filename = "_beekeeper_rapid.rds"
)

Arguments

x	An object to use to define the configuration. It must be translatable to a rapid::class_rapid() object by rapid::as_rapid(). Usually this will be a url pointing to an OpenAPI document, or a list generated by reading such a document.
api_abbr	(character(1)) A short (about 2-5 letter) abbreviation for the API, for use in function names and environment variables.
...	These dots are for future extensions and must be empty.
pkg_dir	(character(1) or fs_path) The directory containing package files.
config_filename	(character(1) or fs_path) The path to a beekeeper yaml config file (relative to the package root).
rapid_filename	(character(1) or fs_path) The path to the R API definition (rapid) file (relative to the package root).

Value

(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 (relative to pkg_dir) is saved in the config file.

Examples

# Set up an empty package.
pkg_dir <- unclass(fs::path_norm(withr::local_tempdir()))
usethis::create_package(pkg_dir, open = FALSE, check_name = FALSE)
usethis::local_project(pkg_dir)

# Read an api definition. This could also simply be a URL to such a
# definition.
api_definition <- read_api_definition(fs::path_package("beekeeper", "guru"))

# Set up the package to use beekeeper with that definition.
use_beekeeper(api_definition, "guru")
read_config()
all.equal(read_api_definition(), api_definition)

# Clean up.
withr::deferred_run()

---