cistern 2.2.7 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: db9f936d47b541eb4361e967bffc5d80b4ec5b92
-  data.tar.gz: 2d07fb4e39fcdc9fad56a97f526331454a972deb
+  metadata.gz: a4ab124cf563b30d3d4a15c1b8b1ada69a30b434
+  data.tar.gz: e52206d15a0da143a293cfacd1ed105f13dcda2b
 SHA512:
-  metadata.gz: b38503613ce1b339b64dc5ea3168f0f327a4d93669098d2690d4050d2f60088416255993148e7d3d089d823535ae9f0b10ebdfa97fb638603ad59f98d98a8d19
-  data.tar.gz: 62472c37f3d596489c2e1bcae14b0b6934d8363459f8af0ae607de1272cb5ccbbe7eec03e9fb963cb8990fbd1dffa27da1602eb500b0d457783ef255e521ab35
+  metadata.gz: 189206346dc0a43b654527bf72d31fba3accb7327b0355ede31a713e3b94a27a05d92e153e84489cd79afb78d99d5d0060b1f4dac44754f5daad58956e42b0c8
+  data.tar.gz: 3440beaa800a967faadca537eee39661294ff10ba681a1d7805733e16714627990d00d4bee942b60f58870873b451bc70577cc1fd7827bcac2098a77f07113f9

data/.travis.yml

@@ -8,9 +8,7 @@ before_install:
 - gem install bundler -v "~> 1.10"
 script: bundle exec rake --trace
 notifications:
-  email:
-    on_success: never
-    on_failure: change
+  email: false
 sudo: false
 services:
 - redis-server

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Change Log
 
