Type: Package
Title: Print Debugging Made Sweeter
Version: 0.2.2
Description: Provides user-friendly and configurable print debugging via a single function, ic(). Wrap an expression in ic() to print the expression, its value and (where available) its source location. Debugging output can be toggled globally without modifying code.
License: MIT + file LICENSE
URL: https://www.lewinfox.com/icecream/, https://github.com/lewinfox/icecream, http://www.lewinfox.com/icecream/
BugReports: https://github.com/lewinfox/icecream/issues
Imports: cli, glue, pillar (≥ 1.6.1), purrr (≥ 0.3.4), rlang
Suggests: checkmate (≥ 2.0.0), testthat (≥ 3.0.0), withr
Config/testthat/edition: 3
Encoding: UTF-8
Language: en-GB
RoxygenNote: 7.2.3
NeedsCompilation: no
Packaged: 2024-02-18 00:34:38 UTC; lewin
Author: Lewin Appleton-Fox [aut, cre], Dominik Rafacz ORCID iD [aut], Ben Stiles [ctb]
Maintainer: Lewin Appleton-Fox <lewin.a.f@gmail.com>
Repository: CRAN
Date/Publication: 2024-02-18 00:50:03 UTC

Icecream: Never use print() to debug again

Description

Icecream provides a more user-friendly print debugging experience. Use ic() wherever you would use print() and see the expression and its value easily.

Options

The following options can be used to control behaviour:

Author(s)

Maintainer: Lewin Appleton-Fox lewin.a.f@gmail.com

Authors:

Other contributors:

See Also

Useful links:


Enable or disable ic()

Description

These functions enable or disable the ic() function. While disabled ic() will do nothing except evaluate and return its input.

Usage

ic_enable()

ic_disable()

Details

These are just convenience wrappers for options(icecream.enabled = TRUE/FALSE) used to align the API with the Python version.

Value

Returns the old value of the option, invisibly.

Functions


User-friendly debug statements

Description

User-friendly debug statements

Usage

ic(x)

Arguments

x

An expression, or nothing

Value

If x is an expression, returns the result of evaluating x. If x is missing nothing is returned.

Examples

f <- function(x) x < 0

ic(f(1))

ic(f(-1))

Temporarily enable or disable ic()

Description

These functions let you evaluate an expression with either ic() enabled or disabled without affecting if ic() is enabled globally.

Usage

with_ic_enable(expr)

with_ic_disable(expr)

Arguments

expr

An expression containing the ic() function.

Value

Returns the result of evaluating the expression.

Functions

Examples

ic_enable()

fun <- function(x) {
  ic(x * 100)
}

fun(2)

with_ic_disable(fun(2))

fun(4)

ic_disable()

fun(1)

with_ic_enable(fun(1))

Get descriptive one-line summary of an object

Description

This function is created as a modification of utils::str() function. It is supposed to create more compacted yet informative summary about an object. It's default value of "icecream.peeking.function"

Usage

ic_autopeek(object, ...)

## S3 method for class 'list'
ic_autopeek(object, max_summary_length = cli::console_width(), ...)

## S3 method for class 'data.frame'
ic_autopeek(object, max_summary_length = cli::console_width(), ...)

Arguments

object

The object to be summarized.

...

Other arguments passed to methods.

max_summary_length

Integer. Maximum length of string summarizing the object. By default this is set to the current terminal width.

Details

This is a generic function. Default method simply calls utils::str function.

Value

The function is mainly used for its side effects – outputting to the terminal. However, it also returns an invisible string of the printed summary.

Methods (by class)

See Also

utils::str() ic_peek()


Get a header of the object peeked at

Description

Get a header of the object peeked at

Usage

ic_autopeek_header(object, ...)

Arguments

object

The object peeked at.

...

Other arguments passed to methods.

Details

This function is used by ic_autopeek to get a header of the summary of a object. It should return object's top-level class name and its dimension.


Peek at value of expression

Description

This function is a proxy for calling peeking function.

Usage

ic_peek(
  value,
  peeking_function = getOption("icecream.peeking.function"),
  max_lines = getOption("icecream.max.lines")
)

Arguments

value

The result of evaluating an expression inside the ic() function.

peeking_function

The function used to peek at the value. Default value is set by the "icecream.peeking.function" option.

max_lines

Maximum number of lines printed. Default value is set by the "icecream.max.lines" option.

Details

Default value of icecream.peeking.function is ic_autopeek. Suggested possible alternatives are:

Value

A string to be printed.

See Also

ic_autopeek() utils::str() base::print() utils::head() base::summary() tibble::glimpse()


Print icecream messages

Description

The printing logic depends on how the ic() function has been called and what user options are set.

Usage

ic_print(
  loc,
  parent_ref,
  deparsed_expression = rlang::missing_arg(),
  value = rlang::missing_arg()
)

Arguments

loc

String detailing function definition location, which may be a source ref (file, line number and character index) or an environment.

parent_ref

The calling function.

deparsed_expression

The deparsed expression (if present) on which ic() was called. If missing (default value), only evaluation context is printed.

value

The result of evaluating deparsed_expression. If expression is missing (default value), this argument should also be missing.

Value

The function is called for its side effect (printing to the console) but it also returns its output string, invisibly.


Functions re-exported from rlang

Description

These are used to extract and format source references. As they are not part of the public rlang API they are reimplemented here.

Usage

src_loc(srcref, dir = getwd())

relish(x, dir = getwd())

Arguments

srcref

A srcref object

dir

Directory path

x

File path

Value

Character vector containing either a source location (for src_loc()) or a path (for relish()).

Functions