Documentation and Error Handling

[davisford]

Hi, Thanks for writing the lib. I realize there's already an issue #12 related to docs, but I wanted to echo it and chime in by asking if there is any way to easily detect parse errors. I'm using the lib to serialize file based yaml specs for swagger documentation, but sometimes things silently fail. I noticed the dump function seems to provide no direct error indication, but if you inspect the results, errors seemed to be buried in the object that encountered the error.

For example, a swagger definitions object in my results contained this:

ReceiptHistory: 
      { [Error]
        context: 'while scanning for the next token',
        context_mark: null,
        problem: 'found character ` that cannot start any token',
        problem_mark: [Object],
        note: undefined,
        message: undefined,
        stack: 'while scanning for the next token\nfound character ` that cannot start any token\n  on line 2, column 14\n    at ScannerError.YAMLError (/doc/api/node_modules/yaml-js/lib/errors.js:70:46)\n    at ScannerError.MarkedYAMLError (/doc/api/node_modules/yaml-js/lib/errors.js:90:45)\n    at new ScannerError (/doc/api/node_modules/yaml-js/lib/scanner.js:23:49)\n    at Constructor.Scanner.Scanner.fetch_more_tokens (/doc/api/node_modules/yaml-js/lib/scanner.js:240:13)\n    at Constructor.Scanner.Scanner.check_token (/doc/api/node_modules/yaml-js/lib/scanner.js:115:14)\n    at Constructor.Parser.Parser.parse_block_mapping_value (/doc/api/node_modules/yaml-js/lib/parser.js:446:19)\n    at Constructor.Parser.Parser.check_event (/doc/api/node_modules/yaml-js/lib/parser.js:61:48)\n    at Constructor.Composer.Composer.compose_node (/doc/api/node_modules/yaml-js/lib/composer.js:72:16)\n    at Constructor.Composer.Composer.compose_mapping_node (/doc/api/node_modules/yaml-js/lib/composer.js:145:27)\n    at Constructor.Composer.Composer.compose_node (/doc/api/node_modules/yaml-js/lib/composer.js:91:21)' },

There seems to be no reasonable path to detect an error like this other than dumping the contents to the console and looking for the error, or else navigating programmatically through the whole object tree and looking for an Error.

It would be nice to have the dump function take a function callback(err) { } or return an array of errors that it encountered.

I was going to take a stab at improving the docs or even error-handling, but...I don't have the time / luxury / desire to spend the time with coffeescript (sorry!)

[connec]

Thanks for the issue, but I'm going to close it since this repository is going to be archived. yaml-js has been unmaintained for some time, so it would be best to use something else.