multiwalk: Traverse data types via generics, acting on multiple types simultaneously.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

This library provides functionality for traversing data types recursively, acting on multiple types during the same traversal. In spirit, it is similar to the Walk type class from Pandoc.Walk, but generalizes it by allowing multiple types to be targeted by the traversal. In general, it only requires an Applicative constraint on the action, making it suitable for situations where you don't have a Monad.


[Skip to Readme]

Properties

Versions 0.3.0.0, 0.3.0.1
Change log CHANGELOG.md
Dependencies base (>=4.16 && <4.19) [details]
License GPL-3.0-or-later
Author Lucas V. R.
Maintainer @lucasvr:matrix.org
Category Control
Source repo head: git clone https://github.com/lucasvreis/multiwalk
Uploaded by lvreis at 2023-07-17T04:59:41Z

Modules

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for multiwalk-0.3.0.0

[back to package description]

MultiWalk

This library provides functionality for traversing data types recursively, acting on multiple types during the same traversal. In spirit, it is similar to the Walk type class from Pandoc.Walk, but generalizes it by allowing multiple types to be targeted by the traversal. Also, by default it only requires an Applicative constraint on the action, making it suitable for situations where you don't have a Monad (for instance, traversing within a composition of monads).

Say, for instance, you want to query all code snippets from a Pandoc document, including both Inline and Block ones, such that the list of results is in the same order as they appear in the document. There is no way to do this with Pandoc's Walk type class, because it only supports querying or walking with one type at once. With MultiWalk you are able to do this with a single query function that targets both types, and it'll look something like this:

multi :: Block -> [Text]
multi = buildMultiQ @PTag $ \sub list ->
    list ?> blks sub
         ?> inls sub
  where
    blks _ (CodeBlock _ c) = [c]
    blks f x = f x
    inls _ (Code _ c) = [c]
    inls f x = f x

(note, however, that this library does not ship with default instances for Pandoc, so you will have to define them yourself. You can find a basic Pandoc instance for reference, and the function above, in Benchmark.hs inside the test directory.)

Another use case is when you want to modify a data type, perhaps targeting multiple subtypes, and you want to do that inside a functor that is Applicative but not a Monad. Such functors may sound unusual, but one of the interesting places where they appear are in composition of monads, which need not be a monad itself.

You can find a use of such monad compositions in my other library here. It's used for resolving cross-references inside documents inside the functor Compose M F, where M is a state monad which holds the links it has found so far, and F is a reader which receives the final, future state (that will only be ready at the end of the computation). In this way I can walk across the document only once, registering and applying cross references at the same time. Note that this is composition is semantically different from using monad transformers, because they would require the reader state to be supplied before the final state is available.