policy 1.2.0 → 2.0.0

data/lib/policy/cli/locale.erb

@@ -8,7 +8,6 @@
 #       models:
 #         <%= project.path %>/<%= policy.path %>:
 #           attributes:
-#             base:
-<% attributes.each do |item| -%>
+<% ["base"].concat(attributes.map(&:name)).sort.each do |item| -%>
 #             <%= item %>:
 <% end -%>

data/lib/policy/cli/policy.erb

@@ -16,18 +16,45 @@
 
 <%= "  " * tabs %># Implements the following policy (invariant):
 <%= "  " * tabs %>#
-<%= "  " * tabs %># @todo: describe the policy
+<%= "  " * tabs %># @todo Describe the policy
 <%= "  " * tabs %>#
 <%= "  " * tabs %># @example
-<%= "  " * tabs %>#   <%= policy.type %>.new(<%= attributes.join(", ") %>)
+<%= "  " * tabs %>#   <%= project.type %>::<%= policy.type %>.new(
+<% attributes.each do |item| -%>
+<%= "  " * tabs %>#     <%= item.name %>: @todo,
+<% end -%>
+<%= "  " * tabs %>#   )
 <%= "  " * tabs %>#
+<%= "  " * tabs %>class <%= policy.const %>
+<%= "  " * tabs %>  include Policy::Base
+
+<%= "  " * tabs %>  # @!scope class
+<%= "  " * tabs %>  # @!method new(attributes)
+<%= "  " * tabs %>  # Creates the policy object with a list of attributes
+<%= "  " * tabs %>  #
+<%= "  " * tabs %>  # @param [Hash] attributes
+<%= "  " * tabs %>  #
+<%= "  " * tabs %>  # @return [<%= project.type %>::<%= policy.type %>]
+<% if attributes.any? -%>
+
+<%= "  " * tabs %>  # @private
+<%= "  " * tabs %>  def initialize(<%= attributes.map { |item| "#{ item.name }:" }.join(", ") -%>)
 <% attributes.each do |item| -%>
-<%= "  " * tabs %># @param [@todo] <%= item %>
-<%= "  " * tabs %>#   @todo: describe the attribute
+<%= "  " * tabs %>    @<%= item.name %> = <%= item.name %>
+<% end -%>
+<%= "  " * tabs %>  end
+<% attributes.each do |item| -%>
+
+<%= "  " * tabs %>  # # @!attribute [r] <%= item.name %>
+<%= "  " * tabs %>  # # @todo Describe the attribute
+<%= "  " * tabs %>  # #
+<%= "  " * tabs %>  # # @return [<%= item.type %>]
+<%= "  " * tabs %>  # attr_reader :<%= item.name %>
+<% end -%>
 <% end -%>
-<%= "  " * tabs %>class <%= policy.const %> < Hexx::Policy.new(<%= attributes.map { |item| ":#{ item }" }.join(", ") %>)
 
-<%= "  " * tabs %>  # Define necessary validations using `validates` or `validate` declarations.
+<%= "  " * tabs %>  # Define necessary validations using either `validates`
+<%= "  " * tabs %>  # or `validate` declarations.
 
 <%= "  " * tabs %>end # class <%= policy.const %>
 <% policy.namespaces.reverse.each do |item| -%>

data/lib/policy/cli/spec.erb

@@ -7,24 +7,44 @@ describe <%= project.type %>::<%= policy.type %> do
 
   # default attributes for a valid policy
 <% attributes.each do |item| -%>
-  # let(:<%= item %>) { @todo }
+  # let(:<%= item.name %>) { @todo }
 <% end -%>
 
-  subject { described_class.new <%= attributes.join(", ") %> }
+  subject do
+    described_class.new(
+<% attributes.each do |item| -%>
+      <%= item.name %>: <%= item.name %>,
+<% end -%>
+    )
+  end
+<% attributes.each do |item| -%>
 
-  context "when @todo: describe the context" do
+  describe "#<%= item.name %>" do
 
-    it { is_expected.to be_valid }
+    it "is initialized" do
+      expect(subject.<%= item.name %>).to eq <%= item.name %>
+    end
 
-  end # context
-<% attributes.each do |item| -%>
+  end # describe #<%= item.name %>
+<% end -%>
 
-  context "when <%= item %> @todo" do
+  describe "#valid?" do
 
-    # let(:<%= item %>) { @todo }
-    it { is_expected.not_to be_valid }
+    context "when @todo: describe the context" do
 
-  end # context
-<% end -%>
+      it { is_expected.to be_valid }
+
+    end # context
+  <% attributes.each do |item| -%>
+
+    context "when the #<%= item.name %> is @todo" do
+
+      # before { allow(subject).to receive(:<%= item.name %>) { @todo } }
+      it { is_expected.to be_invalid }
+
+    end # context
+  <% end -%>
+
+  end # describe #valid?
 
 end # describe <%= policy.type %>

