Change in SYAML 1.0.281

Released Aug 19, 2020.

What's new?

• Improved document errors detection
• Adjusted multi-documents handling
• Interfaces updated for version 1.0

Improved document errors detection

Before this version, when a syntax error was found (for example a missing ":" after a key), the following lines were considered part of the error & only a few cases were taken into account to "recover" from that error section.
In some cases, this means that a simple syntax error affects other sections of the document that are correct.
In this version, this logic has been improved, so now is able to check line by line searching for other keys or indentation changes that enable the parser to continue processing the document regardless of the syntax error.

This error recovery works according to the following criteria:

map:
	key
	map: value

"key" will be treated as an error and "map: value" will be the only entry of this map

map:
	key
	- value

"key" will be treated as an error and "-value" will be the sequence

map:
	key: value
	invalid
	key2: value

"invalid" will be treated as an error. The will have the entries

map:
	key: value
	 invalid: value
	key2: value

" invalid: value" will not be parsed, as has an invalid indentation

Breaking changes

If you were using our pre-release version, take in mind that in order to improve the recovery logic, we 've had to implement some breaking changes

org.yaml.parser.YamlParser changes:

• .parser(): will remain the same, returning more information if there is an error.
• .document(): Before, this method used to invoke .parser() and then return the first document. Now, it executes the parsing in a "single document" context, so multi-documents structures like "---" or "..." will be treated as an error.
  example:

  key:
  ---
  key2
  

  Will return an error over "---" and a single document with a map that contains two entries.

org.yaml.lexer.YamlLexer changes:

• .initialize() is no longer called at instantiation. You have to call it specifically to start filling the token queue. If you try to request a token data or advance before calling the initialization, you can have an exception.
• Optionally, you can pass a context to the initialization logic:
  ** StreamLexerContext: default context for multi-documents. Same behavior than before.
  ** SingleDocumentLexerContext: iterate the char sequence looking for single documents tokens. Any multi-document token will be treated as an error.

More information about your document errors

Taking aside the breaking changes, as the new recovery logic is more specific when you parse a document/documents with errors, it's likely that a bigger AST or more errors than before will be returned (as more tokens are parsed)
For instance, if you have:

key: value
error
{...300 more keys}

All text after "error" used to be ignored, but now is parsed! so the AST will be 300 entries bigger.
On the other hand, if you have:

key: value
error
key2: value
another error
key3: value

With 0.7.x you had only one key and one error. Starting with 1.0 you will have 3 entries, and 2 errors (one new error)

Note: if you are implementing this version & encounter new errors:

• First, check that you are using the parse/document method properly. If you have multi-documents files, you need to separate those or call .documents()
• Then check if the new errors are consequences of more text being parsed (the document were invalid previously)