Errawr

A framework for effectively defining and raising localized errors.

Installation

Add this line to your application's Gemfile:

gem 'errawr'

And then execute:

$ bundle

Or install it yourself as:

$ gem install errawr

Usage

Defining and Raising Errors

Errawr uses I18n for easily managing error localizations. Just define an error in a locale file. Make sure to use the errawr key.

en:
  errawr:
    your_error:
      message: My awesome error message
      metadata:
        http_status: 400

Then just raise your exception using the #error! method.

begin
  Errawr.error!(:your_error)
rescue => e
  puts e.metadata[:http_status] # Will return 400
end

Need to add more locale files? Use I18n's standard load_path.

I18n.load_path += Dir.glob('lib/your_lib/locales/*.{rb,yml}')

Metadata

It's possible to add additional information to a registered error through metadata. Just specify a metadata hash when throwing an error:

begin
  Errawr.error!(:your_error, metadata: { http_status: 400 })
rescue => e
  puts e.metadata[:http_status] # Will return 400
end

I18n Interpolation

You can pass in parameter values to your localized error messages.

en
  errawr:
  your_error:
    message: "My awesome error message is: %{error_message}"

begin
  Errawr.error!(:your_error, error_message: 'You did it wrong!')
rescue => e
  puts e.message # Will return "My awesome error message is: You did it wrong!"
end

Overrides

It's possible to override metadata stored in a locale file both globally and on a per use basis.

en:
  errawr:
    your_error:
      message: My awesome error message
      metadata:
        http_status: 400

The #register! method will override the locale file.

Errawr.register!(:your_error, message: 'Some other error message', metadata: { http_status: 403 })
begin
  Errawr.error!(:your_error)
rescue => e
  puts e.message # => Will return "Some other error message"
  puts e.metadata[:http_status] # => Will return 403
end

The #error! method will override both #register! and the locale file.

Errawr.register!(:your_error, message: 'Some other error message', metadata: { http_status: 403 })
begin
  Errawr.error!(:your_error, message: 'Yet another error message', metadata: { http_status: 404 })
rescue => e
  puts e.message # => Will return "Yet another error message"
  puts e.metadata[:http_status] # => Will return 404
end

Custom Error Classes

Want to write a custom error class? No problem!

class YourError < Errawr::Error
  def your_method
     ...
  end
end

# Register your error with your custom class
Errawr.register!(:your_error, base_class: YourError)

# Do something with it
begin
  Errawr.error!(:your_error)
rescue => e
  e.your_method
end

Contributing

1. Fork it
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 new Pull Request

Credits

Errawr is maintained and funded by Sticksnleaves

Thanks to all of our contributors