Compact, budgeted description of an R object

An S3 generic used for the <attached> and <workspace> context blocks, peter$describe() and console mentions. Methods return successively richer levels of detail and the richest level whose estimated size fits budget is returned. Methods never force promises, never do I/O (no dbListTables(), no collect()) and never call str() on the object. Packages add methods with a delayed S3method(gptr::gptr_describe, <class>).

Usage

gptr_describe(x, budget = 150L, ...)

# Default S3 method
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'data.frame'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'matrix'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'list'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'environment'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class '`function`'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'formula'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'lm'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'dgCMatrix'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'Seurat'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'SingleCellExperiment'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'ArrowTabular'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'Dataset'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'DBIConnection'
gptr_describe(x, budget = 150L, ..., level = NULL)

# S3 method for class 'ggplot'
gptr_describe(x, budget = 150L, ..., level = NULL)

Arguments

x

Any R object.

budget

Estimated tokens, at least 20 (default 150).

...

Passed to methods; built-in methods accept level (1 = header only; larger values give more detail).

level

Built-in methods: the detail level to return (default: the richest that fits).

Value

A character vector of lines; the first is a header <class> shape, size.

Examples

gptr_describe(mtcars, budget = 60)
#> [1] "<data.frame> 32 x 11, 7 KB"                                                                
#> [2] "  mpg:dbl cyl:dbl disp:dbl hp:dbl drat:dbl wt:dbl qsec:dbl vs:dbl am:dbl gear:dbl carb:dbl"
gptr_describe(as.Date("2026-01-01") + 0:9)
#> [1] "<Date> length 10, 400 B"           "  2026-01-01 to 2026-01-10; no NA"