Module: Domainic::Attributer::ClassMethods

Defined in:
lib/domainic/attributer/class_methods.rb

Overview

Note:

This module is automatically extended when Domainic::Attributer is included in a class

This module extends classes that include Domainic::Attributer with methods for defining and managing attributes. It supports two types of attributes:

  1. Arguments - Positional parameters that must be provided in a specific order
  2. Options - Named parameters that can be provided in any order

Examples:

Defining arguments and options

class Person
  include Domainic::Attributer

  argument :name, String
  argument :age, Integer do
    validate_with ->(val) { val >= 0 }
  end

  option :email, String, default: nil
  option :role do
    validate_with ->(val) { %w[admin user guest].include?(val) }
  end
end

person = Person.new('Alice', 30, email: '[email protected]', role: 'user')
# => #<Person:0x0000000104bc5f98 @age=30, @email="[email protected]", @name="Alice", @role="user">

Author:

Since:

  • 0.1.0

Instance Method Summary collapse

Instance Method Details

#argument(attribute_name, type_validator = nil, **options) {|DSL::AttributeBuilder| ... } ⇒ void

Define a positional argument attribute

Arguments are required by default and must be provided in the order they are defined unless they have a default value. They can be type-validated and configured with additional options like defaults and visibility

Examples:

Using the options API

class Person
  argument :name, String
  argument :age, ->(val) { val.is_a?(Integer) && val >= 0 }
  argument :role, default: 'user'
end

Using the block API

class Person
  argument :name, String do
    validate_with ->(val) { val.length >= 3 }
  end

  argument :age, Integer do
    coerce_with ->(val) { val.to_i }
    validate_with ->(val) { val >= 0 }
  end

  argument :role, String do
    validate_with ->(val) { VALID_USER_ROLES.include?(val) }
    default 'user'
  end
end

This method returns an undefined value.

Parameters:

  • attribute_name (String, Symbol) —

    the name of the attribute

  • type_validator (Proc, Object, nil) (defaults to: nil) —

    optional validation handler for type checking

  • options (Hash{Symbol => Object}) —

    additional configuration options

Options Hash (**options):

  • :callbacks (Array<Proc>, Proc) —

    handlers for attribute change events (priority over :callback, :on_change)

  • :callback (Array<Proc>, Proc) —

    alias for :callbacks

  • :coerce (Array<Proc, Symbol>, Proc, Symbol) —

    handlers for value coercion (priority over :coercers, :coerce_with)

  • :coercers (Array<Proc, Symbol>, Proc, Symbol) —

    alias for :coerce

  • :coerce_with (Array<Proc, Symbol>, Proc, Symbol) —

    alias for :coerce

  • :default (Object) —

    the default value (priority over :default_generator, :default_value)

  • :default_generator (Object) —

    alias for :default

  • :default_value (Object) —

    alias for :default

  • :desc (String) —

    short description (overridden by :description)

  • :description (String) —

    description text

  • :non_nil (Boolean) —

    require non-nil values (priority over :non_null, :non_nullable, :not_nil, :not_nilable, :not_null, :not_nullable)

  • :non_null (Boolean) —

    alias for :non_nil

  • :non_nullable (Boolean) —

    alias for :non_nil

  • :not_nil (Boolean) —

    alias for :non_nil

  • :not_nilable (Boolean) —

    alias for :non_nil

  • :not_null (Boolean) —

    alias for :non_nil

  • :not_nullable (Boolean) —

    alias for :non_nil

  • :null (Boolean) —

    inverse of :non_nil

  • :on_change (Array<Proc>, Proc) —

    alias for :callbacks

  • :optional (Boolean) —

    whether attribute is optional (overridden by :required)

  • :position (Integer) —

    specify order position

  • :read (Symbol) —

    read visibility (:public, :protected, :private) (priority over :read_access, :reader)

  • :read_access (Symbol) —

    alias for :read

  • :reader (Symbol) —

    alias for :read

  • :required (Boolean) —

    whether attribute is required

  • :validate (Array<Object>, Object) —

    validators for the attribute (priority over :validate_with, :validators)

  • :validate_with (Array<Object>, Object) —

    alias for :validate

  • :validators (Array<Object>, Object) —

    alias for :validate

  • :write_access (Symbol) —

    write visibility (:public, :protected, :private) (priority over :writer)

  • :writer (Symbol) —

    alias for :write_access

