Class Module
In: lib/core/facets/comparable/comparable.rb
lib/core/facets/module/abstract.rb
lib/core/facets/module/alias_accessor.rb
lib/core/facets/module/alias_method_chain.rb
lib/core/facets/module/alias_module_function.rb
lib/core/facets/module/ancestor.rb
lib/core/facets/module/attr_setter.rb
lib/core/facets/module/basename.rb
lib/core/facets/module/can.rb
lib/core/facets/module/class.rb
lib/core/facets/module/conflict.rb
lib/core/facets/module/include_function_module.rb
lib/core/facets/module/instance_method.rb
lib/core/facets/module/instance_methods.rb
lib/core/facets/module/is.rb
lib/core/facets/module/methodize.rb
lib/core/facets/module/modspace.rb
lib/core/facets/module/module_def.rb
lib/core/facets/module/module_load.rb
lib/core/facets/module/nesting.rb
lib/core/facets/module/op.rb
lib/core/facets/module/pathize.rb
lib/core/facets/module/prepend.rb
lib/core/facets/module/redefine_method.rb
lib/core/facets/module/redirect_method.rb
lib/core/facets/module/rename_method.rb
lib/core/facets/module/revise.rb
lib/core/facets/module/spacename.rb
lib/core/facets/module/wrap_method.rb
lib/more/facets/class_extend.rb
lib/more/facets/equitable.rb
lib/more/facets/instance_function.rb
lib/more/facets/methodspace.rb
lib/more/facets/module/attr.rb
lib/more/facets/module/attr_tester.rb
lib/more/facets/module/attr_toggler.rb
lib/more/facets/module/attr_validator.rb
Parent: Object

Methods

Classes and Modules

Module Module::InstanceFunction

External Aliases

extend -> can
  An alias for extend.
  class X
    can Forwardable
  end

BTW, why is Forwardable an -able? It‘s not a mixin!

=== -> class?
  Alias for #===. This provides a verbal method for inquery.
  s = "HELLO"
  String.class?(s)  #=> true
remove_method -> remove
undef_method -> nodef
append_features -> append_features_without_class_extension
attr_accessor! -> attr_toggler

Public Class methods

Public Instance methods

Rename methods.

  module A
    def a; "a"; end
  end

  B = A * { :a => :b }

  class X; include B; end

  X.new.b    #=> "a"

Thomas Sawyer, Robert Dober

Combine modules.

  module A
    def a; "a"; end
  end

  module B
    def b; "b"; end
  end

  C = A + B

  class X; include C; end

  X.new.a    #=> "a"
  X.new.b    #=> "b"

Note that in the old version of traits.rb we cloned modules and altered their copies. Eg.

    def +(other)
      mod1 = other.clone
      mod2 = clone
      mod1.module_eval{ include mod2 }
    end

Later it was realized that this thwarted the main benefit that Ruby‘s concept of modules has over traditional traits, inheritance.

CREDIT: Thomas Sawyer, Robert Dober

Subtract modules.

  TODO: Should this use all instance_methods, not just public?

CREDIT: Thomas Sawyer, Robert Dober

Automatically generate sorting definitions based on attribute fields.

  include Comparable(:a, :b)

is equivalent to including a module containing:

  def <=>(other)
    cmp = self.a <=> other.a; return cmp unless cmp == 0
    cmp = self.b <=> other.b; return cmp unless cmp == 0
    0
  end

This function provided a "shortcut" for creating the identity method based on given accessors and returns the Equitable module for inclusion.

 include Equitable(:a, :b)

is equivalent to including a module containing:

  def ==(other)
    self.a == other.a && self.b == other.b
  end

  def eql?(other)
    self.a.eql?(other.a) && self.b.eql?(other.b)
  end

  def hash()
    self.a.hash ^ self.b.hash
  end

Create an abstract method. If it is not overridden, it will raise a TypeError when called.

  class C
    abstract :a
  end

  c = C.new
  c.a  #=> Error: undefined abstraction #a

CREDIT: Trans

Create aliases for flag accessors.

CREDIT: Trans

Encapsulates the common pattern of:

  alias_method :foo_without_feature, :foo
  alias_method :foo, :foo_with_feature

With this, you simply do:

  alias_method_chain :foo, :feature

