Module: Enumbler::Enabler::ClassMethods

Defined in:
lib/enumbler/enabler.rb

Overview

These ClassMethods can be included in any model that you wish to Enumble!

class Color < ApplicationRecord
include Enumbler::Enabler

enumble :black, 1
enumble :white, 2
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#enumbles ⇒ Object (readonly)

Returns the value of attribute enumbles.



63
64
65
 
# File 'lib/enumbler/enabler.rb', line 63

def enumbles
  @enumbles
end

Instance Method Details

#enumble(enum, id, label: nil, **attributes) ⇒ Object

Defines an Enumble for this model. An enum with integrity.

# in your migration
create_table :colors, force: true do |t|
t.string :label, null: false, index: { unique: true }
end

class Color < ApplicationRecord
include Enumbler::Enabler

enumble :black, 1, hex: '000000'
enumble :white, 2, hex: 'ffffff'
enumble :dark_brown, 3, # label: 'dark-brown'
enumble :black_hole, 3, label: 'Oh my! It is a black hole!'
end

# Dynamically adds the following methods:
Color::BLACK   #=> 1
Color.black    #=> Color.find(1)
color.black?   #=> true || false
color.is_black #=> true || false

Parameters:

  • enum (Symbol) —

    the enum representation

  • id (Integer) —

    the primary key value

  • label (String) (defaults to: nil) —

    optional: label for humans

  • **attributes (Hash) —

    optional: additional attributes and values that will be saved to the database for this enumble record



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/enumbler/enabler.rb', line 92

def enumble(enum, id, label: nil, **attributes)
  raise_error_if_model_does_not_support_attributes(attributes)

  id = validate_id_is_numeric(enum, id)

  @enumbles ||= Enumbler::Collection.new
  @enumbled_model = self
  @enumbler_label_column_name ||= :label

  enumble = Enumble.new(enum, id, label: label, label_column_name: @enumbler_label_column_name, **attributes)

  if @enumbles.include?(enumble)
    raise Error, "You cannot add the same Enumble twice! Attempted to add: #{enum}, #{id}."
  end

  define_dynamic_methods_and_constants_for_enumbled_model(enumble)

  @enumbles << enumble
end

#enumbler_label_column_name(label_column_name) ⇒ Object

By default, the Enumbler is expecting a table with an underlying column named label that represents the enum in the database. You can change this by calling enumlber_label_column_name before you enumble!

ActiveRecord::Schema.define do
create_table :feelings, force: true do |t|
  t.string :emotion, null: false, index: { unique: true }
end
end

class Feeling < ApplicationRecord
# @!parse extend Enumbler::Enabler::ClassMethods
include Enumbler::Enabler

enumbler_label_column_name :emotion

enumble :sad, 1
enumble :happy, 2
enumble :verklempt, 3, label: 'overcome with emotion'
end


132
133
134
 
# File 'lib/enumbler/enabler.rb', line 132

def enumbler_label_column_name(label_column_name)
  @enumbler_label_column_name = label_column_name
end

#find_by_enumble(arg, case_sensitive: false, raise_error: false) ⇒ self

Like ActiveRecord#find_by, will try and return an instance of this model that matches any of our enumble attributes (instance, id, string, or symbol).

Color.find_by_enumble(1)
Color.find_by_enumble(:black)
Color.find_by_enumble("black")
Color.find_by_enumble("BLACK")
Color.find_by_enumble(Color.black) # => self
Color.find_by_enumble("whoops")    # => nil

Parameters:

  • arg (Class, String, Integer, Symbol) —

    search argument

  • case_sensitive (Boolean) (defaults to: false) —

    string search to be case sensitive (default: false)

  • raise_error (Boolean) (defaults to: false) —

    whether to raise RecordNotFound error (default: false)

Returns:

  • (self) 


151
152
153
154
155
156
157
158
159
160
 
# File 'lib/enumbler/enabler.rb', line 151

def find_by_enumble(arg, case_sensitive: false, raise_error: false)
  return arg if arg.instance_of?(@enumbled_model)

  id = id_from_enumbler(arg, case_sensitive: case_sensitive, raise_error: raise_error)

  find_by = raise_error ? :find_by! : :find_by
  @enumbled_model.public_send(find_by, id: id)
rescue Enumbler::Error
  raise ActiveRecord::RecordNotFound.new("Couldn't find #{@enumbled_model}", @enumbled_model)
end

#find_by_enumble!(arg, case_sensitive: false) ⇒ self

Like ActiveRecord#find, will try and return an instance of this model that matches any of our enumble attributes (instance, id, string, or symbol) raises a RecordNotFound error if none found.

Color.find_by_enumble!(1)
Color.find_by_enumble!(:black)
Color.find_by_enumble!("black")
Color.find_by_enumble!("BLACK")
Color.find_by_enumble!(Color.black) # => returns self
Color.find_by_enumble!("whoops")    # => raise ActiveRecord::RecordNotFound

