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

* + - abstract advise alias_accessor alias_method_chain ancestor? ann ann ann! annotations annotations append_features append_features append_features append_features append_features append_features_without_class_extension append_features_without_instance_interception attr attr attr attr_setter attr_tester attr_tester attr_validator autoscript basename by_name class_inherit class_methods classified_attributes clone_removing clone_renaming clone_using compare_on define_dependency depend dependencies dirname equate_on extend filter heritage include include_and_extend include_as include_function_module included initializer inject instance_method! instance_methods integrate is is? key_attributes memoize method_added method_overloads mixin_parameters modspace module_load module_method module_require namespace namespace nesting new on_included overload prepend private_filter redirect_method revisal setting shadow_all shadow_method sort_attributes sort_on this to_json wrap_method

### 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

append_features(mod)
append_features(mod)
filter(name)

### Public Instance methods

*( rename_map )

Rename methods.

+( other )
-( other )
abstract( *sym )
advise( mod, meth )

Apply the around advice.

alias_accessor( name, target )

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

alias_method_chain(target, feature)

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.

ancestor?( mod )

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

     class X ; end
     class Y < X ; end

      X.ancestor?(Y)

ann( ref, keys_or_class=nil, keys=nil )

Set or read annotations.

ann( key=nil, *options )
ann!( ref, keys_or_class=nil, keys=nil )

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.

annotations()
annotations()
append_features( base )
append_features( mod )

Append features

append_features(mod)
append_features_without_class_extension( base )

Alias for append_features

append_features_without_instance_interception( base )

Alias for append_features

attr( *args )
attr( *args )
attr(*args)

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

attr_setter(*args)

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

attr_tester(*args)

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

attr_tester(*args)

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

attr_validator(*symbols, &validator)

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

autoscript(mod, filename)

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

basename()

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"

by_name(name)

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

class_methods( &yld )
classified_attributes()

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]

clone_removing( *meths )

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

clone_renaming( pairs )

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

clone_using( *methods )

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

compare_on(*fields)

Alias for sort_on

define_dependency( name, *deps )
depend( name_and_deps=nil )
dependencies(name, build=[])

Compile list of all unique prerequisite calls.

dirname()

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.

equate_on(*fields)

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

extend(*args)
heritage(ref)
include(*args)
include_and_extend(*mods)

Both includes and extends a module.

include_as( h )

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_function_module(*mod)

Include module and apply module_fuction to the included methods.

included( base )

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.

initializer(*attributes, &block)

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.

inject( base, &block )
instance_method!(s)

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.

instance_methods(*args)

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).

integrate( mod, &block )
is(*args)

Alias for include

is?( base )

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

memoize(*meths)

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

method_added( meth )

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.

method_overloads()
mixin_parameters()

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

modspace()

Returns the module‘s container module.

      module Example
        class Demo
        end
      end

      Demo.modspace    #=> Example

See also Module#basename.

module_load( path )

Load file into module/class namespace.

module_method(*meth)

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

module_require( path )

Require file into module/class namespace.

namespace( name, mod=nil, &blk )

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

namespace( name, &blk )

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.

nesting()
new(*args,&blk)

Never you a class agian! ;)

on_included(code)

A useful macro for dynamic modules.

overload( name, *signiture, &block )
prepend( aspect )

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}"

private_filter( *filter )
redirect_method( method_hash )

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

revisal( &blk )
setting(sym, options = {})

Defines a configuration setting for the enclosing class.

### Example

class Compiler

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

end

shadow_all( include_ancestors=true )

Creates a shadow method for every currently defined method.

shadow_method( name, old_name=name )

Define a shadow alias for a method.

      class X
        shadow_method( :class )
      end

      X.new.__class__  #=> X

sort_attributes(*fields)

Alias for sort_on

sort_on(*fields)

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

this()
to_json(*)
wrap_method( sym, &blk )

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]