policy 1.0.1

data/config/metrics/rubocop.yml

@@ -0,0 +1,87 @@
+---
+# settings added by the 'hexx-suit' module
+# output: "tmp/rubocop"
+# format: "html"
+
+AllCops:
+  Exclude:
+    - '**/db/schema.rb'
+
+Lint/HandleExceptions:
+  Exclude:
+    - '**/*_spec.rb'
+
+Lint/RescueException:
+  Exclude:
+    - '**/*_spec.rb'
+
+Metrics/ClassLength:
+  Exclude:
+    - '**/generator*'
+
+Style/AccessorMethodName:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/Documentation:
+  Exclude:
+    - '**/version.rb'
+    - '**/*_spec.rb'
+
+Style/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Style/EmptyLinesAroundMethodBody:
+  Enabled: false
+
+Style/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Style/EmptyLineBetweenDefs:
+  Enabled: false
+
+Style/FileName:
+  Enabled: false
+
+Style/RaiseArgs:
+  EnforcedStyle: compact
+
+Style/RescueModifier:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/SingleLineMethods:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/SingleSpaceBeforeFirstArg:
+  Enabled: false
+
+Style/SpecialGlobalVars:
+  Exclude:
+    - '**/Gemfile'
+    - '**/*.gemspec'
+
+Style/StructInheritance:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/TrivialAccessors:
+  Exclude:
+    - '**/*_spec.rb'

data/config/metrics/saikuro.yml

@@ -0,0 +1,3 @@
+---
+warn_cyclo:  4
+error_cyclo: 6

data/config/metrics/simplecov.yml

@@ -0,0 +1,5 @@
+---
+output: tmp/coverage
+filters: # The list of paths to be excluded from coverage checkup
+- "spec/"
+groups: [] # The list of groups to be shown in the coverage report

data/config/metrics/yardstick.yml

@@ -0,0 +1,37 @@
+---
+# Settings added by the 'hexx-suit' gem
+output: "tmp/yardstick/output.log"
+path: "lib/**/*.rb"
+rules:
+  ApiTag::Presence:
+    enabled: true
+    exclude: []
+  ApiTag::Inclusion:
+    enabled: true
+    exclude: []
+  ApiTag::ProtectedMethod:
+    enabled: true
+    exclude: []
+  ApiTag::PrivateMethod:
+    enabled: false
+    exclude: []
+  ExampleTag:
+    enabled: true
+    exclude: []
+  ReturnTag:
+    enabled: true
+    exclude: []
+  Summary::Presence:
+    enabled: true
+    exclude: []
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []
+threshold: 100
+verbose: false

data/lib/policy/follower/followed_policies.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+
+module Policy
+
+  module Follower
+
+    # Describes the list of followed policies
+    #
+    # @api private
+    class FollowedPolicies < Hash
+
+      # Registers followed policy with given unique key
+      #
+      # @param [Policy::Follower::FollowedPolicy] policy
+      #
+      # @return [undefined]
+      def add(policy)
+        self[policy.name] = policy
+      end
+
+      # Applies to follower the policies, selected by names
+      #
+      # @param [Policy::Follower] follower
+      # @param [Array<#to_s>] names
+      #
+      # @raise [Policy::ViolationError]
+      #   unless all policies are met
+      #
+      # @return [undefined]
+      def apply_to(follower, *names)
+        named_by(names).each { |policy| policy.apply_to(follower) }
+      end
+
+      private
+
+      def named_by(list)
+        names = Names.from list
+        names.any? ? names.map(&method(:[])).compact : values
+      end
+
+    end # class FollowedPolicies
+
+  end # module Follower
+
+end # module Policy

