enum_ext 0.5.2 → 0.8.0

data/lib/enum_ext/annotated.rb

@@ -0,0 +1,172 @@
+# I wanted to add some quick live annotation to what's defined and how it could be used
+# but have no idea how to do this in a super-neat way, so it a little bit chaotic and experimental
+module EnumExt::Annotated
+
+  # call it to see what's your enum current opitons
+  def describe_basic
+    puts yellow( "Basic #{enum_name} definition: \n" )
+    print_hash(enum_values)
+  end
+
+  # call it to see all enum extensions defined.
+  def describe_long
+    puts yellow( "\nEnumExt extensions:" )
+
+    puts [
+      describe_enum_i(false),
+      describe_mass_assign_enum(false),
+      describe_multi_enum_scopes(false),
+      describe_supersets(false),
+      describe_translations(false),
+      describe_humanizations(false)
+    ].join( "\n" + "-" * 100 + "\n" )
+  end
+
+  def describe(short = true)
+    describe_basic
+    short ? describe_short : describe_long
+  end
+
+  def describe_short
+    enabled, disabled = enabled_features.except(:key_sample).partition{!_2.blank?}.map{ |prt| prt.map(&:shift) }
+    puts <<~SHORT
+      #{yellow("EnumExt extensions:")}
+      #{cyan("Enabled")}: #{enabled.join(", ")}
+      #{red("Disabled")}: #{disabled.join(", ")}
+    SHORT
+
+    print_short(:supersets)
+    print_short(:translations)
+    print_short(:humanization)
+  end
+
+  # --------------------------------------------------------------------
+  # ------------- per helpers describers -------------------------------
+  # --------------------------------------------------------------------
+  def describe_enum_i(output = true)
+    description = basic_helpers_usage_header(:enum_i)
+    description << <<~ENUM_I if enabled_features[:enum_i]
+      #{black("instance")}.#{cyan( enabled_features[:enum_i] )} 
+      # output will be same as #{base_class.to_s}.#{enum_name}[:#{enabled_features[:key_sample]}]
+    ENUM_I
+
+    output ? puts(description) : description
+  end
+
+  def describe_mass_assign_enum(output = true)
+    description = basic_helpers_usage_header(:mass_assign_enum)
+    description << <<~MASS_ASSIGN if enabled_features[:mass_assign_enum]
+      # To assign #{enabled_features[:key_sample]} to all elements of any_scope or relation call:
+      #{black(base_class.to_s)}.any_scope.#{cyan( enabled_features[:mass_assign_enum] )}
+    MASS_ASSIGN
+
+    output ? puts(description) : description
+  end
+
+  def describe_multi_enum_scopes(output = true)
+    description = basic_helpers_usage_header(:multi_enum_scopes)
+    description << <<~MULTI_SCOPES if enabled_features[:multi_enum_scopes]
+      # Two scopes: with_#{enum_name} and without_#{enum_name} are defined
+      # To get elements with a given enums or supersets values call:
+      #{black(base_class.to_s)}.#{cyan("with_#{enum_name}")}(:#{keys.sample(2).join(", :")})
+      \n# To get all elements except for the ones with enums or supersets values call:
+      #{black(base_class.to_s)}.#{cyan("without_#{enum_name}")}(:#{keys.sample(2).join(", :")})
+    MULTI_SCOPES
+
+    output ? puts(description) : description
+  end
+
+  def describe_supersets(output = true)
+    description = if enabled_features[:supersets].blank?
+      red( "\nSupersets not used!\n" )
+    else
+      red( "\nSupersets definitions:\n" ) << inspect_hash(enabled_features[:supersets]) << <<~SUPERSETS
+          # Instance methods added: #{enabled_features[:supersets].keys.join("?, ")}?
+   
+          # Class level methods added: #{enabled_features[:supersets].keys.join(", ")}
+       SUPERSETS
+    end
+
+    output ? puts(description) : description
+  end
+
+  def describe_translations(output = true)
+    description = if enabled_features[:translations].blank?
+      red( "\nTranslations not used!\n" )
+    else
+      red( "\nTranslations definitions (will skip instance dependent translation)\n" ) <<
+        inspect_hash(enabled_features[:translations])
+    end
+
+    output ? puts(description) : description
+  end
+
+  def describe_humanizations(output = true)
+    description = if enabled_features[:humanization].blank?
+      red( "\nHumanization not used!\n" )
+    else
+      red( "\nHumanization definitions (will skip instance dependent humanization)\n" ) <<
+        inspect_hash(enabled_features[:humanization])
+    end
+
+    output ? puts(description) : description
+  end
+
+  private
+
+  def enabled_features
+    enum_sample = keys.first
+    {
+      key_sample: enum_sample,
+      enum_i: base_class.instance_methods.include?("#{enum_name}_i".to_sym) && "#{enum_name}_i",
+      mass_assign_enum: base_class.respond_to?("#{enum_sample}!") && "#{enum_sample}!",
+      multi_enum_scopes: base_class.respond_to?("with_#{enum_name.to_s.pluralize}") && "with_#{enum_name.to_s.pluralize}",
+      supersets: supersets_raw,
+      translations: try(:t_options),
+      humanization: try(:t_options)
+    }
+  end
+
+  def basic_helpers_usage_header(helper_name)
+    enabled_features[helper_name] ? "\n#{red(helper_name)} helpers enabled, usage:\n"
+           : "\n#{helper_name} wasn't used\n"
+  end
+
+  def print_hash(hsh)
+    defined?(ai) ? ap(hsh) : pp(hsh)
+  end
+
+  def inspect_hash(hsh)
+    defined?(ai) ? hsh.ai : hsh.inspect
+  end
+
+  def print_short(feature)
+    if enabled_features[feature].present?
+      puts black("#{feature.to_s.humanize}:")
+      print_hash(enabled_features[feature])
+    end
+  end
+
+  def yellow(str)
+    # yellow ANSI color
+    "\e[0;33;49m#{str}\e[0m"
+  end
+
+  def cyan(str)
+    # cyan ANSI color
+    "\e[0;36;49m#{str}\e[0m"
+  end
+
+  def red(str)
+    # red ANSI color
+    "\e[0;31;49m#{str}\e[0m"
+  end
+
+  def black(comment)
+    # bright black bold ANSI color
+    "\e[0;90;1;49m#{comment}\e[0m"
+  end
+
+end
+
+

