useful-Class

useful Classical inheritance scaffolding, including singletons and easy to use mixin functionality

Installation

Install with component(1):

$ component install muigui/useful-Class

Install with npm:

$ npm install useful-Class

API

Class( descriptor:Object ):Function

See Class.define below for details of the decriptor Object options.

The only difference between Class and Class.define is that Class simply returns the constructor Function and does not try to create a class namespace for it.

Class.define( class_namespace:String, descriptor:Object ):Function

The descriptor Object will contain all your properties and methods which will be added to your Class' prototype.

default Class descriptor options

The descriptor has the following reserved property names:

However, if a type is also supplied it will overwrite the type created from the path.

property	type	description
constructor	Function	This Class' constructor. This is the method that is called when you do: new Foo.
extend	Function|String	OPTIONAL. If you want to inherit the properties and methods from an existing Class you reference the Class here.
accessors	Object	OPTIONAL. Each property in the accessors Object should have an Object with either a get method, a set method, or both. These will be added to the Class' prototype, using Object.defineProperty
mixins	Object	OPTIONAL. An Object of properties and methods to mix into the Class' prototype.
module	Object	OPTIONAL. If you don't want the Class namespace to be created on the global context, then pass the Object to assign the class namespace to, e.g. a component or npm module.
chain	Boolean	OPTIONAL. Unless this is set explicitly to false, the Class instance will return its context – this – Object whenever an instance method of a Class returns undefined.
singleton	Mixed	OPTIONAL. Whether or not this Class is a Singleton. If you want a Singleton set this property to be either true or to an Array of arguments you wish to pass to the constructor Function. NOTE: Class will internally resolve any attempt to create a new instance of the singleton by simply returning the existing singleton instance.
__override__	Function	This is a reserved method name for overriding a Class instance's methods.
mixin	Function	This is a reserved method name for calling mixin methods.
original	Function	This is a special reserved method name used by overridden methods to call the original method they overrode.
parent	Function	This is a special reserved method for calling super methods. Since super is a reserved word in JavaScript, parent has been used in its place.

Class.create( class_namespace:String, [arg1:Mixed, arg2:Mixed, ..., argN:Mixed] ):Object

A factory method to allow you to:

• create an instance of a class by passing it a reference to its class namespace;
• create an instance of a class using an arbitrary number of arguments; and
• not worry about the correct value of this

Class.new( class_namespace:String, [arg1:Mixed, arg2:Mixed, ..., argN:Mixed] ):Object

Alias for the Class.create method above.

Class.get( class_namespace:String ):Function

Returns the Class matching the passed class namespace or null if none is found.

Class.is( instance:Object, Class:Function|String ):Boolean

Returns true if the passed instance is an instance of the passed Class.

NOTE: This function uses instanceof internally, the only extra thing it does is, if a String is passed as the Class parameter, try to find the matching constructor Function.

Class methods

These are the methods available on a newly created Class

create( [arg1:Mixed, arg2:Mixed, ..., argN:Mixed] ):Object

A create factory method is added to your Class constructor to allow you to:

• create an instance of a class using an arbitrary number of arguments; and
• not worry about the correct value of this

See the Class Examples below on how to create Class instances using the create factory on your class or the Class.create factory.

new( [arg1:Mixed, arg2:Mixed, ..., argN:Mixed] ):Object

Alias for the create method above.

instance methods

this.parent()

When you create an instance of a Class created with Class you can access the super method of a Class you are extending by calling:

   this.parent( arg1, arg2, ..., argN );

Context will be maintained correctly, unless you use Function .call or .apply. In which case you should pass the context in as normal.

Example

   this.parent.call( this, arg1, arg2, ..., argN );

// or

   this.parent.apply( this, [arg1, arg2, ..., argN] );

TODO — Add docs for using mixins

Class examples:

   Class.define( 'Foo', {
      constructor : function( greeting ) {
         this.greeting = greeting;
         this.setNum( 10 );
      },
      getNum      : function() { return this.num; },
      setNum      : function( num ) { return ( this.num = num ); }
   } );

   Class.define( '^path.to.Bar', {
      constructor : function( greeting ) { this.parent( 'bar: ' + greeting, true ); },
      extend      : Foo,
      module      : m8.ENV === 'commonjs' ? module : null,
      getNum      : function() { return this.parent(); }
   } );

   var Zaaz = Class.define( {
      constructor : function( greeting ) { this.parent( 'zaaz: ' + greeting, true ); },
      extend      : path.to.Bar
   } );

   var foo  = new Foo( 'hello world!' ),
       bar  = Class.new( 'path.to.Bar', 'hello world!' ),
       zaaz = Zaaz.create.apply( this, ['hello world!'] );

   foo.greeting;              // returns => "hello world!"
   foo.getNum()       === 10  // returns => true
   foo.setNum( 100 )  === 100 // returns => true
   foo.getNum()       === 100 // returns => true

   bar.greeting;              // returns => "bar: hello world!"
   bar.getNum()       === 10  // returns => true
   bar.setNum( 200 )  === 200 // returns => true
   foo.getNum()       === 100 // returns => true

   zaaz.greeting;             // returns => "bar: zaaz: hello world!"
   zaaz.getNum()      === 10  // returns => true
   zaaz.setNum( 400 ) === 400 // returns => true

License

(The MIT License)

Copyright (c) 2011 christos "constantology" constandinou http://muigui.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.