Add visit(node, visitor) to 'yaml'

[eemeli]

Closes #190, so ping at least @amadare42 and @privatenumber.

This adds the following new export to 'yaml/util':

/**
 * Apply a visitor to an AST node or document.
 *
 * Walks through the tree (depth-first) starting from `node`, calling each of
 * the visitor functions (if defined) according to the current node type.
 */
export function visit(node: Node | Document, visitor: {
  Document?: (doc: Document) => void
  Map?: (map: YAMLMap) => void
  Pair?: (pair: Pair) => void
  Seq?: (seq: YAMLSeq) => void
  Scalar?: (scalar: Scalar) => void
}): void

To start with, this is pretty minimal and just walks the tree. In other words, it does not provide the node's current path, it does not provide control methods for early exits from the walk, and it does not do anything with the value returned from a visitor function.

I'm quite open to developing this API further, but I'd like to see example use cases or other arguments for more complex features.

EDIT: See next comment for updated API.

[eemeli]

Okay, fine, I gave it more features. Looked at a number of different AST visitor implementations, ended up taking quite a bit of inspiration from GraphQL, as well as elsewhere. Here's the new API:

/**
 * Apply a visitor to an AST node or document.
 *
 * Walks through the tree (depth-first) starting from `node`, calling a
 * `visitor` function with three arguments:
 *   - `key`: For sequence values and map `Pair`, the node's index in the
 *     collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
 *     `null` for the root node.
 *   - `node`: The current node.
 *   - `path`: The ancestry of the current node.
 *
 * The return value of the visitor may be used to control the traversal:
 *   - `undefined` (default): Do nothing and continue
 *   - `visit.SKIP`: Do not visit the children of this node, continue with next
 *     sibling
 *   - `visit.BREAK`: Terminate traversal completely
 *   - `visit.REMOVE`: Remove the current node, then continue with the next one
 *   - `Node`: Replace the current node, then continue by visiting it
 *   - `number`: While iterating the items of a sequence or map, set the index
 *     of the next step. This is useful especially if the index of the current
 *     node has changed.
 *
 * If `visitor` is a single function, it will be called with all values
 * encountered in the tree, including e.g. `null` values. Alternatively,
 * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
 *  `Alias` and `Scalar` node.
 */
export declare const visit: visit

export type visitor<T> = (
  key: number | 'key' | 'value' | null,
  node: T,
  path: Node[]
) => void | symbol | number | Node

export interface visit {
  (
    node: Node | Document,
    visitor:
      | visitor<any>
      | {
          Alias?: visitor<Alias>
          Map?: visitor<YAMLMap>
          Pair?: visitor<Pair>
          Scalar?: visitor<Scalar>
          Seq?: visitor<YAMLSeq>
        }
  ): void

  /** Terminate visit traversal completely */
  BREAK: symbol

  /** Remove the current node */
  REMOVE: symbol

  /** Do not visit the children of the current node */
  SKIP: symbol
}

[eemeli]

On further thought, it doesn't make sense to hide this behind 'yaml/util'. Also updated documentation.