Class Trait

Defined in: jstraits.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Trait(o) A trait is a group of pure methods that serves as a building block for classes and is a primitive unit of code reuse.

Method Summary
Method Attributes	Method Name and Description
	aliases(o) Alias a method to a different name during trait composition.
<static>	Trait.define(o) Factory method to create new traits.
	does(trait_ref) Inspect all traits used by this trait.
	excludes(a) Exclude a method during trait composition.
	methods(method_name) Inspect methods exported by this trait.
	requires(method_name) Inspect method names required by this trait.
	subtraits(trait_ref) Inspect subtraits used by this trait.

Class Detail

Trait(o)

A trait is a group of pure methods that serves as a building block for classes and is a primitive unit of code reuse. In this model, classes are composed from a set of traits by specifying glue code that connects the traits together and accesses the necessary state. If you are unfamiliar with the general object oriented programming notion of a trait it would serve you well to check out the synopsis and examples before reading the rest of this documentation.

The constructor creates a new trait for use in other traits or classes. The factory method Trait.define is the preferred way to instantiate new traits, as opposed to calling 'new Trait(...)' directly.

var TColoredCircle = new Trait({
  uses: [TColor, TCircle.aliases({'drawOutline': 'draw'})],
  requires: 'fillWithColor',
  methods: {
    draw: function() {
      // draw a colored circle
      this.drawOutline();
      this.fillWithColor(this.getColor());
    }
  }
});

Parameters:
{Object} o: The trait configuration object.
{Trait|Trait[]} o.uses Optional: Other trait(s) that will be composed into this new trait. Note that trait composition is both associative and commutative, so if specifying more than one trait the order does not matter. To alias or exclude methods from subtraits as they are composed, call Trait#aliases or Trait#excludes. Calls to these functions may be chained. Passing a trait into o.uses causes the methods from that trait (plus any aliases and modulo any excludes) to be added to the new trait. If any of these exported method names conflict with another trait specified in o.uses, the conflict must be resolved (unless the conflicting method names point to the exact same function). Conflicts may be resolved by either 1) overriding the method in o.methods 2) overriding the method at the class level (if this trait is being defined as part of a class) or 3) excluding all but one of the conflicting methods.
{String|String[]} o.requires Optional: A list of method names that must be implemneted before this trait can function properly. A trait may have open requirements, but all its requirements must be fulfilled when it is composed into a class. Requirements can be satisfied by other traits or class methods.
{Object} o.methods Optional: A dictionary of methods that this trait exports (in addition to those composed in o.uses). Methods may access instance methods, but should not directly access instance variables. References to instance methods that are not deinfed in this trait or a composed subtrait should have their method names placed in the o.requires parameter.

Throws:
{Trait.TraitError}: Throws an error if the trait definition arguments are invalid, the trait definition is inconsistent, or there is an unresolved conflict.

See:: Trait.define

Method Detail

{Trait} aliases(o)

Alias a method to a different name during trait composition. Aliases should only be used in a 'uses' clause inside a class or trait definition. It may be chained with Trait#excludes. Aliasing a method causes it to be copied under the new alias name in addition to the original method name. Multiple aliases may be made to the same function. Aliases are treated exactly like normal method names during trait composition.

Parameters:
{Object} o: A String to String mapping of alias names to exported method names.

Throws:
{Trait.TraitError}: Throws a TraitError if attempting to alias a non-existent function, create an alias with the same name as a natively exported method, or create an alias with the same name as one of the required method names.

Returns:: {Trait} this

<static> {Trait} Trait.define(o)

Factory method to create new traits. Arguments are the same as those passed to the Trait constructor. This static method is the preferred way to create new traits.

var TColoredCircle = Trait.define({
  uses: [TColor, TCircle.aliases({'drawOutline': 'draw'})],
  requires: 'fillWithColor',
  methods: {
    draw: function() {
      // draw a colored circle
      this.drawOutline();
      this.fillWithColor(this.getColor());
    }
  }
});

Parameters:
{Object} o
{Trait|Trait[]} o.uses Optional
{String|String[]} o.requires Optional
{Object} o.methods Optional

Throws:
{Trait.TraitError}

Returns:: {Trait}

See:: Trait

{Trait[]|Boolean} does(trait_ref)

Inspect all traits used by this trait. Note that this trait is included in the list of what this trait 'does'. If no argument is passed, an array of all traits is returned. If a trait is passed, a boolean is returned indicating if the specified trait is one of the composed traits. This method differs from Trait#subtraits in that subtraits only checks for traits specified in the use clause, while this method recursively checks to see if any of the subtraits' subraits match, and so on.

Parameters:
{Trait} trait_ref Optional: Trait to check for inclusion in the list of composed traits.

Returns:: {Trait[]|Boolean} List of all traits composed into this trait or a boolean indicating if a particular trait was used.

{Trait} excludes(a)

Exclude a method during trait composition. Excludes should only be used in a 'uses' clause inside a class or trait definition. It may be chained with Trait#aliases. Excluding a method causes it to not be copied into the containing class or trait as it normally would. If a method is excluded a method with the same name must be provided, either by another trait or a class method.

Parameters:
{String|String[]} a: Method(s) to exclude during trait composition.

Throws:
{Trait.TraitError}: Throws a TraitError if attempting to exclude a method that is not exported by this trait.

Returns:: {Trait} this

{Object|Function} methods(method_name)

Inspect methods exported by this trait. If no arguments are passed, an object mapping each method name exported by this trait to its associated function is returned. If a string argument is given, methods checks if this trait exports a method with that name. If so it returns the associated function, otherwise it returns undefined.

Parameters:
{String} method_name Optional: Name of the method to look up in this trait's method export list.

Returns:: {Object|Function} Mapping of method names to functions, a specific function, or undefined.

{Object|Boolean} requires(method_name)

Inspect method names required by this trait. If no arguments are passed, an object with keys representing all the required methods is returned. If a string argument is given, requires returns a boolean indicating if this trait requires a method with that name.

Parameters:
{String} method_name: Method name to check if in required method name list.

Returns:: {Object|Boolean} Object keyed by required method names or boolean indicating if a particular method name is required.

{Trait[]|Boolean} subtraits(trait_ref)

Inspect subtraits used by this trait. Note that only immediate subtraits are dealt with here (i.e. those passed in the 'uses' clause). To recursively check if a trait uses another trait see Trait#does. If no argument is passed, an array of all subtraits is returned. If a trait is passed, a boolean is returned indicating if the specified trait is one of the subtraits.

Parameters:
{Trait} trait_ref Optional: Trait to check for inclusion in the list of subtraits.

Returns:: {Trait[]|Boolean} List of all subtraits or boolean indicating if a particular subtrait was used.

Classes

Class Trait