-
-
Notifications
You must be signed in to change notification settings - Fork 106
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
Refactor options #235
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…CreateNodeOptions, ToJSOptions
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'
…n } from interfaces
This is a workaround for microsoft/TypeScript#15300
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 )`.
This was referenced Mar 15, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
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 inYAML.defaultOptions
. The behaviour ofparse()
is unaffected.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 inYAML.defaultOptions
. The behaviour ofstringify()
is unaffected.Move BigInt option from scalarOptions to ParseOptions
Rather than setting
YAML.scalarOptions.int.asBigInt
, users should use theintAsBigInt
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 atype
will useBLOCK_LITERAL
. To set the type of such nodes, use a visitor:Move all other scalar options to ToStringOptions
Rather than setting these via
YAML.scalarOptions
, users should pass them as options given to thestringify()
function and thedoc.toString()
method.The
defaultKeyType
option now accepts (and defaults to)null
, with which value thedefaultStringType
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 explicitversion
as well as supporting all Schema options. This is required to reduce the dependency on a mutatingdoc.options
object.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
valueTo 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 usedoc.toString({ directives: true )
. To explicitly leave out directives and the doc-start marker from the output, usedoc.toString({ directives: false )
.