A Ruby Hash specification to ensure unstructured data is structured the way you expect it.
The design goal is write specifications in terms of the object that is being validated. For example, I want to write a
specification as a Hash, as opposed to a DSL, when validating a Hash.
Add this line to your application's Gemfile:
gem 'xpect'
And then execute:
$ bundle
Or install it yourself as:
$ gem install xpect
Verify that Hashes are the structure you expect at the on-set, as opposed to finding out a Hash isn't structured
the way you intended deep in a function body. This can be useful for various reasons, such as:
Hashes (or JSON, just parse it first) conform to a particular structuredef some_function(hash_payload)
spec = {
person: {
name: {
first: Xpect::Matchers.truthy,
last: Xpect::Matchers.truthy,
middle: Xpect::Matchers.anything,
},
footwear: lambda {|v| ['flip flops', 'flip flops and socks', 'hiking boots'].include?(v) },
state: 'GA',
age: lambda {|v| v >= 0 }
}
}
Xpect::Spect.validate!(spec: spec, data: hash_payload)
# Continue processing data knowing that the Hash contains valid data.
end
.conform! vs .validate!.validate! ensures the data (i.e. the Hash) adheres to the structure according to the spec (i.e. validates the data).
If the data is valid then it returns the data it was given. .conform! validates the data according to the spec, just like
.validate!, but it returns only the data specified in the spec. Both functions raise a Xpect::FailedSpec if the data
does not adhere to the structure of the spec.
.validate!spec = {
name: 'Andre 3000',
age: lambda {|v| v > 40 }
}
# Passes
validated_data = Xpect::Spect.validate!(
spec: spec,
data: {
name: 'Andre 3000',
age: 47,
footwear: 'flip flops and socks'
}
)
puts validated_data
# {
# name: 'Andre 3000',
# age: 47,
# foot_wear: 'flip flops and socks'
# }
# Fails and raises Xpect::FailedSpec
Xpect::Spect.validate!(
spec: spec,
data: {
name: 'Andre 3000',
age: 4, # Not greater than 40 as specified in spec
footwear: 'flip flops and socks'
}
)
.conform!spec = {
name: 'Andre 3000',
age: lambda {|v| v > 40 }
}
# Passes
conformed_data = Xpect::Spect.conform!(
spec: spec,
data: {
name: 'Andre 3000',
age: 47,
footwear: 'flip flops and socks'
}
)
puts conformed_data
# {
# name: 'Andre 3000',
# age: 47,
# }
# Fails and raises Xpect::FailedSpec
Xpect::Spect.conform!(
spec: spec,
data: {
name: 'Andre 3000',
age: 4, # Not greater than 40 as specified in spec
footwear: 'flip flops and socks'
}
)
Hash valuestruthyspec = { name: Xpect::Matchers.truthy }
# Passes
Xpect::Spect.validate!(spec: spec, data: { name: 'Andre 3000'})
# Fails
Xpect::Spect.validate!(spec: spec, data: { name: false})
falsyspec = { name: Xpect::Matchers.falsy }
# Passes
Xpect::Spect.validate!(spec: spec, data: { name: ''})
# Fails
Xpect::Spect.validate!(spec: spec, data: { name: 'Andre 3000'})
anythingspec = { name: Xpect::Matchers.anything }
# Passes
Xpect::Spect.validate!(spec: spec, data: { name: nil})
Xpect::Spect.validate!(spec: spec, data: { name: 'Andre 3000'})
# Fails
Xpect::Spect.validate!(spec: spec, data: {})
nilspec = { name: Xpect::Matchers.nil }
# Passes
Xpect::Spect.validate!(spec: spec, data: { name: nil})
# Fails
Xpect::Spect.validate!(spec: spec, data: { name: 'Andre 3000'})
spec = { name: lambda {|v| ['Andre 3000', 'Big Boi'].include?(v) } }
# Passes
Xpect::Spect.validate!(spec: spec, data: { name: 'Big Boi'})
Xpect::Spect.validate!(spec: spec, data: { name: 'Andre'})
# Fails
Xpect::Spect.validate!(spec: spec, data: { name: 'Back Street Boys'})
Predspec = {
name: Xpect::Pred.new(
pred: lambda {|v| ['Andre 3000', 'Big Boi'].include?(v) }
)
}
# Passes
Xpect::Spect.validate!(spec: spec, data: { name: 'Big Boi'})
Xpect::Spect.validate!(spec: spec, data: { name: 'Andre'})
# Fails
Xpect::Spect.validate!(spec: spec, data: { name: 'Back Street Boys'})
Providing a default value
spec = {
name: Xpect::Pred.new(
pred: lambda {|v| ['Andre 3000', 'Big Boi'].include?(v) },
default: 'Dr. Seuss'
)
}
# Passes
Xpect::Spect.validate!(spec: spec, data: { name: 'Big Boi'})
Xpect::Spect.validate!(spec: spec, data: { name: 'Andre'})
validated_data = Xpect::Spect.validate!(spec: spec, data: {})
puts validated_data
# { name: 'Dr. Seuss' }
# Fails
Xpect::Spect.validate!(spec: spec, data: { name: 'Back Street Boys'})
Exact item comparison
spec = {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops'
},
{
name: 'Big Boi',
footwear: 'flip flops and socks'
}
]
}
# Passes
Xpect::Spect.validate!(
spec: spec,
data: {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops'
},
{
name: 'Big Boi',
footwear: 'flip flops and socks'
}
]
}
)
# Passes
Xpect::Spect.validate!(
spec: spec,
data: {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops'
},
{
name: 'Big Boi',
footwear: 'flip flops and socks'
},
{
name: 'CeeLo Green',
footwear: 'boots'
}
]
}
)
# Fails - missing second item in array in spec
Xpect::Spect.validate!(
spec: spec,
data: {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops'
}
]
}
)
Ensuring every item in Array meets specification
spec = {
people: Xpect::Every.new(
{
name: Xpect::Matchers.truthy,
footwear: lambda {|v| ['flip flops', 'flip flops and socks'].include?(v) }
}
)
}
# Passes
Xpect::Spect.validate!(
spec: spec,
data: {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops'
},
{
name: 'Big Boi',
footwear: 'flip flops and socks'
}
]
}
)
# Passes
Xpect::Spect.validate!(
spec: spec,
data: {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops'
},
{
name: 'Big Boi',
footwear: 'flip flops and socks'
},
{
name: 'CeeLo Green',
footwear: 'flip flops'
}
]
}
)
# Fails
Xpect::Spect.validate!(
spec: spec,
data: {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops'
},
{
name: 'Big Boi',
footwear: 'flip flops and socks'
},
{
name: 'Travis',
footwear: 'Hiking Boots' # footwear does not adhere to specification
}
]
}
)
Hash keysRequiring keys
spec = {
person: Xpect::Keys.new(
required: {
name: 'Andre 3000',
footwear: lambda {|v| ['flip flops', 'socks'].include?(v) }
}
),
}
# Passes
Xpect::Spect.validate!(
spec: spec,
data: {
person: {
name: 'Andre 3000',
footwear: 'socks',
age: 45
}
}
)
# Fails
Xpect::Spect.validate!(
spec: spec,
data: {
person: {
footwear: 'socks',
age: 45 # Missing the `name` key as specified in spec
}
}
)
Optional keys
spec = {
person: Xpect::Keys.new(
required: {
name: 'Andre 3000',
footwear: lambda {|v| ['flip flops', 'socks'].include?(v) }
},
optional: {
style: 'ice cold'
}
),
}
# Passes
Xpect::Spect.validate!(
spec: spec,
data: {
person: {
name: 'Andre 3000',
footwear: 'socks',
age: 45
}
}
)
Xpect::Spect.validate!(
spec: spec,
data: {
person: {
name: 'Andre 3000',
footwear: 'socks',
age: 45,
style: 'ice cold'
}
}
)
# Fails
Xpect::Spect.validate!(
spec: spec,
data: {
person: {
footwear: 'socks',
age: 45,
style: 'too hot for the hot tub' # Does not meet specification
}
}
)
spec = {
people: Xpect::Every.new(
{
name: Xpect::Matchers.truthy,
footwear: lambda {|v| ['flip flops', 'flip flops and socks'].include?(v) },
things: [
1,
2,
3,
{a: 'a'},
[
'one',
'two',
Xpect::Pred.new(
pred: lambda {|v| v == 'three'},
default: 'my-default'
)
]
],
other: Xpect::Keys.new(
required: {
b: 'b',
c: 'c',
f: [
4,
5,
6,
lambda {|v| v > 8},
],
g: Xpect::Every.new(
{
id: lambda {|v| v > 100}
}
)
},
optional: {d: 'd', e: 'e'}
)
}
),
}
# Passes
conformed_data = Xpect::Spect.conform!(
spec: spec,
data: {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops',
not_required_by_spec: 'not_required_by_spec',
things: [
1,
2,
3,
{a: 'a'},
[
'one',
'two'
]
],
other: {
b: 'b',
c: 'c',
e: 'e',
f: [
4,
5,
6,
9
],
g: [
{
id: 101,
},
{
id: 102
}
],
not_required_by_spec: [1, 2, 3, 4]
}
}
]
}
)
puts conformed_data
# {
# :people => [
# {
# :name => "Andre 3000",
# :footwear => "flip flops",
# :things => [1, 2, 3, {:a => "a"}, ["one", "two", "my-default"]],
# :other => {:b => "b", :c => "c", :f => [4, 5, 6, 9], :g => [{:id=>101}, {:id => 102}], :e => "e"}
# }
# ]
# }
# Fails
Xpect::Spect.conform!(
spec: spec,
data: {
people: [
{
name: 'Andre 3000',
footwear: 'flip flops',
not_required_by_spec: 'not_required_by_spec',
things: [
1,
2,
3,
{a: 'a'},
[
'one',
'two'
]
],
other: {
b: 'b',
c: 'c',
e: 'e',
f: [
4,
5,
6,
9
],
g: [
{
id: 101,
},
{
id: 2 # Not greater than 100 as specified in spec
}
],
not_required_by_spec: [1, 2, 3, 4]
}
}
]
}
)
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/tdouce/xpect. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Xpect project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
FAQs
Unknown package
We found that xpect demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.