StripAttributes

StripAttributes is an ActiveModel extension that automatically strips leading and trailing whitespace from string-valued attributes before validation. If the resulting string is blank, it converts the value to nil by default.

It works by adding a before_validation hook to the record. By default, all string-valued attributes are stripped of whitespace, but :only and :except options can be used to limit which attributes are stripped. Both options accept a single attribute (only: :field) or arrays of attributes (except: [:field1, :field2, :field3]).

It's also possible to skip stripping the attributes altogether per model using the :if and :unless options.

• Installation
• Quick Start
• Options Reference
• Whitespace and Blank Values
• Examples
• Usage Patterns
• Testing Your Models
• Support
• Contributing
• Versioning and Changelog

Include the gem in your Gemfile:

gem "strip_attributes"

For a Rails model with a name attribute:

class User < ApplicationRecord
  strip_attributes only: :name
end

user = User.new(name: "  Ada Lovelace \t")
user.name # => "  Ada Lovelace \t"

user.valid?
user.name # => "Ada Lovelace"

Attributes are normalized before validation, rather than on assignment. Calling valid? updates the selected attributes in memory even without saving the record, and even if validation fails. A normal save also runs validation and triggers normalization. Operations that skip validations, such as save(validate: false) and update_columns, do not trigger this hook.

Pass options to strip_attributes in your model:

With compatible string encodings, collapse_spaces handles tabs, Unicode horizontal whitespace, and the selected invisible characters described below. For incompatible encodings, it only collapses repeated ordinary spaces.

Use either only or except in a declaration. If both are supplied, except takes precedence and only is ignored.

Each strip_attributes declaration registers a separate validation callback. Multiple declarations can apply different options to different attributes; overlapping selections can process the same attribute more than once.

Only String values are processed. Numbers, booleans, arrays, hashes, and nil are left unchanged. Strings nested inside arrays or hashes are not processed.

By default, leading and trailing whitespace is removed, while internal whitespace is preserved. Empty strings and strings containing only whitespace become nil. Use allow_empty: true to keep stripped empty strings as "".

The following examples use Ruby string notation (\t is a tab and \n is a newline):

With compatible string encodings, trimming also handles Unicode whitespace and selected invisible characters, including nonbreaking spaces (U+00A0) and zero-width spaces (U+200B). A string containing only these characters also becomes nil by default. For incompatible encodings, trimming falls back to Ruby's String#strip behavior.

class DrunkPokerPlayer < ActiveRecord::Base
  strip_attributes
end

# all attributes will be stripped except :boxers
class SoberPokerPlayer < ActiveRecord::Base
  strip_attributes except: :boxers
end

# only :shoe, :sock, and :glove attributes will be stripped
class ConservativePokerPlayer < ActiveRecord::Base
  strip_attributes only: [:shoe, :sock, :glove]
end

The if and unless options accept a predicate method name or a proc. The condition is evaluated each time validation runs.

This example normalizes email unless the record's preserve_whitespace flag is set to true:

class User < ActiveRecord::Base
  attr_accessor :preserve_whitespace

  strip_attributes only: :email, if: :normalize_email?

  def normalize_email?
    !preserve_whitespace
  end
end

The same behavior can be expressed with unless and a proc:

class User < ActiveRecord::Base
  attr_accessor :preserve_whitespace

  strip_attributes only: :email, unless: ->(record) { record.preserve_whitespace }
end

# Empty attributes will not be converted to nil
class BrokePokerPlayer < ActiveRecord::Base
  strip_attributes allow_empty: true
end

# Sequential spaces in attributes will be collapsed to one space
class EloquentPokerPlayer < ActiveRecord::Base
  strip_attributes collapse_spaces: true
end

# Newlines in attributes will be replaced with a space
class EloquentPokerPlayer < ActiveRecord::Base
  strip_attributes replace_newlines: true
end

The regex option removes matching characters throughout the string before normal leading and trailing whitespace trimming. It supplements the default trimming behavior rather than replacing it.

class User < ActiveRecord::Base
  # Remove non-alphabetic, non-whitespace characters
  strip_attributes only: [:first_name, :last_name], regex: /[^[:alpha:]\s]/

  # Remove non-digit characters
  strip_attributes only: :phone, regex: /[^0-9]/

  # Keep only alphanumeric characters, underscores, and hyphens
  strip_attributes only: :nickname, regex: /[^[:alnum:]_-]/

  # Remove trailing horizontal whitespace from each line
  strip_attributes only: :code, regex: /[[:blank:]]+$/
end

In the multiline example, normal trimming also removes leading whitespace at the beginning of the entire string and trailing whitespace at its end.

