Popularity
7.8
Stable
Activity
5.5
Declining
57
3
1

Programming language: Crystal
Tags: Debugging    
Latest version: v1.1.0
Add another 'Debugging' Shard

README

debug!(…)

Build Status Releases License

A macro for puts-style debugging fans.

Debuggers are great. But sometimes you just don't have the time and nerve to set up everything correctly and just want a quick way to inspect some values at runtime.

This projects provides debug!(…) macro that can be used in all circumstances where you would typically write puts … or pp …, but with a few extras.

Features

  • Easy to read, colorized output
  • Prints file name, line number, function name and the original expression
  • Adds type information for the printed-out value
  • Specialized pretty-printers for selected classes and modules (like Indexable)
  • Can be used inside expressions

Installation

  1. Add the dependency to your shard.yml:
   dependencies:
     debug:
       github: Sija/debug.cr
  1. Run shards install

  2. Make sure you compile your program with ENV variable DEBUG set to 1 (for instance DEBUG=1 shards build). Otherwise all debug!(…) calls will become a no-op.

  3. Once your program is compiled, you need to pass DEBUG=1 again on the program start, in order to activate debug!(…) logging. Alternatively, you can call Debug.enabled = true within your code to achieve the same behaviour.

Usage

require "debug"

# You can use `debug!(...)` in expressions:
def factorial(n : Int)
  return debug!(1) if debug!(n <= 1)
  debug!(n * factorial(n - 1))
end

message = "hello"
debug!(message)

a = 2
b = debug!(3 * a) + 1

numbers = {b, 13, 42}
debug!(numbers)

debug!("this line is executed")

factorial(4)

The code above produces this output:

debug!(…) macro output

Configuration

You can change the global defaults by calling Debug.configure with a block:

Debug.configure do |settings|
  settings.max_path_length = 100

  settings.colors[:expression] = :magenta
  settings.colors[:value] = :yellow
end

There's also Debug::Logger.configure method which allows you to change global defaults related to the logging itself.

Debug::Logger.configure do |settings|
  settings.progname = "foo.cr"

  settings.show_severity = false
  settings.show_datetime = true
  settings.show_progname = true

  settings.colors[:datetime] = :dark_gray
  settings.colors[:progname] = :light_blue

  settings.severity_colors[:debug] = :cyan
  settings.severity_colors[:info] = :white
end

Customization

If you want debug!(…) to work for your custom class, you can simply overload #to_debug(io) method within your class.

class Foo
  def to_debug(io)
    io << "Foo(@bar = " << @bar.to_s.colorize(:green) << ")"
  end
end

Development

Run specs with:

crystal spec

Contributing

  1. Fork it (https://github.com/Sija/debug.cr/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Contributors

  • @Sija Sijawusz Pur Rahnama - creator, maintainer


*Note that all licence references and agreements mentioned in the debug.cr README section above are relevant to that project's source code only.