Obscenity

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

Installation

Add this line to your application's Gemfile:

gem 'obscenity'

And then execute:

bundle install

Or install it yourself as:

gem install obscenity

Compatibility

Obscenity is compatible with Ruby 1.9.X, Ruby 2.0.X, Rubinius 1.9, Rails 3.X, and Rack as a middleware. Starting with Rails 3, the profanity validation works with any ORM supported by ActiveModel, e.g: ActiveRecord, MongoMapper, Mongoid, etc.

Using Obscenity

The following methods are available to use with Obscenity:

Configuration

Obscenity.configure(&block) allows you to set custom global configuration options. Available options are:

config.blacklist accepts the following values:

An array with words
A string representing a path to a yml file
A Pathname object with a path to a yml file

config.whitelist accepts the following values:

An array with words
A string representing a path to a yml file
A Pathname object with a path to a yml file

config.replacement accepts the following values:

:default : Uses the :garbled method
:garbled : Replaces profane words with $@!#%
:stars : Replaces profane words with '*' up to the word's length
:vowels : Replaces the vowels in the profane word with '*'
:nonconsonants : Replaces non consonants with '*'
"custom string" : Replaces the profane word with the custom string

Example:

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

Basic Usage

Obscenity.profane?(text) analyses the content and returns true or false based on its profanity:

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

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

Obscenity.sanitize(text) sanities the content and returns a new sanitized content (if profane) or the original content (if not profane):

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

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

Obscenity.replacement(style).sanitize(text) allows you to pass the replacement method to be used when sanitizing the given content. Available replacement values are :default, :garbled, :stars, :vowels, and a custom string.

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(:nonconsonants).sanitize('Oh 5hit')
=> "Oh *h*t"

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

Obscenity.offensive(text) returns an array of profane words in the given content:

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

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

ActiveModel

The ActiveModel component provides easy profanity validation for your models.

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

# MongoMapper example
class Book
  include MongoMapper::Document

  key :title, String
  key :body,  String

  validates :title, obscenity: true
  validates :body,  obscenity: { sanitize: true, replacement: :vowels }
end

# Mongoid example
class Page
  include Mongoid::Document

  field :title, type: String
  field :body,  type: String

  validates :title, obscenity: true
  validates :body,  obscenity: { sanitize: true, replacement: :garbled }
end

The following usage is available:

obscenity: true : Does a profanity validation in the field using .profane? and returns true/false. If true, ActiveModel's Validation will return a default error message.

obscenity: { message: 'Custom message' } : Does a profanity validation in the field using .profane? and returns true/false. If true, ActiveModel's Validation will return your custom error message.

obscenity: { sanitize: true } : Silently sanitizes the field and replaces its content with the sanitized version. If the :replacement key is included, it will use that style when replacing the content.

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'

And to use the middleware, the basic syntax is:

use Rack::Obscenity, {} # options Hash

You need to use the options below inside the options Hash (above)

Rejecting Requests:

Any of the following options can be used to reject a request.

reject: true : will reject a request if any parameter value contains profanity.

use Rack::Obscenity, reject: true

reject: { params: [] } : will analyze the selected parameters and reject the request if their values contain profanity.

use Rack::Obscenity, reject: { params: [:foo, :bar] }

reject: { message: 'Custom message' } : will reject a request and display the custom message if any parameter value contains profanity

use Rack::Obscenity, reject: { message: "We don't allow profanity!" }

reject: { path: 'path/to/file' } : will reject a request and render the custom file if any parameter value contains profanity

use Rack::Obscenity, reject: { path: 'public/no_profanity.html' }

More usage example:

# Rejects the request for all params and renders a file
use Rack::Obscenity, reject: { params: :all, path: 'public/no_profanity.html' }

# Rejects the request based on the selected params and renders a file
use Rack::Obscenity, reject: { params: [:foo, :bar], path: 'public/no_profanity.html' }

# Rejects the request based on the selected params and displays a message
use Rack::Obscenity, reject: { params: [:foo, :bar], message: "Profanity is not allowed!" }

Sanitizing Requests:

Any of the following options can be used to sanitize a request.

sanitize: true : will sanitize all parameter values if they contain profanity.

use Rack::Obscenity, sanitize: true

sanitize: { params: [] } : will analyze the selected parameters and sanitize them if their values contain profanity.

use Rack::Obscenity, sanitize: { params: [:foo, :bar] }

sanitize: { replacement: (:default | :garbled | :stars | :vowels | 'custom') } : will use this replacement method when sanitizing parameter values

use Rack::Obscenity, sanitize: { replacement: :vowels }

More usage example:

# Sanitizes all params and replaces their values using :stars
use Rack::Obscenity, sanitize: { params: :all, replacement: :stars }

# Sanitizes the given params and replaces their values using a custom word
use Rack::Obscenity, sanitize: { params: [:foo, :bar], replacement: "[censored]" }

# Sanitizes all params and replaces their values using :garbled
use Rack::Obscenity, sanitize: { replacement: :garbled }

Test Helpers

Obscenity currently provides test helpers for RSpec only, but we have plans to add helpers to Shoulda as well.

RSpec Matcher

A be_profane matcher is available for RSpec. Its usage is very simple:

user.username.should_not be_profane

Contributing to obscenity

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history.

Authors

Thiago Jackiw: @tjackiw

michaelglass/obscenity