ActWithFlags

A Rails gem required by key.matiq.

Handles booleans in "flags". Defines setters and getters to access the booleans.

As usual:

# Gemfile
gem "act_with_flags"

and run "bundle install".

Option "range" can be specified just once for all "add_to_flags" for a specific "origin".

For example:

Order.add_to_flags range: ..0
...
Order.add_to_flags :a

Same as:

Order.add_to_flags :a
...
Order.add_to_flags range: ..0

or:

Order.add_to_flags :a, range: ..0

Examples for "range":

Order.add_to_flags range: 0..17   # legal flag position from 0 to 17
Order.add_to_flags range: ..17    # legal flag position from 0 to 17
Order.add_to_flags range: nil..17 # legal flag position from 0 to 17
Order.add_to_flags range: 3..     # legal flag position from 3 to big_number
Order.add_to_flags range: 3..nil  # legal flag position from 3 to big_number

Invalid ranges:

Order.add_to_flags range: -1..17   # range starting with a negative position
Order.add_to_flags range: :a..:z   # invalid range
Order.add_to_flags range: "a".."z" # invalid range

Added option "range" limiting the position of flags.

An example:

ii = 3
Order.add_to_flags range: (2..4), a: (ii += 1) # accepted
Order.add_to_flags range: (2..4), b: (ii += 1) # raises exception

Option "range" enables an early static check.

Option "range" does not replace the dynamic "validate" in models, which is strongly recommended for complex applications. Due to Ruby "act_with_flags" can handle a huge quantity of booleans in an integer (or a string), but your database may fail above a certain amount of bits.

The option ":max_bits" is deprecated.

As required by key.matiq an enhanced "origin:" has been implemented. Act_with_flags now supports many "origin:"s (not just renaming the default "flags").

An example:

Order.add_to_flags :a # origin is :flags
Order.add_to_flags :b, b2: 63 # origin is :flags
Order.add_to_flags :c, origin: :origin1
Order.add_to_flags d: 3, origin: :origin2
Order.add_to_flags :d2, origin: :origin2

The default "origin:" continues to be "flags".

As "Best Practice" a test coverage of 100% has been achieved (and should be kept).

GitHub workflow enable tests for several configurations. Please, feel free to inspect the corresponding file.

The "gem appraisal" is used for an additional set of configurations. Feel free to inspect the corresponding file.

Further reading:

• gem bitmask_attributes
• gem bitfields
• gem active_flag
• gem has-bit-field
• gem bitfield_attribute
• gem bitwise

Copyright (c) 2019-2024 Dittmar Krall (www.matiq.com), released under the MIT license.