1  import { CST } from './parse-cst'
  2  import {
  3    AST,
  4    Alias,
  5    Collection,
  6    Merge,
  7    Node,
  8    Scalar,
  9    Schema,
 10    YAMLMap,
 11    YAMLSeq
 12  } from './types'
 13  import { Type, YAMLError, YAMLWarning } from './util'
 14  
 15  export { AST, CST }
 16  export { default as parseCST } from './parse-cst'
 17  
 18  /**
 19   * `yaml` defines document-specific options in three places: as an argument of
 20   * parse, create and stringify calls, in the values of `YAML.defaultOptions`,
 21   * and in the version-dependent `YAML.Document.defaults` object. Values set in
 22   * `YAML.defaultOptions` override version-dependent defaults, and argument
 23   * options override both.
 24   */
 25  export const defaultOptions: Options
 26  
 27  export interface Options extends Schema.Options {
 28    /**
 29     * Default prefix for anchors.
 30     *
 31     * Default: `'a'`, resulting in anchors `a1`, `a2`, etc.
 32     */
 33    anchorPrefix?: string
 34    /**
 35     * The number of spaces to use when indenting code.
 36     *
 37     * Default: `2`
 38     */
 39    indent?: number
 40    /**
 41     * Whether block sequences should be indented.
 42     *
 43     * Default: `true`
 44     */
 45    indentSeq?: boolean
 46    /**
 47     * Allow non-JSON JavaScript objects to remain in the `toJSON` output.
 48     * Relevant with the YAML 1.1 `!!timestamp` and `!!binary` tags as well as BigInts.
 49     *
 50     * Default: `true`
 51     */
 52    keepBlobsInJSON?: boolean
 53    /**
 54     * Include references in the AST to each node's corresponding CST node.
 55     *
 56     * Default: `false`
 57     */
 58    keepCstNodes?: boolean
 59    /**
 60     * Store the original node type when parsing documents.
 61     *
 62     * Default: `true`
 63     */
 64    keepNodeTypes?: boolean
 65    /**
 66     * When outputting JS, use Map rather than Object to represent mappings.
 67     *
 68     * Default: `false`
 69     */
 70    mapAsMap?: boolean
 71    /**
 72     * Prevent exponential entity expansion attacks by limiting data aliasing count;
 73     * set to `-1` to disable checks; `0` disallows all alias nodes.
 74     *
 75     * Default: `100`
 76     */
 77    maxAliasCount?: number
 78    /**
 79     * Include line position & node type directly in errors; drop their verbose source and context.
 80     *
 81     * Default: `false`
 82     */
 83    prettyErrors?: boolean
 84    /**
 85     * When stringifying, require keys to be scalars and to use implicit rather than explicit notation.
 86     *
 87     * Default: `false`
 88     */
 89    simpleKeys?: boolean
 90    /**
 91     * The YAML version used by documents without a `%YAML` directive.
 92     *
 93     * Default: `"1.2"`
 94     */
 95    version?: '1.0' | '1.1' | '1.2'
 96  }
 97  
 98  /**
 99   * Some customization options are availabe to control the parsing and
100   * stringification of scalars. Note that these values are used by all documents.
101   */
102  export const scalarOptions: {
103    binary: scalarOptions.Binary
104    bool: scalarOptions.Bool
105    int: scalarOptions.Int
106    null: scalarOptions.Null
107    str: scalarOptions.Str
108  }
109  export namespace scalarOptions {
110    interface Binary {
111      /**
112       * The type of string literal used to stringify `!!binary` values.
113       *
114       * Default: `'BLOCK_LITERAL'`
115       */
116      defaultType: Scalar.Type
117      /**
118       * Maximum line width for `!!binary`.
119       *
120       * Default: `76`
121       */
122      lineWidth: number
123    }
124  
125    interface Bool {
126      /**
127       * String representation for `true`. With the core schema, use `'true' | 'True' | 'TRUE'`.
128       *
129       * Default: `'true'`
130       */
131      trueStr: string
132      /**
133       * String representation for `false`. With the core schema, use `'false' | 'False' | 'FALSE'`.
134       *
135       * Default: `'false'`
136       */
137      falseStr: string
138    }
139  
140    interface Int {
141      /**
142       * Whether integers should be parsed into BigInt values.
143       *
144       * Default: `false`
145       */
146      asBigInt: boolean
147    }
148  
149    interface Null {
150      /**
151       * String representation for `null`. With the core schema, use `'null' | 'Null' | 'NULL' | '~' | ''`.
152       *
153       * Default: `'null'`
154       */
155      nullStr: string
156    }
157  
158    interface Str {
159      /**
160       * The default type of string literal used to stringify values
161       *
162       * Default: `'PLAIN'`
163       */
164      defaultType: Scalar.Type
165      doubleQuoted: {
166        /**
167         * Whether to restrict double-quoted strings to use JSON-compatible syntax.
168         *
169         * Default: `false`
170         */
171        jsonEncoding: boolean
172        /**
173         * Minimum length to use multiple lines to represent the value.
174         *
175         * Default: `40`
176         */
177        minMultiLineLength: number
178      }
179      fold: {
180        /**
181         * Maximum line width (set to `0` to disable folding).
182         *
183         * Default: `80`
184         */
185        lineWidth: number
186        /**
187         * Minimum width for highly-indented content.
188         *
189         * Default: `20`
190         */
191        minContentWidth: number
192      }
193    }
194  }
195  
196  export class Document extends Collection {
197    cstNode?: CST.Document
198    constructor(options?: Options)
199    tag: never
200    directivesEndMarker?: boolean
201    type: Type.DOCUMENT
202    /**
203     * Anchors associated with the document's nodes;
204     * also provides alias & merge node creators.
205     */
206    anchors: Document.Anchors
207    /** The document contents. */
208    contents: any
209    /** Errors encountered during parsing. */
210    errors: YAMLError[]
211    /**
212     * The schema used with the document. Use `setSchema()` to change or
213     * initialise.
214     */
215    schema?: Schema
216    /**
217     * Array of prefixes; each will have a string `handle` that
218     * starts and ends with `!` and a string `prefix` that the handle will be replaced by.
219     */
220    tagPrefixes: Document.TagPrefix[]
221    /**
222     * The parsed version of the source document;
223     * if true-ish, stringified output will include a `%YAML` directive.
224     */
225    version?: string
226    /** Warnings encountered during parsing. */
227    warnings: YAMLWarning[]
228    /**
229     * List the tags used in the document that are not in the default
230     * `tag:yaml.org,2002:` namespace.
231     */
232    listNonDefaultTags(): string[]
233    /** Parse a CST into this document */
234    parse(cst: CST.Document): this
235    /**
236     * When a document is created with `new YAML.Document()`, the schema object is
237     * not set as it may be influenced by parsed directives; call this with no
238     * arguments to set it manually, or with arguments to change the schema used
239     * by the document.
240     **/
241    setSchema(
242      id?: Options['version'] | Schema.Name,
243      customTags?: (Schema.TagId | Schema.Tag)[]
244    ): void
245    /** Set `handle` as a shorthand string for the `prefix` tag namespace. */
246    setTagPrefix(handle: string, prefix: string): void
247    /**
248     * A plain JavaScript representation of the document `contents`.
249     *
250     * @param arg Used by `JSON.stringify` to indicate the array index or property
251     *   name. If its value is a `string` and the document `contents` has a scalar
252     *   value, the `keepBlobsInJSON` option has no effect.
253     * @param onAnchor If defined, called with the resolved `value` and reference
254     *   `count` for each anchor in the document.
255     * */
256    toJSON(arg?: string, onAnchor?: (value: any, count: number) => void): any
257    /** A YAML representation of the document. */
258    toString(): string
259  }
260  
261  export namespace Document {
262    interface Parsed extends Document {
263      contents: Scalar | YAMLMap | YAMLSeq | null
264      /** The schema used with the document. */
265      schema: Schema
266    }
267  
268    interface Anchors {
269      /**
270       * Create a new `Alias` node, adding the required anchor for `node`.
271       * If `name` is empty, a new anchor name will be generated.
272       */
273      createAlias(node: Node, name?: string): Alias
274      /**
275       * Create a new `Merge` node with the given source nodes.
276       * Non-`Alias` sources will be automatically wrapped.
277       */
278      createMergePair(...nodes: Node[]): Merge
279      /** The anchor name associated with `node`, if set. */
280      getName(node: Node): undefined | string
281      /** List of all defined anchor names. */
282      getNames(): string[]
283      /** The node associated with the anchor `name`, if set. */
284      getNode(name: string): undefined | Node
285      /**
286       * Find an available anchor name with the given `prefix` and a
287       * numerical suffix.
288       */
289      newName(prefix: string): string
290      /**
291       * Associate an anchor with `node`. If `name` is empty, a new name will be generated.
292       * To remove an anchor, use `setAnchor(null, name)`.
293       */
294      setAnchor(node: Node | null, name?: string): void | string
295    }
296  
297    interface TagPrefix {
298      handle: string
299      prefix: string
300    }
301  }
302  
303  /**
304   * Recursively turns objects into collections. Generic objects as well as `Map`
305   * and its descendants become mappings, while arrays and other iterable objects
306   * result in sequences.
307   *
308   * The primary purpose of this function is to enable attaching comments or other
309   * metadata to a value, or to otherwise exert more fine-grained control over the
310   * stringified output. To that end, you'll need to assign its return value to
311   * the `contents` of a Document (or somewhere within said contents), as the
312   * document's schema is required for YAML string output.
313   *
314   * @param wrapScalars If undefined or `true`, also wraps plain values in
315   *   `Scalar` objects; if `false` and `value` is not an object, it will be
316   *   returned directly.
317   * @param tag Use to specify the collection type, e.g. `"!!omap"`. Note that
318   *   this requires the corresponding tag to be available based on the default
319   *   options. To use a specific document's schema, use `doc.schema.createNode`.
320   */
321  export function createNode(
322    value: any,
323    wrapScalars?: true,
324    tag?: string
325  ): YAMLMap | YAMLSeq | Scalar
326  
327  /**
328   * YAML.createNode recursively turns objects into Map and arrays to Seq collections.
329   * Its primary use is to enable attaching comments or other metadata to a value,
330   * or to otherwise exert more fine-grained control over the stringified output.
331   *
332   * Doesn't wrap plain values in Scalar objects.
333   */
334  export function createNode(
335    value: any,
336    wrapScalars: false,
337    tag?: string
338  ): YAMLMap | YAMLSeq | string | number | boolean | null
339  
340  /**
341   * Parse an input string into a single YAML.Document.
342   */
343  export function parseDocument(str: string, options?: Options): Document.Parsed
344  
345  /**
346   * Parse the input as a stream of YAML documents.
347   *
348   * Documents should be separated from each other by `...` or `---` marker lines.
349   */
350  export function parseAllDocuments(
351    str: string,
352    options?: Options
353  ): Document.Parsed[]
354  
355  /**
356   * Parse an input string into JavaScript.
357   *
358   * Only supports input consisting of a single YAML document; for multi-document
359   * support you should use `YAML.parseAllDocuments`. May throw on error, and may
360   * log warnings using `console.warn`.
361   *
362   * @param str A string with YAML formatting.
363   * @returns The value will match the type of the root value of the parsed YAML
364   *   document, so Maps become objects, Sequences arrays, and scalars result in
365   *   nulls, booleans, numbers and strings.
366   */
367  export function parse(str: string, options?: Options): any
368  
369  /**
370   * @returns Will always include \n as the last character, as is expected of YAML documents.
371   */
372  export function stringify(value: any, options?: Options): string