Title:	Core Utilities for the 'rtemis' Ecosystem
Version:	0.0.3
Date:	2026-04-19
Description:	Utilities used across packages of the 'rtemis' ecosystem. Includes the msg() messaging system and the fmt() formatting system. Provides test_* functions that return logical values, check_* functions that throw informative errors, and clean_* functions that return validated and coerced values. This code began as part of the 'rtemis' package (<doi:10.32614/CRAN.package.rtemis>).
License:	GPL (≥ 3)
URL:	https://www.rtemis.org, https://github.com/rtemis-org/rtemis.core
BugReports:	https://github.com/rtemis-org/rtemis.core/issues
Depends:	R (≥ 4.1.0)
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	cli, data.table, methods, S7
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
Config/testthat/parallel:	true
NeedsCompilation:	no
Packaged:	2026-04-20 06:48:19 UTC; sdg
Author:	E.D. Gennatas [aut, cre, cph]
Maintainer:	E.D. Gennatas <gennatas@gmail.com>
Repository:	CRAN
Date/Publication:	2026-04-21 19:52:51 UTC

rtemis.core: Rtemis Utilities

Description

Core Utilities for rtemis R Packages

Author(s)

Maintainer: E.D. Gennatas gennatas@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://www.rtemis.org

• https://github.com/rtemis-org/rtemis.core

• Report bugs at https://github.com/rtemis-org/rtemis.core/issues

Abbreviate object class name

Description

Abbreviate object class name

Usage

abbreviate_class(x, n = 4L)

Arguments

Value

Character: Abbreviated class wrapped in angle brackets.

Author(s)

EDG

Examples

abbreviate_class(iris)
abbreviate_class(iris, n = 3)

Convert ANSI 256 color code to HEX

Description

Convert ANSI 256 color code to HEX

Usage

ansi256_to_hex(code)

Arguments

Value

Character: HEX color string.

Author(s)

EDG

Examples

ansi256_to_hex(1)

Make text bold

Description

A fmt() convenience wrapper for making text bold.

Usage

bold(text, output_type = c("ansi", "html", "plain"))

Arguments

Value

Character: Formatted text with bold styling

Author(s)

EDG

Examples

message(bold("This is bold!"))

Check character

Description

Check character

Usage

