aaa2_tinycodet_import: Overview of the 'tinycodet' Import System

In tinycodet: Functions to Help in your Coding Etiquette

Overview of the 'tinycodet' Import System

Description

The 'tinycodet' R-package introduces a new package import system.

One can use a package without attaching the package - for example by using the :: operator.
Or, one can explicitly attach a package - for example by using the library function.
The advantages and disadvantages of using without attaching a package versus attaching a package, at least those relevant here, are compactly presented in the following list:

(1) Prevent masking functions from other packages:
⁠ ⁠

(2) Prevent masking core R functions:
⁠ ⁠

(3) Clarify which function came from which package:
⁠ ⁠

(4) Enable functions only in current/local environment instead of globally:
⁠ ⁠

(5) Prevent namespace pollution:
⁠ ⁠

(6) Minimise typing - especially for infix operators
(i.e. typing package::`%op%`(x, y) instead of x %op% y is cumbersome):
⁠ ⁠

(7) Use multiple related packages, without constantly switching between package prefixes
(i.e. doing packagename1::some_function1();
packagename2::some_function2();
packagename3::some_function3() is chaotic and cumbersome):
⁠ ⁠

What 'tinycodet' attempts to do with its import system, is to somewhat find the best of both worlds. It does this by introducing the following functions:

• import_as: Import a main package, and optionally its re-exports + its direct dependencies + its direct extensions, under a single alias. This essentially combines the attaching advantage of using multiple related packages (item 7 on the list), whilst keeping most advantages of using without attaching a package.

• import_inops: Expose infix operators from a package or an alias object to the current environment. This gains the attaching advantage of less typing (item 6 on the list), whilst simultaneously avoiding the disadvantage of attaching functions from a package globally (item 4 on the list).

• import_data: Directly return a data set from a package, to allow straight-forward assignment.

Furthermore, there are two miscellaneous import_ - functions: import_LL and import_int.

The import system also includes general helper functions:

• The x.import functions: helper functions specifically for the 'tinycodet' import system.

• The pversion_ functions: check mismatch between loaded package version and package version in library path.

• The pkgs - functions: general helper functions regarding packages.

See the examples section below to get an idea of how the 'tinycodet' import system works in practice. More examples can be found on the website (https://tony-aw.github.io/tinycodet/)

Details

When to Use or Not to Use the 'tinycodet' Import System
The 'tinycodet' import system is helpful particularly for packages that have at least one of the following properties:

• The namespace of the package(s) conflicts with other packages.

• The namespace of the package(s) conflicts with core R, or with those of recommended R packages.

• The package(s) have function names that are generic enough, such that it is not obvious which function came from which package.

See examples below.

There is no necessity for using the 'tinycodet' import system with every single package. One can safely attach the 'stringi' package, for example, as 'stringi' uses a unique and immediately recognisable naming scheme (virtually all 'stringi' functions start with "stri_"), and this naming scheme does not conflict with core R, nor with most other packages.

Of course, if one wishes to use a package (like 'stringi') only within a specific environment, it becomes advantageous to still import the package using the 'tinycodet' import system. In that case the import_LL function would be most applicable.


Some Additional Comments on the 'tinycodet' Import System

• (S3) Methods will automatically be registered.

• Pronouns, such as the .data and .env pronouns from the 'rlang' package, will work without any prefixes required.

• All functions imported by the import_as, import_inops, or import_LL functions have a "package" attribute, so you will always know which function came from which package.

See Also

tinycodet_help

Examples

all(c("dplyr", "powerjoin", "magrittr") %installed in% .libPaths())




# NO packages are being attached in any of the following code

# import 'dplyr' + its re-exports + extension 'powerjoin', under alias "dpr.":
import_as(
  ~ dpr., "dplyr", re_exports = TRUE, extensions = "powerjoin"
)

# exposing infix operators from 'magrrittr' to current environment:
import_inops("magrittr")

# directly assigning dplyr's "starwars" dataset to object "d":
d <- import_data("dplyr", "starwars")

# See it in Action:
d %>% dpr.$filter(species == "Droid") %>%
  dpr.$select(name, dpr.$ends_with("color"))

male_penguins <- dpr.$tribble(
  ~name,    ~species,     ~island, ~flipper_length_mm, ~body_mass_g,
  "Giordan",    "Gentoo",    "Biscoe",               222L,        5250L,
  "Lynden",    "Adelie", "Torgersen",               190L,        3900L,
  "Reiner",    "Adelie",     "Dream",               185L,        3650L
)

female_penguins <- dpr.$tribble(
  ~name,    ~species,  ~island, ~flipper_length_mm, ~body_mass_g,
  "Alonda",    "Gentoo", "Biscoe",               211,        4500L,
  "Ola",    "Adelie",  "Dream",               190,        3600L,
  "Mishayla",    "Gentoo", "Biscoe",               215,        4750L,
)
dpr.$check_specs()

dpr.$power_inner_join(
  male_penguins[c("species", "island")],
  female_penguins[c("species", "island")]
)

mypaste <- function(x, y) {
  import_LL("stringi", selection = "stri_c")
  stringi::stri_c(x, y)
}
mypaste("hello ", "world")

tinycodet documentation built on Sept. 12, 2024, 7:03 a.m.