Yields:

See Also:

Since:

  • 0.1.0



148
149
150
151
152
153
154
155
156
157
 
# File 'lib/domainic/attributer/class_methods.rb', line 148

def argument(attribute_name, type_validator = Undefined, **options, &)
  position = __attributes__.count { |_, attribute| attribute.signature.argument? }

  attribute = DSL::AttributeBuilder.new(
    self, attribute_name, :argument, type_validator, **options.merge(position:), &
  ).build!

  __attributes__.add(attribute)
  DSL::MethodInjector.inject!(self, attribute)
end

#option(attribute_name, type_validator = nil, **options) {|DSL::AttributeBuilder| ... } ⇒ void

Define a named option attribute

Options are optional by default and can be provided in any order. They can be type-validated and configured with additional options like defaults and visibility

Examples:

Using the options API

class Person
  option :email, String
  option :age, ->(val) { val.is_a?(Integer) && val >= 0 }
  option :role, default: 'user'
end

Using the block API

class Person
  option :email, String do
    coerce_with ->(val) { val.downcase }
    validate_with ->(val) { URI::MailTo::EMAIL_REGEXP.match?(val) }
  end

  option :age, Integer do
    coerce_with ->(val) { val.to_i }
    validate_with ->(val) { val >= 0 }
  end

  option :role, String do
    validate_with ->(val) { VALID_USER_ROLES.include?(val) }
    default 'user'
  end
end

This method returns an undefined value.

Parameters:

  • attribute_name (String, Symbol) —

    the name of the attribute

  • type_validator (Proc, Object, nil) (defaults to: nil) —

    optional validation handler for type checking

  • options (Hash{Symbol => Object}) —

    additional configuration options

Options Hash (**options):

  • :callbacks (Array<Proc>, Proc) —

    handlers for attribute change events (priority over :callback, :on_change)

  • :callback (Array<Proc>, Proc) —

    alias for :callbacks

  • :coerce (Array<Proc, Symbol>, Proc, Symbol) —

    handlers for value coercion (priority over :coercers, :coerce_with)

  • :coercers (Array<Proc, Symbol>, Proc, Symbol) —

    alias for :coerce

  • :coerce_with (Array<Proc, Symbol>, Proc, Symbol) —

    alias for :coerce

  • :default (Object) —

    the default value (priority over :default_generator, :default_value)

  • :default_generator (Object) —

    alias for :default

  • :default_value (Object) —

    alias for :default

  • :desc (String) —

    short description (overridden by :description)

  • :description (String) —

    description text

  • :non_nil (Boolean) —

    require non-nil values (priority over :non_null, :non_nullable, :not_nil, :not_nilable, :not_null, :not_nullable)

  • :non_null (Boolean) —

    alias for :non_nil

  • :non_nullable (Boolean) —

    alias for :non_nil

  • :not_nil (Boolean) —

    alias for :non_nil

  • :not_nilable (Boolean) —

    alias for :non_nil

  • :not_null (Boolean) —

    alias for :non_nil

  • :not_nullable (Boolean) —

    alias for :non_nil

  • :null (Boolean) —

    inverse of :non_nil

  • :on_change (Array<Proc>, Proc) —

    alias for :callbacks

  • :optional (Boolean) —

    whether attribute is optional (overridden by :required)

  • :position (Integer) —

    specify order position

  • :read (Symbol) —

    read visibility (:public, :protected, :private) (priority over :read_access, :reader)

  • :read_access (Symbol) —

    alias for :read

  • :reader (Symbol) —

    alias for :read

  • :required (Boolean) —

    whether attribute is required

  • :validate (Array<Object>, Object) —

    validators for the attribute (priority over :validate_with, :validators)

  • :validate_with (Array<Object>, Object) —

    alias for :validate

  • :validators (Array<Object>, Object) —

    alias for :validate

  • :write_access (Symbol) —

    write visibility (:public, :protected, :private) (priority over :writer)

  • :writer (Symbol) —

    alias for :write_access

Yields:

See Also:

Since:

  • 0.1.0



269
270
271
272
273
274
 
# File 'lib/domainic/attributer/class_methods.rb', line 269

def option(attribute_name, ...)
  attribute = DSL::AttributeBuilder.new(self, attribute_name, :option, ...).build! # steep:ignore

  __attributes__.add(attribute)
  DSL::MethodInjector.inject!(self, attribute)
end