Parameters:

  • arg (Class, String, Integer, Symbol) —

    search argument

  • case_sensitive (Boolean) (defaults to: false) —

    string search to be case sensitive (default: false)

  • raise_error (Boolean) —

    whether to raise RecordNotFound error (default: false)

Returns:

  • (self) 


177
178
179
 
# File 'lib/enumbler/enabler.rb', line 177

def find_by_enumble!(arg, case_sensitive: false)
  find_by_enumble(arg, case_sensitive: case_sensitive, raise_error: true)
end

#find_enumble(arg, case_sensitive: false, raise_error: false) ⇒ Enumbler::Enumble

See #find_enumbles. Simply returns the first object. Use when you want one argument to be found and not returned in an array.

Parameters:

  • args (Integer, String, Symbol)
  • case_sensitive (Boolean) (defaults to: false) —

    should a String search be case sensitive (default: false)

  • raise_error (Boolean) (defaults to: false) —

    raise an error if not found (default: false)

Returns:

Raises:

  • (Error) —

    when there is no [Enumbler::Enumble] to be found and raise_error: true



191
192
193
 
# File 'lib/enumbler/enabler.rb', line 191

def find_enumble(arg, case_sensitive: false, raise_error: false)
  find_enumbles(arg, case_sensitive: case_sensitive, raise_error: raise_error).first
end

#find_enumble!(arg, case_sensitive: false) ⇒ Enumbler::Enumble

See #find_enumbles. Simply returns the first object. Use when you want one argument to be found and not returned in an array. Raises error if none found.

Parameters:

  • args (Integer, String, Symbol)
  • case_sensitive (Boolean) (defaults to: false) —

    should a String search be case sensitive (default: false)

Returns:

Raises:

  • (Error) —

    when there is no [Enumbler::Enumble] to be found and raise_error: true



204
205
206
 
# File 'lib/enumbler/enabler.rb', line 204

def find_enumble!(arg, case_sensitive: false)
  find_enumbles(arg, case_sensitive: case_sensitive, raise_error: true).first
end

#find_enumbles(*args, case_sensitive: false, raise_error: false) ⇒ Array<Enumbler::Enumble>

Finds an array of Enumbler::Enumble objects matching the given argument. Accepts an Integer, String, Symbol, or ActiveRecord instance.

This method is designed to let you get information about the record without having to hit the database. Returns nil when none found unless raise_error is true.

Color.find_enumbles(:black, 'white', 'not-found')
 #=> [Enumbler::Enumble<:black>, Enumbler::Enumble<:white>, nil]

Parameters:

  • args (Integer, String, Symbol)
  • case_sensitive (Boolean) (defaults to: false) —

    should a String search be case sensitive (default: false)

  • raise_error (Boolean) (defaults to: false) —

    raise an error if not found (default: false)

Returns:

Raises:

  • (Error) —

    when there is no [Enumbler::Enumble] to be found and raise_error: true



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/enumbler/enabler.rb', line 226

def find_enumbles(*args, case_sensitive: false, raise_error: false)
  args.flatten.compact.uniq.map do |arg|
    err = "Unable to find a #{@enumbled_model}#enumble with #{arg}"

    begin
      arg = Integer(arg) # raises Type error if not a real integer
      enumble = @enumbled_model.enumbles.find { |e| e.id == arg }
    rescue TypeError, ArgumentError
      enumble =
        if arg.is_a?(Symbol)
          @enumbled_model.enumbles.find { |e| e.enum == arg }
        elsif arg.is_a?(Enumbler::Enumble)
          @enumbled_model.enumbles.find { |e| e.enum == arg.enum }
        elsif arg.is_a?(String)
          @enumbled_model.enumbles.find do |e|
            if case_sensitive
              [e.label, e.enum.to_s].include?(arg)
            else
              arg.casecmp?(e.label) || arg.casecmp?(e.enum.to_s)
            end
          end
        elsif arg.instance_of?(@enumbled_model)
          arg.enumble
        end
    end

    if enumble.present?
      enumble
    else
      raise Error if raise_error

      nil
    end
  rescue Error
    raise Error, err
  end
end

#find_enumbles!(*args, case_sensitive: false) ⇒ Array<Enumbler::Enumble>

See #find_enumbles. Same method, only raises error when none found.

Parameters:

  • args (Integer, String, Symbol)
  • case_sensitive (Boolean) (defaults to: false) —

    should a String search be case sensitive (default: false)

Returns:

Raises:

  • (Error) —

    when there is no [Enumbler::Enumble] to be found



270
271
272
 
# File 'lib/enumbler/enabler.rb', line 270

def find_enumbles!(*args, case_sensitive: false)
  find_enumbles(*args, case_sensitive: case_sensitive, raise_error: true)
end

#id_from_enumbler(arg, case_sensitive: false, raise_error: false) ⇒ Integer

Return the record id for a given argument. Can accept an Integer, a Symbol, or an instance of Enumbled model. This lookup is a database-free lookup.