data/lib/enum_ext/basic_helpers.rb

@@ -0,0 +1,79 @@
+module EnumExt::BasicHelpers
+
+  # Defines instance method a shortcut for getting integer value of an enum.
+  # for enum named 'status' will generate:
+  #
+  # instance.status_i
+  private
+  def enum_i( enum_name )
+    define_method "#{enum_name}_i" do
+      self.class.send("#{enum_name.to_s.pluralize}")[send(enum_name)].to_i
+    end
+  end
+
+  # Defines two scopes for one for an inclusion: `WHERE enum IN( enum1, enum2 )`,
+  # and the second for an exclusion: `WHERE enum NOT IN( enum1, enum2 )`
+  #
+  # Ex:
+  #  Request.with_statuses( :payed, :delivery_set )    # >> :payed and [:ready_for_shipment, :on_delivery, :delivered] requests
+  #  Request.without_statuses( :payed )                # >> scope for all requests with statuses not eq to :payed
+  #  Request.without_statuses( :payed, :in_warehouse ) # >> scope all requests with statuses not eq to :payed or :ready_for_shipment
+  def multi_enum_scopes(enum_name)
+    enum_plural = enum_name.to_s.pluralize
+    enum_obj = send(enum_plural)
+
+    self.instance_eval do
+      # EnumExt.define_superset_to_enum_method(self, enum_plural)
+      # EnumExt.define_summary_methods(self, enum_plural)
+
+      # with_enums scope
+      scope "with_#{enum_plural}", -> (*enum_list) {
+        enum_list.blank? ? nil : where( enum_name => enum_obj.superset_to_enum(*enum_list) )
+      } if !respond_to?("with_#{enum_plural}") && respond_to?(:scope)
+
+      # without_enums scope
+      scope "without_#{enum_plural}", -> (*enum_list) {
+        enum_list.blank? ? nil : where.not( enum_name => enum_obj.superset_to_enum(*enum_list) )
+      } if !respond_to?("without_#{enum_plural}") && respond_to?(:scope)
+    end
+  end
+
+  # Ex mass_assign_enum
+  #
+  # Used for mass assigning for collection without callbacks it creates bang methods for collections using update_all.
+  # it's often case when you need bulk update without callbacks, so it's gets frustrating to repeat:
+  # some_scope.update_all(status: Request.statuses[:new_status], update_at: Time.now)
+  #
+  # If you need callbacks you can do like this: some_scope.each(&:new_stat!) but if you don't need callbacks
+  # and you have lots of records to change at once you need update_all
+  #
+  #  mass_assign_enum( :status )
+  #
+  #  class methods:
+  #    in_cart! paid! in_warehouse! and so
+  #
+  # Console:
+  # request1.in_cart!
+  # request2.waiting_for_payment!
+  # Request.with_statuses( :in_cart, :waiting_for_payment ).payed!
+  # request1.paid?                          # >> true
+  # request2.paid?                          # >> true
+  # request1.updated_at                     # >> Time.now
+  #
+  # order.requests.paid.all?(&:paid?)       # >> true
+  # order.requests.paid.delivered!
+  # order.requests.map(&:status).uniq       #>> [:delivered]
+
+  def mass_assign_enum( *enums_names )
+    enums_names.each do |enum_name|
+      enum_vals = self.send( enum_name.to_s.pluralize )
+
+      enum_vals.keys.each do |enum_el|
+        define_singleton_method( "#{enum_el}!" ) do
+          self.update_all( {enum_name => enum_vals[enum_el]}.merge( self.column_names.include?('updated_at') ? {updated_at: Time.now} : {} ))
+        end
+      end
+    end
+  end
+  alias_method :enum_mass_assign, :mass_assign_enum
+end

