0.12.1

Maintenance release; no functional changes. Full Changelog: 0.12.0...0.12.1

Library Updates

• cats-core 2.8.0 -> 2.10.0
• cats-effect 3.3.13 -> 3.5.2
• fs2-core 3.2.7 -> 3.9.2
• fs2-io 3.2.7 -> 3.9.2
• fs2-data-json 1.4.1 -> 1.9.0
• fs2-data-xml 1.4.1 -> 1.9.0
• jackson-core 2.12.3 -> 2.15.3
• typename 1.0.0 -> 1.1.0

Build Updates

• SBT 1.5.2 -> 1.9.6
• Scala 2.12.16 -> 2.12.18
• Scala 2.13.8 -> 2.13.12
• Scala 3.1.3 -> 3.3.1
• sbt-pgp 2.1.2 -> 2.2.1
• sbt-sonatype 3.9.7 -> 3.9.21

0.12.0

This was a purely-additive feature release, and is binary-compatible with 0.11.0

Additions

• Added and and or methods to Parser[*, Boolean], with && and || operator equivalents

0.11.0

Changes

• JavaxSource.fromInputStream has been split into fromInputStream and fromInputStreamWithCharset
• JavaxSource.fromFile has been split into fromFile and fromFileWithCharset

Bugfix

• JacksonSource.fromString is now reusable as intended

Additions

• Added Source.defer to help construct reusable Sources

0.10.0

This is another refactor release, with two focus areas:

• reduce usage of typeclasses involved with the .parse method
• decouple the library from cats-effect and fs2

The bottom line is that the interfaces for Parser construction remain the same, but the way you run a Parser to consume data is different.

Major Changes

• Removed JavaxSupport and IntoXmlEventReader - use JavaxSource methods instead
• Removed JacksonSupport and IntoJacksonJsonParser - use JacksonSource instead
• Removed Fs2DataSupport (for both XML and JSON) - use Fs2DataSource instead
• Removed ChunkSize
• Removed Parsable - methods formerly using this now accept Source / Iterator / fs2.Stream explicitly
• Refactored Parser#parse - no longer uses Parsable typeclass; two overloads take Iterator[In] and Source[In] respectively.
• Refactored JavaxSource - provides explicit fromX methods returning Source[XmlEvent], no longer provides fs2.Stream constructors
• Refactored JacksonSource - provides explicit fromX methods returning Source[JsonEvent], no longer provides fs2.Stream constructors
• Refactored Fs2DataSource (for both XML and JSON) - provides explicit fromX methods returning Stream[F, XmlEvent] and Stream[F, JsonEvent] respectively
• Refactored XML Fs2DataSource.Middleware; rename to Cleanup, Middleware.default became Cleanup (object), and Middleware.none became NoCleanup
• Moved Parser#parseF to io.dylemma.spac.interop.fs2
• Moved Parser#toPipe to io.dylemma.spac.interop.fs2
• Moved Transformer#toPipe to io.dylemma.spac.interop.fs2
• Added overload for Transformer#transform that takes a Source
• Added Source[A] trait (like an upgraded Iterable adds resource management around its iterator)
• Added Source#toResource and Source#toStream to io.dylemma.spac.interop.fs2
• Added Parser#start for situations where you don't want to consume the entire input all at once
• Added Parser#flatten
• Added JsonSplitter#asNullable

Dependency Updates

• Scala 2.12.10 -> 2.12.16
• Scala 2.13.5 -> 2.13.8
• Scala 3.0.0 -> 3.1.3
• Cats Core 2.6.1 -> 2.8.0
• Cats Effect 3.1.1 -> 3.3.13
• FS2 3.0.3 -> 3.2.7
• FS2-Data 1.0.0-RC3 -> 1.4.1

0.9.2

Add Scala 3 Support

0.9.1

Bugfix release for 0.9

• 52a6c18 - the ContextLocation toString method was inadvertently broken as part of a performance improvement that was made just before releasing 0.9

0.9

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.

0.8

This release addresses concerns raised by #21

• Make XMLResource and JsonResource contravariant
• Ensure InputStreams and Readers not created by *Resource will not be closed by that resource. Responsibility for closing streams should lie with whoever constructed the stream.
• Introduce *Resource for () => T types to allow for easier support for specialized types. Due to the constructor style, Resources created in this way will close the constructed stream.

0.7

This release closes #18 and #22.

• Add support for scala 2.13
• Use SBT version 1.3.3
• Add firstNotNull convenience to JsonSplitter
• Add JsonParser.objectOf[T] to parse a JSON object into Map[String, T]
• Add flatten method to Transformers
• Cleaned up the XMLSplitter.firstOption API (no longer uses the Try type)
• Removed the HandlerFactory abstraction as it was no longer necessary

0.6

Major Changes

• Parser and Consumer have been merged.
  • Parser no longer wraps its results with Try; exceptions will be thrown. Use parser.wrapSafe to emulate old behavior.
• xml-spac has been split into separate modules: spac-core, xml-spac, and json-spac
  • All XML-specific features of Parser and Splitter now exist in XMLParser and XMLSplitter
    • If you were using Parser, you should now use XMLParser.
      • except for Parser.constant
    • If you were using Splitter, you should now use XMLSplitter.
  • New JSON-specific features exist on JsonParser and JsonSplitter
  • The Splitter trait and companion still exist, but only with general-purpose methods
  • The Parser companion now only contains generic parser constructors. For XML or JSON-specific parsers, use the XMLParser or JsonParser objects.
• Removed the homemade Functor implementation, and the FunctorSyntax convenience methods. Possible integration with Cats at a later date.

Minor Changes

• Most of the Consumer/Parser and Transformer convenience constructors have been lower-cased
• ContextMatcher now takes an Elem type parameter (to support matching against JSON and XML contexts)
• The internals of Splitter have some new abstractions that make it easier to create custom splitters
• The new FromHandlerFactor typeclass makes it easier to convert between Parser and Consumer
• Deprecated Splitter#through, renamed it to map
• Changed some of the internal event management classes to better support JSON events/contexts

New Features

• JSON support via json-spac
• Add Transformer#transform for #16
• Splitter now supports flatMap-ing with Transformer (see Example6 for why this is helpful)
• ConsumableLike now exposes an Iterator for pull-style parsing
• Add Parser#orElse to handle varying input formats
• Add Parser#interruptedBy to help with certain followedBy scenarios (see Example7)
• Add Parser#beforeContext as a convenience for Parser#interruptedBy