awesome_print

Colorful pretty printing for Crystal.

awesome_print provides an ap! debug macro and a string formatter. It is inspired by Ruby awesome_print and amazing_print, but implemented in a Crystal-friendly style.

Installation

dependencies:
  awesome_print:
    github: zw963/awesome_print
    version: ~> 0.1.0

Then run:

shards install

Usage

require "awesome_print"

user = {name: "Diana", rank: 1, admin: false}

ap! user

ap! prints the source location, expression, formatted value, and type. It returns the original value, so it can stay inside debugging expressions.

value = ap!(user) # => returns user

Multiple expressions are printed one by one and returned as a tuple:

id, name = ap!(user[:id], user[:name])

To format without printing:

text = AwesomePrint.format(user)

AwesomePrint.format(...) returns plain text by default. Use colors_enabled: true for ANSI colors. ap! prints with colors by default.

Options

Options are passed to AwesomePrint::Inspector:

ap!(user, limit: 5, order: :sorted)
AwesomePrint.format(user, multiline: false)

Common options:

• indent_size: 4
• multiline: true
• index: true
• limit: nil
• order: :natural | :sorted
• hash_format: :symbol | :rocket | :json
• raw: false
• colors_enabled: true
• show_backtrace: true
• backtrace_limit: 8
• object_id: true
• max_path_length: 42

Configuration

Set global defaults with AwesomePrint.configure:

AwesomePrint.configure do |settings|
  settings.indent_size = 4
  settings.limit = 20
  settings.object_id = false
  settings.max_path_length = 42
  settings.order = :natural
end

Per-call options override configured defaults:

ap!(users, limit: 5)
AwesomePrint.format(user, object_id: true)

ap! uses colors by default. AwesomePrint.format(...) returns plain text by default, unless colors_enabled is configured or passed explicitly.

Examples

ap!([1, 2, 3], multiline: false)
ap!([1, 2, 3, 4, 5, 6, 7], limit: 5)
ap!(hash, hash_format: :rocket)
ap!(object, raw: true)
ap!(object, object_id: false)
ap!(error, backtrace_limit: 5)

Objects that implement to_h and return a Hash or NamedTuple are formatted as mappings by default. Use raw: true to inspect their instance variables instead.

Supported Types

Custom formatters currently cover:

Array, Hash, NamedTuple, Tuple, Set, Slice, Bytes, StaticArray, Struct, regular objects, Class, Enum, Exception, Path, File, Dir, Regex, Range, and Time.

Preview

Run:

crystal run example.cr

example.cr shows the current output style across common Crystal values.

Development

CRYSTAL_CACHE_DIR=/tmp/crystal-cache crystal spec

Contributors

• Billy.Zheng