373 lines
10 KiB
TypeScript
373 lines
10 KiB
TypeScript
import { CST } from './parse-cst'
|
|
import {
|
|
AST,
|
|
Alias,
|
|
Collection,
|
|
Merge,
|
|
Node,
|
|
Scalar,
|
|
Schema,
|
|
YAMLMap,
|
|
YAMLSeq
|
|
} from './types'
|
|
import { Type, YAMLError, YAMLWarning } from './util'
|
|
|
|
export { AST, CST }
|
|
export { default as parseCST } from './parse-cst'
|
|
|
|
/**
|
|
* `yaml` defines document-specific options in three places: as an argument of
|
|
* parse, create and stringify calls, in the values of `YAML.defaultOptions`,
|
|
* and in the version-dependent `YAML.Document.defaults` object. Values set in
|
|
* `YAML.defaultOptions` override version-dependent defaults, and argument
|
|
* options override both.
|
|
*/
|
|
export const defaultOptions: Options
|
|
|
|
export interface Options extends Schema.Options {
|
|
/**
|
|
* Default prefix for anchors.
|
|
*
|
|
* Default: `'a'`, resulting in anchors `a1`, `a2`, etc.
|
|
*/
|
|
anchorPrefix?: string
|
|
/**
|
|
* The number of spaces to use when indenting code.
|
|
*
|
|
* Default: `2`
|
|
*/
|
|
indent?: number
|
|
/**
|
|
* Whether block sequences should be indented.
|
|
*
|
|
* Default: `true`
|
|
*/
|
|
indentSeq?: boolean
|
|
/**
|
|
* Allow non-JSON JavaScript objects to remain in the `toJSON` output.
|
|
* Relevant with the YAML 1.1 `!!timestamp` and `!!binary` tags as well as BigInts.
|
|
*
|
|
* Default: `true`
|
|
*/
|
|
keepBlobsInJSON?: boolean
|
|
/**
|
|
* Include references in the AST to each node's corresponding CST node.
|
|
*
|
|
* Default: `false`
|
|
*/
|
|
keepCstNodes?: boolean
|
|
/**
|
|
* Store the original node type when parsing documents.
|
|
*
|
|
* Default: `true`
|
|
*/
|
|
keepNodeTypes?: boolean
|
|
/**
|
|
* When outputting JS, use Map rather than Object to represent mappings.
|
|
*
|
|
* Default: `false`
|
|
*/
|
|
mapAsMap?: boolean
|
|
/**
|
|
* Prevent exponential entity expansion attacks by limiting data aliasing count;
|
|
* set to `-1` to disable checks; `0` disallows all alias nodes.
|
|
*
|
|
* Default: `100`
|
|
*/
|
|
maxAliasCount?: number
|
|
/**
|
|
* Include line position & node type directly in errors; drop their verbose source and context.
|
|
*
|
|
* Default: `false`
|
|
*/
|
|
prettyErrors?: boolean
|
|
/**
|
|
* When stringifying, require keys to be scalars and to use implicit rather than explicit notation.
|
|
*
|
|
* Default: `false`
|
|
*/
|
|
simpleKeys?: boolean
|
|
/**
|
|
* The YAML version used by documents without a `%YAML` directive.
|
|
*
|
|
* Default: `"1.2"`
|
|
*/
|
|
version?: '1.0' | '1.1' | '1.2'
|
|
}
|
|
|
|
/**
|
|
* Some customization options are availabe to control the parsing and
|
|
* stringification of scalars. Note that these values are used by all documents.
|
|
*/
|
|
export const scalarOptions: {
|
|
binary: scalarOptions.Binary
|
|
bool: scalarOptions.Bool
|
|
int: scalarOptions.Int
|
|
null: scalarOptions.Null
|
|
str: scalarOptions.Str
|
|
}
|
|
export namespace scalarOptions {
|
|
interface Binary {
|
|
/**
|
|
* The type of string literal used to stringify `!!binary` values.
|
|
*
|
|
* Default: `'BLOCK_LITERAL'`
|
|
*/
|
|
defaultType: Scalar.Type
|
|
/**
|
|
* Maximum line width for `!!binary`.
|
|
*
|
|
* Default: `76`
|
|
*/
|
|
lineWidth: number
|
|
}
|
|
|
|
interface Bool {
|
|
/**
|
|
* String representation for `true`. With the core schema, use `'true' | 'True' | 'TRUE'`.
|
|
*
|
|
* Default: `'true'`
|
|
*/
|
|
trueStr: string
|
|
/**
|
|
* String representation for `false`. With the core schema, use `'false' | 'False' | 'FALSE'`.
|
|
*
|
|
* Default: `'false'`
|
|
*/
|
|
falseStr: string
|
|
}
|
|
|
|
interface Int {
|
|
/**
|
|
* Whether integers should be parsed into BigInt values.
|
|
*
|
|
* Default: `false`
|
|
*/
|
|
asBigInt: boolean
|
|
}
|
|
|
|
interface Null {
|
|
/**
|
|
* String representation for `null`. With the core schema, use `'null' | 'Null' | 'NULL' | '~' | ''`.
|
|
*
|
|
* Default: `'null'`
|
|
*/
|
|
nullStr: string
|
|
}
|
|
|
|
interface Str {
|
|
/**
|
|
* The default type of string literal used to stringify values
|
|
*
|
|
* Default: `'PLAIN'`
|
|
*/
|
|
defaultType: Scalar.Type
|
|
doubleQuoted: {
|
|
/**
|
|
* Whether to restrict double-quoted strings to use JSON-compatible syntax.
|
|
*
|
|
* Default: `false`
|
|
*/
|
|
jsonEncoding: boolean
|
|
/**
|
|
* Minimum length to use multiple lines to represent the value.
|
|
*
|
|
* Default: `40`
|
|
*/
|
|
minMultiLineLength: number
|
|
}
|
|
fold: {
|
|
/**
|
|
* Maximum line width (set to `0` to disable folding).
|
|
*
|
|
* Default: `80`
|
|
*/
|
|
lineWidth: number
|
|
/**
|
|
* Minimum width for highly-indented content.
|
|
*
|
|
* Default: `20`
|
|
*/
|
|
minContentWidth: number
|
|
}
|
|
}
|
|
}
|
|
|
|
export class Document extends Collection {
|
|
cstNode?: CST.Document
|
|
constructor(options?: Options)
|
|
tag: never
|
|
directivesEndMarker?: boolean
|
|
type: Type.DOCUMENT
|
|
/**
|
|
* Anchors associated with the document's nodes;
|
|
* also provides alias & merge node creators.
|
|
*/
|
|
anchors: Document.Anchors
|
|
/** The document contents. */
|
|
contents: any
|
|
/** Errors encountered during parsing. */
|
|
errors: YAMLError[]
|
|
/**
|
|
* The schema used with the document. Use `setSchema()` to change or
|
|
* initialise.
|
|
*/
|
|
schema?: Schema
|
|
/**
|
|
* Array of prefixes; each will have a string `handle` that
|
|
* starts and ends with `!` and a string `prefix` that the handle will be replaced by.
|
|
*/
|
|
tagPrefixes: Document.TagPrefix[]
|
|
/**
|
|
* The parsed version of the source document;
|
|
* if true-ish, stringified output will include a `%YAML` directive.
|
|
*/
|
|
version?: string
|
|
/** Warnings encountered during parsing. */
|
|
warnings: YAMLWarning[]
|
|
/**
|
|
* List the tags used in the document that are not in the default
|
|
* `tag:yaml.org,2002:` namespace.
|
|
*/
|
|
listNonDefaultTags(): string[]
|
|
/** Parse a CST into this document */
|
|
parse(cst: CST.Document): this
|
|
/**
|
|
* When a document is created with `new YAML.Document()`, the schema object is
|
|
* not set as it may be influenced by parsed directives; call this with no
|
|
* arguments to set it manually, or with arguments to change the schema used
|
|
* by the document.
|
|
**/
|
|
setSchema(
|
|
id?: Options['version'] | Schema.Name,
|
|
customTags?: (Schema.TagId | Schema.Tag)[]
|
|
): void
|
|
/** Set `handle` as a shorthand string for the `prefix` tag namespace. */
|
|
setTagPrefix(handle: string, prefix: string): void
|
|
/**
|
|
* A plain JavaScript representation of the document `contents`.
|
|
*
|
|
* @param arg Used by `JSON.stringify` to indicate the array index or property
|
|
* name. If its value is a `string` and the document `contents` has a scalar
|
|
* value, the `keepBlobsInJSON` option has no effect.
|
|
* @param onAnchor If defined, called with the resolved `value` and reference
|
|
* `count` for each anchor in the document.
|
|
* */
|
|
toJSON(arg?: string, onAnchor?: (value: any, count: number) => void): any
|
|
/** A YAML representation of the document. */
|
|
toString(): string
|
|
}
|
|
|
|
export namespace Document {
|
|
interface Parsed extends Document {
|
|
contents: Scalar | YAMLMap | YAMLSeq | null
|
|
/** The schema used with the document. */
|
|
schema: Schema
|
|
}
|
|
|
|
interface Anchors {
|
|
/**
|
|
* Create a new `Alias` node, adding the required anchor for `node`.
|
|
* If `name` is empty, a new anchor name will be generated.
|
|
*/
|
|
createAlias(node: Node, name?: string): Alias
|
|
/**
|
|
* Create a new `Merge` node with the given source nodes.
|
|
* Non-`Alias` sources will be automatically wrapped.
|
|
*/
|
|
createMergePair(...nodes: Node[]): Merge
|
|
/** The anchor name associated with `node`, if set. */
|
|
getName(node: Node): undefined | string
|
|
/** List of all defined anchor names. */
|
|
getNames(): string[]
|
|
/** The node associated with the anchor `name`, if set. */
|
|
getNode(name: string): undefined | Node
|
|
/**
|
|
* Find an available anchor name with the given `prefix` and a
|
|
* numerical suffix.
|
|
*/
|
|
newName(prefix: string): string
|
|
/**
|
|
* Associate an anchor with `node`. If `name` is empty, a new name will be generated.
|
|
* To remove an anchor, use `setAnchor(null, name)`.
|
|
*/
|
|
setAnchor(node: Node | null, name?: string): void | string
|
|
}
|
|
|
|
interface TagPrefix {
|
|
handle: string
|
|
prefix: string
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Recursively turns objects into collections. Generic objects as well as `Map`
|
|
* and its descendants become mappings, while arrays and other iterable objects
|
|
* result in sequences.
|
|
*
|
|
* The primary purpose of this function is to enable attaching comments or other
|
|
* metadata to a value, or to otherwise exert more fine-grained control over the
|
|
* stringified output. To that end, you'll need to assign its return value to
|
|
* the `contents` of a Document (or somewhere within said contents), as the
|
|
* document's schema is required for YAML string output.
|
|
*
|
|
* @param wrapScalars If undefined or `true`, also wraps plain values in
|
|
* `Scalar` objects; if `false` and `value` is not an object, it will be
|
|
* returned directly.
|
|
* @param tag Use to specify the collection type, e.g. `"!!omap"`. Note that
|
|
* this requires the corresponding tag to be available based on the default
|
|
* options. To use a specific document's schema, use `doc.schema.createNode`.
|
|
*/
|
|
export function createNode(
|
|
value: any,
|
|
wrapScalars?: true,
|
|
tag?: string
|
|
): YAMLMap | YAMLSeq | Scalar
|
|
|
|
/**
|
|
* YAML.createNode recursively turns objects into Map and arrays to Seq collections.
|
|
* Its primary use is to enable attaching comments or other metadata to a value,
|
|
* or to otherwise exert more fine-grained control over the stringified output.
|
|
*
|
|
* Doesn't wrap plain values in Scalar objects.
|
|
*/
|
|
export function createNode(
|
|
value: any,
|
|
wrapScalars: false,
|
|
tag?: string
|
|
): YAMLMap | YAMLSeq | string | number | boolean | null
|
|
|
|
/**
|
|
* Parse an input string into a single YAML.Document.
|
|
*/
|
|
export function parseDocument(str: string, options?: Options): Document.Parsed
|
|
|
|
/**
|
|
* Parse the input as a stream of YAML documents.
|
|
*
|
|
* Documents should be separated from each other by `...` or `---` marker lines.
|
|
*/
|
|
export function parseAllDocuments(
|
|
str: string,
|
|
options?: Options
|
|
): Document.Parsed[]
|
|
|
|
/**
|
|
* Parse an input string into JavaScript.
|
|
*
|
|
* Only supports input consisting of a single YAML document; for multi-document
|
|
* support you should use `YAML.parseAllDocuments`. May throw on error, and may
|
|
* log warnings using `console.warn`.
|
|
*
|
|
* @param str A string with YAML formatting.
|
|
* @returns The value will match the type of the root value of the parsed YAML
|
|
* document, so Maps become objects, Sequences arrays, and scalars result in
|
|
* nulls, booleans, numbers and strings.
|
|
*/
|
|
export function parse(str: string, options?: Options): any
|
|
|
|
/**
|
|
* @returns Will always include \n as the last character, as is expected of YAML documents.
|
|
*/
|
|
export function stringify(value: any, options?: Options): string
|