sullivan 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b993257c0f51eb41768a9c272798cd6ec6caa160
-  data.tar.gz: 5e15408676c3ad43fb4645581120072914ae60aa
+  metadata.gz: facd94a17e179bef5d7a3caa27a183b1bc855a9c
+  data.tar.gz: 1abdb5a1efee46327163f3bf68eb5d43c825ceaa
 SHA512:
-  metadata.gz: da18cbc61e3cff2bb8e1715126a9e46dd8ead724d719a5c8534eb3717074fac16568ac9127bc461aeb32515d30981400e925e3c7c4e4511abef429f51ce8e675
-  data.tar.gz: 13dece6a3657c7e653b87db7847ef42ad6faee4db2c6ee70cc52d62295ab05f08c4781bb3f5913843dee6a4499a6805797a168bd849cb9475773c71ef5ad34d8
+  metadata.gz: 79388d55c6f019930dcfb8607927021190678d4967c11daf7ca20a734b18708a93c0f3f161e646430e3791b5b3a92e2bb5cabe96822c588790d64a5600e6648c
+  data.tar.gz: c9e6f2c9d92a24844d9e764cc37f30be64000f96947abd5edf3830db7c7fd05d9bf2d5858f609b9616593a3a4f9a46acd82c5c071a1921ce4e214e8c6b22fc57

data/README.md

@@ -1,6 +1,78 @@
 # Sullivan
 
-TODO: Write a gem description
+<img src="doc/img/LouisSullivan.jpg" alt="Louis Sullivan" align="right" />
+
+> It is the pervading law of all things organic and inorganic,  
+> Of all things physical and metaphysical,  
+> Of all things human, and all things super-human,  
+> Of all true manifestations of the head,  
+> Of the heart, of the soul,  
+> That the life is recognizable in its expression,  
+> That **form ever follows function**. This is the law.  
+> <cite>— Louis Sullivan, 1896</cite>
+
+**Sullivan** is a functional, composable, simple way to validate nested data
+structures. It generates validation errors which are especially suitable for
+API responses.
+
+Sullivan doesn't do much, because it doesn't need to. It's three things:
+
+1. A simple pattern for defining validators,
+2. A handful of useful, composable validators provided for free, and
+3. Some syntactic sugar for using the built-in validators.
+
+## Example
+
+
+```ruby
+require 'sullivan'
+
+laugh_session_validation = Sullivan.validation do
+  laugh = hash(
+    sound: string_matching(/\Al(ol)+\z/, error: "must be be a laughing sound of some length"),
+    intensity: optional(kind_of(Numeric))
+  )
+
+  hash(
+    primary_laugh:   laugh,
+    rebound_giggles: many(laugh)
+  )
+end
+
+laugh_session = {
+  primary_laugh: {
+    sound: "lolololol",
+    intensity: "High"
+  },
+  rebound_giggles: [
+    {
+      sound: "lololol",
+      intensity: 2
+    },
+    {
+      sound: "sigh",
+      mood: "pleasant"
+    }
+  ]
+}
+
+laugh_session_validation.validate(laugh_session)
+
+# =>
+# {
+#   :primary_laugh => {
+#     :intensity => "must be a kind of Numeric, if present"
+#   },
+#   :rebound_giggles => [
+#     nil,
+#     {
+#       :sound => "must be be a laughing sound of some length",
+#       :mood => "is unexpected"
+#     }
+#   ]
+# }
+```
+
 
 ## Installation
 
