Grapoi

Grapoi combines the concept of graph pointers and paths. The Grapoi class is based on the PathList class. A PathList wraps multiple Path objects in the ptrs property and adds some convenience methods. PathList and Grapoi have almost the same interface, besides a stricter type interface for PathList. That makes code written with PathList slightly faster; Grapoi code is, on the other hand, a bit more readable.

Interfaces

GraphPointer

A GraphPointer refers to a term in a dataset and optional also a specific graph:

interface GraphPointer {
  attribute Term term;
  attribute Dataset dataset;
  attribute Term? graph;
};

Path

A Path is, in the simplest case, just a GraphPointer, but it can also describe a path over multiple edges in a dataset:

interface Path {
  attribute Dataset dataset;
  attribute Term? term;
  attribute Term? graph;
  attribute sequence<Edge> edges;
};

Edge

An Edge describes one traversing step in a dataset with a quad and the start and end. The start and end are strings with the according property name of the quad, like subject or predicate:

interface Edge {
  attribute Dataset dataset;
  attribute Quad quad;
  attribute DOMString start;
  attribute DOMString end;
};

Example

The following example is based on the housemdopen in new window dataset and shows the path and pointer functionality of Grapoi:

import housemd from 'housemd'
import rdf from 'rdf-ext'

const ns = {
  schema: rdf.namespace('http://schema.org/')
}

const dataset = rdf.dataset(housemd({ factory: rdf }))
const house = rdf.grapoi({ dataset, term: 'Gregory' }).in().trim()

console.log('properties of the guy named Gregory:')

for (const quad of house.out().quads()) {
  console.log(`\t${quad.predicate.value}: ${quad.object.value}`)
}

const nationalities = house
  .out(ns.schema.knows)
  .out(ns.schema.nationality)
  .distinct()

console.log('nationalities of all known people:')

for (const value of nationalities.values) {
  console.log(`\t${value}`)
}

JSDoc

Grapoi ⇐ PathList

A graph pointer object

Kind: global class
Extends: PathList

new Grapoi(dataset, factory, ptrs, term, terms, graph, graphs)

Create a new instance

ParamTypeDescription
datasetDatasetCoreDataset for the pointers
factoryEnvironmentFactory for new quads
ptrsArray.<Path>Use existing pointers
termTermTerm for the pointers
termsArray.<Term>Terms for the pointers
graphTermGraph for the pointers
graphsArray.<Term>Graphs for graph pointers

grapoi.dataset ⇒ DatasetCore | null

Dataset of the pointer or null if there is no unique dataset.

Kind: instance property of Grapoi
Overrides: dataset
Returns: DatasetCore | null - Unique dataset or null

grapoi.datasets ⇒ Array.<DatasetCore>

An array of all datasets of all pointers.

Kind: instance property of Grapoi
Overrides: datasets
Returns: Array.<DatasetCore> - Array of datasets.

grapoi.term ⇒ Term | undefined

The term of the pointers if all pointers refer to a unique term.

Kind: instance property of Grapoi
Overrides: term
Returns: Term | undefined - Term of undefined

grapoi.terms ⇒ Array.<Term>

An array of all terms of all pointers.

Kind: instance property of Grapoi
Overrides: terms
Returns: Array.<Term> - Array of all terms

grapoi.value ⇒ String | undefined

The value of the pointers if all pointers refer to a unique term.

Kind: instance property of Grapoi
Overrides: value
Returns: String | undefined - Value or undefined

grapoi.values ⇒ Array.<String>

An array of all values of all pointers.

Kind: instance property of Grapoi
Overrides: values
Returns: Array.<String> - Array of all values

grapoi.addIn(predicates, [subjects], [callback]) ⇒ Grapoi

Add quad(s) with the current terms as the object

Kind: instance method of Grapoi
Overrides: addIn
Returns: Grapoi - this

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the quads
[subjects]Grapoi | Array.<Grapoi> | Term | Array.<Term>Subjects of the quads
[callback]functionFunction called for each subject as a pointer argument

grapoi.addList(predicates, [items]) ⇒ Grapoi

Add list(s) with the given items

Kind: instance method of Grapoi
Overrides: addList
Returns: Grapoi - this

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the lists
[items]Grapoi | Array.<Grapoi> | Term | Array.<Term>List items

grapoi.addOut(predicates, [objects], [callback]) ⇒ Grapoi

Add quad(s) with the current terms as the subject

Kind: instance method of Grapoi
Overrides: addOut
Returns: Grapoi - this

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the quads
[objects]Grapoi | Array.<Grapoi> | Term | Array.<Term>Objects of the quads
[callback]functionFunction called for each subject as a pointer argument

grapoi.base(base) ⇒ Constructor

Base all terms with a relative IRI with the given base.

Kind: instance method of Grapoi
Returns: Constructor - Instance with a single pointer with the term based

ParamTypeDescription
baseGrapoi | Array.<Grapoi> | Term | Array.<Term>Base of the terms

grapoi.best(score) ⇒ Constructor

Use the given score function on all pointers and return the pointer with the best score.

Kind: instance method of Grapoi
Returns: Constructor - Instance with a single pointer with the best score

ParamTypeDescription
scorefunctionScore function

grapoi.deleteIn(predicates, [subjects]) ⇒ Grapoi

Delete quad(s) with the current terms as the object.

Kind: instance method of Grapoi
Overrides: deleteIn
Returns: Grapoi - this

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the quads
[subjects]Grapoi | Array.<Grapoi> | Term | Array.<Term>Subjects of the quads

grapoi.deleteList(predicates) ⇒ Grapoi

Delete list(s).

Kind: instance method of Grapoi
Overrides: deleteList
Returns: Grapoi - this

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the lists

grapoi.deleteOut(predicates, [objects]) ⇒ Constructor

Delete quad(s) with the current terms as the subject.

Kind: instance method of Grapoi
Overrides: deleteOut
Returns: Constructor - this

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the quads
[objects]Grapoi | Array.<Grapoi> | Term | Array.<Term>Objects of the quads

grapoi.hasIn(predicates, [subjects]) ⇒ Constructor

Filter the pointers based on matching quad(s) with the current terms as the object.

Kind: instance method of Grapoi
Overrides: hasIn
Returns: Constructor - Instance that contains only the filtered pointers

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the quads
[subjects]Grapoi | Array.<Grapoi> | Term | Array.<Term>Subjects of the quads

grapoi.hasOut(predicates, [objects]) ⇒ Constructor

Filter the pointers based on matching quad(s) with the current terms as the subject.

Kind: instance method of Grapoi
Overrides: hasOut
Returns: Constructor - Instance that contains only the filtered pointers

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the quads
[objects]Grapoi | Array.<Grapoi> | Term | Array.<Term>Objects of the quads

grapoi.in(predicates, [subjects]) ⇒ Constructor

Traverse the graph with the current terms as the object.

Kind: instance method of Grapoi
Overrides: in
Returns: Constructor - Instance with pointers of the traversed target terms

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the quads
[subjects]Grapoi | Array.<Grapoi> | Term | Array.<Term>Subjects of the quads

grapoi.out(predicates, [objects]) ⇒ Constructor

Traverse the graph with the current terms as the subject.

Kind: instance method of Grapoi
Overrides: out
Returns: Constructor - Instance with pointers of the traversed target terms

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Predicates of the quads
[objects]Grapoi | Array.<Grapoi> | Term | Array.<Term>Objects of the quads

grapoi.node(predicates) ⇒ Constructor

Jump to random terms.

Kind: instance method of Grapoi
Overrides: node
Returns: Constructor - Instance with pointers of the selected terms

ParamTypeDescription
predicatesGrapoi | Array.<Grapoi> | Term | Array.<Term>Terms for the new pointers

grapoi.rebase(base) ⇒ Constructor

Rebase all terms of the current pointers with a new base.

Kind: instance method of Grapoi
Returns: Constructor - Instance with a single pointer with the new base as the term

ParamTypeDescription
baseGrapoi | Array.<Grapoi> | Term | Array.<Term>New base of the terms

grapoi.replace(replacement) ⇒ Constructor

Replace all terms of the current pointers with another term.

Kind: instance method of Grapoi
Returns: Constructor - Instance with a single pointer with the replacement as the term

ParamTypeDescription
replacementGrapoi | Array.<Grapoi> | Term | Array.<Term>Term used as replacement

grapoi.score(score, [limit], [offset]) ⇒ Constructor

Score the pointers and sort them by score value.

Kind: instance method of Grapoi
Returns: Constructor - Instance of the scored pointers, sorted and sliced.

ParamTypeDescription
scorefunction@rdfjs/score compatible score function
[limit]NumberLimit for the result pointers
[offset]NumberOffset for the result pointers

grapoi.clone(args) ⇒ Constructor

Create a new instance of the Constructor with a cloned list of pointers.

Kind: instance method of Grapoi
Overrides: clone
Returns: Constructor - Cloned instance

ParamDescription
argsAdditional arguments for the constructor

grapoi.distinct() ⇒ Constructor

Create a new instance with a unique set of pointers. The path of the pointers is trimmed.

Kind: instance method of Grapoi
Overrides: distinct
Returns: Constructor - Instance with unique pointers

grapoi.execute(instruction) ⇒ Constructor

Executes a single instruction.

Kind: instance method of Grapoi
Overrides: execute
Returns: Constructor - Instance with the result pointers.

ParamDescription
instructionThe instruction to execute

grapoi.executeAll(instruction) ⇒ Constructor

Executes an array of instructions.

Kind: instance method of Grapoi
Overrides: executeAll
Returns: Constructor - Instance with the result pointers.

ParamDescription
instructionThe instructions to execute

grapoi.filter(callback) ⇒ Constructor

Filter the pointers based on the result of the given callback function.

Kind: instance method of Grapoi
Overrides: filter
Returns: Constructor - Instance with the filtered pointers.

Param
callback

grapoi.isAny() ⇒ boolean

Check if any pointer is an any-pointer.

Kind: instance method of Grapoi
Overrides: isAny
Returns: boolean - True if any any-pointer was found

grapoi.isList() ⇒ boolean

Check if there is only one pointer and whether that pointer is a list.

Kind: instance method of Grapoi
Overrides: isList
Returns: boolean - True if the pointer is a list

grapoi.list() ⇒ Iterator.<Constructor> | undefined

Create an iterator for the list if the instance is a list; otherwise, return undefined.

Kind: instance method of Grapoi
Overrides: list
Returns: Iterator.<Constructor> | undefined - Iterator or undefined

grapoi.map(callback) ⇒ Array

Map each pointer using the given callback function.

Kind: instance method of Grapoi
Overrides: map
Returns: Array - Array of mapped results

Param
callback

grapoi.quads() ⇒ Iterator.<Quad>

Create an iterator of all quads of all pointer paths.

Kind: instance method of Grapoi
Overrides: quads
Returns: Iterator.<Quad> - Iterator for the quads

grapoi.trim() ⇒ Constructor

Trim the path of all pointers and create a new instance for the result.

Kind: instance method of Grapoi
Overrides: trim
Returns: Constructor - Instance of the trimmed pointers

PathList

List of paths

Kind: global class
Properties

NameTypeDescription
ptrsArrayAll paths of this list

new PathList(dataset, factory, ptrs, terms, graphs)

Create a new instance

ParamTypeDescription
datasetDatasetCoreDataset for the pointers
factoryEnvironmentFactory for new quads
ptrsArray.<Path>Use existing pointers
termsArray.<Term>Terms for the pointers
graphsArray.<Term>Graphs for the pointers

pathList.dataset ⇒ DatasetCore | null

Dataset of the pointer or null if there is no unique dataset.

Kind: instance property of PathList
Returns: DatasetCore | null - Unique dataset or null

pathList.datasets ⇒ Array.<DatasetCore>

An array of all datasets of all pointers.

Kind: instance property of PathList
Returns: Array.<DatasetCore> - Array of datasets.

pathList.term ⇒ Term | undefined

The term of the pointers if all pointers refer to a unique term.

Kind: instance property of PathList
Returns: Term | undefined - Term of undefined

pathList.terms ⇒ Array.<Term>

An array of all terms of all pointers.

Kind: instance property of PathList
Returns: Array.<Term> - Array of all terms

pathList.value ⇒ String | undefined

The value of the pointers if all pointers refer to a unique term.

Kind: instance property of PathList
Returns: String | undefined - Value or undefined

pathList.values ⇒ Array.<String>

An array of all values of all pointers.

Kind: instance property of PathList
Returns: Array.<String> - Array of all values

pathList.addIn(predicates, subjects, [callback]) ⇒ PathList

Add quads with the current terms as the object

Kind: instance method of PathList
Returns: PathList - this

ParamTypeDescription
predicatesArray.<Term>Predicates of the quads
subjectsArray.<Term>Subjects of the quads
[callback]functionFunction called for each subject as a pointer argument

pathList.addList(predicates, items) ⇒ PathList

Add lists with the given items

Kind: instance method of PathList
Returns: PathList - this

ParamTypeDescription
predicatesArray.<Term>Predicates of the lists
itemsArray.<Term>List items

pathList.addOut(predicates, objects, [callback]) ⇒ PathList

Add quads with the current terms as the subject

Kind: instance method of PathList
Returns: PathList - this

ParamTypeDescription
predicatesArray.<Term>Predicates of the quads
objectsArray.<Term>Objects of the quads
[callback]functionFunction called for each subject as a pointer argument

pathList.clone(args) ⇒ Constructor

Create a new instance of the Constructor with a cloned list of pointers.

Kind: instance method of PathList
Returns: Constructor - Cloned instance

ParamDescription
argsAdditional arguments for the constructor

pathList.deleteIn(predicates, subjects) ⇒ PathList

Delete quads with the current terms as the object.

Kind: instance method of PathList
Returns: PathList - this

ParamTypeDescription
predicatesArray.<Term>Predicates of the quads
subjectsArray.<Term>Subjects of the quads

pathList.deleteList(predicates) ⇒ PathList

Delete lists.

Kind: instance method of PathList
Returns: PathList - this

ParamTypeDescription
predicatesArray.<Term>Predicates of the lists

pathList.deleteOut(predicates, objects) ⇒ PathList

Delete quads with the current terms as the subject.

Kind: instance method of PathList
Returns: PathList - this

ParamTypeDescription
predicatesArray.<Term>Predicates of the quads
objectsArray.<Term>Objects of the quads

pathList.distinct() ⇒ Constructor

Create a new instance with a unique set of pointers. The path of the pointers is trimmed.

Kind: instance method of PathList
Returns: Constructor - Instance with unique pointers

pathList.execute(instruction) ⇒ Constructor

Executes a single instruction.

Kind: instance method of PathList
Returns: Constructor - Instance with the result pointers.

ParamDescription
instructionThe instruction to execute

pathList.executeAll(instruction) ⇒ Constructor

Executes an array of instructions.

Kind: instance method of PathList
Returns: Constructor - Instance with the result pointers.

ParamDescription
instructionThe instructions to execute

pathList.filter(callback) ⇒ Constructor

Filter the pointers based on the result of the given callback function.

Kind: instance method of PathList
Returns: Constructor - Instance with the filtered pointers.

Param
callback

pathList.hasIn(predicates, subjects) ⇒ Constructor

Filter the pointers based on matching quad(s) with the current terms as the object.

Kind: instance method of PathList
Returns: Constructor - Instance that contains only the filtered pointers

ParamTypeDescription
predicatesArray.<Term>Predicates of the quads
subjectsArray.<Term>Subjects of the quads

pathList.hasOut(predicates, objects) ⇒ Constructor

Filter the pointers based on matching quad(s) with the current terms as the subject.

Kind: instance method of PathList
Returns: Constructor - Instance that contains only the filtered pointers

ParamTypeDescription
predicatesArray.<Term>Predicates of the quads
objectsArray.<Term>Objects of the quads

pathList.in(predicates, subjects) ⇒ Constructor

Traverse the graph with the current terms as the object.

Kind: instance method of PathList
Returns: Constructor - Instance with pointers of the traversed target terms

ParamTypeDescription
predicatesArray.<Term>Predicates of the quads
subjectsArray.<Term>Subjects of the quads

pathList.isAny() ⇒ boolean

Check if any pointer is an any-pointer.

Kind: instance method of PathList
Returns: boolean - True if any any-pointer was found

pathList.isList() ⇒ boolean

Check if there is only one pointer and whether that pointer is a list.

Kind: instance method of PathList
Returns: boolean - True if the pointer is a list

pathList.list() ⇒ Iterator.<Constructor> | undefined

Create an iterator for the list if the instance is a list; otherwise, return undefined.

Kind: instance method of PathList
Returns: Iterator.<Constructor> | undefined - Iterator or undefined

pathList.map(callback) ⇒ Array

Map each pointer using the given callback function.

Kind: instance method of PathList
Returns: Array - Array of mapped results

Param
callback

pathList.node(terms) ⇒ Constructor

Create a new instance with pointers using the given terms.

Kind: instance method of PathList
Returns: Constructor - Instance with pointers of the given terms

ParamDescription
termsArray of terms for the pointers

pathList.out(predicates, objects) ⇒ Constructor

Traverse the graph with the current terms as the subject.

Kind: instance method of PathList
Returns: Constructor - Instance with pointers of the traversed target terms

ParamTypeDescription
predicatesArray.<Term>Predicates of the quads
objectsArray.<Term>Objects of the quads

pathList.quads() ⇒ Iterator.<Quad>

Create an iterator of all quads of all pointer paths.

Kind: instance method of PathList
Returns: Iterator.<Quad> - Iterator for the quads

pathList.trim() ⇒ Constructor

Trim the path of all pointers and create a new instance for the result.

Kind: instance method of PathList
Returns: Constructor - Instance of the trimmed pointers