Class Module
In: lib/facets/more/methodfilter.rb
lib/facets/more/classmethods.rb
lib/facets/more/json.rb
lib/facets/more/ann.rb
lib/facets/more/settings.rb
lib/facets/more/overload.rb
lib/facets/more/paramix.rb
lib/facets/more/ann_attr.rb
lib/facets/more/instance_intercept.rb
lib/facets/more/cut.rb
lib/facets/more/dependency.rb
lib/facets/more/autoscript.rb
lib/facets/core/kernel/method.rb
lib/facets/core/module/on_included.rb
lib/facets/core/module/ancestor.rb
lib/facets/core/module/integrate.rb
lib/facets/core/module/redirect_method.rb
lib/facets/core/module/initializer.rb
lib/facets/core/module/sort_on.rb
lib/facets/core/module/redef.rb
lib/facets/core/module/shadow_method.rb
lib/facets/core/module/nodef.rb
lib/facets/core/module/modspace.rb
lib/facets/core/module/attr_setter.rb
lib/facets/core/module/attr_tester.rb
lib/facets/core/module/attr_validator.rb
lib/facets/core/module/clone_using.rb
lib/facets/core/module/revisal.rb
lib/facets/core/module/include_as.rb
lib/facets/core/module/nesting.rb
lib/facets/core/module/rename.rb
lib/facets/core/module/this.rb
lib/facets/core/module/wrap_method.rb
lib/facets/core/module/shadow_all.rb
lib/facets/core/module/dirname.rb
lib/facets/core/module/attr_query.rb
lib/facets/core/module/equate_on.rb
lib/facets/core/module/alias_method_chain.rb
lib/facets/core/module/redefine_method.rb
lib/facets/core/module/instance_methods.rb
lib/facets/core/module/namespace.rb
lib/facets/core/module/remove.rb
lib/facets/core/module/rename_method.rb
lib/facets/core/module/redirect.rb
lib/facets/core/module/abstract.rb
lib/facets/core/module/class_extension.rb
lib/facets/core/module/memoize.rb
lib/facets/core/module/class.rb
lib/facets/core/module/alias_module_function.rb
lib/facets/core/module/wrap.rb
lib/facets/core/module/attr.rb
lib/facets/core/module/by_name.rb
lib/facets/core/module/is.rb
lib/facets/core/module/new.rb
lib/facets/core/module/basename.rb
lib/facets/core/module/alias_accessor.rb
lib/facets/core/module/prepend.rb
lib/facets/core/module/include_and_extend.rb
lib/facets/core/module/module_method.rb
lib/facets/core/module/module_load.rb
lib/facets/core/module/include_function_module.rb
lib/facets/core/module/self/op_add.rb
lib/facets/yore/annotation.rb
lib/facets/yore/annattr.rb
lib/facets/yore/module/namespace.rb
lib/facets/yore/module/inject.rb
Parent: Object

TODO What is this?

Methods

Constants

STANDARD_FILTER = /(\?$|^(__|object_|instance_)|^(send|inspect|dup|clone|null|\W+)$)/
METHOD_TYPES = [ :inherited, :ancestors, :local, :public, :private, :protected, :all ]

External Aliases

append_features -> append_features_without_classmethods
include -> include_without_parameters
extend -> extend_without_parameters
attr_reader -> plain_reader
attr_writer -> plain_writer
attr_accessor -> plain_accessor
attr_accessor -> attribute
  TODO Should attribute alias be kept?
const_missing -> const_missing_before_autoscript
redefine_method -> redef
undef_method -> nodef
  Alias for undef_method.
rename_method -> rename
remove_method -> remove
=== -> class?
attr_accessor -> attribute

Public Class methods

Public Instance methods

Rename methods.

Apply the around advice.

As with alias_method, but alias both reader and writer.

  attr_accessor :x
  self.x = 1
  alias_accessor :y, :x
  y #=> 1
  self.y = 2
  x #=> 2

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_without_feature?

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

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

 class X ; end
 class Y < X ; end

  X.ancestor?(Y)

To change an annotation‘s value in place for a given class or module it first must be duplicated, otherwise the change may effect annotations in the class or module‘s ancestors.

Append features

append_features_without_class_extension( base )

Alias for append_features

append_features_without_instance_interception( base )

Alias for append_features

There‘s a school of thought that says an attribute show always have a reader and a writer.

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

Create an tester attribute. This creates two methods for each given variable name. One is used to test the attribute and the other is used to set or toggle it.

  attr_tester :a

is equivalent to

  def a?
    @a ? true : @a
  end

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

Create an tester attribute. This creates two methods for each given variable name. One is used to test the attribute and the other is used to set or toggle it.

  attr_switch :a

is equivalent to

  def a?
    @a ? true : @a
  end

  def a!(switch=nack)
    if switch == nack
      @a = ! @a
    else
      @a = @a ? switch : @a
      self
    end
  end

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

When the constant named by symbol mod is referenced, loads the script in filename using Script.load and defines the constant to be equal to the resulting Script module.

Use like Module#autoload—however, the underlying opertation is load rather than require, because scripts, unlike libraries, can be loaded more than once. See examples/autoscript-example.rb

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"

Note: the following documentation uses "class" because it‘s more common, but it applies to modules as well.

Given the name of a class, returns the class itself (i.e. instance of Class). The dereferencing starts at Object. That is,

  Class.by_name("String")

is equivalent to

  Object.const_get("String")

The parameter name is expected to be a Symbol or String, or at least to respond to to_str.

An ArgumentError is raised if name does not correspond to an existing class. If name is not even a valid class name, the error you‘ll get is not defined.

Examples:

  Class.by_name("String")             # -> String
  Class.by_name("::String")           # -> String
  Class.by_name("Process::Sys")       # -> Process::Sys
  Class.by_name("GorillaZ")           # -> (ArgumentError)

  Class.by_name("Enumerable")         # -> Enumerable
  Module.by_name("Enumerable")        # -> Enumerable
class_inherit( &yld )

Alias for class_methods

Return list of attributes that have a :class annotation.

  class MyClass
    attr_accessor :test
    attr_accessor :name, String, :doc => 'Hello'
    attr_accessor :age, Fixnum
  end

  MyClass.attributes # => [:test, :name, :age, :body]
  MyClass.classified_attributes # => [:name, :age]

Returns an anonymous module with the specified methods of the receiving module removed.

Returns an anonymous module with the specified methods of the receiving module renamed.

Returns an anonymous module with only the specified methods of the receiving module intact.

compare_on(*fields)

Alias for sort_on

Compile list of all unique prerequisite calls.

Returns the name of module‘s container module.

  module Example
    class Demo
    end
  end

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

See also Module#basename.

Generates identity/key methods based on specified attributes.

 equate_on :a, :b

_is equivalent to_

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

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

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

Both includes and extends a module.

Include a module via a specified namespace.

  module T
    def t ; "HERE" ; end
  end

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

  X.new.t  #=> "HERE"

Include module and apply module_fuction to the included methods.

When a module is included, we need to look at all it‘s methods and see if they match any cut points and if so join them.

Automatically create an initializer assigning the given arguments.

  class MyClass
    initializer(:a, "b", :c)
  end

_is equivalent to_

  class MyClass
    def initialize(a, b, c)
      @a,@b,@c = a,b,c
    end
  end

Downside: Initializers defined like this can‘t take blocks. This can be fixed when Ruby 1.9 is out.

The initializer will not raise an Exception when the user does not supply a value for each instance variable. In that case it will just set the instance variable to nil. You can assign default values or raise an Exception in the block.

Easy access to method as objects, and they retain state!

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

CAUTION! This will not work exactly right until class variable lookup is fixed. Presently it is limited to the scope of the current module/class.

Provides an improved method lookup routnine. It returns a list of methods according to symbol(s) given.

Recognized symbols are:

  • :public include public methods
  • :private include private methods
  • :protected include protected methods
  • :ancestors include all ancestor‘s methods
  • :inherited (same as above)
  • <tt>:local</tti> include non-ancestor methods
  • :all include all of the above

This method also uses the symbol-not system. So you can specify the inverse of all of the above. For instance ~:public would mean :private, :protected (see facets/core/symbol/not).

If no symbol is given then :public, :local is assumed. Unrecognized symbols raise an error.

  module Demo
    def test
      puts("Hello World!")
    end
  end

  Demo.instance_methods(:local)    #=> ['test']

To maintain backward compatibility true as an intitial argument is converted to :local, :ancestors (i.e. it includes both).

is(*args)

Alias for include

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

 class X ; end
 class Y < X ; end

  Y.is?(X)  #=> true
key_attributes(*fields)

Alias for equate_on

Directive for making your functions faster by trading space for time. When you "memoize" a method/function its results are cached so that later calls with the same arguments returns results in the cache instead of recalculating them.

  class T
    def initialize(a)
      @a = a
    end
    def a
      "#{@a ^ 3 + 4}"
    end
    memoize :a
  end

  t = T.new
  t.a.__id__ == t.a.__id__  #=> true

TODO make method_added hook more robust so not as to clobber others. If a method is added to the module/class that is advised.

Store for module parameters. This is local per module and indexed on module/class included-into.

Returns the module‘s container module.

  module Example
    class Demo
    end
  end

  Demo.modspace    #=> Example

See also Module#basename.

Load file into module/class namespace.

Like module_funtion but makes the instance method public rather than private.

Require file into module/class namespace.

Define a simple method namespace.

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

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

Create a seperated method namespace.

  module T
    def t ; "HERE" ; end
  end

  class X
    namespace :test { include T }
    def t ; test.t ; end
  end

  X.new.t  #=> "HERE"

NOTE: This is not as functional as it ought be in that the instance variables of the object are not accessible within the namespace.

Never you a class agian! ;)

A useful macro for dynamic modules.

Prepend an aspect module to a module.

  module X
    def x; "x"; end
  end

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

  X.prepend U

  X.x  # => "{x}"

Redirect methods to other methods. This simply defines methods by the name of a hash key which calls the method with the name of the hash‘s value.

  class Example
    redirect_method :hi => :hello, :hey => :hello
    def hello(name)
      puts "Hello, #{name}."
    end
  end

  e = Example.new
  e.hello("Bob")    #=> "Hello, Bob."
  e.hi("Bob")       #=> "Hello, Bob."
  e.hey("Bob")      #=> "Hello, Bob."

The above class definition is equivalent to:

  class Example
    def hi(*args)
      hello(*args)
    end
    def hey(*args)
      hello(*args)
    end
    def hello
      puts "Hello"
    end
  end

Defines a configuration setting for the enclosing class.

Example

class Compiler

  setting :template_root, :default => 'src/template', :doc => 'The template root dir'

end

Creates a shadow method for every currently defined method.

Define a shadow alias for a method.

  class X
    shadow_method( :class )
  end

  X.new.__class__  #=> X
sort_attributes(*fields)

Alias for sort_on

Automatically generate sorting defintions base on attribute fields.

  sort_on :a, :b

_is equivalent to_

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

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.

[Validate]