enum_ext 0.5.3 → 0.8.1

data/lib/enum_ext/annotated.rb

@@ -0,0 +1,181 @@
+# 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 options are
+  def describe_basic
+    puts yellow( "Basic #{enum_name} definition: \n" )
+    print_hash(enum_values)
+  end
+
+  # call it to see which enum extensions are defined.
+  def describe_long
+    puts yellow( "\n\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
+      superset_method = enabled_features[:supersets].keys.first
+      red( "\nSupersets definitions:\n" ) << inspect_hash(enabled_features[:supersets]) << <<~SUPERSETS
+          
+          # Instance methods added: #{enabled_features[:supersets].keys.join("?, ")}?
+          # Usage:
+          #{black("instance")}.#{cyan(superset_method)}?
+          # Will be equal true if any of: #{supersets_raw[superset_method].join("?, ")}? is true
+          
+          # Class level methods/scopes added: #{enabled_features[:supersets].keys.join(", ")}
+          # Usage:
+          #{black(base_class.to_s)}.#{cyan(superset_method)}
+          # Will be getting all instances with #{enum_name} equals to any of: #{supersets_raw[superset_method].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,86 @@
+module EnumExt::BasicHelpers
+
+  private
+  # Defines instance method a shortcut for getting integer value of an enum.
+  # for enum named 'status' will generate:
+  #
+  # instance.status_i
+  #
+  # Rem. Will not define helper when enum values are strings, and will print warning
+  def enum_i( enum_name )
+    return puts(<<~NOTINTEGER) if columns_hash[enum_name.to_s].type != :integer
+      ---------------------NOTINTEGER WARNING!---------------------------
+      #{enum_name} is not an integer column, so enum_i helper useless and method will not be defined
+    NOTINTEGER
+
+    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 )`
+  # works fine with supersets and basic enums
+  #
+  # 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
+
+    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 => send(enum_plural).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 => send(enum_plural).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: :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,159 @@
+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.statuses.t_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
+
+    self.instance_eval do
+      # instance.t_enum
+      define_method "t_#{enum_name}" do
+        t = block || self.class.send(enum_plural).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
+      send(enum_plural).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
+
+    base_class.send(enum_plural).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
+    base_class.send(enum_plural).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 )
+    base_class.send(enum_plural).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?
+
+      base_class.send(enum_plural).localizations.slice( *base_class.send(enum_plural).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,83 @@
+module EnumExt::SupersetHelpers
+  # enum_supersets
+  # **Use-case** whenever you need superset of enums to behave like a super enum.
+  #
+  #   You can do this with method **enum_supersets** it creates:
+  #     - scopes for subsets,
+  #     - instance methods with `?`
+  #
+  #   For example:
+  #    enum status: [:in_cart, :waiting_for_payment, :paid, :packing, :ready_for_shipment, :on_delivery, :delivered],
+  #         ext: [enum_supersets: {
+  #                 around_delivery: [: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: [:paid, :around_delivery, :in_warehouse, :delivered] # also you can define any superposition of already defined supersets or enum values
+  #               }]
+  #
+  #    # supersets will be stored inside enum wrapper object, and can be de-referenced to basic enum values
+  #    # using wrapper defined methods: "superset_enum_plural", i.e. statuses.sold_statuses -> [:paid, :packing, :ready_for_shipment, :on_delivery, :delivered]
+  #    # so new supersets could be defined using Array operations against newly defined methods
+  #    enum_ext :status, enum_supersets: {
+  #                   outside_warehouse: ( statuses.around_delivery - statuses.in_warehouse ) #... any other array operations like &, + and so can be used
+  #                 }
+  #
+  #   it will generate:
+  #
+  # instance:
+  #   - methods: around_delivery?, in_warehouse?
+  #
+  # class:
+  #   - named scopes: around_delivery, in_warehouse
+  #
+  # enum methods:
+  #   - Class.statuses.supersets -- will output superset definition hash
+  #   - Class.statuses.supersets_raw -- will output superset decompositions to basic enum types hash
+  #
+  #   - Class.statuses.around_delivery (=[:ready_for_shipment, :on_delivery, :delivered] ), in_warehouse_statuses
+  #   - around_delivery_statuses_i (= [3,4,5]), in_warehouse_statuses_i (=[3])
+  #
+  #   translation helpers grouped for superset ( started with t_... ):
+  #   - Class.statuses.t_around_delivery_options (= [['translation or humanization', :ready_for_shipment] ...] ) for select inputs purposes
+  #   - Class.statuses.t_around_delivery_options_i (= [['translation or humanization', 3] ...]) same as above but with integer as value ( for example to use in Active admin filters )
+  #
+  #   In console:
+  #   request.on_delivery!
+  #   request.around_delivery?                    # >> true
+  #
+  #   Request.around_delivery.exists?(request)    # >> true
+  #   Request.in_warehouse.exists?(request)    # >> false
+  #
+  #   Request.statuses.around_delivery            # >> ["ready_for_shipment", "on_delivery", "delivered"]
+
+  private
+  def enum_supersets( enum_name, options = {} )
+    enum_plural = enum_name.to_s.pluralize
+
+    self.instance_eval do
+      send(enum_plural).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 send(enum_plural).respond_to?(superset_name)
+
+        send(enum_plural).supersets_raw[superset_name] = send(enum_plural).superset_to_enum(*enum_vals)
+
+        # class.enum_wrapper.superset
+        send(enum_plural).define_singleton_method(superset_name) { base_class.send(enum_plural).superset_to_enum(*enum_vals) }
+
+        # superset_name scope
+        scope superset_name, -> { where( enum_name => send(enum_plural).send(superset_name) ) } if respond_to?(:scope)
+
+        # instance.superset_name?
+        define_method "#{superset_name}?" do
+          send(enum_name) && self.class.send(enum_plural).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.3"
+  VERSION = "0.8.1"
 end