Object Identifier

Object Identifier allows quick, easy, and uniform identification of an object by inspecting its class name and outputting any desirable attributes/methods. It is great for logging, sending descriptive notification messages, etc.

For example:

some_object.identify(:id, :name)

Which is the same as:

"#{some_object.class.name}[id:#{some_object.id}, name:\"#{some_object.name}\"]"

Installation

Add this line to your application's Gemfile:

gem "object_identifier"

And then execute:

$ bundle

Or install it yourself as:

$ gem install object_identifier

Compatibility

Tested MRI Ruby Versions:

• 2.2.10
• 2.3.7
• 2.4.4
• 2.5.1
• edge

Usage

Defaults

identify outputs the id of the receiving object by default, if it exists and no other attributes/methods are specified.

my_movie.identify           # => Movie[id:1]
my_movie.identify(:rating)  # => Movie[rating:"7/10"]

Private methods can be identified just the same as public methods.

my_movie.identify(:my_private_method)  # => Movie[my_private_method:"Shh"]

Unknown Attributes/Methods

If the object doesn't respond to a specified attribute/method it is simply ignored:

my_movie.identify(:gobble_gobble, :rating)  # => Movie[rating:"7/10"]

Overriding Class Names

my_delayed_job.identify(klass: "Delayed::Job")  # => Delayed::Job[id:1]
my_movie.identify(klass: nil)                   # => [id:1]

Identifying Nil

nil.identify(:id, :name)                 # => [no objects]
nil.identify(:id, :name, klass: "Nope")  # => [no objects]

Collections

Collections of objects are each identified in turn.

[my_movie, my_user].identify(:id, :name)
# => Movie[id:1, name:"Pi"], User[id:1, name:"Bob"]

The number of results that will be identified from a collection can be truncated by specifying the limit option.

[my_movie, my_contact].identify(:id, :name, limit: 1)
# => Movie[id:1, name:"Pi"], ... (1 more)

Empty Collections

[].identify  # => [no objects]
{}.identify  # => [no objects]

Custom Object Identifiers

Internally, Object Identifier calls inspect_lit to return a "literally-inspected" string representation of an object. This works because Object, itself, is monkey-patched to define inspect_lit which just returns inspect. This is sufficient for most objects, but some objects will benefit from defining special output from inspect_lit.

Object Identifier defines inspect_lit on three other core objects: String, Symbol, and BigDecimal.

"a_string".inspect_lit           # => "\"a_string\""
:a_symbol.inspect_lit            # => ":\"a_symbol\""
BigDecimal(1.99, 3).inspect_lit  # => "<BD:1.99>"

To identify an object in a special way, just define inspect_lit to return a custom String.

class MyValueObject
  def initialize(val)
    @val = val
  end

  def inspect_lit
    "#{@val} Meters"
  end
end

my_value_object = MyValueObject.new(42)
OpenStruct.new(my_value: my_value_object).identify(:my_value)
# => "OpenStruct[my_value:42 Meters]"

Supporting Gems

ObjectIdentifier works great with the ObjectInspector gem.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/pdobb/object_identifier.

License

The gem is available as open source under the terms of the MIT License.