data/lib/policy/follower.rb

@@ -2,140 +2,100 @@
 
 module Policy
 
-  # Adds features for the object to follow external policies
+  # Interface for the class that follows policies
   module Follower
 
-    require_relative "follower/names"
-    require_relative "follower/followed_policy"
-    require_relative "follower/followed_policies"
-
-    # Methods to be added to the class the module is included to
-    #
-    # @private
+    # Methods to be added to the follower class
     module ClassMethods
 
-      # @!attribute [r] followed_policies
-      # The collection of policies to be followed by instances of the class
-      #
-      # @return [Policy::Follower::FollowedPolicies]
-      #
-      # @private
-      def followed_policies
-        @followed_policies ||= FollowedPolicies.new
-      end
-
-      # Adds a policy to the list of {#followed_policies}
+      # Declares a policy to be followed
       #
-      # @param [Class] policy
-      #   the policy object klass
-      # @param [Array<#to_sym>] attributes
-      #   the list of attributes of the instance the policy should be applied to
+      # Mutates the object by adding an item to its {#policies}.
       #
-      # @option [#to_sym] :as
-      #   the name for the policy to be used for selecting it
-      #   in {#follow_policies!} and {#follow_policies?} methods
+      # @param [Symbol] name
       #
-      # @return [undefined]
-      def follow_policy(policy, *attributes, as: nil)
-        object = FollowedPolicy.new(__policies__, policy, as, *attributes)
-        followed_policies.add object
+      # @return [:follows_policy] the name of the method
+      def follows_policy(name)
+        policies.add name
+
+        :follows_policy
       end
 
-      # Changes the namespace for applied policies
+      # Declares policies to be followed
       #
-      # @example For Policies::Finances::TransferConsistency
-      #   use_policies Policies::Finances do
-      #     apply_policy :TransferConstistency, :debet, :credit
-      #   end
+      # Mutates the object by adding items to its {#policies}.
       #
-      # @param [Module] namespace
+      # @param [Symbol, Array<Symbol>] names
       #
-      # @yield the block in the current scope
-      #
-      # @return [undefined]
-      def use_policies(namespace, &block)
-        @__policies__ = namespace
-        instance_eval(&block)
-      ensure
-        @__policies__ = nil
-      end
+      # @return [:follows_policies] the name of the method
+      def follows_policies(*names)
+        names.each(&method(:follows_policy))
 
-      private
-
-      def __policies__
-        @__policies__ ||= self
+        :follows_policies
       end
 
-    end
+      # @!attribute [r] policies
+      # The collection of followed policies
+      #
+      # @return [Policy::Follower::Policies]
+      def policies
+        @policies ||= Policies.new(self)
+      end
 
-    # Checks whether an instance meets selected policies
-    #
-    # Mutates the object by adding new #errors
-    #
-    # @param [Array<#to_sym>] names
-    #   the ordered list of names to select policies by
-    #   when not names selected all policies will be applied
-    #
-    # @raise [Policy::ViolationError]
-    #   unless all selected policies has been met
-    #
-    # @return [undefined]
-    def follow_policies!(*names)
-      followed_policies.apply_to self, *names
-    rescue ViolationError => error
-      collect_errors_from(error)
-      raise
     end
 
-    # Syntax shugar for the {#follow_policies!} with one argument
+    # Checks whether an object follows all its policies or subset of policies
     #
-    # @param [#to_sym] name
-    #   the name of the policy to follow
+    # @overload follow_policies?()
+    #   Checks whether an object follows all registered policies
     #
-    # @raise (see #follow_policies!)
+    # @overload follow_policies?(names)
+    #   Checks whether an object follows given policies
     #
-    # @return [undefined]
-    def follow_policy!(name)
-      follow_policies! name
-    end
-
-    # Safely checks whether an instance meets selected policies
+    #   @param [#to_sym, Array<#to_sym>] names
     #
-    # Mutates the object by adding new #errors
+    #   @raise [Policy::Follower::NameError]
+    #     if the policy is not registered by name
     #
-    # @param (see #follow_policies!)
+    # @raise [NoMethodError]
+    #   if the name not implemented as follower's instance method
+    # @raise [ViolationError]
+    #   if the policy is violated by the follower
     #
-    # @return [Boolean]
+    # @return [true] if no exception being raised
     def follow_policies?(*names)
-      follow_policies!(*names)
+      __policies__
+        .subset(names)                       # raises NameError
+        .map(&method(:__send__))             # raises NoMethodError
+        .each(&method(:__validate_policy__)) # raises ViolationError
       true
-    rescue ViolationError
-      false
     end
 
