strip_attributes

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.

Contents

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

Installation

Include the gem in your Gemfile:

gem "strip_attributes"

Quick Start

For a Rails model with a name attribute:

class User  "  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.

Options Reference

Pass options to strip_attributes in your model:

Option	Accepted values	Default	Effect
only	Attribute name as a symbol or string, or an array of names	All attributes	Process only the named attributes.
except	Attribute name as a symbol or string, or an array of names	No exclusions	Skip the named attributes.
allow_empty	true or false	Disabled	Keep stripped empty strings as "" instead of converting them to nil. Existing nil values remain nil.
collapse_spaces	true or false	Disabled	Replace runs of horizontal whitespace with one space, preserving internal newlines.
replace_newlines	true or false	Disabled	Replace runs of carriage returns (\r) and line feeds (\n) with one space. Surrounding spaces remain unless collapse_spaces is also enabled.
regex	Regular expression	None	Remove all matches before normal whitespace trimming.
if	Predicate method name as a symbol or a proc	No condition	Run the validation callback only when the condition is truthy.
unless	Predicate method name as a symbol or a proc	No condition	Skip the validation callback when the condition is truthy.

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.

Whitespace and Blank Values

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):

Input	Options	Result
" \t "	Default	nil
" \t "	allow_empty: true	""
"a b"	Default	"a b"
"a \n b"	collapse_spaces: true	"a \n b"
"a \n b"	replace_newlines: true	"a b"
"a \n b"	replace_newlines: true, collapse_spaces: true	"a b"

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.

Examples

Default Behavior

class DrunkPokerPlayer (record) { record.preserve_whitespace }
end

Using allow_empty

# Empty attributes will not be converted to nil
class BrokePokerPlayer  "foo"
StripAttributes.strip(" foo   bar", collapse_spaces: true) #=> "foo bar"

Testing Your Models

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.

Setup spec_helper.rb or test_helper.rb

To initialize RSpec, add this to your spec_helper.rb:

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

To initialize Shoulda (with test-unit), add this to your test_helper.rb:

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

Minitest-MatchersVaccine

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

Minitest-Matchers

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

Writing Tests

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

Support

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.

Credits

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.

Versioning and Changelog

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

License

MIT License