+## [Unreleased](https://github.com/lanej/cistern/tree/HEAD)
+
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.7...HEAD)
+
+**Implemented enhancements:**
+
+- 'requires' function should return a hash of matching requirements [\#45](https://github.com/lanej/cistern/issues/45)
+
+**Closed issues:**
+
+- rename `service` to `cistern` [\#50](https://github.com/lanej/cistern/issues/50)
+
+**Merged pull requests:**
+
+- add return values for \#requires and \#requires\_one [\#55](https://github.com/lanej/cistern/pull/55) ([lanej](https://github.com/lanej))
+- officially deprecate class interface [\#54](https://github.com/lanej/cistern/pull/54) ([lanej](https://github.com/lanej))
+- use \#stage\_attributes to make \#dirty\_attributes available on \#update [\#53](https://github.com/lanej/cistern/pull/53) ([lanej](https://github.com/lanej))
+- deprecate \#service, use \#cistern [\#52](https://github.com/lanej/cistern/pull/52) ([lanej](https://github.com/lanej))
+
+## [v2.2.7](https://github.com/lanej/cistern/tree/v2.2.7) (2016-05-13)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.6...v2.2.7)
+
+**Merged pull requests:**
+
+- service is not required to determine \#missing\_attributes [\#51](https://github.com/lanej/cistern/pull/51) ([lanej](https://github.com/lanej))
+
+## [v2.2.6](https://github.com/lanej/cistern/tree/v2.2.6) (2016-02-28)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.5...v2.2.6)
+
+## [v2.2.5](https://github.com/lanej/cistern/tree/v2.2.5) (2016-01-14)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.4...v2.2.5)
+
+## [v2.2.4](https://github.com/lanej/cistern/tree/v2.2.4) (2015-11-27)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.3...v2.2.4)
+
+**Closed issues:**
+
+- Optional coverage feature creates too many NoMethodErrors [\#49](https://github.com/lanej/cistern/issues/49)
+
+## [v2.2.3](https://github.com/lanej/cistern/tree/v2.2.3) (2015-10-27)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.2...v2.2.3)
+
+## [v2.2.2](https://github.com/lanej/cistern/tree/v2.2.2) (2015-10-27)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.1...v2.2.2)
+
+## [v2.2.1](https://github.com/lanej/cistern/tree/v2.2.1) (2015-10-02)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.0...v2.2.1)
+
+## [v2.2.0](https://github.com/lanej/cistern/tree/v2.2.0) (2015-10-02)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.1.0...v2.2.0)
+
+## [v2.1.0](https://github.com/lanej/cistern/tree/v2.1.0) (2015-09-29)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.0.5...v2.1.0)
+
+## [v2.0.5](https://github.com/lanej/cistern/tree/v2.0.5) (2015-09-21)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.0.4...v2.0.5)
+
 ## [v2.0.4](https://github.com/lanej/cistern/tree/v2.0.4) (2015-09-10)
 [Full Changelog](https://github.com/lanej/cistern/compare/v0.12.2...v2.0.4)
 

data/README.md

@@ -11,7 +11,7 @@ Cistern helps you consistently build your API clients and faciliates building mo
 
 ### Custom Architecture
 
-By default a service's `Request`, `Collection`, and `Model` are all classes. In Cistern ~> 3.0, the default will be modules.
+By default a service's `Request`, `Collection`, and `Model` are all classes. In cistern `~> 3.0`, the default will be modules.
 
 You can modify your client's architecture to be forwards compatible by using `Cistern::Client.with`
 
@@ -58,7 +58,7 @@ while living on a `Prayer`
 ```ruby
 class Foo::GetBar < Foo::Prayer
   def real
-    service.request.get("/wing")
+    cistern.request.get("/wing")
   end
 end
 ```
@@ -109,7 +109,7 @@ fake.is_a?(Foo::Client::Mock) # true
 
 Requests are defined by subclassing `#{service}::Request`.
 
-* `service` represents the associated `Foo::Client` instance.
+* `cistern` represents the associated `Foo::Client` instance.
 
 ```ruby
 class Foo::Client::GetBar < Foo::Client::Request
@@ -127,11 +127,11 @@ end
 Foo::Client.new.get_bar # "i'm real"
 ```
 
-The `#service_method` function allows you to specify the name of the generated method.
+The `#cistern_method` function allows you to specify the name of the generated method.
 
 ```ruby
 class Foo::Client::GetBars < Foo::Client::Request
-  service_method :get_all_the_bars
+  cistern_method :get_all_the_bars
 
   def real(params)
     "all the bars"
@@ -150,7 +150,7 @@ Foo::Client.requests # => [Foo::Client::GetBars, Foo::Client::GetBar]
 
 ### Models
 
-* `service` represents the associated `Foo::Client` instance.
+* `cistern` represents the associated `Foo::Client` instance.
 * `collection` represents the related collection (if applicable)
 * `new_record?` checks if `identity` is present
 * `requires(*requirements)` throws `ArgumentError` if an attribute matching a requirement isn't set
@@ -182,7 +182,7 @@ class Foo::Client::Bar < Foo::Client::Model
     params  = {
       "id" => self.identity
     }
-    self.service.destroy_bar(params).body["request"]
+    self.cistern.destroy_bar(params).body["request"]
   end
 
   def save
@@ -196,11 +196,11 @@ class Foo::Client::Bar < Foo::Client::Model
     }
 
     if new_record?
-      merge_attributes(service.create_bar(params).body["bar"])
+      merge_attributes(cistern.create_bar(params).body["bar"])
     else
       requires :identity
 
-      merge_attributes(service.update_bar(params).body["bar"])
+      merge_attributes(cistern.update_bar(params).body["bar"])
     end
   end
 end
@@ -209,7 +209,7 @@ end
 ### Collection
 
 * `model` tells Cistern which class is contained within the collection.
-* `service` is the associated `Foo::Client` instance
+* `cistern` is the associated `Foo::Client` instance
 * `attribute` specifications on collections are allowed. use `merge_attributes`
 * `load` consumes an Array of data and constructs matching `model` instances
 
@@ -221,7 +221,7 @@ class Foo::Client::Bars < Foo::Client::Collection
   model Foo::Client::Bar
 
   def all(params = {})
-    response = service.get_bars(params)
+    response = cistern.get_bars(params)
 
     data = response.body
 
@@ -235,11 +235,11 @@ class Foo::Client::Bars < Foo::Client::Collection
     }
     params.merge!("location" => options[:location]) if options.key?(:location)
 
-    service.requests.new(service.discover_bar(params).body["request"])
+    cistern.requests.new(cistern.discover_bar(params).body["request"])
   end
 
   def get(id)
-    if data = service.get_bar("id" => id).body["bar"]
+    if data = cistern.get_bar("id" => id).body["bar"]
       new(data)
     else
       nil

data/lib/cistern/attributes.rb

@@ -191,69 +191,63 @@ module Cistern::Attributes
       end
     end
 
+    # Update model's attributes.  New attributes take precedence over existing attributes.
+    #
+    # This is bst called within a {Cistern::Model#save}, when {#new_attributes} represents a recently presented remote
+    # resource.  {#dirty_attributes} is cleared after merging.
+    #
+    # @param new_attributes [Hash] attributes to merge with current attributes
     def merge_attributes(new_attributes = {})
-      protected_methods  = (Cistern::Model.instance_methods - PROTECTED_METHODS)
-      ignored_attributes = self.class.ignored_attributes
-      class_attributes   = self.class.attributes
-      class_aliases      = self.class.aliases
-
-      new_attributes.each do |_key, value|
-        string_key = _key.is_a?(String) ? _key : _key.to_s
-        symbol_key = case _key
-                     when String
-                       _key.to_sym
-                     when Symbol
-                       _key
-                     else
-                       string_key.to_sym
-                     end
-
-        # find nested paths
-        value.is_a?(::Hash) && class_attributes.each do |name, options|
-          if options[:squash] && options[:squash].first == string_key
-            send("#{name}=", symbol_key => value)
-          end
-        end
-
-        next if ignored_attributes.include?(symbol_key)
-
-        if class_aliases.key?(symbol_key)
-          class_aliases[symbol_key].each do |aliased_key|
-            send("#{aliased_key}=", value)
-          end
-        end
-
-        assignment_method = "#{string_key}="
-
-        if !protected_methods.include?(symbol_key) && self.respond_to?(assignment_method, true)
-          send(assignment_method, value)
-        end
-      end
+      _merge_attributes(new_attributes)
 
       changed.clear
 
       self
     end
 
+    # Update model's attributes.  New attributes take precedence over existing attributes.
+    #
+    # This is best called within a {Cistern::Model#update}, when {#new_attributes} represents attributes to be
+    # presented to a remote service. {#dirty_attributes} will contain the valid portion of {#new_attributes}
+    #
+    # @param new_attributes [Hash] attributes to merge with current attributes
+    def stage_attributes(new_attributes = {})
+      _merge_attributes(new_attributes)
+      self
+    end
+
     def new_record?
       identity.nil?
     end
 
-    # check that the attributes specified in args exist and is not nil
+    # Require specification of certain attributes
+    #
+    # @raise [ArgumentError] if any requested attribute does not have a value
+    # @return [Hash] of matching attributes
     def requires(*args)
-      missing = missing_attributes(args)
+      missing, required = missing_attributes(args)
+
       if missing.length == 1
-        fail(ArgumentError, "#{missing.first} is required for this operation")
+        fail(ArgumentError, "#{missing.keys.first} is required for this operation")
       elsif missing.any?
-        fail(ArgumentError, "#{missing[0...-1].join(', ')} and #{missing[-1]} are required for this operation")
+        fail(ArgumentError, "#{missing.keys[0...-1].join(', ')} and #{missing.keys[-1]} are required for this operation")
       end
+
+      required
     end
 
+    # Require specification of one or more attributes.
+    #
+    # @raise [ArgumentError] if no requested attributes have values
+    # @return [Hash] of matching attributes
     def requires_one(*args)
-      missing = missing_attributes(args)
+      missing, required = missing_attributes(args)
+
       if missing.length == args.length
-        fail(ArgumentError, "#{missing[0...-1].join(', ')} or #{missing[-1]} are required for this operation")
+        fail(ArgumentError, "#{missing.keys[0...-1].join(', ')} or #{missing.keys[-1]} are required for this operation")
       end
+
+      required
     end
 
     def dirty?
@@ -268,10 +262,12 @@ module Cistern::Attributes
       @changes ||= {}
     end
 
-    protected
+    private
 
-    def missing_attributes(args)
-      args.select { |arg| send("#{arg}").nil? }
+    def missing_attributes(keys)
+      keys.reduce({}) { |a,e| a.merge(e => send("#{e}")) }
+        .partition { |_,v| v.nil? }
+        .map { |s| Hash[s] }
     end
 
     def changed!(attribute, from, to)
@@ -281,5 +277,45 @@ module Cistern::Attributes
                              [from, to]
                            end
     end
+
+    def _merge_attributes(new_attributes)
+      protected_methods  = (Cistern::Model.instance_methods - PROTECTED_METHODS)
+      ignored_attributes = self.class.ignored_attributes
+      class_attributes   = self.class.attributes
+      class_aliases      = self.class.aliases
+
+      new_attributes.each do |_key, value|
+        string_key = _key.is_a?(String) ? _key : _key.to_s
+        symbol_key = case _key
+                     when String
+                       _key.to_sym
+                     when Symbol
+                       _key
+                     else
+                       string_key.to_sym
+                     end
+
+        # find nested paths
+        value.is_a?(::Hash) && class_attributes.each do |name, options|
+          if options[:squash] && options[:squash].first == string_key
+            send("#{name}=", symbol_key => value)
+          end
+        end
+
+        next if ignored_attributes.include?(symbol_key)
+
+        if class_aliases.key?(symbol_key)
+          class_aliases[symbol_key].each do |aliased_key|
+            send("#{aliased_key}=", value)
+          end
+        end
+
+        assignment_method = "#{string_key}="
+
+        if !protected_methods.include?(symbol_key) && self.respond_to?(assignment_method, true)
+          send(assignment_method, value)
+        end
+      end
+    end
   end
 end

data/lib/cistern/client.rb

@@ -1,11 +1,11 @@
 module Cistern::Client
   module Collections
     def collections
-      service.collections
+      cistern.collections
     end
 
     def requests
-      service.requests
+      cistern.requests
     end
   end
 
@@ -42,20 +42,43 @@ module Cistern::Client
     interface = options[:interface] || :class
     interface_callback = (:class == interface) ? :inherited : :included
 
+    if interface == :class
+      Cistern.deprecation(
+        %q{class' interface is deprecated. Use `include Cistern::Client.with(interface: :module). See https://github.com/lanej/cistern#custom-architecture},
+        caller[2],
+      )
+    end
+
     unless klass.name
-      fail ArgumentError, "can't turn anonymous class into a Cistern service"
+      fail ArgumentError, "can't turn anonymous class into a Cistern cistern"
     end
 
     klass.class_eval <<-EOS, __FILE__, __LINE__
       module Collections
         include ::Cistern::Client::Collections
 
-        def service
+        def cistern
+          Cistern.deprecation(
+            '#cistern is deprecated.  Please use #cistern',
+            caller[0]
+          )
+          #{klass.name}
+        end
+
+        def cistern
           #{klass.name}
         end
       end
 
-      def self.service
+      def self.cistern
+        Cistern.deprecation(
+          '#cistern is deprecated.  Please use #cistern',
+          caller[0]
+        )
+        #{klass.name}
+      end
+
+      def self.cistern
         #{klass.name}
       end
 
@@ -71,21 +94,29 @@ module Cistern::Client
 
       #{interface} #{model_class}
         def self.#{interface_callback}(klass)
-          service.models << klass
+          cistern.models << klass
 
           klass.send(:include, ::Cistern::Model)
 
           super
         end
 
-        def self.service
+        def self.cistern
+          Cistern.deprecation(
+            '#cistern is deprecated.  Please use #cistern',
+            caller[0]
+          )
+          #{klass.name}
+        end
+
+        def self.cistern
           #{klass.name}
         end
       end
 
       #{interface} #{singular_class}
         def self.#{interface_callback}(klass)
-          service.singularities << klass
+          cistern.singularities << klass
 
           klass.send(:include, ::Cistern::Singular)
 
@@ -93,6 +124,14 @@ module Cistern::Client
         end
 
         def self.service
+          Cistern.deprecation(
+            '#service is deprecated.  Please use #cistern',
+            caller[0]
+          )
+          #{klass.name}
+        end
+
+        def self.cistern
           #{klass.name}
         end
       end
@@ -105,12 +144,20 @@ module Cistern::Client
           klass.send(:extend, Cistern::Collection::ClassMethods)
           klass.send(:include, Cistern::Attributes::InstanceMethods)
 
-          service.collections << klass
+          cistern.collections << klass
 
           super
         end
 
         def self.service
+          Cistern.deprecation(
+            '#service is deprecated.  Please use #cistern',
+            caller[0]
+          )
+          #{klass.name}
+        end
+
+        def self.cistern
           #{klass.name}
         end
       end
@@ -119,13 +166,21 @@ module Cistern::Client
         include ::Cistern::Request
 
         def self.service
+          Cistern.deprecation(
+            '#service is deprecated.  Please use #cistern',
+            caller[0]
+          )
+          #{klass.name}
+        end
+
+        def self.cistern
           #{klass.name}
         end
 
         def self.#{interface_callback}(klass)
           klass.extend(::Cistern::Request::ClassMethods)
 
-          service.requests << klass
+          cistern.requests << klass
 
           super
         end
@@ -219,31 +274,31 @@ module Cistern::Client
       return true if @_setup
 
       requests.each do |klass|
-        name = klass.service_method ||
+        name = klass.cistern_method ||
                Cistern::String.camelize(Cistern::String.demodulize(klass.name))
 
-        Cistern::Request.service_request(self, klass, name)
+        Cistern::Request.cistern_request(self, klass, name)
       end
 
       collections.each do |klass|
-        name = klass.service_method ||
+        name = klass.cistern_method ||
                Cistern::String.underscore(klass.name.gsub("#{self.name}::", '').gsub('::', ''))
 
-        Cistern::Collection.service_collection(self, klass, name)
+        Cistern::Collection.cistern_collection(self, klass, name)
       end
 
       models.each do |klass|
-        name = klass.service_method ||
+        name = klass.cistern_method ||
                Cistern::String.underscore(klass.name.gsub("#{self.name}::", '').gsub('::', ''))
 
-        Cistern::Model.service_model(self, klass, name)
+        Cistern::Model.cistern_model(self, klass, name)
       end
 
       singularities.each do |klass|
-        name = klass.service_method ||
+        name = klass.cistern_method ||
                Cistern::String.underscore(klass.name.gsub("#{self.name}::", '').gsub('::', ''))
 
-        Cistern::Singular.service_singular(self, klass, name)
+        Cistern::Singular.cistern_singular(self, klass, name)
       end
 
       @_setup = true