Skip to content

0.9
Compare
Choose a tag to compare
@dylemma dylemma released this 09 May 22:09
· 34 commits to main since this release
0.9
5b352de

This is a big one! See here for a full list of issues and PRs related to this release, but I'll point out the highlights:

Better Error Handling (#14)

In previous versions of SPaC, it was pretty difficult to tell exactly what was going wrong if a complicated parser crashed. Most of the time it was due to some optional attribute/element being treated as mandatory, but the exceptions thrown when that happened didn't do a good job of informing you about what was missing, from where, and which part of your parser wanted it.

This release introduces SpacException, which comes with a special "Spac Trace" (I couldn't resist the pun on "Stack Trace"), where the normal StackTraceElements are replaced with SpacTraceElements which will provide useful debug information, like:

io.dylemma.spac.SpacException$MissingFirstException: Parser context ended before the first String could be found.
        at Input(</data>) - {line: 11, col: 14, offset: 230}                                                     
        at Splitter(elem(data) \ elem(bar)) - ErrorHandlingTest.scala:32                                         
        at Compound Parser member 3 of 3                                                                         
        at InputContext(<data id="123">) - {line: 8, col: 22, offset: 151}                                       
        at InputContext(<thing>) - {line: 2, col: 11, offset: 18}                                                
        at InputContext(<root>) - {line: 1, col: 7, offset: 6}                                                   
        at Splitter(elem(root) \ elem(thing) \ elem(data)) - ErrorHandlingTest.scala:44                          
        at parse - ErrorHandlingTest.scala:60

(see the linked issue for the raw XML and associated Parser that caused this exception)

Integration with Cats and Fs2 (#27)

SPaC now comes with a built-in integration with Cats and Fs2. Some cool things come from that:

  • There's an Applicative[Parser[In, *]], which means you can use Cats' mapN method to combine multiple parsers
  • Parser and Transformer can both be converted to an fs2 Pipe
  • Parser gains a parseF method that suspends the parser handler logic in an F[_] effect like cats.effect.IO

Support for Multiple Parser Backends (#27)

In previous versions of SPaC, XMLParser was implemented in terms of javax.xml.stream.event.XMLEvent, meaning that all of the underlying XML parsing logic was done by classes provided by the Java standard library. Similarly. JsonParser was implemented in a way that only allowed for the Jackson JSON library to be used as the underlying parser.

This release introduces the concept of a "parser backend", allowing you to choose how you want to obtain your XML/JSON data.
You use a specific import to select your backend, and SPaC will use that backend to create the underlying event stream, and convert that stream to one of the event models defined in xml-spac or json-spac as appropriate.

The Javax and Jackson logic is still available via their own respective imports, but this release also introduces support for fs2-data to be used as the parser backend.

Migration Guide

There were a handful of source-breaking changes made in this release. See the wiki for a hopefully-complete migration guide.

Assets 2
Loading