tram-policy 0.0.1

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/setup"
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new :default
+
+task default: :spec

data/bin/tram-policy

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require File.expand_path("lib/tram/policy/generator", Dir.pwd)
+
+Tram::Policy::Generator.start

data/lib/tram-policy.rb

@@ -0,0 +1 @@
+require_relative "tram/policy"

data/lib/tram/policy.rb

@@ -0,0 +1,113 @@
+require "dry-initializer"
+require "i18n"
+
+module Tram
+  # Base class for policy objects with composable validation errors
+  class Policy
+    require_relative "policy/validation_error"
+    require_relative "policy/inflector"
+    require_relative "policy/error"
+    require_relative "policy/errors"
+
+    extend Dry::Initializer
+
+    class << self
+      # Registers a validator
+      #
+      # @param  [#to_sym, Array<#to_sym>] names
+      # @return [self]
+      #
+      def validate(*names)
+        @validators = validators | names.flatten.map(&:to_sym)
+        self
+      end
+
+      # Policy constructor/validator (alias for [.new])
+      #
+      # @param  [Object] *args
+      # @return [Tram::Policy]
+      #
+      def [](*args)
+        new(*args)
+      end
+
+      private
+
+      def validators
+        @validators ||= []
+      end
+
+      def inherited(klass)
+        super
+        klass.validate validators
+      end
+    end
+
+    # Translates a message in the scope of current policy
+    #
+    # @param  [#to_s] message
+    # @param  [Hash<Symbol, Object>] options
+    # @return [String]
+    #
+    def t(message, **options)
+      return message.to_s unless message.is_a? Symbol
+      I18n.t message, options.merge(scope: @__scope__)
+    end
+
+    # Collection of validation errors
+    #
+    # @return [Tram::Policy::Errors]
+    #
+    def errors
+      @errors ||= Errors.new(self)
+    end
+
+    # Checks whether the policy is valid
+    #
+    # @param  [Proc, nil] filter Block describing **errors to be skipped**
+    # @return [Boolean]
+    #
+    def valid?(&filter)
+      filter ? errors.reject(&filter).empty? : errors.empty?
+    end
+
+    # Checks whether the policy is invalid
+    #
+    # @param  [Proc, nil] filter Block describing **the only errors to count**
+    # @return [Boolean]
+    #
+    def invalid?(&filter)
+      filter ? errors.any?(&filter) : errors.any?
+    end
+
+    # Raises exception if the policy is not valid
+    #
+    # @param  (see #valid?)
+    # @raise  [Tram::Policy::ValidationError] if the policy isn't valid
+    # @return [nil] if the policy is valid
+    #
+    def validate!(&filter)
+      raise ValidationError.new(self, filter) unless valid?(&filter)
+    end
+
+    # Human-readable representation of the policy
+    #
+    # @example Displays policy name and its attributes
+    #   UserPolicy[name: "Andy"].inspect
+    #   # => #<UserPolicy["name" => "Andy"]>
+    #
+    # @return [String]
+    #
+    def inspect
+      "#<#{self.class.name}[#{@__options__}]>"
+    end
+
+    private
+
+    def initialize(*)
+      super
+      @__scope__ = Inflector.underscore(self.class.name)
+      self.class.send(:validators).each { |name| send(name) }
+    end
+  end
+end

data/lib/tram/policy/error.rb