-    # Syntax shugar for the {#follow_policies?} with one argument
+    # Checks whether an object follows given policy
     #
-    # @param  (see #follow_policy!)
+    # @param [#to_sym] name
+    #   the name of the policy to follow
+    #
+    # @raise  (see #follow_policies?)
     #
     # @return (see #follow_policies?)
     def follow_policy?(name)
       follow_policies? name
     end
 
-    private
-
-    # @!parse extend  Policy::Follower::ClassMethods
-    # @!parse include ActiveModel::Validations
+    # @private
     def self.included(klass)
-      klass.extend(ClassMethods).__send__(:include, Validations)
+      klass.instance_eval { extend ClassMethods }
     end
 
-    def followed_policies
-      @followed_policies ||= self.class.followed_policies
+    private
+
+    def __validate_policy__(policy)
+      fail ViolationError.new(self, policy) unless policy.valid?
     end
 
-    def collect_errors_from(exception)
-      exception.messages.each { |text| errors.add :base, text }
+    def __policies__
+      self.class.policies
     end
 
   end # module Follower

data/lib/policy/follower/name_error.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+module Policy
+
+  module Follower
+
+    # An exception to be risen when a policy name is not followed by a follower
+    class NameError < RuntimeError
+
+      # @!scope class
+      # @!method new(follower, name)
+      # Constructs an exception for the follower class and the policy name
+      #
+      # @param [Class] follower
+      # @param [#to_sym] name
+      #
+      # @return [Policy::Follower::NameError]
+      def initialize(follower, name)
+        @follower = follower
+        @name = name.to_sym
+      end
+
+      # @!attribute [r] follower
+      # The follower class that doesn't follow given policy
+      #
+      # @return [Class]
+      attr_reader :follower
+
+      # @!attribute [r] name
+      # The name of the policy that is not followed by the follower
+      #
+      # @return [String]
+      attr_reader :name
+
+      # The human-readable exception message
+      #
+      # @return [String]
+      def message
+        "#{ follower.inspect } hasn't registered the policy \"#{ name }\""
+      end
+
+      # The human-readable description for the exception
+      #
+      # @return [String]
+      def inspect
+        "#<#{ self }: #{ message }>"
+      end
+
+    end # class NameError
+
+  end # module Follower
+
+end # module Policy

data/lib/policy/follower/policies.rb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+
+module Policy
+
+  module Follower
+
+    # Collection of policy names to be followed
+    #
+    # @api private
+    class Policies
+      include Enumerable
+
+      # @!scope class
+      # @!method new(follower)
+      # Creates the empty collection for the follower class
+      #
+      # @param [Class] follower
+      #
+      # @return [Policy::Follower::Policies] the collection object
+      def initialize(follower)
+        @follower = follower
+        @names = []
+      end
+
+      # Adds the policy name to the list of followed policies
+      #
+      # @example
+      #   Policies.new.add("some_policy")
+      #
+      # @param [#to_sym] policy
+      #
+      # @return [self] itself
+      def add(policy)
+        name = policy.to_sym
+        names << name unless names.include? name
+        self
+      end
+
+      # Checks whether the name is included to the {#names}
+      #
+      # @param [Symbol] name
+      #
+      # @raise [Policy::Followers::NameError] if the name not registered yet
+      #
+      # @return [true]
+      def include?(name)
+        fail(NameError.new(follower, name)) unless names.include?(name)
+        true
+      end
+
+      # Returns the subset of current collection
+      #
+      # @overload subset()
+      #   @return [self] itself
+      #
+      # @overload subset(*names)
+      #   @example
+      #     policies = Policies.new(follower, %i(foo bar baz))
+      #     policies.subset(:baz, :foo)
+      #     # => #<Policies @names=[:baz, :foo]>
+      #
+      #   @param [Symbol, Array<Symbol>] names
+      #
+      #   @raise [Policy::Follower::NameError]
+      #     if subset contains unregistered policies
+      #
+      # @return [Policy::Follower::Policies]
+      def subset(*names)
+        return self unless names.flatten.any?
+        policies = self.class.new(follower)
+        valid(names).each(&policies.method(:add))
+
+        policies
+      end
+
+      # Iterates through names of the policies
+      #
+      # @return [Enumerator]
+      #
+      # @yieldparam [Symbol] the name of the registered policy
+      def each
+        return to_enum unless block_given?
+        names.each { |name| yield(name) }
+      end
+
+      # @!attribute [r] follower
+      # The class that follows policies
+      #
+      # @return [Class]
+      attr_reader :follower
+
+      private
+
+      attr_reader :names
+
+      def valid(names)
+        names.flatten.map(&:to_sym).select(&method(:include?))
+      end
+
+    end # class Policies
+
+  end # module Follower
+
+end # module Policy