Mercator

Mercator is a macro for automatically constructing evidence that a known type may be used in a for-comprehension, for abstracting over monad-like types with no impact on performance. This allows us to write code against generic type constructors which can assume that they are usable in a for-comprehension, without having the evidence that they are until the application point when the type constructor is known, at which point, Mercator will construct it.

Features

• abstracts over monad-like types
• constructs a monad typeclass instance for any type with flatMap, map and a "point" constructor
• makes intelligent guesses about identifying the "point" constructor for a type
• constructs a functor instance if only map and "point" are available

Getting Started

It is not possible to write code such as,

// does not compile
def increment[F[_]](xs: F[Int]) = for(x <- xs) yield x + 1

because the compiler is not able to enforce the constraint that the type constructor F[_] provides the methods map and flatMap (with the correct signatures) which are necessary for the for-comprehension to compile.

With Mercator, it is possible to demand an implicit instance of Monadic[F] to enforce this constraint. Mercator will automatically instantiate such an instance at the use-site for any type which has the required methods, like so,

import mercator._
def increment[F[_]: Monadic](xs: F[Int]) = for(x <- xs) yield x + 1

The methods flatMap and map will be provided to the instance of F[_] as extension methods, using an implicit value class in the mercator package. This incurs no allocations at runtime, and the performance overhead should be zero or negligible.

Point

An instance of Monadic[F] will generate an implementation of point, which constructs a new instance of the type from a single value. This implementation assumes the existence of an apply method on the type's companion object, and that applying the value to it will produce a result of the correct type.

If this is not the case, Mercator will try to find a unique subtype of F[_] whose companion object has an apply method taking a single value and returning the correct type. In the case of Either or Scalaz's \/, this will do the right thing.

Status

Mercator is classified as fledgling. Propensive defines the following five stability levels for open-source projects:

• embryonic: for experimental or demonstrative purposes only, without guarantee of longevity
• fledgling: of proven utility, seeking contributions, but liable to significant redesigns
• maturescent: major design decisions broady settled, seeking probatory adoption and refinement of designs
• dependable: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version 1.0 or later
• adamantine: proven, reliable and production-ready, with no further breaking changes ever anticipated

Availability

Mercator’s source is available on GitHub, and may be built with Fury by cloning the layer propensive/mercator.

fury layer clone -i propensive/mercator

or imported into an existing layer with,

fury layer import -i propensive/mercator

A binary is available on Maven Central as com.propensive:mercator-core_<scala-version>:0.4.0. This may be added to an sbt build with:

libraryDependencies += "com.propensive" %% "mercator-core" % "0.4.0"

Contributing

Contributors to Mercator are welcome and encouraged. New contributors may like to look for issues marked .

We suggest that all contributors read the Contributing Guide to make the process of contributing to Mercator easier.

Please do not contact project maintainers privately with questions, as other users cannot then benefit from the answers.

Author

Mercator was designed and developed by Jon Pretty, and commercial support and training is available from Propensive OÜ.

License

Mercator is copyright © 2018-20 Jon Pretty & Propensive OÜ, and is made available under the Apache 2.0 License.