check_character(x, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if check fails.

Author(s)

EDG

Examples

check_character("papaya")
# Throws error:
try(check_character(42L))

Check data.table

Description

Check data.table

Usage

check_data.table(x, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if input is not a data.table, returns x invisibly otherwise.

Author(s)

EDG

Examples

check_data.table(data.table::as.data.table(iris))
# Throws error:
try(check_data.table(iris))

rtemis.core internal: Dependencies check

Description

Checks if dependencies can be loaded; names missing dependencies if not.

Usage

check_dependencies(..., verbosity = 0L)

Arguments

Value

Called for side effects. Aborts and prints list of missing dependencies, if any.

Author(s)

EDG

Examples

check_dependencies("base")
# Throws error:
try(check_dependencies("zlorbglorb"))

Check if value is in set of allowed values

Description

Checks if a value is in a set of allowed values, and throws an error if not.

Usage

check_enum(x, allowed_values, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if x is not in allowed_values, returns x invisibly otherwise.

Author(s)

EDG

Examples

check_enum("apple", c("apple", "banana", "cherry"))
# Throws error:
try(check_enum("granola", c("croissant", "bagel", "scramble")))

Check float between 0 and 1, exclusive

Description

Check float between 0 and 1, exclusive

Usage

check_float01exc(x, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if checks fail.

Author(s)

EDG

Examples

check_float01exc(c(0.2, 0.7))
# Throws error:
try(check_float01exc(c(0, 0.5, 1)))

Check float between 0 and 1, inclusive

Description

Check float between 0 and 1, inclusive

Usage

check_float01inc(x, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if checks fail.

Author(s)

EDG

Examples

check_float01inc(0.5)

Check float greater than or equal to 0

Description

Checks if an input is a numeric vector containing non-negative (>= 0) values and no NAs. It is designed to validate function arguments.

Usage

check_float0pos(x, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if checks fail.

Author(s)

EDG

Examples

check_float0pos(c(0, 0.5, 1))
# Allows integers since they are numeric and can be coerced to double without loss of information
check_float0pos(c(0L, 1L))
# Throws error:
try(check_float0pos(c(-1.5, 0, 1.5)))

Check float -1 <= x <= 1

Description

Check float -1 <= x <= 1

Usage

check_float_neg1_1(x, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if checks fail.

Author(s)

EDG

Examples

check_float_neg1_1(c(-1, 0, 1))
# Throws error:
try(check_float_neg1_1(c(-1.5, 0, 1.5)))

Check positive float

Description

Check positive float

Usage

check_floatpos(x, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Details

Checking with is.numeric() allows integer inputs as well, which should be ok since it is unlikely the function that consumes this will enforce double type only, but instead is most likely to allow implicit coercion from integer to numeric.

Value

Called for side effects. Throws an error if checks fail.

Author(s)

EDG

Examples

check_floatpos(c(0.5, 1.5))
# Allows integers since they are numeric and can be coerced to double without loss of information
check_floatpos(c(1L, 3L))
# Throws error:
try(check_floatpos(c(-1.5, 0.5, 1.5)))

Check float in (0, 1]

Description

Check float in (0, 1]

Usage

check_floatpos1(x, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if checks fail.

Author(s)

EDG

Examples

check_floatpos1(c(0.5, 1))
# Throw error:
try(check_floatpos1(c(0, 0.7)))
try(check_floatpos1(c(0.5, 1.5)))

Check class of object

Description

Check class of object

Usage

check_inherits(x, cl, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if checks fail.

Author(s)

EDG

Examples

check_inherits("papaya", "character")
# These will throw errors:
try(check_inherits(c(1, 2.5, 3.2), "integer"))
try(check_inherits(iris, "list"))

Check logical

Description

Check logical

Usage

check_logical(x, allow_null = TRUE, arg_name = deparse(substitute(x)))

Arguments

Value

Called for side effects. Throws an error if checks fail.

Author(s)

EDG

Examples

check_logical(c(TRUE, FALSE))
# Throws error:
try(check_logical(c(0, 1)))

Check Optional Scalar Character

Description

Check Optional Scalar Character

Usage

check_optional_scalar_character(x, arg_name)

Arguments

Value

Called for side effects.

Author(s)

EDG

Examples

check_optional_scalar_character(NULL, "my_arg") # Passes
check_optional_scalar_character("hello", "my_arg") # Passes
# Throw error:
try(check_optional_scalar_character(c("hello", "world"), "my_arg"))
try(check_optional_scalar_character(123, "my_arg"))

Check Scalar Logical

Description

Check Scalar Logical

Usage

check_scalar_logical(x, arg_name)

Arguments

Value

Called for side effects.

Author(s)

EDG

Examples

check_scalar_logical(TRUE, "my_arg") # Passes
check_scalar_logical(FALSE, "my_arg") # Passes
# Throw error:
try(check_scalar_logical(c(TRUE, FALSE), "my_arg"))
try(check_scalar_logical(NA, "my_arg"))
try(check_scalar_logical("TRUE", "my_arg"))

Check object is tabular

Description

Checks if object is of class data.frame, data.table, or tbl_df.

Usage

check_tabular(x)

Arguments

Value

Called for side effects. Throws an error if input is not tabular, returns x invisibly otherwise.

Author(s)

EDG

Examples

check_tabular(iris)
check_tabular(data.table::as.data.table(iris))
# Throws error:
try(check_tabular(matrix(1:10, ncol = 2)))

Clean column names

Description

Clean column names by replacing all spaces and punctuation with a single underscore

Usage

clean_colnames(x)

Arguments

Value

Character vector.

Author(s)

EDG

Examples

clean_colnames(iris)

Clean integer input

Description

Clean integer input

Usage

clean_int(x, xname = deparse(substitute(x)))

Arguments

Details

The goal is to return an integer vector. If the input is integer, it is returned as is. If the input is numeric, it is coerced to integer only if the numeric values are integers, otherwise an error is thrown.

Value

Integer vector.

Author(s)

EDG

Examples

clean_int(6L)
clean_int(3)
# clean_int(12.1) # Error
clean_int(c(3, 5, 7))
# clean_int(c(3, 5, 7.01)) # Error

Clean names

Description

Clean character vector by replacing all symbols and sequences of symbols with single underscores, ensuring no name begins or ends with a symbol

Usage

clean_names(x, prefix_digits = "V_")

Arguments

Value

Character vector.

Author(s)

EDG

Examples

x <- c("Patient ID", "_Date-of-Birth", "SBP (mmHg)")
x
clean_names(x)

Check positive integer

Description

Check positive integer

Usage

clean_posint(x, allow_na = FALSE, xname = deparse(substitute(x)))

Arguments

Value

Integer vector of positive values.

Author(s)

EDG

Examples

clean_posint(5)

Apply 256-color formatting

Description

Apply 256-color formatting

Usage

col256(text, col = "79", bg = FALSE, output_type = c("ansi", "html", "plain"))

Arguments

Value

Character: Formatted text with 256-color styling

Author(s)

EDG

Examples

col256("Hello", col = 160, output_type = "ansi")

Format Numbers for Printing

Description

2 Decimal places, otherwise scientific notation

Usage

ddSci(x, decimal_places = 2, hi = 1e+06, as_numeric = FALSE)

Arguments

Details

Numbers will be formatted to 2 decimal places, unless this results in 0.00 (e.g. if input was .0032), in which case they will be converted to scientific notation with 2 significant figures. ddSci will return 0.00 if the input is exactly zero. This function can be used to format numbers in plots, on the console, in logs, etc.

Value

Formatted number

Author(s)

EDG

Examples

x <- .34876549
ddSci(x)
# "0.35"
x <- .00000000457823
ddSci(x)
# "4.6e-09"

Text formatting

Description

Formats text with specified color, styles, and background using ANSI escape codes or HTML, with support for plain text output.

Usage

fmt(
  x,
  col = NULL,
  bold = FALSE,
  italic = FALSE,
  underline = FALSE,
  thin = FALSE,
  muted = FALSE,
  bg = NULL,
  pad = 0L,
  output_type = c("ansi", "html", "plain")
)

Arguments

Details

This function combines multiple formatting options into a single call, making it more efficient than nested function calls. It generates optimized ANSI escape sequences and clean HTML output.

Value

Character: Formatted text with specified styling.

Author(s)

EDG

Examples

# Simple color
fmt("Hello", col = "red")

# Bold red text
fmt("Error", col = "red", bold = TRUE)

# Multiple styles
fmt("Warning", col = "yellow", bold = TRUE, italic = TRUE)

# With background
fmt("Highlight", col = "white", bg = "blue", bold = TRUE)

Gradient text

Description

Gradient text

Usage

fmt_gradient(x, colors, bold = FALSE, output_type = c("ansi", "html", "plain"))

Arguments

Value

Character: Text with gradient color applied.

Author(s)

EDG

Examples

fmt_gradient("Gradient Text", colors = c("blue", "red")) |> message()

Get output type

Description

Get output type for printing text.

Usage

get_output_type(output_type = c("ansi", "html", "plain"), filename = NULL)

Arguments

Details

Exported as internal function for use by other rtemis packages.

Value

Character with selected output type.

Author(s)

EDG

Examples

get_output_type()

Highlight text

Description

A fmt() convenience wrapper for highlighting text.

Usage

highlight(x, pad = 0L, output_type = c("ansi", "html", "plain"))

Arguments

Value

Character: Formatted text with highlight.

Author(s)

EDG

Examples

message(highlight("This is highlighted!"))

Format text for label printing

Description

Format text for label printing

Usage

labelify(
  x,
  underscores_to_spaces = TRUE,
  dotsToSpaces = TRUE,
  toLower = FALSE,
  toTitleCase = TRUE,
  capitalize_strings = c("id"),
  stringsToSpaces = c("\\$", "`")
)

Arguments

Value

Character vector.

Author(s)

EDG

Examples

x <- c("county_name", "total.cost$", "age", "weight.kg")
labelify(x)

Match Arguments Ignoring Case

Description

Match Arguments Ignoring Case

Usage

match_arg(x, choices)

Arguments

Value

Character: Matched argument.

Author(s)

EDG

Examples

match_arg("papaya", c("AppleExtreme", "SuperBanana", "PapayaMaster"))

Message with provenance

Description

Print message to output with a prefix including data and time, and calling function or full call stack

Usage

msg(
  ...,
  caller = NULL,
  call_depth = 1L,
  caller_id = 1L,
  newline_pre = FALSE,
  newline = TRUE,
  format_fn = plain,
  sep = " ",
  verbosity = 1L
)

msg0(
  ...,
  caller = NULL,
  call_depth = 1,
  caller_id = 1,
  newline_pre = FALSE,
  newline = TRUE,
  format_fn = plain,
  sep = "",
  verbosity = 1L
)

Arguments

Details

If msg is called directly from the console, it will print ⁠[interactive>]⁠ in place of the call stack. msg0, similar to paste0, is msg(..., sep = "")

Value

If verbosity > 0L, returns a list with call, message, and date, invisibly, otherwise returns NULL invisibly.

Author(s)

EDG

Examples

msg("Hello")

msgdone

Description

msgdone

Usage

msgdone(caller = NULL, call_depth = 1, caller_id = 1, sep = " ")

Arguments

Value

NULL invisibly

Author(s)

EDG

Examples

msgstart("Starting process...")
msgdone("Process complete")

msgstart

Description

msgstart

Usage

msgstart(..., newline_pre = FALSE, sep = "")

Arguments

Value

NULL invisibly

Author(s)

EDG

Examples

msgstart("Starting process...")
msgdone("Process complete.")

Create an optional S7 type

Description

Creates an S7 union type that allows for the specified type or NULL.

Usage

optional(type)

Arguments

Value

An S7 union type that allows for the specified type or NULL.

Author(s)

EDG

Examples

# Create an optional character type
optional(S7::class_character)

Force plain text when using message()

Description

Force plain text when using message()

Usage

plain(x)

Arguments

Value

Character: Text with ANSI escape codes removed.

Author(s)

EDG

Examples

message(plain("hello"))

Print data frame

Description

Pretty print a data frame

Usage

printdf(
  x,
  pad = 0,
  spacing = 1,
  ddSci_dp = NULL,
  transpose = FALSE,
  justify = "right",
  colnames = TRUE,
  rownames = TRUE,
  column_fmt = highlight,
  row_fmt = gray,
  newline_pre = FALSE,
  newline = FALSE
)

Arguments

Details

By design, numbers will not be justified, but using ddSci_dp will convert to characters, which will be justified. This is intentional for internal use.

Value

NULL invisibly

Author(s)

EDG

Examples

printdf(iris[1:6, ])

Pretty print list

Description

Pretty print a list (or data frame) recursively

Usage

printls(
  x,
  prefix = "",
  pad = 2L,
  item_format = bold,
  maxlength = 4L,
  center_title = TRUE,
  title = NULL,
  title_newline = TRUE,
  newline_pre = FALSE,
  format_fn_rhs = ddSci,
  print_class = TRUE,
  abbrev_class_n = 3L,
  print_df = FALSE,
  print_S4 = FALSE,
  limit = 12L
)

Arguments

Details

Data frames in R began life as lists

Value

NULL invisibly

Author(s)

EDG

Examples

printls(list(a = 1:10, b = "Hello", c = list(d = 1, e = 2)), title = "A List")

String representation

Description

String representation

Usage

repr(x, ...)

Arguments

Value

Character string representation of the object.

Author(s)

EDG

Examples

S7::method(repr, S7::class_character) <- function(x, ...) {
  paste0("<chr> \"", x, "\"")
}
cat(repr("hello"))

Show S7 class name

Description

Show S7 class name

Usage

repr_S7name(x, col = col_object, pad = 0L, prefix = NULL, output_type = NULL)

Arguments

Value

Character: Formatted string that can be printed with cat().

Author(s)

EDG

Examples

repr_S7name("Supervised") |> cat()

Show list as formatted string

Description

Works exactly like printls, but instead of printing to console with cat, it outputs a single string, formatted using mformat, so that cat(repr_ls(x)) looks identical to printls(x) for any list x

Usage

repr_ls(
  x,
  prefix = "",
  pad = 2L,
  item_format = bold,
  maxlength = 4L,
  center_title = TRUE,
  title = NULL,
  title_newline = TRUE,
  newline_pre = FALSE,
  format_fn_rhs = ddSci,
  print_class = TRUE,
  abbrev_class_n = 3L,
  print_df = FALSE,
  print_S4 = FALSE,
  limit = 12L,
  output_type = c("ansi", "html", "plain")
)

Arguments

Details

Exported as internal function for use by other rtemis packages.

Value

Character: Formatted string that can be printed with cat()

Author(s)

EDG

Examples

x <- list(
  a = 1:10,
  b = "Hello",
  c = list(
    d = 1,
    e = 2
  )
)
cat(repr_ls(x, title = "A List"))

rtemis Colors

Description

A named vector of colors used in the rtemis ecosystem, provided as hex strings.

Usage

rtemis_colors

Format

An object of class character of length 12.

Value

Named character vector of hex color codes.

Author(s)

EDG

Examples

rtemis_colors[["teal"]]

Check class of object

Description

Check class of object

Usage

test_inherits(x, cl)

Arguments

Value

Logical

Author(s)

EDG

Examples

test_inherits("papaya", "character") # TRUE
test_inherits(c(1, 2.5, 3.2), "integer")
test_inherits(iris, "list") # FALSE, compare to is_check(iris, is.list)