JSDoc: Class: Capsule

Constructor

(abstract) new Capsule()

Since:

0.1.0

Source:

capsula.js, line 322

Methods

accept(visitor, opt_postorder)

Accepts visitor object and calls its visit method for each visited capsule in the subtree of this capsule: visit(this). Parameters for and results of calling visit method could be placed in the visitor object itself. To prevent capsule from being visited, override this (accept) method to do nothing.

Parameters:

Name	Type	Description
`visitor`	Object	the visitor object
`opt_postorder`	boolean	whether to use postorder (true) or preorder (false) approach when traversing the tree of capsules

Since:

0.1.0

Source:

capsula.js, line 1352

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

add(…var_args)

Ties select hooks or loops of the given capsules (children) to a select hook or loop of this capsule (parent). The parent's hook or loop is first determined:

If this capsule represents the current context of execution, then its loop returned by the getDefaultParentLoop method is considered as a parent here.

If this capsule represents a capsule which is a part of the capsule that represents the current context of execution, then its hook returned by the getDefaultParentHook method is considered as a parent here.

For each of the given capsules, the child hook or loop is determined like this:

If the given capsule represents the current context of execution, then its hook returned by the getDefaultChildHook method is considered as a child here.

If the given capsule represents a capsule which is a part of the capsule that represents the current context of execution, then its loop returned by the getDefaultChildLoop method is considered as a child here.

Parameters:

Name	Type	Attributes	Description
`var_args`	module:capsula.Capsule	<repeatable>	child capsules whose hooks or loops would be added to their new parent (an array of capsules also accepted)

Since:

0.2.0

Source:

capsula.js, line 1829

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

addAt(at, …var_args)

Ties select hooks or loops of the given capsules (children) to a select hook or loop of this capsule (parent) according to the given at index. The parent's hook or loop is first determined:

If this capsule represents the current context of execution, then its loop returned by the getDefaultParentLoop method is considered as a parent here.

For each of the given capsules, the child hook or loop is determined like this:

If the given capsule represents the current context of execution, then its hook returned by the getDefaultChildHook method is considered as a child here.

Parameters:

Name	Type	Attributes	Description
`at`	number		the index at which the child hooks or loops should be added to their new parent
`var_args`	module:capsula.Capsule	<repeatable>	child capsules whose hooks or loops would be added to their new parent (an array of capsules also accepted)

Since:

0.2.0

Source:

capsula.js, line 1855

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT, INDEX_OUT_OF_BOUNDS
Type Error

attach()

Attaches this capsule to be a part of the capsule that represents the current context of execution. Creates an implicit reference between the two capsules.

Recursively calls onAttach method (or operation) on this capsule and all its descendent capsules if they have that method.

Since:

0.1.0

Source:

capsula.js, line 1498

Throws:

ILLEGAL_ARGUMENT, CAPSULE_ALREADY_ATTACHED
Type Error

clear()

Clears child hooks or loops of a select hook or loop of this capsule (parent). The parent's hook or loop is determined like this:

If this capsule represents the current context of execution, then its loop returned by the getDefaultParentLoop method is considered as a parent here.

Since:

0.2.0

Source:

capsula.js, line 1899

Throws:

OUT_OF_CONTEXT
Type Error

detach()

Detaches this capsule as a part of the capsule that represents the current context of execution. Destroys an implicit reference between the two capsules. Detaching the capsule also means destroying all the wires and ties that exist between that capsule and all other sibling capsules (including itself) as well as between that capsule and its owner capsule.

Recursively calls onDetach method (or operation) on this capsule and all its descendent capsules if they have that method (this is to release resources and prevent memory leak).

Since:

0.1.0

Source:

capsula.js, line 1551

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

(protected) detachAll()

Detaches all the parts of this capsule (inherited ones included) one by one using detach. It is assumed that this capsule represents the current context of execution; otherwise an error is thrown.

Since:

0.1.0

Source:

capsula.js, line 2122

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

getChildren() → {Array.<module:capsula.Capsule>}

Returns an array of capsules (children) whose select hooks or loops are children of a select hook or loop of this capsule (parent). The parent's hook or loop is determined like this:

If this capsule represents the current context of execution, then its loop returned by the getDefaultParentLoop method is considered as a parent here.

Since:

0.2.0

Source:

capsula.js, line 1800

Throws:

OUT_OF_CONTEXT
Type Error

Returns:

an array of child capsules depending on the current context of execution

Type: Array.<module:capsula.Capsule>

(protected) getCurrentOperation() → {module:capsula.Operation}

Returns the currently executing operation.

Since:

0.1.0

Source:

capsula.js, line 2165

Returns:

the currently executing operation

Type: module:capsula.Operation

(protected) getData(id) → {Object}

Returns this capsule's protected data associated with the given id (from this[id]), or null if there is no such data.

Parameters:

Name	Type	Description
`id`	string	the id of the data to return

Since:

0.1.0

Deprecated:

since version 0.2.0: instead of this.getData('x') write this.x.get()

Source:

capsula.js, line 2087

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

the data associated with the given id, or null if there is no such data

Type: Object

(protected) getDefaultChildHook()

Returns the default hook of this capsule, a hook that can act as a child in the current context of execution.

By default this method works this way: when there is only one hook in this capsule, that hook is returned. When there is none or when there are more than one hook, an error is thrown.

The method is meant to be overridden in cases when capsule has more than one hook.

This method could only be called from the capsule's interior, i.e. only with "this".

Since:

0.2.0

Source:

capsula.js, line 2053

Throws:

OUT_OF_CONTEXT, DEFAULT_NOT_FOUND
Type Error

getDefaultChildLoop()

Returns the default loop of this capsule, a loop that can act as a child in the current context of execution.

By default this method works this way: when there is only one loop in this capsule, that loop is returned. When there is none or when there are more than one loop, an error is thrown.

The method is meant to be overridden in cases when capsule has more than one loop.

Since:

0.2.0

Source:

capsula.js, line 2016

Throws:

OUT_OF_CONTEXT, DEFAULT_NOT_FOUND
Type Error

getDefaultParentHook()

Returns the default hook of this capsule, a hook that can act as a parent in the current context of execution.

By default this method works this way: when there is only one hook in this capsule, that hook is returned. When there is none or when there are more than one hook, an error is thrown.

The method is meant to be overridden in cases when capsule has more than one hook.

Since:

0.2.0

Source:

capsula.js, line 2032

Throws:

OUT_OF_CONTEXT, DEFAULT_NOT_FOUND
Type Error

(protected) getDefaultParentLoop()

Returns the default loop of this capsule, a loop that can act as a parent in the current context of execution.

By default this method works this way: when there is only one loop in this capsule, that loop is returned. When there is none or when there are more than one loop, an error is thrown.

The method is meant to be overridden in cases when capsule has more than one loop.

This method could only be called from the capsule's interior, i.e. only with "this".

Since:

0.2.0

Source:

capsula.js, line 2070

Throws:

OUT_OF_CONTEXT, DEFAULT_NOT_FOUND
Type Error

getFQName(opt_sepopt) → {string}

Returns the fully qualified name of this capsule, using the given separator if provided (if not, the :: is used by default).

The fully qualified name comprises the name of this capsule (in the context of its owner capsule), the name of the owner capsule of this capsule, and so on all the way up the capsule hierarchy.

Parameters:

Name	Type	Attributes	Description
`opt_sep`	string	<optional>	the separator to use to separate names in the returned fully qualified name

Since:

0.1.0

Source:

capsula.js, line 1715

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

the fully qualified name of this capsule

Type: string

getHook(name) → {module:capsula.Hook}

Returns a hook (of this capsule) with the given name, or null if there is no such a hook.

Parameters:

Name	Type	Description
`name`	string	the name of the hook to return

Since:

0.1.0

Source:

capsula.js, line 1771

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

a hook (of this capsule) with the given name, or null if there is no such a hook

Type: module:capsula.Hook

getHooks() → {Array.<module:capsula.Hook>}

Returns an array of hooks (inherited ones included) of this capsule.

Since:

0.1.0

Source:

capsula.js, line 1472

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an array of hooks (inherited ones included)

Type: Array.<module:capsula.Hook>

getId() → {number}

Returns the id of this capsule.

Since:

0.1.0

Source:

capsula.js, line 1381

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

the id of this capsule

Type: number

getInput(name) → {module:capsula.Operation}

Returns an input operation (of this capsule) with the given name, or null if there is no such an operation.

Parameters:

Name	Type	Description
`name`	string	the name of the input operation to return

Since:

0.1.0

Source:

capsula.js, line 1743

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an input operation (of this capsule) with the given name, or null if there is no such an operation

Type: module:capsula.Operation

getInputs() → {Array.<module:capsula.Input>}

Returns an array of input operations (inherited ones included) of this capsule.

Since:

0.1.0

Source:

capsula.js, line 1434

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an array of input operations (inherited ones included)

Type: Array.<module:capsula.Input>

getLoop(name) → {module:capsula.Loop}

Returns a loop (of this capsule) with the given name, or null if there is no such a loop.

Parameters:

Name	Type	Description
`name`	string	the name of the loop to return

Since:

0.1.0

Source:

capsula.js, line 1785

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

a loop (of this capsule) with the given name, or null if there is no such a loop

Type: module:capsula.Loop

getLoops() → {Array.<module:capsula.Loop>}

Returns an array of loops (inherited ones included) of this capsule.

Since:

0.1.0

Source:

capsula.js, line 1485

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an array of loops (inherited ones included)

Type: Array.<module:capsula.Loop>

getName() → {string}

Returns the name of this capsule; i.e. the name of this capsule in the context of its owner capsule (whose part is this capsule).

Since:

0.1.0

Source:

capsula.js, line 1394

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

the name of this capsule

Type: string

getOperation(name) → {module:capsula.Operation}

Returns an operation (of this capsule) with the given name, or null if there is no such an operation.

Parameters:

Name	Type	Description
`name`	string	the name of the operation to return

Since:

0.1.0

Source:

capsula.js, line 1729

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an operation (of this capsule) with the given name, or null if there is no such an operation

Type: module:capsula.Operation

getOperations() → {Array.<module:capsula.Operation>}

Returns an array of input and output operations (inherited ones included) of this capsule.

Since:

0.1.0

Source:

capsula.js, line 1421

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an array of input and output operations (inherited ones included)

Type: Array.<module:capsula.Operation>

getOutput(name) → {module:capsula.Operation}

Returns an output operation (of this capsule) with the given name, or null if there is no such an operation.

Parameters:

Name	Type	Description
`name`	string	the name of the output operation to return

Since:

0.1.0

Source:

capsula.js, line 1757

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an output operation (of this capsule) with the given name, or null if there is no such an operation

Type: module:capsula.Operation

getOutputs() → {Array.<module:capsula.Output>}

Returns an array of output operations (inherited ones included) of this capsule.

Since:

0.1.0

Source:

capsula.js, line 1453

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an array of output operations (inherited ones included)

Type: Array.<module:capsula.Output>

getParent()

Returns a capsule whose hook or loop is a parent of a select hook or loop of this capsule (child). The child's hook or loop is determined like this:

If this capsule represents the current context of execution, then its hook returned by the getDefaultChildHook method is considered as a child here.

If this capsule represents a capsule which is a part of the capsule that represents the current context of execution, then its loop returned by the getDefaultChildLoop method is considered as a child here.

Since:

0.2.0

Source:

capsula.js, line 1966

Throws:

OUT_OF_CONTEXT
Type Error

getPart(name) → {module:capsula.Operation}

Returns a part (of this capsule) with the given name, or null if there is no such a part.

Parameters:

Name	Type	Description
`name`	string	the name of the part to return

Since:

0.1.0

Source:

capsula.js, line 2140

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

a part (of this capsule) with the given name, or null if there is no such a part

Type: module:capsula.Operation

getParts() → {Array.<module:capsula.Capsule>}

Returns an array of parts (inherited ones included) of this capsule.

Since:

0.1.0

Source:

capsula.js, line 2153

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

an array of parts (inherited ones included)

Type: Array.<module:capsula.Capsule>

isAttached()

Returns whether this capsule is attached to the capsule that represents the current context of execution.

Since:

0.1.0

Source:

capsula.js, line 1531

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

whether this capsule is attached to the capsule that represents the current context of execution

isParentOf(…var_args)

Returns whether all the select hooks or loops of the given capsules (children) are tied to a select hook or loop of this capsule (parent). The parent's hook or loop is first determined:

If this capsule represents the current context of execution, then its loop returned by the getDefaultParentLoop method is considered as a parent here.

For each of the given capsules, the child hook or loop is determined like this:

If the given capsule represents the current context of execution, then its hook returned by the getDefaultChildHook method is considered as a child here.

Parameters:

Name	Type	Attributes	Description
`var_args`	module:capsula.Capsule	<repeatable>	child capsules whose hooks or loops would be checked (an array of capsules also accepted)

Since:

0.2.0

Source:

capsula.js, line 1879

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

remove(…var_args)

Removes select hooks or loops of the given capsules (children) from the hook or loop of this capsule (parent). The parent's hook or loop is first determined:

If this capsule represents the current context of execution, then its loop returned by the getDefaultParentLoop method is considered as a parent here.

For each of the given capsules, the child hook or loop is determined like this:

If the given capsule represents the current context of execution, then its hook returned by the getDefaultChildHook method is considered as a child here.

Parameters:

Name	Type	Attributes	Description
`var_args`	module:capsula.Capsule	<repeatable>	child capsules whose hooks or loops would be removed from their old parent (an array of capsules also accepted)

Since:

0.2.0

Source:

capsula.js, line 1922

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

set(…var_args)

Sets select hooks or loops of the given capsules (children) to the hook or loop of this capsule (parent). The parent's hook or loop is first determined:

If this capsule represents the current context of execution, then its loop returned by the getDefaultParentLoop method is considered as a parent here.

For each of the given capsules, the child hook or loop is determined like this:

If the given capsule represents the current context of execution, then its hook returned by the getDefaultChildHook method is considered as a child here.

Parameters:

Name	Type	Attributes	Description
`var_args`	module:capsula.Capsule	<repeatable>	child capsules whose hooks or loops would be set to their new parent (an array of capsules also accepted)

Since:

0.2.0

Source:

capsula.js, line 1946

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

(protected) setData(id, data)

Associates the given data to the given id. Overwrites existing data associated with the same id if it exists. Puts new data into this[id].

Parameters:

Name	Type	Description
`id`	string	the id under which to store the given data in the (protected) context of this capsule
`data`	Object	the data to store in the (protected) context of this capsule

Since:

0.1.0

Deprecated:

since version 0.2.0: instead of this.setData('x', 'hello!') write this.x = new Data('hello!')

Source:

capsula.js, line 2104

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

setName(name)

Sets a new name to this capsule in the context of its owner capsule. New name can later be used to obtain a reference to this capsule from its owner capsule using getPart.

Parameters:

Name	Type	Description
`name`	string	a new name of this capsule

Since:

0.1.0

Source:

capsula.js, line 1407

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT, FORBIDDEN_NAME
Type Error

setParent(capsule)

Sets a select hook or loop of the given capsule (parent) as a parent of a select hook or loop of this capsule (child). The child's hook or loop is determined like this:

If the given capsule represents the current context of execution, then its loop returned by the getDefaultParentLoop method is considered as a parent here.

If the given capsule represents a capsule which is a part of the capsule that represents the current context of execution, then its hook returned by the getDefaultParentHook method is considered as a parent here.

If this capsule represents the current context of execution, then its hook returned by the getDefaultChildHook method is considered as a child here.

Parameters:

Name	Type	Description
`capsule`	module:capsula.Capsule	a capsule whose select hook or loop would be set as a new parent to this capsule's select hook or loop.

Since:

0.2.0

Source:

capsula.js, line 1994

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

superior() → {Object}

Returns the super prototype object to enable calls to a method that is just being overridden.

Since:

0.1.0

Source:

capsula.js, line 1338

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

Returns:

the super prototype object

Type: Object

Example

Example of using superior

capsula.defCapsule({
    base: BaseCapsule,
    '+ myMethod': function(){
        this.superior().myMethod.call(...); // calling a method that is just being overridden
    }
});

untie(…var_args)

Unties all the hooks and loops of this capsule (including inherited ones) from the hooks and loops of the given capsules they are tied to in the current context of execution.

Parameters:

Name	Type	Attributes	Description
`var_args`	module:capsula.Capsule	<repeatable>	capsules to untie this capsule from (an array of capsules also accepted)

Since:

0.1.0

Source:

capsula.js, line 1679

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

untieAll()

Unties all the hooks and loops of this capsule (including inherited ones) from all the hooks and loops they are tied to in the current context of execution.

Since:

0.1.0

Source:

capsula.js, line 1663

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

unwire(…var_args)

Unwires all the operations of this capsule (including inherited ones) from the operations and functions of the given capsules they are wired to in the current context of execution.

Parameters:

Name	Type	Attributes	Description
`var_args`	module:capsula.Capsule	<repeatable>	capsules to unwire this capsule from (an array of capsules also accepted)

Since:

0.1.0

Source:

capsula.js, line 1622

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error

unwireAll()

Unwires all the operations of this capsule (including inherited ones) from all the operations and functions they are wired to in the current context of execution.

Since:

0.1.0

Source:

capsula.js, line 1603

Throws:

ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type Error