Practical Ruby

Obscenity, a profanity filter for Ruby, ActiveModel, and Rack.

Obscenity is a profanity filter gem for Ruby/Rubinius, Rails (through ActiveModel), and Rack middleware.

What that means is that you can use Obscenity in plain Ruby or Rubinius, use it to validate and sanitize attributes in your models through ActiveModel (ActiveRecord, MongoMapper, Mongoid, etc), and use the Rack middleware to automatically reject requests that include profane parameters or sanitize those values before they reach your Application.

Enough said, let’s see some action!

Installation

If you’re using Bundler, add this line to your application’s Gemfile:

gem 'obscenity'

And then execute:

bundle install

Or install it yourself as:

gem install obscenity

Configuration

Obscenity allows you to set custom configuration options, including a blacklist, a whitelist, and the replacement method used when sanitizing profane text. Here’s how you configure Obscenity:

Obscenity.configure do |config|
  config.blacklist   = "path/to/blacklist/file.yml"
  config.whitelist   = ["safe", "word"]
  config.replacement = :stars
end

You can find more details about Obscenity’s configuration in the project’s github page.

Basic Usage

To check if a text contains profanity:

Obscenity.profane?("simple text")
=> false

Obscenity.profane?("text with shit")
=> true

To sanitize a text that may or may not include profanity:

Obscenity.sanitize("simple text")
=> "simple text"

Obscenity.sanitize("text with shit")
=> "text with $@!#%"

To use a custom replacement method when sanitizing a text:

Obscenity.replacement(:default).sanitize("text with shit")
=> "text with $@!#%"

Obscenity.replacement(:garbled).sanitize("text with shit")
=> "text with $@!#%"

Obscenity.replacement(:stars).sanitize("text with shit")
=> "text with ****"

Obscenity.replacement(:vowels).sanitize("text with shit")
=> "text with sh*t"

Obscenity.replacement("[censored]").sanitize("text with shit")
=> "text with [censored]"

To return the list of offensive words:

Obscenity.offensive("simple text")
=> []

Obscenity.offensive("text with shit and another biatch")
=> ["shit", "biatch"]

You can find more details about Obscenity’s basic usage in the project’s github page.

Using with ActiveModel

The ActiveModel component provides easy profanity validation for your models, and you can use it with any ORM that supports ActiveModel, e.g: ActiveRecord, MongoMapper, Mongoid, etc

First, you need to explicitly require the ActiveModel component:

require 'obscenity/active_model'

Then you can use it in your models as such:

# ActiveRecord example
class Post < ActiveRecord::Base
  validates :title, obscenity: true
  validates :body,  obscenity: { sanitize: true, replacement: "[censored]" }
end

Now that we have the model setup, let’s see what happens when we try creating a record that contains profanity:

  post = Post.new(title: "The story of an assclown", body: "Profane, like shit or assclown.")
  post.valid?
  => false
  post.errors.messages
  => {:title=>["cannot be profane"]}
  post.body
  => "Something profane, like [censored] or [censored]."

You can find more details about Obscenity’s ActiveModel usage in the project’s github page.

Using as a Rack middleware

You can use Obscenity as a Rack middleware to automatically reject requests that include profane parameter values or sanitize those values before they reach your Application.

First you need to explicitly require the Rack middleware:

require 'obscenity/rack'

Now, to reject requests, we simply do:

  use Rack::Obscenity, reject: true

And any parameters that contain profanity will cause the request to be rejected.

Alternatively, you can silently sanitize parameters that contain profanity:

  use Rack::Obscenity, sanitize: true

You can find more details about Obscenity’s Rack usage in the project’s github page.

What’s next?

I encourage you reading the full documentation in the project’s github page to better understand the ins-and-outs of this gem. As always, feedback, bug report and contribution are always welcome.