@@ -0,0 +1,88 @@
+class Tram::Policy
+  # Validation error with message and assigned tags
+  #
+  # Notice: an error is context-independent; it knows nothing about
+  #         a collection it is placed to; it can be safely moved
+  #         from one collection of [Tram::Policy::Errors] to another.
+  #
+  class Error
+    # Builds an error
+    #
+    # If another error is send to the constructor, the error returned unchanged
+    #
+    # @param  [Tram::Policy::Error, #to_s] value
+    # @param  [Hash<Symbol, Object>] opts
+    # @return [Tram::Policy::Error]
+    #
+    def self.new(value, **opts)
+      return value if value.is_a? self
+      super
+    end
+
+    # @!attribute [r] message
+    #
+    # @return [String] The error message text
+    #
+    attr_reader :message
+
+    # The full message (message and tags info)
+    #
+    # @return [String]
+    #
+    def full_message
+      [message, @tags].reject(&:empty?).join(" ")
+    end
+
+    # Converts the error to a simple hash with message and tags
+    #
+    # @return [Hash<Symbol, Object>]
+    #
+    def to_h
+      @tags.merge(message: message)
+    end
+
+    # Fetches either message or a tag
+    #
+    # @param [#to_sym] tag
+    # @return [Object]
+    #
+    def [](tag)
+      to_h[tag.to_sym]
+    end
+
+    # Fetches either message or a tag
+    #
+    # @param [#to_sym] tag
+    # @param [Object] default
+    # @param [Proc] block
+    # @return [Object]
+    #
+    def fetch(tag, default, &block)
+      to_h.fetch(tag.to_sym, default, &block)
+    end
+
+    # Compares an error to another object using method [#to_h]
+    #
+    # @param  [Object] other Other object to compare to
+    # @return [Boolean]
+    #
+    def ==(other)
+      other.respond_to?(:to_h) && other.to_h == to_h
+    end
+
+    private
+
+    def initialize(message, **tags)
+      @message = message.to_s
+      @tags = tags
+    end
+
+    def respond_to_missing?(*)
+      true
+    end
+
+    def method_missing(name, *args, &block)
+      args.any? || block ? super : @tags[name]
+    end
+  end
+end

data/lib/tram/policy/errors.rb

@@ -0,0 +1,102 @@
+class Tram::Policy
+  # Enumerable collection of unique unordered validation errors
+  #
+  # Notice: A collection is context-dependent;
+  #         it knows about a scope of policy it belongs to,
+  #         and how to translate error messages in that scope.
+  #
+  class Errors
+    include Enumerable
+
+    # @!attribute [r] policy
+    #
+    # @return [Tram::Policy] the poplicy errors provided by
+    #
+    attr_reader :policy
+
+    # Adds error message to the collection
+    #
+    # @param [#to_s] message Either a message, or a symbolic key for translation
+    # @param [Hash<Symbol, Object>] tags Tags to be attached to the message
+    # @return [self] the collection
+    #
+    def add(message = nil, **tags)
+      message ||= tags.delete(:message)
+      raise ArgumentError.new("Error message should be defined") unless message
+
+      @set << Tram::Policy::Error.new(@policy.t(message, tags), **tags)
+      self
+    end
+
+    # Iterates by collected errors
+    #
+    # @yeldparam [Tram::Policy::Error]
+    # @return [Enumerator<Tram::Policy::Error>]
+    #
+    def each
+      @set.each { |error| yield(error) }
+    end
+
+    # Selects errors filtered by tags
+    #
+    # @param  [Hash<Symbol, Object>] filter
+    # @return [Hash<Symbol, Object>]
+    #
+    def by_tags(**filter)
+      filter = filter.to_a
+      reject { |error| (filter - error.to_h.to_a).any? }
+    end
+
+    # Checks whether a collection is empty
+    #
+    # @return [Boolean]
+    #
+    def empty?
+      !any?
+    end
+
+    # The array of ordered error messages
+    #
+    # @return [Array<String>]
+    #
+    def messages
+      @set.map(&:message).sort
+    end
+
+    # The array of ordered error messages with error tags info
+    #
+    # @return [Array<String>]
+    #
+    def full_messages
+      @set.map(&:full_message).sort
+    end
+
+    # Merges other collection to the current one and returns new collection
+    # with the current scope
+    #
+    # param [Tram::Policy::Errors] other Collection to be merged
+    # yieldparam [Hash<Symbol, Object>]
+    #
+    # @example Add some tag to merged errors
+    #   policy.merge(other) { |err| err[:source] = "other" }
+    #
+    def merge(other)
+      return self unless other.is_a?(self.class) && other.any?
+
+      if block_given?
+        other.each { |err| add yield(err.to_h) }
+      else
+        @set |= other.to_a
+      end
+
+      self
+    end
+
+    private
+
+    def initialize(policy, errors = Set.new)
+      @policy = policy
+      @set    = errors
+    end
+  end
+end