data/lib/enum_ext/enum_wrapper.rb

@@ -0,0 +1,78 @@
+# This is an wrapper class for a basic enum.
+# Since enum values will be freezed right after the definition, we can't enrich enum directly functionality
+# We can only wrap it with our own object and delegate enum base base functionality internally
+class EnumExt::EnumWrapper
+  include EnumExt::Annotated
+
+  # supersets is storing exact definitions, if you need a raw mapping use class.statuses.superset_statuses
+  attr_reader :enum_values, :supersets, :supersets_raw, :t_options_raw, :localizations, :base_class, :enum_name
+
+  delegate_missing_to :enum_values
+  delegate :inspect, to: :enum_values
+
+  def initialize(enum_values, base_class, enum_name)
+    @enum_values = enum_values
+    @supersets = ActiveSupport::HashWithIndifferentAccess.new
+    @supersets_raw = ActiveSupport::HashWithIndifferentAccess.new
+
+    @t_options_raw = ActiveSupport::HashWithIndifferentAccess.new
+    @localizations = ActiveSupport::HashWithIndifferentAccess.new
+
+    @base_class = base_class
+    @enum_name = enum_name
+  end
+
+  #  ext_sets_to_kinds( :ready_for_shipment, :delivery_set ) -->
+  #                   [:ready_for_shipment, :on_delivery, :delivered]
+  def superset_to_enum( *enum_or_sets )
+    return [] if enum_or_sets.blank?
+    enum_or_sets_strs = enum_or_sets.map(&:to_s)
+
+    next_level_deeper = supersets.slice( *enum_or_sets_strs ).values.flatten
+    (enum_or_sets_strs & enum_values.keys | send(:superset_to_enum, *next_level_deeper)).uniq
+  end
+
+  def all
+    {
+      **enum_values,
+      supersets: {
+        **send(:supersets_raw)
+      }
+    }
+  end
+
+  def t_options_i
+    evaluate_localizations_to_i(localizations)
+  end
+
+  def t_options
+    evaluate_localizations(localizations)
+  end
+
+  alias_method :t, :localizations
+
+  private
+
+  def evaluate_localizations(t_enum_set)
+    # { kind => kind_translator, kind2 => kind2_translator } --> [[kind_translator, kind], [kind2_translator, kind2]]
+    t_enum_set.invert.to_a.map do | translator, enum_key |
+      # since all procs in t_enum are evaluated in context of a record than it's not always possible to create select options automatically
+      translation = if translator.respond_to?(:call)
+        if translator.arity < 1
+          translator.call rescue "Cannot create option for #{enum_key} ( proc fails to evaluate )"
+        else
+          "Cannot create option for #{enum_key} because of a lambda"
+        end
+      end || translator
+      [translation, enum_key]
+    end
+  end
+
+  def evaluate_localizations_to_i(t_enum_set)
+    # { kind => kind_translation, kind2 => kind2_translation } --> [[kind_translation, kind_i], [kind2_translation, kind2_i]]
+    evaluate_localizations(t_enum_set).map do | translation, name |
+      [ translation, self[name] ]
+    end
+  end
+
+end