data/lib/policy/follower/followed_policy.rb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+
+module Policy
+
+  module Follower
+
+    # Stores the policy to be applied to all instances of the follower
+    #
+    # The policy object can be set either as a constant, or by name
+    # in given namespace. Namespace and policy name can be set separately.
+    #
+    # The separation is used at the {Policy::Follower#apply_policies}.
+    #
+    # @example The policy can be constant
+    #   FollowedPolicy.new nil, Foo::Bar::Baz, :baz_policy, :baz
+    #
+    # @example The policy can be name, relative to the namespace
+    #   FollowedPolicy.new Foo::Bar, :Baz, :baz_policy, :baz
+    #   # Foo::Bar::Baz policy object will be used
+    #
+    # @api private
+    class FollowedPolicy
+
+      # @!scope class
+      # @!method new(namespace, policy, name, *attributes)
+      # Creates the immutable policy to be followed by given object
+      #
+      # @param [Module] namespace
+      #   the namespace for the policy, given by name
+      # @param [Class, #to_s] policy
+      #   the class for applicable policy
+      # @param [#to_sym, nil] name
+      #   the name for the policy
+      # @param [Array<Symbol>] attributes
+      #   the list of follower attributes to apply the policy to
+      #
+      # @return [Policy::Follower::FollowedPolicy]
+      #   immutable object
+      def initialize(namespace, policy, name, *attributes)
+        @policy     = find_policy(namespace, policy)
+        @name       = (name || SecureRandom.uuid).to_sym
+        @attributes = check_attributes attributes
+      end
+
+      # @!attribute [r] name
+      # The name for the policy
+      #
+      # @return [Symbol]
+      attr_reader :name
+
+      # @!attribute [r] policy
+      # The policy object class to be followed
+      #
+      # @return [Class]
+      attr_reader :policy
+
+      # @!attribute [r] attributes
+      # The list of follower attributes to be send to the policy object
+      #
+      # @return [Array<Symbol>]
+      attr_reader :attributes
+
+      # Applies the policy to follower instance
+      #
+      # @param [Policy::Follower]
+      #   follower
+      #
+      # @raise [Policy::ViolationError]
+      #   it the follower doesn't meet the policy
+      #
+      # @return [undefined]
+      def apply_to(follower)
+        policy.apply(*attributes_of(follower))
+      end
+
+      private
+
+      def find_policy(namespace, policy)
+        return policy if policy.instance_of?(Class)
+        instance_eval [namespace, policy].join("::")
+      end
+
+      def attributes_of(follower)
+        attributes.map(&follower.method(:send))
+      end
+
+      def check_attributes(attributes)
+        number = policy.members.count
+        return attributes if attributes.count.equal?(number)
+        fail wrong_number(number, attributes)
+      end
+
+      def wrong_number(number, attributes)
+        ArgumentError.new [
+          "#{ policy } requires #{ number } attribute(s).",
+          "#{ attributes } cannot be assigned."
+        ].join(" ")
+      end
+
+    end # class FollowedPolicy
+
+  end # module Follower
+
+end # module Policy

data/lib/policy/follower/names.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+module Policy
+
+  module Follower
+
+    # Converter of items to array of unique symbols
+    #
+    # @api private
+    module Names
+
+      # Converts items to array of unique symbols
+      #
+      # @example
+      #   Policy::Follower::Names.from "foo", [:foo, "bar"], "baz"
+      #   # => [:foo, :bar, :baz]
+      #
+      # @param [Array<#to_sym>] items
+      #
+      # @return [Array<Symbol>]
+      def self.from(*items)
+        items.flatten.map(&:to_sym)
+      end
+
+    end
+
+  end
+
+end

data/lib/policy/follower.rb

@@ -0,0 +1,143 @@
+# encoding: utf-8
+
+module Policy
+
+  # Adds features for the object to follow external 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
+    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}
+      #
+      # @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
+      #
+      # @option [#to_sym] :as
+      #   the name for the policy to be used for selecting it
+      #   in {#follow_policies!} and {#follow_policies?} methods
+      #
+      # @return [undefined]
+      def follow_policy(policy, *attributes, as: nil)
+        object = FollowedPolicy.new(__policies__, policy, as, *attributes)
+        followed_policies.add object
+      end
+
+      # Changes the namespace for applied policies
+      #
+      # @example For Policies::Finances::TransferConsistency
+      #   use_policies Policies::Finances do
+      #     apply_policy :TransferConstistency, :debet, :credit
+      #   end
+      #
+      # @param [Module] namespace
+      #
+      # @yield the block in the current scope
+      #
+      # @return [undefined]
+      def use_policies(namespace, &block)
+        @__policies__ = namespace
+        instance_eval(&block)
+      ensure
+        @__policies__ = nil
+      end
+
+      private
+
+      def __policies__
+        @__policies__ ||= self
+      end
+
+    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
+    #
+    # @param [#to_sym] name
+    #   the name of the policy to follow
+    #
+    # @raise (see #follow_policies!)
+    #
+    # @return [undefined]
+    def follow_policy!(name)
+      follow_policies! name
+    end
+
+    # Safely checks whether an instance meets selected policies
+    #
+    # Mutates the object by adding new #errors
+    #
+    # @param (see #follow_policies!)
+    #
+    # @return [Boolean]
+    def follow_policies?(*names)
+      follow_policies!(*names)
+      true
+    rescue ViolationError
+      false
+    end
+
+    # Syntax shugar for the {#follow_policies?} with one argument
+    #
+    # @param  (see #follow_policy!)
+    #
+    # @return (see #follow_policies?)
+    def follow_policy?(name)
+      follow_policies? name
+    end
+
+    private
+
+    # @!parse extend  Policy::Follower::ClassMethods
+    # @!parse include ActiveModel::Validations
+    def self.included(klass)
+      klass.extend(ClassMethods).__send__(:include, Validations)
+    end
+
+    def followed_policies
+      @followed_policies ||= self.class.followed_policies
+    end
+
+    def collect_errors_from(exception)
+      exception.messages.each { |text| errors.add :base, text }
+    end
+
+  end # module Follower
+
+end # module Policy