Color.id_from_enumbler(1) # => 1
Color.id_from_enumbler(:black) # => 1
Color.id_from_enumbler(Color.black) # => 1

Parameters:

  • arg (Integer, Symbol, Class)
  • case_sensitive (Boolean) (defaults to: false) —

    should a string search be performed with case sensitivity (default: false)

  • raise_error (Boolean) (defaults to: false) —

    raise an error if not found (default: false)

Returns:

  • (Integer)

Raises:

  • (Error) —

    when there is no enumble to be found



289
290
291
 
# File 'lib/enumbler/enabler.rb', line 289

def id_from_enumbler(arg, case_sensitive: false, raise_error: false)
  ids_from_enumbler(arg, case_sensitive: case_sensitive, raise_error: raise_error).first
end

#id_from_enumbler!(arg, case_sensitive: false) ⇒ Integer

See #ids_from_enumbler. Raises error if none found.

Parameters:

  • arg (Integer, Symbol, Class)
  • case_sensitive (Boolean) (defaults to: false) —

    should a string search be performed with case sensitivity (default: false)

  • raise_error (Boolean) —

    raise an error if not found (default: false)

Returns:

  • (Integer)

Raises:

  • (Error) —

    when there is no enumble to be found



301
302
303
 
# File 'lib/enumbler/enabler.rb', line 301

def id_from_enumbler!(arg, case_sensitive: false)
  ids_from_enumbler(arg, case_sensitive: case_sensitive, raise_error: true).first
end

#ids_from_enumbler(*args, case_sensitive: false, raise_error: false) ⇒ Array<Integer>

Return the record id(s) based on different argument types. Can accept an Integer, a Symbol, or an instance of Enumbled model. This lookup is a database-free lookup.

Color.ids_from_enumbler(1, 2) # => [1, 2]
Color.ids_from_enumbler(:black, :white) # => [1, 2]
Color.ids_from_enumbler('black', :white) # => [1, 2]
Color.ids_from_enumbler(Color.black, Color.white) # => [1, 2]

Parameters:

  • *args (Integer, Symbol, Class)
  • case_sensitive (Boolean) (defaults to: false) —

    should a string search be performed with case sensitivity (default: false)

  • raise_error (Boolean) (defaults to: false) —

    raise an error if not found (default: false)

Returns:

  • (Array<Integer>)

Raises:

  • (Error) —

    when there is no enumble to be found



321
322
323
324
 
# File 'lib/enumbler/enabler.rb', line 321

def ids_from_enumbler(*args, case_sensitive: false, raise_error: false)
  enumbles = find_enumbles(*args, case_sensitive: case_sensitive, raise_error: raise_error)
  enumbles.map { |e| e&.id }
end

#ids_from_enumbler!(*args, case_sensitive: false) ⇒ Array<Integer>

See #ids_from_enumbler. Raises error when none found.

Parameters:

  • *args (Integer, Symbol, Class)
  • case_sensitive (Boolean) (defaults to: false) —

    should a string search be performed with case sensitivity (default: false)

Returns:

  • (Array<Integer>)

Raises:

  • (Error) —

    when there is no enumble to be found



332
333
334
335
 
# File 'lib/enumbler/enabler.rb', line 332

def ids_from_enumbler!(*args, case_sensitive: false)
  enumbles = find_enumbles!(*args, case_sensitive: case_sensitive)
  enumbles.map(&:id)
end

#seed_the_enumbler(delete_missing_records: false, validate: true) ⇒ Object

Seeds the database with the Enumbler data.

Parameters:

  • delete_missing_records (Boolean) (defaults to: false) —

    remove any records that are no longer defined (default: false)

  • validate (Boolean) (defaults to: true) —

    validate on save?



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/enumbler/enabler.rb', line 341

def seed_the_enumbler(delete_missing_records: false, validate: true)
  max_database_id = all.order("id desc").take&.id || 0
  max_enumble_id = @enumbles.map(&:id).max

  # If we are not deleting records, we just need to update each listed
  # enumble and skip anything else in the database.  If we are deleting
  # records, we need to know the max database id.
  iterator = if !delete_missing_records
               @enumbles.map(&:id)
             elsif max_enumble_id > max_database_id
               (1..max_enumble_id)
             else
               (1..max_database_id)
             end

  discarded_ids = []

  iterator.each do |id|
    enumble = @enumbles.find { |e| e.id == id }

    if enumble.nil?
      discarded_ids << id
      next
    end

    record = find_or_initialize_by(id: id)
    record.attributes = enumble.attributes
    record.save!(validate: validate)
  end

  where(id: discarded_ids).delete_all if delete_missing_records
end

#seed_the_enumbler!(validate: true) ⇒ Object

Seeds the database with the Enumble data, removing any records that are no longer defined.

Parameters:

  • validate (Boolean) (defaults to: true) —

    validate on save?



377
378
379
 
# File 'lib/enumbler/enabler.rb', line 377

def seed_the_enumbler!(validate: true)
  seed_the_enumbler(delete_missing_records: true, validate: validate)
end