Merge branch 'main' into docusaurus

src/index.ts

@@ -5,12 +5,12 @@ export { Tree } from './lib/tree';
 export { Graph, Triple } from './lib/graph';
 export {
   PENMANCodec,
-  _decode as decode,
-  _dump as dump,
-  _dumps as dumps,
-  _encode as encode,
-  _iterdecode as iterdecode,
-  _load as load,
-  _loads as loads,
+  decode,
+  dump,
+  dumps,
+  encode,
+  iterdecode,
+  load,
+  loads,
 } from './lib/codec';
 export { DecodeError, PenmanError } from './lib/exceptions';

src/lib/_format.ts

@@ -51,7 +51,6 @@ export const format = (
  * // ARG0(b, d) ^
  * // instance(d, dog)
  */
-
 export const formatTriples = (
   triples: BasicTriple[],
   indent = true,

src/lib/_lexer.ts

@@ -145,8 +145,7 @@ export class TokenIterator {
   /**
    * Return the next token if its type is in *choices*.
    *
-   * The iterator is advanced if successful. If unsuccessful,
-   * ``None`` is returned.
+   * The iterator is advanced if successful. If unsuccessful, `None` is returned.
    */
   accept(...choices: string[]): Token | null {
     if (this._next != null && choices.includes(this._next.value[0])) {

src/lib/codec.ts

@@ -98,7 +98,6 @@ export class PENMANCodec {
    * console.log(codec.encode(new Graph([['h', 'instance', 'hi']])));
    * // '(h / hi)'
    */
-
   encode(
     g: Graph,
     top?: Variable,
@@ -154,7 +153,7 @@ export class PENMANCodec {
  *
  * const graph = decode('(b / bark-01 :ARG0 (d / dog))');
  */
-export function _decode(s: string, model?: Model): Graph {
+export function decode(s: string, model?: Model): Graph {
   const codec = new PENMANCodec(model);
   return codec.decode(s);
 }
@@ -172,8 +171,7 @@ export function _decode(s: string, model?: Model): Graph {
  *   // ...
  * }
  */
-
-export function* _iterdecode(
+export function* iterdecode(
   lines: string | string[],
   model?: Model,
 ): IterableIterator<Graph> {
@@ -196,8 +194,7 @@ export function* _iterdecode(
  * console.log(encode(new Graph([['h', 'instance', 'hi']])));
  * // '(h / hi)'
  */
-
-export function _encode(
+export function encode(
   g: Graph,
   top?: Variable,
   model?: Model,
@@ -215,7 +212,7 @@ export function _encode(
  * @param model - The model used for interpreting the graph.
  * @returns A list of `Graph` objects.
  */
-export function _load(
+export function load(
   source: string,
   model?: Model,
   encoding?: string,
@@ -234,7 +231,7 @@ export function _load(
  * @param model - The model used for interpreting the graph.
  * @returns A list of `Graph` objects.
  */
-export function _loads(string: string, model?: Model): Graph[] {
+export function loads(string: string, model?: Model): Graph[] {
   const codec = new PENMANCodec(model);
   return Array.from(codec.iterdecode(string));
 }
@@ -248,7 +245,7 @@ export function _loads(string: string, model?: Model): Graph[] {
  * @param indent - How to indent formatted strings.
  * @param compact - If `true`, put initial attributes on the first line.
  */
-export function _dump(
+export function dump(
   graphs: Graph[],
   file: string,
   model?: Model,
@@ -261,7 +258,7 @@ export function _dump(
 }
 
 /** Helper method for dump() for incremental printing. */
-export function _dumpStream(
+function _dumpStream(
   file: string,
   gs: Graph[],
   codec: PENMANCodec,
@@ -290,7 +287,7 @@ export function _dumpStream(
  * @param compact - If `true`, put initial attributes on the first line.
  * @returns The string of serialized graphs.
  */
-export function _dumps(
+export function dumps(
   graphs: Graph[],
   model?: Model,
   indent: number | null | undefined = -1,

src/lib/constant.ts

@@ -80,7 +80,6 @@ export const type = (constant_string: string | null | undefined): Type => {
  * console.log(evaluate('1.2')); // Outputs: 1.2
  * console.log(evaluate('') === null); // Outputs: true
  */
-
 export const evaluate = (
   constantString: string | null | undefined,
 ): Constant => {

src/lib/graph.ts

@@ -22,10 +22,6 @@ export const CONCEPT_ROLE = ':instance';
 
 /**
  * Represents a relation between nodes or between a node and a constant.
- *
- * @param source - The source variable of the triple.
- * @param role - The edge label between the source and target.
- * @param target - The target variable or constant.
  */
 export type Triple = [source: Variable, role: Role, target: Target];
 
@@ -70,21 +66,22 @@ let graphIdCounter = 0;
  * ]);
  */
 export class Graph {
-  _id: number;
+  private _id: number;
+  private _top: Variable | null;
 
   /**
    * @param triples - An iterable of triples (either `Triple` objects or 3-tuples).
-   * @param top - The variable of the top node; if unspecified, the source
-   *              of the first triple is used.
+   * @param top - The variable of the top node; if unspecified, the source of the first triple is used.
    * @param epidata - A mapping of triples to epigraphical markers.
    * @param metadata - A mapping of metadata types to descriptions.
    */
   constructor(
     public triples: Triples = [],
-    private _top: Variable = null,
+    top: Variable = null,
     public epidata: EpidataMap = new EpidataMap(),
     public metadata: Record<string, string> = {},
   ) {
+    this._top = top;
     // the following (a) creates a new list (b) validates that
     // they are triples, and (c) ensures roles begin with :
     this.triples = triples.map(([src, role, tgt]) => [
@@ -96,6 +93,7 @@ export class Graph {
     this._id = graphIdCounter++;
   }
 
+  /** @ignore */
   __repr__() {
     const name = this.constructor.name;
     return `<${name} object (top=${this.top}) at ${this._id}>`;
@@ -123,6 +121,7 @@ export class Graph {
     );
   }
 
+  /** @ignore */
   __or__(other: any) {
     if (other instanceof Graph) {
       const g = cloneDeep(this);
@@ -136,6 +135,7 @@ export class Graph {
     return this.__or__(other);
   }
 
+  /** @ignore */
   __ior__(other: any) {
     if (other instanceof Graph) {
       const new_: Triples = differenceWith(
@@ -161,6 +161,7 @@ export class Graph {
     return this.__ior__(other);
   }
 
+  /** @ignore */
   __sub__(other: any) {
     if (other instanceof Graph) {
       const g = cloneDeep(this);
@@ -174,6 +175,7 @@ export class Graph {
     return this.__sub__(other);
   }
 
+  /** @ignore */
   __isub__(other: any) {
     if (other instanceof Graph) {
       const removed = other.triples;
@@ -264,7 +266,7 @@ export class Graph {
   }
 
   /** Filter triples based on their source, role, and/or target. */
-  _filterTriples(
+  private _filterTriples(
     // TODO: use proper typescript optional types instead of 'null'
     source: Variable | null = null,
     role: Role | null = null,

src/lib/layout.ts

@@ -6,46 +6,54 @@
  * choosing the order of the edges from a node and the paths to get to a
  * node definition (the position in the tree where a node's concept and
  * edges are specified). For instance, the following graphs for "The dog
- * barked loudly" have different edge orders on the ``b`` node::
+ * barked loudly" have different edge orders on the ``b`` node:
  *
+ * ```
  * (b / bark-01           (b / bark-01
  *     :ARG0 (d / dog)        :mod (l / loud)
  *     :mod (l / loud))       :ARG0 (d / dog))
+ * ```
  *
  * With re-entrancies, there are choices about which location of a
  * re-entrant node gets the full definition with its concept (node
  * label), etc. For instance, the following graphs for "The dog tried to
- * bark" have different locations for the definition of the ``d`` node::
+ * bark" have different locations for the definition of the ``d`` node:
  *
+ * ```
  * (t / try-01              (t / try-01
  *     :ARG0 (d / dog)          :ARG0 d
  *     :ARG1 (b / bark-01       :ARG1 (b / bark-01
  *         :ARG0 d))                :ARG0 (d / dog))
+ * ```
  *
- * With inverted edges, there are even more possibilities, such as::
+ * With inverted edges, there are even more possibilities, such as:
  *
+ * ```
  * (t / try-01                (t / try-01
  *     :ARG0 (d / dog             :ARG1 (b / bark-01
  *         :ARG0-of b)                :ARG0 (d / dog
  *     :ARG1 (b / bark-01))             :ARG0-of t)))
+ * ```
  *
  * This module introduces two epigraphical markers so that a pure graph
  * parsed from PENMAN can retain information about its tree layout
  * without altering its graph properties. The first marker type is
- * :class:`Push`, which is put on a triple to indicate that the triple
- * introduces a new node context, while the sentinel :data:`POP`
+ * `Push`, which is put on a triple to indicate that the triple
+ * introduces a new node context, while the sentinel `POP`
  * indicates that a triple is at the end of one or more node contexts.
  * These markers only work if the triples in the graph's data are
  * ordered. For instance, one of the graphs above (repeated here) has the
- * following data::
+ * following data:
  *
+ * ```
  * PENMAN                 Graph                            Epigraph
  * (t / try-01            [('t', ':instance', 'try-01'),   :
  *    :ARG0 (d / dog)      ('t', ':ARG0', 'd'),            : Push('d')
  *    :ARG1 (b / bark-01   ('d', ':instance', 'dog'),      : POP
  *       :ARG0 d))         ('t', ':ARG1', 'b'),            : Push('b')
  *                         ('b', ':instance', 'bark-01'),  :
  *                         ('b', ':ARG0', 'd')]            : POP
+ * ```
  */
 
 import cloneDeep from 'lodash.clonedeep';
@@ -93,7 +101,7 @@ export class Push extends LayoutMarker {
   }
 }
 
-/**Epigraph marker to indicate the end of a node context.*/
+/** Epigraph marker to indicate the end of a node context. */
 export class Pop extends LayoutMarker {
   toString() {
     return 'POP';
@@ -133,7 +141,6 @@ export const POP = new Pop();
  * // ['b', ':ARG0', 'd']
  * // ['d', ':instance', 'dog']
  */
-
 export function interpret(
   t: Tree | null,
   model: Model = _default_model,
@@ -281,7 +288,6 @@ const _processAtomic = (target: string): [string, Epidatum[]] => {
  * console.log(t);
  * // Tree('b', [['/', 'bark-01'], [':ARG0', new Tree('d', [['/', 'dog']])]])
  */
-
 export function configure(
   g: Graph,
   top: Variable = null,
@@ -624,7 +630,6 @@ export function reconfigure(
  * //    :ARG0 (d / dog)
  * //    :ARG1 (c / cat))
  */
-
 export function rearrange(
   t: Tree,
   key: (role: Role) => any = null,
@@ -675,7 +680,6 @@ const _rearrange = (node: Node, key: (branch: Branch) => any) => {
  * console.log(getPushedVariable(g, ['a', ':instance', 'alpha'])); // Outputs: null
  * console.log(getPushedVariable(g, ['a', ':ARG0', 'b'])); // Outputs: 'b'
  */
-
 export function getPushedVariable(
   g: Graph,
   triple: BasicTriple,
@@ -704,7 +708,6 @@ export function getPushedVariable(
  * @param triple - The triple that does or does not appear inverted.
  * @returns `true` if `triple` appears inverted in graph `g`.
  */
-
 export function appearsInverted(g: Graph, triple: BasicTriple): boolean {
   const variables = g.variables();
   if (triple[1] === CONCEPT_ROLE || !variables.has(triple[2] as string)) {