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.



56
57
58
 
# File 'lib/enumbler/enabler.rb', line 56

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



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/enumbler/enabler.rb', line 85

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 `enumber_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



125
126
127
 
# File 'lib/enumbler/enabler.rb', line 125

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) 


144
145
146
147
148
149
150
151
152
153
 
# File 'lib/enumbler/enabler.rb', line 144

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) 


170
171
172
 
# File 'lib/enumbler/enabler.rb', line 170

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`



184
185
186
 
# File 'lib/enumbler/enabler.rb', line 184

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`



197
198
199
 
# File 'lib/enumbler/enabler.rb', line 197

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`



219
220
221
222
223
224
225
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
 
# File 'lib/enumbler/enabler.rb', line 219

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



263
264
265
 
# File 'lib/enumbler/enabler.rb', line 263

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



282
283
284
 
# File 'lib/enumbler/enabler.rb', line 282

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



294
295
296
 
# File 'lib/enumbler/enabler.rb', line 294

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



314
315
316
317
 
# File 'lib/enumbler/enabler.rb', line 314

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



325
326
327
328
 
# File 'lib/enumbler/enabler.rb', line 325

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?



334
335
336
337
338
339
340
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
 
# File 'lib/enumbler/enabler.rb', line 334

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?



370
371
372
 
# File 'lib/enumbler/enabler.rb', line 370

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