Module documentation for 1.0.9.0

mono-traversable

Type classes for mapping, folding, and traversing monomorphic and polymorphic containers.
Haskell is good at operating over polymorphic containers such as a list [a].
A monomorphic container is one such as Text which has a type Text that does not expose a type variable for the underlying characters.

Using Typeclasses

There are 2 use cases for mono-traversable: application authors and library authors.

Library authors

As a library author, if you want to allow a user to pass in a Text or a String,
then you need to expose an API with a mono-traversable typeclass.
You should think twice about using mono-traversable though because

Using Typeclasses makes type inference more difficult. It is usually better to force the user to give a Text. Another option is to just have multiple APIs.

If you are operating on polymorphic structures in which the normal typeclasses suffice, you should just use them from base. On the other hand, even if you are using polymorphic containers you may want to leverage IsSequence or MinLen.

Application authors

As an application author, you should consider using classy-prelude, which leans heavily on mono-traversable.

When writing your own function signatures, you should default to making them concrete: if you are actually using a list, then make your function take a list rather than an IsSequence. This will improve type inference, error messages, and make your code easier to understand. When you decide to use a Vector instead of a list, change the type signature to use a Vector. When you actually need a function to both accept a Vector and a list, it is easy to change the function signature to the more abstract typeclasses that you require.

Standard Typeclasses

in the upcoming GHC 7.10, using Functor, Foldable, and Traversable will become common-place. This means that rather than using List.map, Vector.map, etc, the map from the prelude will work on all data types that are a Functor. Of course, you can already do this now using fmap.

For a Haskeller, it is important to understand Functor, Applicative, Monad, Foldable, and Monoid: these are encountered in every day code. For mono-traversable, it is most important to understand Foldable.

mono-traversable Typeclasses

MonoFunctor

Element is a type family. This tells the compiler to substitute Char for Element Text.
We can create this rule for every monomorphic container we want to operate on such as Text
And we can also create it for a polymorphic container.

The list definition was able to default to using fmap so no body was needed.

MonoFoldable

Same as Foldable, but also operates over monomorphic containers.

MonoFoldable is the heart of the power of mono-traversable (and arguably the package should be named mono-foldable) because anything that can be done with Foldable can be done with MonoFoldable.
The reason why is that a monomorphic container can never change its type.
So omap is a restricted fmap.
However, folding generates a new structure, so we have no such concerns.
In the classy-prelude package, map is set to fmap and omap must be used separately.
However, foldMap is set to just use the mono-traversable version: ofoldMap

MonoPointed abstracts over the concept of a singleton. For any Applicative, opoint is the same as pure from Applicative. Since mono-traversable did not bother with a MonoApplicative typeclass, we added MonoPointed to still have the functionality of pure.

MonoTraversable

MonoTraversable is Traversable for monomorphic containers, just as
MonoFunctor is Functor for monomorphic containers.

The laws state that an IsSequence is a list-like (sequential) structure.

an IsSequence is not just something that can be converted to a list (MonoFoldable), but something that can be created from a list.

Converting to and from a list does not change the IsSequence, and it doesn’t even change the IsSequence if you do the conversions on chunks of the IsSequence.

SemiSequence is required by IsSequence. It is conceptually the same as IsSequence, but contains operations that can also be used on a NonEmpty or a MinLen (which are SemiGroups) because they do not reduce the number of elements in the sequence.

Textual functions are always safe to use with Unicode (it is possible to misuse other functions that operate on individual characters).

MinLen

Did you notice minimumEx and maximumEx from above? Ex stands for ‘Exception’.
An exception will occur if you call minimumEx on an empty list.
MinLen is a tool to guarantee that this never occurs, and instead to prove that there are one or more elements in your list.

The minimum function exposed from MinLen is very similar to minimumEx, but has a MinLen wrapper that ensures it will never throw an exception.
MinLen is a newtype with a phantom type that contains information about the minimum number of elements we know are in the structure. That is done through type-level Peano numbers.

What do we know about the input to minimum? If nat is Zero, then it reduces to MinLen (Succ Zero) mono. Succ means successor, and the successor of 0 is 1, so the data structure has a minimum length of 1.

Now you are ready to use CustomType a with the functions defined in this package.

Note: if your type is a monomorphic container without the proper typeclasses, then you will have to provide an implementation rather than using the default. However, this should be fairly simple, as can be seen in the code

mono-traversable versus lens Traversal

lens is a library with a lot of functionality covering a variety of patterns. One piece of functionality it exposes is Fold and Traversal which can also be used to deal with monomorphic containers.

You could prefer mono-traversable to using this part of lens because

Familiar API - If you know Foldable, you can use MonoFoldable just as easily

mono-traversable’s typeclass based approach means many methods are included in the class but can be given specialised optimized implementations

You don’t explicitly pass around the Traversal

The last point is also a point of inflexibility and points to a use case where you could prefer using a lens Traversal. mono-traversable treats ByteString as a sequence of bytes. If you want to treat it as both bytes and characters, mono-traversable would require a newtype wrapper around ByteString, whereas a lens Traversal would use a different traversal function.

mono-traversable is only an alternative for Fold and Traversal, not for Lens, Prism, Iso, Getter, Setter, Review, or Equality.