@@ -18,11 +90,161 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Like it says above, Sullivan is three things.
+
+### `validate`: A simple pattern for defining validators.
+
+Sullivan specifies a simple API for defining validators. It's so simple, you
+don't need Sullivan to use it. All you need is an object which responds to
+`#validate`. If it fails to validate, it should return an error message (a
+string). If it passes validation, it should return `nil`. That's all there is
+to it.
+
+If your validator takes parameters, it might make sense to write it as a class
+and instantiate it:
+
+
+```ruby
+class LegalVotingAge
+  def initialize(country:)
+    @minimum_age =
+      case country
+      when :united_states
+        18
+      when :austria
+        16
+      else
+        raise "Don't know the voting age in #{country}"
+      end
+  end
+
+  def validate(age)
+    "is too young to vote" if age < @minimum_age
+  end
+end
+
+LegalVotingAge.new(:united_states).validate(17) #=> "is too young to vote"
+LegalVotingAge.new(:austria).validate(17)       #=> nil
+```
+
+If your validator doesn't take parameters, you might want to just make it an
+object:
+
+```ruby
+ApiBoolean = Object.tap do |v|
+  def v.validate(value)
+    "must be a boolean value" unless [true, false, 'true', 'false'].include?(value)
+  end
+end
+
+ApiBoolean.validate(true)       #=> nil
+ApiBoolean.validate('false')    #=> nil
+ApiBoolean.validate('not sure') #=> "must be a boolean value"
+```
+
+Sullivan doesn't care. In fact, Sullivan-the-libary isn't even involved yet.
+
+### `Sullivan::Validators`: A handful of useful, composable validators provided for free
+
+Sometimes you need a really custom validator, but there are a few staples we
+need in all sorts of projects. Sullivan provides those, including some
+**higher-order validators** (validators which take other validators as
+parameters, like `Hash` and `Optional`), which is where Sullivan's
+composability really shines.
+
+Sullivan's built-in validators live in `Sullivan::Validators`. Look there to
+read more about each one.
+
+
+### `Sullivan.validation`: Some syntactic sugar for using the built-in validators
+
+The built-in validators are a bit cumbersome to instantiate, considering you'll
+be using them quite a bit. To help, there's `Sullivan.validation`. Within its
+block, you can instantiate the validators in `Sullivan::Validators` as
+`snake_cased` methods. So:
+
+```ruby
+v = Sullivan.validation do
+  hash({})
+end
+
+v.class #=> Sullivan::Validators::Hash
+```
+
+There's one catch: because this uses `instance_eval`, inside the block `self`
+will not be the same as `self` outside the block, so you can't use method calls
+the way you might like to. That is, this won't work:
+
+```ruby
+class User
+  def valid_username_regex
+    %r{\w+}
+  end
+
+  def validation
+    Sullivan.validation do
+      string_matching(valid_username_regex)
+        #=> NameError: undefined local variable or method `valid_username_regex' for #<Sullivan::DSL:0x007fa5c44e1508>
+    end
+  end
+end
+```
+
+If you need to do something like that, you can use the 1-arity form of the block, for a slightly more verbose syntax:
+
+```ruby
+class User
+  def valid_username_regex
+    %r{\w+}
+  end
+
+  def validation
+    Sullivan.validation do |vals|
+      vals.string_matching(valid_username_regex)
+    end
+  end
+end
+```
+
+Of course, `Sullivan.validation` is completely optional. Feel free to instantiate the validation classes directly.
+
+
+### Composition: Bringing it all together
+
+This is where it gets fun. Let's say you're validating API input. Suppose you
+have an API that can create a Person record and one that can create multiple
+Person records at once. You might have validations like:
+
+```ruby
+module Validations
+  Person = Sullivan.validation do
+    hash(
+      name: kind_of(String),
+      favorite_ice_cream_flavor: optional(kind_of(String))
+    )
+  end
+
+  PersonCreation = Sullivan.validation do
+    hash(person: Person)
+  end
+
+  PeopleCreation = Sullivan.validation do
+    hash(people: many(Person))
+  end
+end
+```
+
+Now your API could use `Validations::PersonCreation.validate` and `Validations::PeopleCreation.validate`
+to validate the two kinds of requests.
+
+Notice that I've assigned these validators to constants in a module. That's a
+useful pattern in some cases, but it's completely optional. Store them wherever
+they're most useful in your application. They're just objects.
+
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/sullivan/fork )
+1. Fork it ( http://github.com/Peeja/sullivan/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/sullivan.rb

@@ -1,6 +1,15 @@
 module Sullivan
   def self.validation(&block)
-    DSL.new.instance_eval(&block)
+    dsl = DSL.new
+
+    case block.arity
+    when 0
+      dsl.instance_eval(&block)
+    when 1
+      block.call(dsl)
+    else
+      raise ArgumentError.new("Sullivan.validation's block must have an arity of 0 or 1.")
+    end
   end
 
   class DSL < BasicObject

data/lib/sullivan/version.rb

@@ -1,3 +1,3 @@
 module Sullivan
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/sullivan_spec.rb

@@ -6,7 +6,7 @@ describe Sullivan do
       v = Sullivan.validation do
         hash(
           string_matching: string_matching(/\Al(ol)+\z/, error: "must be be a laugh"),
-          kind_of: kind_of(Numeric),
+          kind_of: kind_of(Numeric)
         )
       end
 
@@ -15,5 +15,25 @@ describe Sullivan do
       expect(error[:string_matching]).to eq("must be be a laugh")
       expect(error[:kind_of]).to eq("must be a kind of Numeric")
     end
+
+    it "uses a non-instance-eval version when the block has an arity of 1" do
+      v = Sullivan.validation do |vals|
+        expect(a_method_on_self).to eq("can be called without an error")
+
+        vals.hash(
+          string_matching: vals.string_matching(/\Al(ol)+\z/, error: "must be be a laugh"),
+          kind_of: vals.kind_of(Numeric)
+        )
+      end
+
+      error = v.validate({})
+
+      expect(error[:string_matching]).to eq("must be be a laugh")
+      expect(error[:kind_of]).to eq("must be a kind of Numeric")
+    end
+
+    def a_method_on_self
+      "can be called without an error"
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sullivan
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Peter Jaros
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-07 00:00:00.000000000 Z
+date: 2014-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler