Skip to contents

# Overview of the 'tinycodet' Import System

Source: `R/aaa2_tinycodet_import.R`
`aaa2_tinycodet_import.Rd`

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.

For R Package Developers
It goes without saying, just like one should NEVER use `library()` or `require()` inside an R-package, similarly, one should NOT use tinycodet’s import functions inside an R-Package.
The import functions can still be used inside functions defined in a file to be sourced, though.
Just not in functions inside an R-package.

## See also

tinycodet_help

## Examples

    all(c("dplyr", "powerjoin", "magrittr") %installed in% .libPaths())
    #> [1] TRUE

    # \donttest{

    # 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"
    )
    #> Importing packages and registering methods...
    #> Done
    #> You can now access the functions using `dpr.$`
    #> For conflicts report, packages order, and other attributes, run `attr.import(dpr.)`

    # exposing infix operators from 'magrrittr' to current environment:
    import_inops("magrittr")
    #> Checking for conflicting infix operators in the current environment...
    #> Placing infix operators in current environment...
    #> Done

    # 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"))
    #> # A tibble: 6 × 4
    #>   name   hair_color skin_color  eye_color
    #>   <chr>  <chr>      <chr>       <chr>
    #> 1 C-3PO  NA         gold        yellow
    #> 2 R2-D2  NA         white, blue red
    #> 3 R5-D4  NA         white, red  red
    #> 4 IG-88  none       metal       red
    #> 5 R4-P17 none       silver, red red, blue
    #> 6 BB8    none       none        black

    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()
    #> # powerjoin check specifications
    #> ℹ implicit_keys
    #> → column_conflict
    #> → duplicate_keys_left
    #> → duplicate_keys_right
    #> → unmatched_keys_left
    #> → unmatched_keys_right
    #> → missing_key_combination_left
    #> → missing_key_combination_right
    #> → inconsistent_factor_levels
    #> → inconsistent_type
    #> → grouped_input
    #> → na_keys

    dpr.$power_inner_join(
      male_penguins[c("species", "island")],
      female_penguins[c("species", "island")]
    )
    #> Joining, by = c("species", "island")
    #> # A tibble: 3 × 2
    #>   species island
    #>   <chr>   <chr>
    #> 1 Gentoo  Biscoe
    #> 2 Gentoo  Biscoe
    #> 3 Adelie  Dream

    mypaste <- function(x, y) {
      import_LL("stringi", selection = "stri_c")
      stringi::stri_c(x, y)
    }
    mypaste("hello ", "world")
    #> exposing and locking functions to current environment ...
    #> Done
    #> [1] "hello world"

    # }