data/lib/tram/policy/generator.rb

@@ -0,0 +1,111 @@
+require "thor/group"
+require "i18n"
+
+module Tram
+  class Policy
+    require_relative "inflector"
+
+    class Generator < Thor::Group
+      include Thor::Actions
+
+      desc "Generates new policy class along with its specification"
+      argument :name, desc: "policy class name", type: :string
+      class_option :params,     desc:    "list of policy params",
+                                type:    :array,
+                                default: [],
+                                aliases: "-p",
+                                banner:  "param[ param]"
+      class_option :options,    desc:    "list of policy options",
+                                type:    :array,
+                                default: [],
+                                aliases: "-o",
+                                banner:  "option[ option]"
+      class_option :validators, desc:    "list of policy validators",
+                                type:    :array,
+                                default: [],
+                                aliases: "-v",
+                                banner:  "validator[ validator]"
+
+      def self.source_root
+        File.dirname(__FILE__)
+      end
+
+      def generate_class
+        template "generator/policy.erb", "app/policies/#{file}.rb"
+      end
+
+      def generate_locales
+        available_locales.each do |locale|
+          @locale = locale
+          add_locale
+          localize_policy
+          parsed_validators.each { |validator| localize_validator(validator) }
+        end
+      end
+
+      def generate_spec
+        template "generator/policy_spec.erb", "spec/policies/#{file}_spec.rb"
+      end
+
+      no_tasks do
+        def klass
+          @klass ||= Inflector.camelize name
+        end
+
+        def file
+          @file ||= Inflector.underscore name
+        end
+
+        def parsed_options
+          @parsed_options ||= options[:options].map(&:downcase)
+        end
+
+        def parsed_params
+          @parsed_params ||= options[:params].map(&:downcase)
+        end
+
+        def parsed_validators
+          @parsed_validators ||= options[:validators].map(&:downcase)
+        end
+
+        def policy_signature
+          @policy_signature ||= \
+            parsed_params + \
+            parsed_options.map { |option| "#{option}: #{option}" }
+        end
+
+        def available_locales
+          ask("What locales should be used for translation?").scan(/\w{2}/)
+        end
+
+        def locale_file
+          "config/locales/tram-policy.#{@locale}.yml"
+        end
+
+        def locale_header
+          "---\n#{@locale}:\n"
+        end
+
+        def locale_group
+          @locale_group ||= "  #{file}:\n"
+        end
+
+        def locale_line(validator)
+          "    #{validator}: #{validator}\n"
+        end
+
+        def add_locale
+          create_file(locale_file, skip: true) { locale_header }
+        end
+
+        def localize_policy
+          append_to_file(locale_file, locale_group)
+        end
+
+        def localize_validator(name)
+          insert_into_file locale_file, locale_line(name), after: locale_group
+        end
+      end
+    end
+  end
+end

data/lib/tram/policy/generator/policy.erb

@@ -0,0 +1,20 @@
+class <%= klass %> < Tram::Policy
+<% parsed_params.each do |param| -%>
+  param :<%= param %>
+<% end -%>
+<% parsed_options.each do |option| -%>
+  option :<%= option %>
+<% end -%>
+
+<% parsed_validators.each do |validator| -%>
+  validate :<%= validator %>
+<% end -%>
+
+  private
+<% parsed_validators.each do |validator| %>
+  def <%= validator %>
+    return if true # define a condition
+    errors.add :<%= validator %> # add necessary tags
+  end
+<% end -%>
+end