Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor options #235

Merged
merged 20 commits into from Mar 8, 2021
Merged

Refactor options #235

merged 20 commits into from Mar 8, 2021

Conversation

eemeli
Copy link
Owner

@eemeli eemeli commented Mar 1, 2021

Some prior discussion is found in issue #190.

This does a bunch of stuff that changes (and breaks!) the options used by yaml by moving them closer to where they're actually used:

Drop the keepCstNodes and keepNodeTypes options completely

The earlier parser change has meant that information is retained differently during composition. Effectively, the values of these options are no longer used, so they should be explicitly dropped from the options interfaces to make that clear. The behaviour now is as if { keepCstNodes: false, keepNodeTypes: true } is always set.

This may require some API changes for CST users, as errors also no longer provide a reference to the source CST node, just the original line position. To match an error to a node, you should search for a node that includes the error position in its range.

To discard node type information from the tree, use a visitor:

import { isNode, parseDocument, visit } from 'yaml'

const doc = parseDocument('{ foo: "bar" }')
visit(doc, (key, node) => {
  if (isNode(node)) delete node.type
})

String(doc) === 'foo: bar\n'
Move mapAsMap and maxAliasCount from DocumentOptions to ToJSOptions

The option now needs to be given to the document's toJS() method, rather than being also available on the document constructor and in YAML.defaultOptions. The behaviour of parse() is unaffected.

import { parseDocument } from 'yaml'

-const doc = parseDocument('foo: bar', { mapAsMap: true, maxAliasCount: -1 })
-const js = doc.toJS()
+const doc = parseDocument('foo: bar')
+const js = doc.toJS({ mapAsMap: true, maxAliasCount: -1 })
Move indent, indentSeq & simpleKeys from DocumentOptions to ToStringOptions

These options now need to be given to the document's toString() method, rather than being also available on the document constructor and in YAML.defaultOptions. The behaviour of stringify() is unaffected.

import { parseDocument } from 'yaml'

-const doc = parseDocument('foo: bar', { indent: 4, indentSeq: false })
-const str = doc.toString()
+const doc = parseDocument('foo: bar')
+const str = doc.toString({ indent: 4, indentSeq: false })
Move BigInt option from scalarOptions to ParseOptions

Rather than setting YAML.scalarOptions.int.asBigInt, users should use the intAsBigInt option given to parse functions and constructors.

Drop special options for !!binary

The line width now follows the general lineWidth value and takes indent level into account. !!binary nodes that do not explicitly declare a type will use BLOCK_LITERAL. To set the type of such nodes, use a visitor:

import { visit } from 'yaml'

visit(doc, {
  Scalar(key, value) {
    if (value.tag === 'tag:yaml.org,2002:binary')
      value.type = 'QUOTE_DOUBLE'
  }
})
Move all other scalar options to ToStringOptions

Rather than setting these via YAML.scalarOptions, users should pass them as options given to the stringify() function and the doc.toString() method.

The defaultKeyType option now accepts (and defaults to) null, with which value the defaultStringType also controls implicit key types.

Some of the options are renamed and their structure is flattened:

  • bool.falseStr -> falseStr
  • bool.trueStr -> trueStr
  • null.nullStr -> nullStr
  • str.defaultType -> defaultStringType
  • str.defaultKeyType -> defaultKeyType
  • str.defaultQuoteSingle -> singleQuote
  • str.doubleQuoted.jsonEncoding -> doubleQuotedAsJSON
  • str.doubleQuoted.minMultiLineLength -> doubleQuotedMinMultiLineLength
  • str.fold.lineWidth -> lineWidth
  • str.fold.minContentWidth -> minContentWidth
Refactor doc.setSchema()

The API of doc.setSchema() now requires an explicit version as well as supporting all Schema options. This is required to reduce the dependency on a mutating doc.options object.

-doc.setSchema('json')
+doc.setSchema('1.2', { schema: 'json' })

-doc.options.merge = false
-doc.setSchema('1.1')
+doc.setSchema('1.1', { merge: false })
Drop Document.defaults and doc.getDefaults()

This was effectively a side effect of the doc.setSchema() refactor. The version-specific schema options now need to be set explicitly in function arguments.

Drop scalarOptions

All of the options under this object are now elsewhere.

Drop options from the tag interface

Tag-specific options are now handled for the built-in tags via ParseOptions and ToJSOptions; custom tags should provide their own configuration separately, if any is needed.

Un-document the YAML.defaultOptions export

I'm reeeeally tempted to remove this entirely, as that would remove the last explicitly mutating global state from the library.

Replace doc.directivesEndMarker with doc.directives.marker & directives option

As cleanup, also remove the now-obsolete doc.version value

