deepseq-bounded 0.5 → 0.6 (and plans for 0.7)

This document accompanies the release of deepseq-bounded-0.6.0.0, which makes some API breaking changes. Only changes which are API breaking are discussed here. (Refer to the changelog and homepage documents for more information, in addition to more specific documents cited below.)

Nobody seems to care at the moment (just as well in flux of nascency), but I feel somehow morally obligated to provide this library, and ill-documented software is shoddy, how ever-miraculously the fancy types fit together. `^Ȣ(

API breaking changes consist of module renamings, pattern DSL syntax tweaks, and PatNode data type changes. Also there are some new flags, and the roles of certain flags have changed slightly. Please refer to the deepseq-bounded.cabal package description for flag documentation, including remarks about changes and deprecation.

There is a flag (NEW_IMPROVED_PATTERN_GRAMMAR, True by default) which, set to False, will restore the old pattern syntax of version 0.5.*, while still allowing you to enjoy bug fixes and code improvements since version 0.5.5, and continuing as version 0.6 progresses towards 0.7.

However, in the version 0.7 release this compatibility flag will likely be removed, so please try to avoid reliance on the flags characterised as deprecated...

Finally a mention is in order, that at least fifteen new modules were necessary to organise the support for both old and new grammars and PatNode definitions. It seems I've managed not to expose any in the API however! (Wasn't the case in the first draft of this paragraph; come to think of it, it was this paragraph that spurred me to un-expose the three that were still exposed...). These transient internal modules will be gone in 0.7.

API breaking changes in 0.5.5 -> 0.6.0.0

• Module renamings (all are prefixed Control.DeepSeq.Bounded):
  • Generics → Generic
  • (and Generics.* → Generic.*)
  • PatAlg → PatUtil  (also  isSubPatOf → subPat)
• Changed the pattern grammar considerably, for a number of benefits. Refer to this document for details of the old and new grammars, and some discussion.
• Changed PatNode (compare version 5 PatNode) so that constructors all take a single parameter of (new) type PatNodeAttrs. This simplified the PatNode type itself, which is more uniform, and has fewer constructors (and will have even fewer by version 0.7).

Related changes planned for 0.7.0.0 (ETA early March)

• The backwards compatibility flag NEW_IMPROVED_PATTERN_GRAMMAR will be removed, and only the new grammar will remain available.
• Also, the module structure will become simpler in consequence. At present, there are at lest fifteen extra modules, just to organise the support for both old and new grammars and PatNode definitions.
• The flag PARALLELISM_EXPERIMENT is only used in the old grammar code, and will be removed as well (USE_PAR_PATNODE is the equivalent in the new grammar, along with a half dozen other new capabilities).
• Type-constrained PatNode's, and the type-reflective NFDataPDyn facilities, will become stabilised -- at present, these are quite experimental, and haven't recevied much attention because seqaid provides a more powerful approach. But if the features are to stay in deepseq-bounded at all, they should be finished properly...
• In particular, the type-constrained PatNode's TI, TR, TN and TW will be obsoleted, with type constraints being handled just like any other attribute (PatNodeAttrs) of the PatNode. The urge to do this will probably be the main push bumping to 0.7, but the refactoring is a big one and I don't want to rush it for 0.6 (which already feels overdue to me).
• As of 0.6.1.0, we now have an H98 parser for the new grammar. Also, 0.6.0.*, if built with HASKELL98_FRAGMENT True, lacks pattern DSL facilities (except showPat). This is because attoparsec is not H98. There will be an H98 alternative parser again soon, probably by version 0.6.1.0.

There will be other changes for 0.7 (probably a few API breaking), but whatever they will be, they're probably independent of the changes we're focused on for the bump 0.5 → 0.6. Possibly this document will be evolved to cover those changes too, as well as non-API-breaking changes that are ongoing...