data/lib/enum_ext/humanize_helpers.rb

@@ -0,0 +1,161 @@
+module EnumExt::HumanizeHelpers
+
+  # if app doesn't need internationalization, it may use humanize_enum to make enum user friendly
+  #
+  # class Request
+  #   humanize_enum :status, {
+  #     #locale dependent example with pluralization and lambda:
+  #     payed: -> (t_self) { I18n.t("request.status.payed", count: t_self.sum ) }
+  #
+  #     #locale dependent example with pluralization and proc:
+  #     payed: Proc.new{ I18n.t("request.status.payed", count: self.sum ) }
+  #
+  #     #locale independent:
+  #     ready_for_shipment: "Ready to go!"
+  #   }
+  # end
+  #
+  # Could be called multiple times, all humanization definitions will be merged under the hood:
+  #  humanize_enum :status, {
+  #     payed: I18n.t("scope.#{status}")
+  # }
+  # humanize_enum :status, {
+  #   billed: I18n.t("scope.#{status}")
+  # }
+  #
+  #
+  # Example with block:
+  #
+  # humanize_enum :status do
+  #  I18n.t("scope.#{status}")
+  # end
+  #
+  # in views select:
+  #   f.select :status, Request.t_statuses_options
+  #
+  # in select in Active Admin filter
+  #   collection: Request.t_statuses_options_i
+  #
+  # Rem: select options breaks when using lambda() with params
+  #
+  # Console:
+  #   request.sum = 3
+  #   request.payed!
+  #   request.status     # >> payed
+  #   request.t_status   # >> "Payed 3 dollars"
+  #   Request.t_statuses # >> { in_cart: -> { I18n.t("request.status.in_cart") }, ....  }
+  def humanize_enum( *args, &block )
+    enum_name = args.shift
+    localization_definitions = args.pop
+    enum_plural = enum_name.to_s.pluralize
+    enum_object = send( enum_plural )
+
+    self.instance_eval do
+      # instance.t_enum
+      define_method "t_#{enum_name}" do
+        t = block || enum_object.localizations[send(enum_name)]
+        if t.try(:lambda?)
+          t.try(:arity) == 1 && t.call( self ) || t.try(:call)
+        elsif t.is_a?(Proc)
+          instance_eval(&t)
+        else
+          t
+        end.to_s
+      end
+
+      # if localization is absent than block must be given
+      enum_object.localizations.merge!(
+        localization_definitions.try(:with_indifferent_access) ||
+          send(enum_plural).map do |k, _v|
+            # little bit hackerish: instantiate object just with enum setup and then call its t_.. method which
+            [k, Proc.new{ self.new({ enum_name => k }).send("t_#{enum_name}") }]
+          end.to_h.with_indifferent_access
+      )
+
+      # hm.. lost myself here, why did I implement this method
+      define_method "t_#{enum_name}=" do |new_val|
+        send("#{enum_name}=", new_val)
+      end
+
+    end
+  end
+  alias localize_enum humanize_enum
+
+  # Simple way to translate enum.
+  # It use either given scope as second argument, or generated activerecord.attributes.model_name_underscore.enum_name
+  # If block is given than no scopes are taken in consider
+  def translate_enum( *args, &block )
+    enum_name = args.shift
+    enum_plural = enum_name.to_s.pluralize
+    t_scope = args.pop || "activerecord.attributes.#{self.name.underscore}.#{enum_plural}"
+
+    if block_given?
+      humanize_enum( enum_name, &block )
+    else
+      humanize_enum( enum_name, send(enum_plural).keys.map{|en| [ en, Proc.new{ I18n.t("#{t_scope}.#{en}") }] }.to_h )
+    end
+  end
+
+  # human_attribute_name is redefined for automation like this:
+  # p #{object.class.human_attribute_name( attr_name )}:
+  # p object.send(attr_name)
+  def human_attribute_name( name, options = {} )
+    # if name starts from t_ and there is a column with the last part then ...
+    name[0..1] == 't_' && column_names.include?(name[2..-1]) ? super( name[2..-1], options ) : super( name, options )
+  end
+
+
+  # t_... methods for supersets will just slice
+  # original enum t_.. methods output and return only superset related values from it
+  #
+  def self.define_superset_humanization_helpers(base_class, superset_name, enum_name)
+    enum_plural = enum_name.to_s.pluralize
+    enum_object = base_class.send(enum_plural)
+
+    enum_object.define_singleton_method( "t_#{superset_name}_options" ) do
+      result = evaluate_localizations(send("t_#{superset_name}"))
+      return result unless result.blank?
+
+      [["Enum translations call missed. Did you forget to call translate #{enum_name}"]*2]
+    end
+
+    # enums.t_options_i
+    enum_object.define_singleton_method( "t_#{superset_name}_options_i" ) do
+      result = evaluate_localizations_to_i( send("t_#{superset_name}") )
+      return result unless result.to_h.values.all?(&:blank?)
+
+      [["Enum translations are missing. Did you forget to translate #{enum_name}"]*2]
+    end
+
+
+    # enums.t_superset ( translations or humanizations subset for a given set )
+    enum_object.define_singleton_method( "t_#{superset_name}" ) do
+      return [(["Enum translations are missing. Did you forget to translate #{enum_name}"]*2)].to_h if localizations.blank?
+
+      enum_object.localizations.slice( *enum_object.send(superset_name) )
+    end
+  end
+end
+
+
+# # t_... - are translation dependent methods
+# # This one is a narrow case helpers just a quick subset of t_ enums options for a set
+# # class.t_enums_options
+# enum_obj.define_singleton_method( "t_#{superset_name}_options" ) do
+#   return [["Enum translations call missed. Did you forget to call translate #{enum_name}"]*2] unless respond_to?( "t_#{enum_plural}_options_raw" )
+#
+#   send("t_#{enum_plural}_options_raw", send("t_#{superset_name}_#{enum_plural}") )
+# end
+#
+# # class.t_enums_options_i
+# enum_obj.define_singleton_method( "t_#{superset_name}_options_i" ) do
+#   return [["Enum translations call missed. Did you forget to call translate #{enum_name}"]*2] unless respond_to?( "t_#{enum_plural}_options_raw_i" )
+#
+#   send("t_#{enum_plural}_options_raw_i", send("t_#{superset_name}_#{enum_plural}") )
+# end
+#
+# enum_obj.define_singleton_method( "t_#{superset_name}_options" ) do
+#   return [["Enum translations call missed. Did you forget to call translate #{enum_name}"]*2] if t_options_raw.blank?
+#
+#   t_options_raw["t_#{superset_name}"]
+# end