To now detect if a parsed document included an explicit doc-start marker, use doc.directives.marker === true. To include the marker when stringifying, either set that value to true, or use doc.toString({ directives: true ). To explicitly leave out directives and the doc-start marker from the output, use doc.toString({ directives: false ).

eemeli added 19 commits March 7, 2021 12:45
BREAKING CHANGE: The earlier parser change has meant that information is
retained differently during composition. Effectively, the values of
these options are no longer used, so they should be explicitly dropped
from the options interfaces to make that clear. The behaviour now is as
if `{ keepCstNodes: false, keepNodeTypes: true }` is always set.

This may require some API changes for CST users, as errors also no
longer provide a reference to the source CST node, just the original
line position. To match an error to a node, you should search for a node
that includes the error position in its range.

To discard node type information from the tree, use a visitor:

    import { isNode, parseDocument, visit } from 'yaml'

    const doc = parseDocument('{ foo: "bar" }')
    visit(doc, (key, node) => {
      if (isNode(node)) delete node.type
    })

    String(doc) === 'foo: bar\n'
BREAKING CHANGE: The option now needs to be given to the document's
toJS() method, rather than being also available on the document
constructor and in YAML.defaultOptions. The behaviour of parse() is
unaffected.

```diff
 import { parseDocument } from 'yaml'

-const doc = parseDocument('foo: bar', { mapAsMap: true })
-const js = doc.toJS()
+const doc = parseDocument('foo: bar')
+const js = doc.toJS({ mapAsMap: true })
```
BREAKING CHANGE: The option now needs to be given to the document's
toJS() method, rather than being also available on the document
constructor and in YAML.defaultOptions. The behaviour of parse() is
unaffected.

```diff
 import { parseDocument } from 'yaml'

-const doc = parseDocument('foo: bar', { maxAliasCount: -1 })
-const js = doc.toJS()
+const doc = parseDocument('foo: bar')
+const js = doc.toJS({ maxAliasCount: -1 })
```
BREAKING CHANGE: These options now need to be given to the document's
toString() method, rather than being also available on the document
constructor and in YAML.defaultOptions. The behaviour of stringify()
is unaffected.

```diff
 import { parseDocument } from 'yaml'

-const doc = parseDocument('foo: bar', { indent: 4, indentSeq: false })
-const str = doc.toString()
+const doc = parseDocument('foo: bar')
+const str = doc.toString({ indent: 4, indentSeq: false })
```
BREAKING CHANGE: The new API of doc.setSchema(), now requiring an
explicit version as well as supporting all Schema options. This is
required to reduce the dependency on a mutating doc.options object.

-doc.setSchema('json')
+doc.setSchema('1.2', { schema: 'json' })

-doc.options.merge = false
-doc.setSchema('1.1')
+doc.setSchema('1.1', { merge: false })

As a side effect of these changes, the Document.defaults object is
removed, along with the doc.getDefaults() method. The version-specific
schema options now need to be set explicitly in function arguments.
BREAKING CHANGE: Rather than setting `YAML.scalarOptions.int.asBigInt`,
users should use the `intAsBigInt` option given to parse functions and
constructors.
…ptions

BREAKING CHANGE: Rather than setting these via `scalarOptions.bool`
and `scalarOptions.null`, users should pass them as options given
to the stringify() function and the doc.toString() method.
…ptions

BREAKING CHANGE: Rather than setting these via `scalarOptions.str.fold`,
users should pass them as options given to the stringify() function and
the doc.toString() method.
BREAKING CHANGE: The line width now follows the general `lineWidth`
value and takes indent level into account. `!!binary` nodes that do
not explicitly declare a `type` will use `BLOCK_LITERAL`. To set the
type of such nodes, use a visitor:

    import { visit } from 'yaml'

    visit(doc, {
      Scalar(key, value) {
        if (value.tag === 'tag:yaml.org,2002:binary')
          value.type = 'QUOTE_DOUBLE'
      }
    })
The options are also renamed:
- doubleQuoted.jsonEncoding -> doubleQuotedAsJSON
- doubleQuoted.minMultiLineLength -> doubleQuotedMinMultiLineLength

BREAKING CHANGE: Rather than setting these via
`scalarOptions.str.doubleQuoted`, users should pass them as options
given to the stringify() function and the doc.toString() method.
The `defaultKeyType` option now accepts (and defaults to) `null`, with
which value the `defaultStringType` also controls implicit key types.

Some of the options are renamed:
- defaultType -> defaultStringType
- defaultKeyType -> defaultKeyType (unchanged)
- defaultQuoteSingle -> singleQuote

BREAKING CHANGE: Rather than setting these via `scalarOptions.str`,
users should pass them as options given to the stringify() function
and the doc.toString() method.
Additionally, un-document the YAML.defaultOptions export.

BREAKING CHANGE: These are no longer used, as their functionality has
been moved to ParseOptions and ToStringOptions.
…es option

As cleanup, also remove the now-obsolete doc.version value

BREAKING CHANGE: To now detect if a parsed document included an explicit
doc-start marker, use `doc.directives.marker === true`. To include the
marker when stringifying, either set that value to true, or use
`doc.toString({ directives: true )`. To explicitly leave out directives
and the doc-start marker from the output, use
`doc.toString({ directives: false )`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant