Class: Base

troop. Base

Base class. Implements tools for building, instantiating and testing classes.
Source:

Members

<static> instanceRegistry :object

Lookup registry for instances of the memoized class. Has to be own property as child classes may put their instances here, too. Added to class via .setInstanceMapper().
Source:

<static> surrogateInfo :object

Container for surrogate info. Added to class via .initSurrogates().
Source:

Methods

<static> addMethods(methods) → {troop.Base}

Adds a block of public read-only methods to the class it's called on. When troop.testing is on, methods will be placed on the class differently than other properties, therefore it is important to use .addMethods and .addPrivateMethods for method addition.
Parameters:
Name Type Description
methods object Name - value pairs of methods to apply. Values must be functions, or objects implementing a pair of get and set functions.
Source:
Returns:
Type
troop.Base
Example
var myClass = troop.extend()
   .addMethods({
       foo: function () {alert("Foo");},
       bar: {get: function () {return "Bar";}
   });

<static> addPrivateMethods(methods) → {troop.Base}

Adds a block of private (non-enumerable) read-only methods to the class it's called on. Method names must match the private prefix rule set by `troop.privatePrefix`. When troop.testing is on, methods will be placed on the class differently than other properties, therefore it is important to use .addMethods and .addPrivateMethods for method addition.
Parameters:
Name Type Description
methods object Name - value pairs of methods to apply. Values must be functions, or objects implementing a pair of get and set functions.
Source:
Returns:
Type
troop.Base
Example
var myClass = troop.extend()
   .addMethods({
       _foo: function () {alert("Foo");},
       _bar: {get: function () {return "Bar";}
   });

<static> addSurrogate(namespace, className, filter) → {troop.Base}

Adds a surrogate class to the current class. Instantiation is forwarded to the first surrogate where the filter returns true.
Parameters:
Name Type Description
namespace object Namespace in which the surrogate class resides.
className string Surrogate class name. The class the namespace / class name point to does not have to exist (or be resolved when postponed) at the time of adding the filter.
filter function Function evaluating whether the surrogate class specified by the namespace and class name fits the arguments.
Source:
Returns:
Type
troop.Base
Example
var ns = {}; // namespace
ns.Horse = troop.Base.extend()
    .prepareSurrogates(function (height) {
        return [height < 5]; // isPony
    })
    .addSurrogate(ns, 'Pony', function (isPony) {
        return isPony;
    })
    .addMethods({ init: function () {} });
ns.Pony = ns.Horse.extend()
    .addMethods({ init: function () {} });
var myHorse = ns.Horse.create(10), // instance of ns.Horse
    myPony = ns.Horse.create(3); // instance of ns.Pony

<static> addTrait(trait) → {troop.Base}

Adds a trait to the current class. A trait may be as simple as a plain object holding properties and methods to be copied over to the current class. More often however, a trait is a Troop class, through which, Troop realizes a form of multiple inheritance. There will still be just one prototype from which the current class stems, but methods delegated by the trait class will be used the same way as if they were implemented on the current class. Trait addition preserves ES5 attributes of copied properties, but skips property named `init`. Each trait must be initialized manually.
Parameters:
Name Type Description
trait object | troop.Base Trait object
Source:
Returns:
Type
troop.Base
Example
MyTrait = troop.Base.extend()
   .addMethods({
       init: function () { alert("trait init"); }
       foo: function () { alert("hello"); }
   });
MyClass = troop.Base.extend()
   .addTrait(MyTrait)
   .addMethods({ init: function () { MyTrait.init.call(this); } });
myInstance = MyClass.create(); // alerts "trait init"
myInstance.foo(); // alerts "hello"

<static> addTraitAndExtend(trait) → {troop.Base}

Adds trait to current class then extends it, allowing subsequently added methods to override the trait's methods.
Parameters:
Name Type Description
trait object | troop.Base
Source:
See:
Returns:
Type
troop.Base

<static> clearInstanceRegistry() → {troop.Base}

Clears instance registry. After the registry is cleared, a new set of instances will be created for distinct constructor arguments.
Source:
See:
Returns:
Type
troop.Base

<static> create() → {troop.Base}

Creates a new instance of the class it was called on. Arguments passed to .create will be handed over to the user-defined .init method, which will decorate the new instance with properties. Class must implement .init method in order to be instantiable. Instantiation might return an existing instance of the same class if the class is memoized.
Source:
See:
  • troop.Base.setInstanceMapper Instantiation might create a new instance of a subclass if the current class has surrogates.
  • troop.Base.addSurrogate
Returns:
Type
troop.Base
Example
var MyClass = troop.extend({
        init: function (foo) {
           this.foo = 'bar';
        }
    }),
    myInstance = MyClass.create("bar");
myInstance.foo // "bar"

<static> extend() → {troop.Base}

Extends class. Extended classes may override base class methods and properties according to regular OOP principles.
Source:
Returns:
Type
troop.Base
Example
var MyClass = troop.Base.extend();

<static> getBase() → {troop.Base}

Retrieves the base class of the current class.
Source:
Returns:
Type
troop.Base
Example
var MyClass = troop.Base.extend();
MyClass.getBase() === troop.Base; // true

<static> getTarget() → {troop.Base}

Determines target object of method addition. In testing mode, each class has two prototype levels and methods should go to the lower one so they may be covered on the other. Do not use in production, only testing.
Source:
Returns:
Type
troop.Base

<static> instanceMapper() → {string}

Maps constructor arguments to instance keys in the registry. Added to class via .setInstanceMapper().
Source:
Returns:
Type
string

<static> instanceOf(base) → {Boolean}

Tests whether the current class or instance is the direct extension or instance of the specified class.
Parameters:
Name Type Description
base troop.Base
Source:
Returns:
Type
Boolean
Example
var ClassA = troop.Base.extend(),
    ClassB = ClassA.extend();
ClassA.instanceOf(troop.Base) // true
ClassB.instanceOf(troop.Base) // false
ClassB.instanceOf(ClassA) // true

<static> isA(base) → {boolean}

Tests whether the current class or instance is a descendant of base.
Parameters:
Name Type Description
base troop.Base
Source:
Returns:
Type
boolean
Example
var MyClass = troop.Base.extend();
MyClass.isA(troop.Base) // true
MyClass.isA(MyClass) // false

<static> isBaseOf() → {boolean}

Tests whether the current class is base of the provided object.
Source:
Returns:
Type
boolean
Example
var MyClass = troop.Base.extend();
MyClass.isA(troop.Base) // true
MyClass.isA(MyClass) // false

<static> isMemoized() → {boolean}

Tells whether the current class (or any of its base classes) is memoized.
Source:
See:
Returns:
Type
boolean

<static> prepareSurrogates(handler) → {troop.Base}

Adds a handler to be called before evaluating any of the surrogate filters. The specified handler receives the original constructor arguments and is expected to return a modified argument list (array) that will be passed to the surrogate filters.
Parameters:
Name Type Description
handler function
Source:
See:
Returns:
Type
troop.Base

<static> setInstanceMapper(instanceMapper) → {troop.Base}

Assigns instance key calculator to class. Makes class memoized.
Parameters:
Name Type Description
instanceMapper function Instance key mapper function.
Source:
Returns:
Type
troop.Base
Example
var MyClass = troop.Base.extend()
    .setInstanceMapper(function (arg) {return '' + arg;})
    .addMethods({
        init: function () {}
    }),
    myInstance1 = MyClass.create('foo'),
    myInstance2 = MyClass.create('foo');
MyClass.isMemoized() // true
myInstance 1 === myInstance2 // true

addConstants(properties) → {troop.Base}

Adds a block of public (enumerable) constant (read-only) properties to the current class or instance.
Parameters:
Name Type Description
properties object Name-value pairs of constant properties
Source:
Returns:
Type
troop.Base

addMocks(methods) → {troop.Base}

Adds a block of public (enumerable) mock methods (read-only, but removable) to the current instance or class.
Parameters:
Name Type Description
methods object Name-value pairs of methods. Values must be functions or getter-setter objects.
Source:
See:
  • troop.Base#addMethods
Returns:
Type
troop.Base
Example
troop.testing = true;
MyClass = troop.Base.extend()
     .addMethods({
         init: function () {},
         foo: function () {}
     });
myInstance = MyClass.create();
MyClass.addMocks({
    foo: function () {return 'FOO';}
});
myInstance.foo() // returns 'FOO'

addPrivate(properties) → {troop.base}

Adds a block of private (non-enumerable) writable properties to the current class or instance. Property names must match the private prefix rule set by `troop.privatePrefix`.
Parameters:
Name Type Description
properties object Name-value pairs of properties.
Source:
Returns:
Type
troop.base

addPrivateConstants(properties) → {troop.Base}

Adds a block of private (non-enumerable) constant (read-only) properties to the current class or instance. Property names must match the private prefix rule set by `troop.privatePrefix`.
Parameters:
Name Type Description
properties object Name-value pairs of private constant properties.
Source:
Returns:
Type
troop.Base

addPublic(properties) → {troop.Base}

Adds a block of public (enumerable) writable properties to the current class or instance.
Parameters:
Name Type Description
properties object Name-value pairs of properties.
Source:
Returns:
Type
troop.Base

elevateMethod(methodName) → {troop.Base}

Elevates method from class level to instance level. (Or from base class to current class.) Ties context to the object it was elevated to, so methods may be safely passed as event handlers.
Parameters:
Name Type Description
methodName string Name of method to elevate.
Source:
Returns:
Type
troop.Base
Example
ClassA = troop.Base.extend()
   .addMethods({
       init: function () {},
       foo: function () { alert(this.bar); }
   });
ClassB = ClassA.extend()
    .addMethods({
        init: function () {
            this.bar = "hello";
            this.elevateMethod('foo');
        }
    });
foo = ClassB.create().foo; // should lose context
foo(); // alerts "hello", for context was preserved

removeMocks() → {troop.Base}

Removes all mock methods from the current class or instance.
Source:
Returns:
Type
troop.Base