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 [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:

• icecream.enabled: Boolean. If FALSE, calls to ic(foo) simply evaluate and return foo. No output is printed.

• icecream.prefix: This is printed at the beginning of every line. Defaults to "ic|".

• icecream.include.context: Boolean. If TRUE, when calling ic(foo) the source file:line or environment will be printed along with the expression and value. This can be useful for more complicated debugging but produces a lot of output so is disabled by default. When ic() is called with no arguments, the context is always printed because showing the location of the call is the only reason to call ic() on its own.

• icecream.peeking.function: indicates the function that summarizes the object. Default value is ic_autopeek, which works like utils::str for most of the time, but gives more informative output for lists, data.frames and their subclasses in a more compact way.

• icecream.max.lines Integer. Determines maximum number of lines that the peek of an object occupies; defaults to 1.

• icecream.output.function: Not implemented yet. See the configuration section of the original project docs for details of what it will do.

• icecream.arg.to.string.function: Not implemented yet. See the configuration section of the original project docs for details of what it will do.

Author(s)

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

Authors:

• Dominik Rafacz dominikrafacz@gmail.com (ORCID)

Other contributors:

• Ben Stiles [contributor]

See Also

Useful links:

• https://www.lewinfox.com/icecream/

• https://github.com/lewinfox/icecream

• http://www.lewinfox.com/icecream/

• Report bugs at https://github.com/lewinfox/icecream/issues

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

• ic_enable(): Enable ic().

• ic_disable(): Disable ic().

User-friendly debug statements

Description

User-friendly debug statements

Usage

ic(x)

Arguments

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

Value

Returns the result of evaluating the expression.

Functions

• with_ic_enable(): evaluates the expression with ic() enabled.

• with_ic_disable(): evaluates the expression with ic() disabled.

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

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)

• ic_autopeek(list): Method for list

• ic_autopeek(data.frame): Method for data.frame

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

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

Details

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

• utils::str

• print

• head

• summary

• tibble::glimpse

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

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

Value

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

Functions

• src_loc(): Return source location from a srcref. If no srcref is found, return "".

• relish(): Tidy file paths by removing instances of dir from x. Ensures that we get a relative path for x.