Type.js

VIE - Vienna IKS Editables
(c) 2011 Henri Bergius, IKS Consortium
(c) 2011 Sebastian Germesin, IKS Consortium
(c) 2011 Szaby Grünwald, IKS Consortium
VIE may be freely distributed under the MIT license.
For all details and documentation:
http://viejs.org/

VIE.Types

Within VIE, we provide special capabilities of handling types of entites. This helps for example to query easily for certain entities (e.g., you only need to query for Persons and not for all subtypes).

VIE.Type(id, attrs)

This is the constructor of a VIE.Type.
Parameters:
{string} id The id of the type.
{string|array|VIE.Attribute} attrs A string, proper VIE.Attribute or an array of these which are the possible attributes of the type
Throws:
{Error} if one of the given paramenters is missing.
Returns:
{VIE.Type} : A new VIE.Type object.
Example usage:

var person = new vie.Type("Person", ["name", "knows"]);

id

This field stores the id of the type's instance.
Parameters:
nothing Throws:
nothing
Returns:
{string} : The id of the type as a URI.
Example usage:

console.log(person.id);
 // --> "<http://viejs.org/ns/Person>"

supertypes

This field stores all parent types of the type's instance. This is set if the current type inherits from another type.
Parameters:
nothing
Throws:
nothing
Returns:
{VIE.Types} : The supertypes (parents) of the type.
Example usage:

console.log(person.supertypes);

subtypes

This field stores all children types of the type's instance. This will be set if another type inherits from the current type.
Parameters:
nothing
Throws:
nothing
Returns:
{VIE.Types} : The subtypes (parents) of the type.
Example usage:

console.log(person.subtypes);

attributes

This field stores all attributes of the type's instance as a proper VIE.Attributes class. (see also VIE.Attributes)
Parameters:
nothing
Throws:
nothing
Returns:
{VIE.Attributes} : The attributes of the type.
Example usage:

console.log(person.attributes);

isof(type)

This method checks whether the current type is a child of the given type.
Parameters:
{string|VIE.Type} type The type (or the id of that type) to be checked.
Throws:
{Error} If the type is not valid.
Returns:
{boolean} : true if the current type inherits from the type, false otherwise.
Example usage:

console.log(person.isof("owl:Thing"));
// <-- true    

subsumes(type)

This method checks whether the current type is a parent of the given type.
Parameters:
{string|VIE.Type} type The type (or the id of that type) to be checked.
Throws:
{Error} If the type is not valid.
Returns:
{boolean} : true if the current type is a parent of the type, false otherwise.
Example usage:

var x = new vie.Type(...);
var y = new vie.Type(...).inherit(x);
y.isof(x) === x.subsumes(y);

inherit(supertype)

This method invokes inheritance throught the types. This adds the current type to the subtypes of the supertype and vice versa.
Parameters:
{string|VIE.Type|array} supertype The type to be inherited from. If this is an array the inherit method is called sequentially on all types.
Throws:
{Error} If the type is not valid.
Returns:
{VIE.Type} : The instance itself.
Example usage:

var x = new vie.Type(...);
var y = new vie.Type(...).inherit(x);
y.isof(x) // <-- true

hierarchy()

This method serializes the hierarchy of child types into an object.
Parameters:
nothing
Throws:
nothing
Returns:
{object} : The hierachy of child types as an object.
Example usage:

var x = new vie.Type(...);
var y = new vie.Type(...).inherit(x);
x.hierarchy();

instance()

This method creates a VIE.Entity instance from this type. Parameters:
{object} attrs see constructor of VIE.Entity
{object} opts see constructor of VIE.Entity
Throws:
{Error} if the instance could not be built
Returns:
{VIE.Entity} : A new instance of a VIE.Entity with the current type.
Example usage:

var person = new vie.Type("person");
var sebastian = person.instance(
    {"@subject" : "#me", 
     "name" : "Sebastian"});
console.log(sebastian.get("name")); // <-- "Sebastian"

toString()

This method returns the id of the type.
Parameters:
nothing
Throws:
nothing
Returns:
{string} : The id of the type.
Example usage:

var x = new vie.Type(...);
x.toString() === x.id;

VIE.Types()

This is the constructor of a VIE.Types. This is a convenience class to store VIE.Type instances properly.
Parameters:
nothing
Throws:
nothing
Returns:
{VIE.Types} : A new VIE.Types object.
Example usage:

var types = new vie.Types();

add(id, attrs)

This method adds a VIE.Type to the types.
Parameters:
{string|VIE.Type} id If this is a string, the type is created and directly added.
{string|object} attrs Only used if id is a string.
Throws:
{Error} if a type with the given id already exists a VIE.Entity instance from this type.
Returns:
{VIE.Types} : The instance itself.
Example usage:

var types = new vie.Types();
types.add("Person", ["name", "knows"]);

addOrOverwrite(id, attrs)

This method adds or overwrites a VIE.Type to the types. This is the same as this.remove(id); this.add(id, attrs);
Parameters:
{string|VIE.Type} id If this is a string, the type is created and directly added.
{string|object} attrs Only used if id is a string.
Throws:
nothing
Returns:
{VIE.Types} : The instance itself.
Example usage:

var types = new vie.Types();
types.addOrOverwrite("Person", ["name", "knows"]);

get(id)

This method retrieves a VIE.Type from the types by it's id.
Parameters:
{string|VIE.Type} id The id or the type itself.
Throws:
nothing
Returns:
{VIE.Type} : The instance of the type or undefined.
Example usage:

var types = new vie.Types();
types.addOrOverwrite("Person", ["name", "knows"]);
types.get("Person");

remove(id)

This method removes a type of given id from the type. This also removes all children if their only parent were this type. Furthermore, this removes the link from the super- and subtypes.
Parameters:
{string|VIE.Type} id The id or the type itself.
Throws:
nothing
Returns:
{VIE.Type} : The removed type.
Example usage:

var types = new vie.Types();
types.addOrOverwrite("Person", ["name", "knows"]);
types.remove("Person");

toArray() === list()

This method returns an array of all types.
Parameters:
nothing
Throws:
nothing
Returns:
{array} : An array of VIE.Type instances.
Example usage:

var types = new vie.Types();
types.addOrOverwrite("Person", ["name", "knows"]);
types.list();

sort(types, desc)

This method sorts an array of types in their order, given by the inheritance. This returns a copy and leaves the original array untouched.
Parameters:
{array|VIE.Type} types The array of VIE.Type instances or ids of types to be sorted.
{boolean} desc If 'desc' is given and 'true', the array will be sorted in descendant order.
nothing
Throws:
nothing
Returns:
{array} : A sorted copy of the array.
Example usage:

var types = new vie.Types();
types.addOrOverwrite("Person", ["name", "knows"]);
types.sort(types.list(), true);