And both aliases are set up for you.

Query and bang methods (foo?, foo!) keep the same punctuation:

  alias_method_chain :foo?, :feature

is equivalent to

  alias_method :foo_without_feature?, :foo?
  alias_method :foo?, :foo_with_feature?

so you can safely chain foo, foo?, and foo! with the same feature.

CREDIT: Bitsweat, Rails Team

alias_reader?(*args)

Alias for alias_tester

Alias an accessor. This create an alias for both a reader and a writer.

  class X
    attr_accessor :a
    alias_accessor :b, :a
  end

  x = X.new
  x.b = 1
  x.a        #=> 1

CREDIT: Trans

alias_switcher(*args)

Alias for alias_accessor!

Create aliases for flag reader.

CREDIT: Trans

Create aliases for attr_toggler.

CREDIT: Trans

alias_toggler(*args)

Alias for alias_accessor!

Create aliases for validators.

Create aliases for flag writer.

CREDIT: Trans

List all instance methods, equivalent to

  public_instance_methods +
  protected_instance_methods +
  private_instance_methods

TODO: Better name for all_instance_methods?

CREDIT: Trans

Is a given class or module an ancestor of this class or module?

 class X ; end
 class Y < X ; end

  X.ancestor?(Y)

Override append_features to handle class-inheritable extensions.

attr_reader?(*args)

Alias for attr_tester

Create an attribute method for both getting and setting an instance variable.

  attr_setter :a

_is equivalent to_

  def a(*args)
    if args.size > 0
      @a = args[0]
      self
    else
      @a
    end
  end

CREDIT: Trans

Create a toggle attribute. This creates two methods for each given name. One is a form of tester and the other is used to toggle the value.

  attr_accessor! :a

is equivalent to

  def a?
    @a
  end

  def a!(value=true)
    @a = value
    self
  end

CREDIT: Trans

Create an tester attribute. This creates a single method used to test the attribute for truth.

  attr_tester :a

is equivalent to

  def a?
    @a ? true : @a
  end

Create a flaggable attribute. This creates a single methods used to set an attribute to "true".

  attr_toggler :a

is equivalent to

  def a?
    @a ? true : @a
  end

  def a!(value=Exception)
    if Exception
      @a = @a ? false : true
    else
      @a = value
    end
    self
  end

Like attr_writer, but the writer method validates the setting against the given block.

CREDIT: ?

Create a flaggable attribute. This creates a single methods used to set an attribute to "true".

  attr_writer! :a

is equivalent to

  def a!(value=true)
    @a = value
    self
  end

Returns the root name of the module/class.

  module Example
    class Demo
    end
  end

  Demo.name       #=> "Example::Demo"
  Demo.basename   #=> "Demo"

For anonymous modules this will provide a basename based on Module#inspect.

  m = Module.new
  m.inspect       #=> "#<Module:0xb7bb0434>"
  m.basename      #=> "Module_0xb7bb0434"

CREDIT: Trans

Defines an instance method within a class/module.

CREDIT: WhyTheLuckyStiff

Normally when including modules, class/module methods are not extended. To achieve this behavior requires some clever Ruby Karate. Instead class_extend provides an easy to use and clean solution. Simply place the extending class methods in a block of the special module method class_extend.

  module Mix
    def inst_meth
      puts 'inst_meth'
    end

    class_extend do
      def class_meth
        "Class Method!"
      end
    end
  end

  class X
    include Mix
  end

  X.class_meth  #=> "Class Method!"

NOTE: This old class_extension version of this method did not extend the containing class automatically —it had to be done by hand. With class_extend, that is no longer the case.

class_extension(*mods, &block)

Alias for class_extend

class_load( path )

Alias for module_load

class_require( path )

Alias for module_require

Detect conflicts.

  module A
    def c; end
  end

  module B
    def c; end
  end

  A.conflict?(B)  #=> ["c"]

  TODO: All instance methods, or just public?

CREDIT: Thomas Sawyer, Robert Dober

Include a module via a specified space.

  module T
    def t ; "HERE" ; end
  end

  class X
    include_as :test => T
    def t ; test.t ; end
  end

  X.new.t  #=> "HERE"

Converts module methods into instance methods such that the first parameter is passed self. This promotes DRY programming when wishing to offer both inheritable and module callable procedures.

