cistern 0.2.1 → 0.2.2

data/README.md

@@ -1,26 +1,183 @@
 # Cistern
 
 [![Build Status](https://secure.travis-ci.org/lanej/cistern.png)](http://travis-ci.org/lanej/cistern)
+[![Dependencies](https://gemnasium.com/lanej/cistern.png)](https://gemnasium.com/lanej/cistern.png)
 
-TODO: Write a gem description
+Cistern helps you consistenly build your API clients and faciliates building mock support.
 
-## Installation
+## Usage
 
-Add this line to your application's Gemfile:
+### Service
 
-    gem 'cistern'
+This represents the remote service that you are wrapping. If the service name is 'foo' then a good name is 'Foo::Client'.
 
-And then execute:
+Service initialization will only accept parameters enumerated by ```requires``` and ```recognizes```. ```model```, ```collection```, and ```request``` enumerate supported features and require them directly within the context of the ```model_path``` and ```request_path```.
 
-    $ bundle
+```Mock.data``` is commonly used to store mock data.  It is often easiest to use identity to raw response mappings within the ```Mock.data``` hash.
 
-Or install it yourself as:
+```ruby
 
-    $ gem install cistern
+class Foo::Client < Cistern::Service
 
-## Usage
+  model_path "foo/models"
+  request_path "foo/requests"
+
+  model :bar
+  collection :bars
+  request :create_bar
+  request :get_bar
+  request :get_bars
+
+  requires :hmac_id, :hmac_secret
+  recognizes :host
+
+  class Real
+    def initialize(options={})
+      # setup connection
+    end
+  end
+
+  class Mock
+    def self.data
+      @data ||= {
+                  :bars => {},
+                }
+    end
+
+    def self.reset!
+      @data = nil
+    end
+
+    def data
+      self.class.data
+    end
+    def initialize(options={})
+      # setup mock data
+    end
+  end
+end
+
+```
+
+### Model
+
+```connection``` represents the associated ```Foo::Client``` instance.
+
+```ruby
+
+class Foo::Client::Bar < Cistern::Model
+  identity :id
+
+  attribute :flavor
+  attribute :keypair_id, aliases: "keypair",  squash: "id"
+  attribute :private_ips, type: :array
+
+  def destroy
+    params  = {
+      "id" => self.identity
+    }
+    self.connection.destroy_bar(params).body["request"]
+  end
+
+  def save
+    requires :keypair_id
+
+    params = {
+      "keypair" => self.keypair_id,
+      "bar"     => {
+        "flavor" => self.flavor,
+      },
+    }
+
+    if new_record?
+      request_attributes = connection.create_bar(params).body["request"]
+      merge_attributes(new_attributes)
+    end
+  end
+end
+
+```
+
+### Collection
+
+```model``` tells Cistern which class is contained within the collection.  ```Cistern::Collection``` inherits from ```Array``` and lazy loads where applicable.
+
+```ruby
+
+class Foo::Client::Bars < Cistern::Collection
+
+  model Foo::Client::Bar
+
+  def all(params = {})
+    response = connection.get_bars(params)
+
+    data = self.clone.load(response.body["bars"])
+
+    collection.attributes.clear
+    collection.merge_attributes(data)
+  end
+
+  def discover(provisioned_id, options={})
+    params = {
+      "provisioned_id" => provisioned_id,
+    }
+    params.merge!("location" => options[:location]) if options.key?(:location)
+
+    connection.requests.new(connection.discover_bar(params).body["request"])
+  end
+
+  def get(id)
+    if data = connection.get_bar("id" => id).body["bar"]
+      new(data)
+    else
+      nil
+    end
+  end
+end
+
+```
+
+### Request
+
+```ruby
+
+module Foo
+  class Client
+    class Real
+      def create_bar(options={})
+        request(
+          :body     => {"bar" => options},
+          :method   => :post,
+          :path     => '/bar'
+        )
+      end
+    end # Real
+
+    class Mock
+      def create_bar(options={})
+        id = Foo.random_hex(6)
+
+        bar = {
+          "id" => id
+        }.merge(options)
+
+        self.data[:bars][id]= bar
+
+        response(
+          :body   => {"bar" => bar},
+          :status => 201,
+          :path => '/bar',
+        )
+      end
+    end # Mock
+  end # Client
+end # Foo
+
+```
+
+## Examples
 
-TODO: Write usage instructions here
+* [zendesk2](https://github.com/lanej/zendesk2)
 
 ## Releasing
 
@@ -32,4 +189,4 @@ TODO: Write usage instructions here
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-. Create new Pull Request
+5. Create new Pull Request

data/lib/cistern/version.rb

@@ -1,3 +1,3 @@
 module Cistern
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/lib/cistern.rb

@@ -16,6 +16,14 @@ module Cistern
 
   def self.timeout=(timeout); @timeout= timeout; end
   def self.timeout; @timeout || 0; end
-  def self.formatter; @formatter ||= Cistern::Formatter::Default; end
   def self.formatter=(formatter); @formatter = formatter; end
+
+  def self.formatter
+    @formatter ||= if defined?(AwesomePrint)
+                     Cistern::Formatter::AwesomePrint
+                   elsif defined?(Formatador)
+                     Cistern::Formatter::Formatador
+                   else Cistern::Formatter::Default
+                   end
+  end
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: cistern
 version: !ruby/object:Gem::Version
-  version: 0.2.1
   prerelease: 
+  version: 0.2.2
 platform: ruby
 authors:
 - Josh Lane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-17 00:00:00.000000000 Z
+date: 2013-06-05 00:00:00.000000000 Z
 dependencies: []
 description: API client framework extracted from Fog
 email:
@@ -50,20 +50,20 @@ rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-  none: false
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-  none: false
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: API client framework
@@ -72,4 +72,3 @@ test_files:
 - spec/collection_spec.rb
 - spec/model_spec.rb
 - spec/spec_helper.rb
-has_rdoc: