# Module: CompoundPath

Accessible via `require('@buggyorg/graphtools').CompoundPath`

A compound path is a unique representation of a node in the graph. It is defined as an array of parent nodes starting at the root level, e.g. `['A', 'B', 'C']` points to the node `C` whose parent is `B` and the parent of `B` is `A`. All methods accept the array notation or the shorthand string notation. The shorthand string notation starts with a `»` (ALT-GR+Y) and separates each node with a `»`, e.g. `»A»B»C` describes the exact same path as above. For elements on the root level it is okay to omit the `»`, i.e. `»A` is the same as `A`.

Source:
  - compoundPath.js, line 1

### Methods

#### (static) base() → {CompoundPath}

Returns the root node in the path, i.e. the first node indicated by the path.

Source:
  - compoundPath.js, line 102

##### Returns:

The id of the base/root element in the path.

Type
  CompoundPath

#### (static) fromString(compoundPathStr) → {Array.<String>}

Converts a compound path string into its array representation. The seperate parts must be divided by a '»'.

##### Parameters:

Name | Type | Description
--- | --- | ---
`compoundPathStr` | String | A string reperesenting the compound path divded by '»'.

Source:
  - compoundPath.js, line 30

##### Returns:

An array of node IDs representing the compound path.

Type
  Array.<String>

#### (static) isCompoundPath(path) → {boolean}

Returns whether a string represents a compound path or not.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path` | string | The path string to test.

Source:
  - compoundPath.js, line 40

##### Returns:

True if the path represents a compound path, false otherwise.

Type
  boolean

#### (static) isRoot(path) → {boolean}

Returns whether a path points to the root element or not.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path` | CompoundPath | The path to check

Source:
  - compoundPath.js, line 73

##### Returns:

True if the path points to the root element ('', '»' or []), false otherwise.

Type
  boolean

#### (static) join(base, rest) → {CompoundPath}

Joins two paths into one.

##### Parameters:

Name | Type | Description
--- | --- | ---
`base` | CompoundPath | The prefix of the new path
`rest` | CompoundPath | The postfix of the new path.

Source:
  - compoundPath.js, line 63

##### Returns:

The new path in the form `<base>»<rest>`.

Type
  CompoundPath

#### (static) node(path) → {String}

Returns the node element, i.e. the last element in the path.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path` | CompoundPath | The path

Source:
  - compoundPath.js, line 121

##### Returns:

The id of the the element at the end of the path chain.

Type
  String

#### (static) normalize(path) → {CompoundPath}

Convert a path representation into its normalized array form.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path` | string | Array.<string> | The path as a string or array.

Source:
  - compoundPath.js, line 49

##### Returns:

The normalized path.

Type
  CompoundPath

#### (static) parent(path) → {CompoundPath|string}

Returns the parent of a compound path.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path` | CompoundPath | string | The path either as a string or an array.

Source:
  - compoundPath.js, line 87

##### Throws:

If the input format is invalid.

Type
  Error

##### Returns:

The parent of the path in the same format as the input.

Type
  CompoundPath | string

#### (static) rest(path) → {CompoundPath}

Returns a new path that omits the root component.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path` | CompoundPath | The path

Source:
  - compoundPath.js, line 136

##### Returns:

A path that omits the root component. E.g. rest([a, b, c]) -> [b, c].

Type
  CompoundPath

#### (static) sameParents(path1, path2) → {boolean}

Returns if the pathes have the same parent node.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path1` | CompoundPath | One of the paths.
`path2` | CompoundPath | The other path.

Source:
  - compoundPath.js, line 219

##### Returns:

True if path1 and path2 have the same parents, false otherwise.

Type
  boolean

#### (static) toString(compoundPathArr) → {String}

Converts a compound path into its string representation. The seperate parts are divided by a '»'.

##### Parameters:

Name | Type | Description
--- | --- | ---
`compoundPathArr` | Array.<String> | An array of node IDs reperesenting the compound path.

Source:
  - compoundPath.js, line 20

##### Returns:

The string representation of the compound path.

Type
  String

#### (inner) equal(path1, path2) → {boolean}

Returns whether two compound paths are equal

##### Parameters:

Name | Type | Description
--- | --- | ---
`path1` | CompoundPath | The first path to compare.
`path2` | CompoundPath | The second path to compare.

Source:
  - compoundPath.js, line 201

##### Returns:

True if the paths are the same, false otherwise.

Type
  boolean

#### (inner) prefix(path1, path2) → {CompoundPath}

Prefixes path1 by path2. Does not duplicate entries in path1 if they are already part of path1. Every entry in the path is a unique id and if path1 already has a subset of path2 this subset is not prefixed too.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path1` | CompoundPath | The path that gets its prefix.
`path2` | CompoundPath | The prefix path.

Source:
  - compoundPath.js, line 175

##### Returns:

A new path that prefixed path2 onto path1

Type
  CompoundPath

##### Example

    // Compound paths contain IDs which are usually not that short. Only for brevity.
    prefix([d, e], [a, b]) => [a, b, d, e]
    prefix([b, c], [a, b]) => [a, b, c]
    prefix([a, b, c], [a, b]) => [a, b, c]
    prefix([a, c], [a, b]) => Throws exception as path2 cannot be a prefix!

#### (inner) relativeTo(path1, path2) → {CompoundPath}

Creates a new path that shortens path1 assuming that path2 is a prefix to path1.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path1` | CompoundPath | The path to shorten
`path2` | CompoundPath | The path that is a prefix of path1 and by what path1 is shortend.

Source:
  - compoundPath.js, line 146

##### Throws:

Of path2 is no prefix of path2.

Type
  Error

##### Returns:

A new shortend path that has the prefix path2 removed.

Type
  CompoundPath