awesome_print/README.md at 7eef826a63a15848e133c1722a9eea3d909a6cce

kotovalexarian-likes-github/awesome_print

mirror of https://github.com/awesome-print/awesome_print synced 2023-03-27 23:22:34 -04:00

Michael Dvorkin 6e46a12184 Update README.md

2012-11-23 20:31:04 -08:00

10 KiB

Raw Blame History

Awesome Print

Awesome Print is a Ruby library that pretty prints Ruby objects in full color exposing their internal structure with proper indentation. Rails ActiveRecord objects and usage within Rails templates are supported via included mixins.

Installation

# Installing as Ruby gem
$ gem install awesome_print

# Cloning the repository
$ git clone git://github.com/michaeldv/awesome_print.git

Usage

require "awesome_print"
ap object, options = {}

Default options:

:indent     => 4,      # Indent using 4 spaces.
:index      => true,   # Display array indices.
:html       => false,  # Use ANSI color codes rather than HTML.
:multiline  => true,   # Display in multiple lines.
:plain      => false,  # Use colors.
:raw        => false,  # Do not recursively format object instance variables.
:sort_keys  => false,  # Do not sort hash keys.
:limit      => false,  # Limit large output for arrays and hashes. Set to a boolean or integer.
:color => {
  :args       => :pale,
  :array      => :white,
  :bigdecimal => :blue,
  :class      => :yellow,
  :date       => :greenish,
  :falseclass => :red,
  :fixnum     => :blue,
  :float      => :blue,
  :hash       => :pale,
  :keyword    => :cyan,
  :method     => :purpleish,
  :nilclass   => :red,
  :rational   => :blue,
  :string     => :yellowish,
  :struct     => :pale,
  :symbol     => :cyanish,
  :time       => :greenish,
  :trueclass  => :green,
  :variable   => :cyanish
}

Supported color names:

:gray, :red, :green, :yellow, :blue, :purple, :cyan, :white
:black, :redish, :greenish, :yellowish, :blueish, :purpleish, :cyanish, :pale

Examples

$ cat > 1.rb
require "awesome_print"
data = [ false, 42, %w(forty two), { :now => Time.now, :class => Time.now.class, :distance => 42e42 } ]
ap data
^D
$ ruby 1.rb
[
    [0] false,
    [1] 42,
    [2] [
        [0] "forty",
        [1] "two"
    ],
    [3] {
           :class => Time < Object,
             :now => Fri Apr 02 19:55:53 -0700 2010,
        :distance => 4.2e+43
    }
]

$ cat > 2.rb
require "awesome_print"
data = { :now => Time.now, :class => Time.now.class, :distance => 42e42 }
ap data, :indent => -2  # <-- Left align hash keys.
^D
$ ruby 2.rb
{
  :class    => Time < Object,
  :now      => Fri Apr 02 19:55:53 -0700 2010,
  :distance => 4.2e+43
}

$ cat > 3.rb
require "awesome_print"
data = [ false, 42, %w(forty two) ]
data << data  # <-- Nested array.
ap data, :multiline => false
^D
$ ruby 3.rb
[ false, 42, [ "forty", "two" ], [...] ]

$ cat > 4.rb
require "awesome_print"
class Hello
  def self.world(x, y, z = nil, &blk)
  end
end
ap Hello.methods - Class.methods
^D
$ ruby 4.rb
[
    [0] world(x, y, *z, &blk) Hello
]

$ cat > 5.rb
require "awesome_print"
ap (''.methods - Object.methods).grep(/!/)
^D
$ ruby 5.rb
[
    [ 0] capitalize!()           String
    [ 1]      chomp!(*arg1)      String
    [ 2]       chop!()           String
    [ 3]     delete!(*arg1)      String
    [ 4]   downcase!()           String
    [ 5]     encode!(*arg1)      String
    [ 6]       gsub!(*arg1)      String
    [ 7]     lstrip!()           String
    [ 8]       next!()           String
    [ 9]    reverse!()           String
    [10]     rstrip!()           String
    [11]      slice!(*arg1)      String
    [12]    squeeze!(*arg1)      String
    [13]      strip!()           String
    [14]        sub!(*arg1)      String
    [15]       succ!()           String
    [16]   swapcase!()           String
    [17]         tr!(arg1, arg2) String
    [18]       tr_s!(arg1, arg2) String
    [19]     upcase!()           String
]

$ cat > 6.rb
require "awesome_print"
ap 42 == ap(42)
^D
$ ruby 6.rb
42
true
$ cat 7.rb
require "awesome_print"
some_array = (1..1000).to_a
ap some_array, :limit => true
^D
$ ruby 7.rb
[
    [  0] 1,
    [  1] 2,
    [  2] 3,
    [  3] .. [996],
    [997] 998,
    [998] 999,
    [999] 1000
]

$ cat 8.rb
require "awesome_print"
some_array = (1..1000).to_a
ap some_array, :limit => 5
^D
$ ruby 8.rb
[
    [  0] 1,
    [  1] 2,
    [  2] .. [997],
    [998] 999,
    [999] 1000
]

Example (Rails console)

$ rails console
rails> require "awesome_print"
rails> ap Account.all(:limit => 2)
[
    [0] #<Account:0x1033220b8> {
                     :id => 1,
                :user_id => 5,
            :assigned_to => 7,
                   :name => "Hayes-DuBuque",
                 :access => "Public",
                :website => "http://www.hayesdubuque.com",
        :toll_free_phone => "1-800-932-6571",
                  :phone => "(111)549-5002",
                    :fax => "(349)415-2266",
             :deleted_at => nil,
             :created_at => Sat, 06 Mar 2010 09:46:10 UTC +00:00,
             :updated_at => Sat, 06 Mar 2010 16:33:10 UTC +00:00,
                  :email => "info@hayesdubuque.com",
        :background_info => nil
    },
    [1] #<Account:0x103321ff0> {
                     :id => 2,
                :user_id => 4,
            :assigned_to => 4,
                   :name => "Ziemann-Streich",
                 :access => "Public",
                :website => "http://www.ziemannstreich.com",
        :toll_free_phone => "1-800-871-0619",
                  :phone => "(042)056-1534",
                    :fax => "(106)017-8792",
             :deleted_at => nil,
             :created_at => Tue, 09 Feb 2010 13:32:10 UTC +00:00,
             :updated_at => Tue, 09 Feb 2010 20:05:01 UTC +00:00,
                  :email => "info@ziemannstreich.com",
        :background_info => nil
    }
]
rails> ap Account
class Account < ActiveRecord::Base {
                 :id => :integer,
            :user_id => :integer,
        :assigned_to => :integer,
               :name => :string,
             :access => :string,
            :website => :string,
    :toll_free_phone => :string,
              :phone => :string,
                :fax => :string,
         :deleted_at => :datetime,
         :created_at => :datetime,
         :updated_at => :datetime,
              :email => :string,
    :background_info => :string
}
rails>

IRB integration

To use awesome_print as default formatter in irb and Rails console add the following code to your ~/.irbrc file:

require "awesome_print"
AwesomePrint.irb!

PRY integration

If you miss awesome_print's way of formatting output, here's how you can use it in place of the formatting which comes with pry. Add the following code to your ~/.pryrc:

require "awesome_print"
AwesomePrint.pry!

Logger Convenience Method

awesome_print adds the 'ap' method to the Logger and ActiveSupport::BufferedLogger classes letting you call:

logger.ap object

By default, this logs at the :debug level. You can override that globally with:

:log_level => :info

in the custom defaults (see below). You can also override on a per call basis with:

logger.ap object, :warn

ActionView Convenience Method

awesome_print adds the 'ap' method to the ActionView::Base class making it available within Rails templates. For example:

<%= ap @accounts.first %>   # ERB
!= ap @accounts.first       # HAML

With other web frameworks (ex: in Sinatra templates) you can explicitly request HTML formatting:

<%= ap @accounts.first, :html => true %>

Setting Custom Defaults

You can set your own default options by creating .aprc file in your home directory. Within that file assign your defaults to AwesomePrint.defaults. For example:

# ~/.aprc file.
AwesomePrint.defaults = {
  :indent => -2,
  :color => {
    :hash  => :pale,
    :class => :white
  }
}

Running Specs

$ gem install rspec           # RSpec 2.x is the requirement.
$ rake spec                   # Run the entire spec suite.
$ rspec spec/logger_spec.rb   # Run individual spec file.

Note on Patches/Pull Requests

Fork the project on Github.
Make your feature addition or bug fix.
Add specs for it, making sure $ rake spec is all green.
Commit, do not mess with rakefile, version, or history.
Send me commit URL (do not send pull requests).

Contributors

Adam Doppelt -- https://github.com/gurgeous
Andrew O'Brien -- https://github.com/AndrewO
Andrew Horsman -- https://github.com/basicxman
Barry Allard -- https://github.com/steakknife
Benoit Daloze -- http://github.com/eregon
Brandon Zylstra -- https://github.com/brandondrew
Dan Lynn -- https://github.com/danlynn
Daniel Johnson -- https://github.com/adhd360
Daniel Bretoi -- http://github.com/danielb2
Eloy Duran -- http://github.com/alloy
Elpizo Choi -- https://github.com/fuJiin
Evan Senter -- https://github.com/evansenter
George . -- https://github.com/gardelea
Greg Weber -- https://github.com/gregwebs
Jeff Felchner -- https://github.com/jfelchner
Nikolaj Nikolajsen -- https://github.com/nikolajsen
Ryan Schlesinger -- https://github.com/ryansch
Sean Gallagher -- http://github.com/torandu
Stephan Hagemann -- https://github.com/shageman
Tim Harper -- http://github.com/timcharper
Tobias Crawley -- http://github.com/tobias
Thibaut Barrère -- https://github.com/thbar
Viktar Basharymau -- https://github.com/DNNX

License

http://www.dvorkin.net

%w(mike dvorkin.net) * "@" || %w(mike fatfreecrm.com) * "@"

Released under the MIT license. See LICENSE file for details.

10 KiB Raw Blame History