data/lib/enum_ext/superset_helpers.rb

@@ -0,0 +1,77 @@
+module EnumExt::SupersetHelpers
+  # enum_supersets
+  # This method intend for creating and using some sets of enum values,
+  # you should
+  #
+  # it creates: scopes for subsets,
+  #             instance method with ?
+  #
+  # For this call:
+  #   enum status: [:in_cart, :waiting_for_payment, :paid, :packing, :ready_for_shipment, :on_delivery, :delivered],
+  #      ext:[  , supersets: {
+  #                   delivery_set: [:ready_for_shipment, :on_delivery] # for shipping department for example
+  #                   in_warehouse: [:packing, :ready_for_shipment]            # this scope is just for superposition example below
+  #                   sold: [:payd, :delivery_set, :in_warehouse, :delivered]
+  #                 } ]
+  #Rem:
+  #  enum_supersets can be called twice defining a superposition of already defined supersets
+  #  based on array operations, with already defined array methods ( considering previous example ):
+  #  enum_supersets :status, {
+  #                  outside_warehouse: ( delivery_set_statuses - in_warehouse_statuses )... any other array operations like &, + and so can be used
+  #                }
+  #
+  # so the enum_supersets will generate:
+  #   instance:
+  #     methods: delivery_set?, in_warehouse?
+  #   class:
+  #     named scopes: delivery_set, in_warehouse
+  #     class helpers:
+  #       - delivery_set_statuses (=[:ready_for_shipment, :on_delivery, :delivered] ), in_warehouse_statuses
+  #       - delivery_set_statuses_i (= [3,4,5]), in_warehouse_statuses_i (=[3])
+  #     class translation helpers ( started with t_... )
+  #       for select inputs purposes:
+  #       - t_delivery_set_statuses_options (= [['translation or humanization', :ready_for_shipment] ...])
+  #       same as above but with integer as value ( for example to use in Active admin filters )
+  #       - t_delivery_set_statuses_options_i (= [['translation or humanization', 3] ...])
+
+  # Console:
+  #  request.on_delivery!
+  #  request.delivery_set?                    # >> true
+
+  #  Request.delivery_set.exists?(request)    # >> true
+  #  Request.in_warehouse.exists?(request)    # >> false
+  #
+  #  Request.statuses.supersets[:delivery_set]           # >> [:ready_for_shipment, :on_delivery, :delivered]
+  private
+  def enum_supersets( enum_name, options = {} )
+    enum_plural = enum_name.to_s.pluralize
+
+    self.instance_eval do
+      enum_obj = send(enum_plural)
+      enum_obj.supersets.merge!( options.transform_values{ _1.try(:map, &:to_s) || _1.to_s } )
+
+      options.each do |superset_name, enum_vals|
+        raise "Can't define superset with name: #{superset_name}, #{enum_plural} already has such method!" if enum_obj.respond_to?(superset_name)
+
+        enum_obj.supersets_raw[superset_name] = enum_obj.superset_to_enum(*enum_vals)
+
+        # class.statuses.superset_statuses
+        enum_obj.define_singleton_method(superset_name) { enum_obj.superset_to_enum(*enum_vals) }
+
+        # superset_name scope
+        scope superset_name, -> { where( enum_name => enum_obj.send(superset_name) ) } if respond_to?(:scope)
+
+        # instance.superset_name?
+        define_method "#{superset_name}?" do
+          send(enum_name) && enum_obj.send(superset_name).include?( send(enum_name) )
+        end
+
+        EnumExt::HumanizeHelpers.define_superset_humanization_helpers( self, superset_name, enum_name )
+      end
+
+    end
+  end
+  alias_method :ext_enum_sets, :enum_supersets
+end
+
+

data/lib/enum_ext/version.rb

@@ -1,3 +1,3 @@
 module EnumExt
-  VERSION = "0.5.2"
+  VERSION = "0.8.0"
 end