This method is modeled after module_function which essentially has the the opposite effect. Due to implementation limitations, this must use the callback singleton_method_added to emulate module_function when no method names are given.

  module MyModule
    instance_function

    def self.jumble( obj, arg )
      obj + arg
    end
  end

  class String
    include MyModule
  end

  MyModule.jumble( "Try", "Me" )  #=> "TryMe"

  "Try".jumble( "Me" )            #=> 'TryMe'

Note: This used to be a module called PromoteSelf and later Instantize, before becoming a method.

Access method as a singleton object and retain state.

  module K
    def hello
      puts "Hello World!"
    end
  end
  p K.instance_method!(:hello)   #=> <UnboundMethod: #hello>

NOTE: This is limited to the scope of the current module/class.

Query whether a public instance method is defined for the module.

CREDIT: Gavin Sinclair, Noah Gibbs

Using integrate is just like using include except the module included is a reconstruction of the one given altered by the commands given in the block.

Convenient commands available are: rename, redef, remove, nodef and wrap. But any module method can be used.

  module W
    def q ; "q" ; end
    def y ; "y" ; end
  end

  class X
    integrate W do
      nodef :y
    end
  end

  x = X.new
  x.q  #=> "q"
  x.y  #=> missing method error

This is like revisal, but revisal only returns the reconstructred module. It does not include it.

CREDIT: Trans

An alias for include.

  class X
    is Enumerable
  end

CREDIT: Trans

Is a given class or module an ancestor of this class or module?

 class X ; end
 class Y < X ; end

 Y.is?(X)  #=> true

CREDIT: Trans

Define a simple method namespace.

  class A
    attr_writer :x
    method_space :inside do
      def x; @x; end
    end
  end

  a = A.new
  a.x = 10
  a.inside.x #=> 10
  a.x  # no method error

Translate a module name to a suitable method name.

  My::CoolClass.methodize => "my__cool_class"

Returns the module‘s container module.

  module Example
    class Demo
    end
  end

  Example::Demo.modspace   #=> Example

See also Module#basename.

CREDIT: Trans

Defines an instance method within a class/module.

CREDIT: WhyTheLuckyStiff

Load file directly into module/class namespace.

Please use this with careful consideration. It is best suited to loading plugin-type scripts, and should generally not be used as a substitue for Ruby‘s standard load system.

CREDIT: Trans

module_method_defined?(meth)

Alias for singleton_method_defined?

Require file into module/class namespace.

Unlike load this keeps a per-module cache and will not load the same file into the same module more than once despite repeated attempts.

The cache is kept in a global var called +$module_require+.

Please use this with careful consideration. It is best suited to loading plugin-type scripts, and should generally not be used as a substitue for Ruby‘s standard load system.

CREDIT: Trans

Show a modules nesting in module namespaces.

  A::B::C.nesting  #=> [ A, A::B ]

CREDIT: Trans

Converts a class name to a unix path

Examples

  CoolClass.pathize       #=> "cool_class"
  My::CoolClass.pathize   #=> "my/cool_class"

Prepend an aspect module to a module. This only works at the module level.

  module X
    def x; "x"; end
  end

  module U
    def x; '{' + super + '}'; end
  end

  X.prepend U

  X.x  # => "{x}"

CREDIT Trans

Like conflict?, but checks only private methods.

Like conflict?, but checks only protected methods.

Like conflict?, but checks only public methods.

revisal(&blk)

Alias for revise

Return a new module based on another. This includes the original module into the new one.

CREDIT: Trans

Query whether a normal (singleton) method is defined for the module.

CREDIT: Gavin Sinclair, Noah Gibbs

Returns the name of module‘s container module.

  module Example
    class Demo
    end
  end

  Demo.name         #=> "Example::Demo"
  Demo.spacename    #=> "Example"

This used to be called dirname.

See also Module#basename.

CREDIT: Trans

wrap( sym, &blk )

Alias for wrap_method

Creates a new method wrapping the previous of the same name. Reference to the old method is passed into the new definition block as the first parameter.

  wrap_method( sym ) { |old_meth, *args|
    old_meth.call
    ...
  }

Keep in mind that this can not be used to wrap methods that take a block.

CREDIT: Trans

[Validate]