data/lib/policy/interface.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+module Policy
+
+  # Policy object interface
+  module Interface
+
+    # @private
+    def self.included(klass)
+      klass.extend(ClassMethods).__send__(:include, Validations)
+    end
+
+    # Container for the policy class methods
+    module ClassMethods
+
+      # Creates and validates the policy object
+      #
+      # @param (see Policy.new)
+      #
+      # @raise (see Policy::Interface#apply)
+      #
+      # @return [undefined]
+      def apply(*attributes)
+        new(*attributes).apply
+      end
+
+    end
+
+    # Returns the list of error messages
+    #
+    # @return [Array<String>]
+    def messages
+      errors.messages.values.flatten
+    end
+
+    # Validates the policy object
+    #
+    # @raise [ViolationError]
+    #   if a policy is invalid
+    #
+    # @return [undefined]
+    def apply
+      fail ViolationError.new(self) unless valid?
+    end
+
+  end # class Interface
+
+end # module Policy

data/lib/policy/validations.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+require "active_model"
+
+module Policy
+
+  # Wrapper around the ActiveModel::Validations
+  #
+  # Provides shared interface for [Policy::Inteface] and [Policy::Follower].
+  #
+  # @todo Implement it later from scratch without excessive features
+  #
+  # @example
+  #   MyClass.include, Policy::Validations
+  #
+  # @private
+  module Validations
+
+    # The implementation for validations
+    IMPLEMENTATION = ActiveModel::Validations
+
+    # @private
+    def self.included(klass)
+      klass.__send__(:include, IMPLEMENTATION)
+    end
+
+  end # module Validations
+
+end # module Policy

data/lib/policy/version.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+module Policy
+
+  # The semantic version of the module.
+  # @see http://semver.org/ Semantic versioning 2.0
+  VERSION = "1.0.1".freeze
+
+end # module Hexx

data/lib/policy/violation_error.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+module Policy
+
+  # An exception to be risen by {Policy::Interface#apply}
+  class ViolationError < RuntimeError
+    include Adamantium
+
+    # @!attribute [r] policy
+    # The violated policy object
+    #
+    # @return [Policy::Follower]
+    attr_reader :policy
+
+    # @!attribute [r] messages
+    # The list of messages from the broken policy
+    #
+    # @return [Array<String>]
+    attr_reader :messages
+
+    # @!scope class
+    # @!method new(policy)
+    # Constructs an exception
+    #
+    # @param [Policy::Follower] policy
+    #   the violated policy object
+    #
+    # @return [Policy::ViolationError]
+    def initialize(policy)
+      @policy   = policy.dup
+      @messages = @policy.messages
+    end
+
+    # The human-readable description for the exception
+    #
+    # @return [String]
+    def inspect
+      "#<#{ self }: #{ message }>"
+    end
+
+    # The human-readable exception message
+    #
+    # @return [String]
+    def message
+      "#{ policy } violated: #{ messages }"
+    end
+
+    memoize :policy, :messages
+
+  end # module Follower
+
+end # module Policy

data/lib/policy.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+require "adamantium"
+
+# Policy Object builder
+#
+# @!parse include Policy::Interface
+module Policy
+
+  require_relative "policy/version"
+  require_relative "policy/validations"
+  require_relative "policy/violation_error"
+  require_relative "policy/interface"
+  require_relative "policy/follower"
+
+  class << self
+
+    # Builds a base class for the policy object with some attributes
+    #
+    # @example
+    #   class TransactionPolicy < Policy.new(:debet, :credit)
+    #   end
+    #
+    # @param [Array<Symbol>] attributes
+    #   names for the policy object attributes
+    #
+    # @return [Struct]
+    def new(*attributes)
+      Struct.new(*attributes) do
+        include Interface
+
+        def self.name
+          "Policy"
+        end
+      end
+    end
+
+  end # Policy singleton class
+
+end # module Policy

data/policy.gemspec

@@ -0,0 +1,23 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "policy/version"
+
+Gem::Specification.new do |s|
+  s.name        = "policy"
+  s.version     = Policy::VERSION.dup
+  s.author      = "Andrew Kozin"
+  s.email       = "andrew.kozin@gmail.com"
+  s.homepage    = "https://github.com/nepalez/policy"
+  s.summary     = "Policy Objects for Ruby."
+  s.description = "A tiny library implementing the Policy Object pattern."
+  s.license     = "MIT"
+
+  s.files            = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  s.test_files       = Dir["spec/**/*.rb"]
+  s.extra_rdoc_files = Dir["README.md", "LICENSE", "config/metrics/STYLEGUIDE"]
+  s.require_paths    = ["lib"]
+
+  s.add_runtime_dependency "activemodel", ">= 3.1"
+  s.add_runtime_dependency "adamantium", "~> 0.2"
+
+  s.add_development_dependency "hexx-rspec", "~> 0.1"
+end