index.d.ts 10 KB

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