It also works on other ActiveModel classes, such as Mongoid documents:

class User
  include Mongoid::Document
  strip_attributes only: :email
end

class Person
  include ActiveAttr::Model
  include ActiveModel::Validations::Callbacks

  attribute :name
  attribute :email

  strip_attributes
end

# where record is an ActiveModel instance
StripAttributes.strip(record, collapse_spaces: true)

# works directly on Strings too
StripAttributes.strip(" foo \t") #=> "foo"
StripAttributes.strip(" foo   bar", collapse_spaces: true) #=> "foo bar"

StripAttributes provides an RSpec/Shoulda-compatible matcher for easier testing of attribute normalization during validation. The matcher assigns test values, calls valid?, and checks the resulting attribute values. You can use it with RSpec, Shoulda, Minitest-MatchersVaccine (preferred), or Minitest-Matchers.

require "strip_attributes/matchers"
RSpec.configure do |config|
  config.include StripAttributes::Matchers
end

require "strip_attributes/matchers"
class Test::Unit::TestCase
  extend StripAttributes::Matchers
end

OR if in a Rails environment, you might prefer this:

require "strip_attributes/matchers"
class ActiveSupport::TestCase
  extend StripAttributes::Matchers
end

Add the adapter gem to your Gemfile and run bundle install:

gem "minitest-matchers_vaccine", group: :test

Then add this to your test_helper.rb:

require "minitest/autorun"
require "minitest/matchers_vaccine"
require "strip_attributes/matchers"
class Minitest::Spec
  include StripAttributes::Matchers
end

OR if in a Rails environment, you might prefer this:

require "minitest/matchers_vaccine"
require "strip_attributes/matchers"
class ActiveSupport::TestCase
  include StripAttributes::Matchers
end

Add the adapter gem to your Gemfile and run bundle install:

gem "minitest-matchers", group: :test

Then add this to your test_helper.rb:

require "minitest/autorun"
require "minitest/matchers"
require "strip_attributes/matchers"
class Minitest::Spec
  include StripAttributes::Matchers
end

The matcher uses "string" as its default test value. Use .using("AAPL") to provide a value that remains unchanged by other setters or callbacks, such as one that uppercases a stock ticker. The matcher adds whitespace around that value and expects it to be removed during validation.

A positive multi-attribute matcher requires every listed attribute to match. Negating it only establishes that at least one attribute does not match. Use separate negative assertions to check that each attribute preserves whitespace, as shown below.

RSpec:

describe User do
  it { is_expected.to strip_attribute(:name).collapse_spaces }
  it { is_expected.to strip_attribute(:name).replace_newlines }
  it { is_expected.to strip_attribute :email }
  it { is_expected.to strip_attributes(:name, :email) }
  it { is_expected.to strip_attributes(:ticker).using("AAPL") }
  it { is_expected.not_to strip_attribute :password }
  it { is_expected.not_to strip_attribute :encrypted_password }
end

Shoulda (with test-unit):

class UserTest < ActiveSupport::TestCase
  should strip_attribute(:name).collapse_spaces
  should strip_attribute(:name).replace_newlines
  should strip_attribute :email
  should strip_attributes(:name, :email)
  should strip_attributes(:ticker).using("AAPL")
  should_not strip_attribute :password
  should_not strip_attribute :encrypted_password
end

Minitest-MatchersVaccine:

describe User do
  subject { User.new }

  it "should strip attributes" do
    must strip_attribute(:name).collapse_spaces
    must strip_attribute(:name).replace_newlines
    must strip_attribute :email
    must strip_attributes(:name, :email)
    must strip_attributes(:ticker).using("AAPL")
    wont strip_attribute :password
    wont strip_attribute :encrypted_password
  end
end

Minitest-Matchers:

describe User do
  subject { User.new }

  must { strip_attribute(:name).collapse_spaces }
  must { strip_attribute(:name).replace_newlines }
  must { strip_attribute :email }
  must { strip_attributes(:name, :email) }
  must { strip_attributes(:ticker).using("AAPL") }
  wont { strip_attribute :password }
  wont { strip_attribute :encrypted_password }
end

Submit suggestions or feature requests as a GitHub Issue or Pull Request (preferred). If you send a pull request, remember to update the corresponding unit tests. In fact, I prefer new features to be submitted in the form of new unit tests.

The idea was originally triggered by the information at the (now defunct) Rails Wiki but was modified from the original to include more idiomatic ruby and rails support.

StripAttributes follows Semantic Versioning 2.0. See CHANGELOG.md for release notes and changes between versions.

MIT License