NOTE: This project is no longer maintened.

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)

config.blacklist

• 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

• 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

• :default : Uses the :garbled method
• :garbled : Replaces profane words with [email protected]!#%
• :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)

true

false

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

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

Obscenity.sanitize(text)

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

Obscenity.sanitize("text with shit")
=> "text with [email protected]!#%"

Obscenity.replacement(style).sanitize(text)

:default

:garbled

:stars

:vowels

Obscenity.replacement(:default).sanitize("text with shit")
=> "text with [email protected]!#%"

Obscenity.replacement(:garbled).sanitize("text with shit")
=> "text with [email protected]!#%"
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 ht"
Obscenity.replacement("[censored]").sanitize("text with shit")
=> "text with [censored]"

Obscenity.offensive(text)

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

.profane?

true/false

obscenity: { message: 'Custom message' }

.profane?

true/false

obscenity: { sanitize: true }

:replacement

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

use Rack::Obscenity, reject: true

reject: { params: [] }

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

reject: { message: 'Custom message' }

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

reject: { path: 'path/to/file' }

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

use Rack::Obscenity, sanitize: true

sanitize: { params: [] }

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

sanitize: { replacement: (:default | :garbled | :stars | :vowels | 'custom') }

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

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

Copyright

Copyright (c) 2012 Thiago Jackiw. See LICENSE.txt for further details.