Cats Documentation

A semigroup is an algebraic structure with an associative binary operation (mappend). Most of the builtin collections form a semigroup because their associative binary operation is analogous to Clojure’s into.

Given that the values it contains form a Semigroup, we can mappend multiple Maybe values.

A Monoid is a Semigroup with an identity element (mempty). For the collection types the mempty function is analogous to Clojure’s empty.

Given that the values it contains form a Semigroup, we can mappend multiple Maybe, with Nothing being the identity element.

Let’s dive into the functor. The Functor represents some sort of "computational context", and the abstraction consists of one unique function: fmap.

The higher-order function fmap takes a plain function as the first parameter and a value wrapped in a functor context as the second parameter. It extracts the inner value, applies the function to it and returns the result wrapped in same type as the second parameter.

But what is the functor context? It sounds more complex than it is. A Functor wrapper is any type that acts as "Box" and implements the Context and Functor protocols.

The just function is a constructor of the Just type that is part of the Maybe monad.

Let’s see one example of using fmap over a just instance:

The Maybe type also has another constructor: nothing. It represents the absence of a value. It is a safe substitute for nil and may represent failure.

Let’s see what happens if we perform the same operation as the previous example over a nothing instance:

Oh, awesome, instead of raising a NullPointerException, it just returns nothing. Another advantage of using the functor abstraction, is that it always returns a result of the same type as its second argument.

Let’s see an example of applying fmap over a Clojure vector:

The main difference compared to the previous example with Clojure’s map function, is that map returns lazy seqs no matter what collection we pass to it:

But why can we pass vectors to the fmap function? Because some Clojure container types like vectors, lists and sets, also implement the functor abstraction. See the section on built-in types for more information.

Let’s continue with applicative functors. The Applicative Functor represents some sort of "computational context" like a plain Functor, but with the ability to execute a function wrapped in the same context.

The Applicative Functor abstraction consists of two functions: fapply and pure.

The use case for Applicative Functors is roughly the same as for plain Functors: safe evaluation of some computation in a context.

Let’s see an example to better understand the differences between functor and applicative functor:

Imagine you have some factory function that, depending on the language, returns a greeter function, and you only support a few languages.

Now, before using the resulting greeter you should always defensively check if the returned greeter is a valid function or a nil value.

Let’s convert this factory to use the Maybe type:

As you can see, this version of the factory differs only slightly from the original implementation. And this tiny change gives you a new superpower: you can apply the returned greeter to any value without a defensive nil check:

Moreover, the applicative functor comes with the pure function, which allows you to put some value in side-effect-free context of the current type.

Examples:

If you do not understand the purpose of the pure function, the next sections should clarify its purpose.

The Foldable is a generic abstraction for data structures that can be folded. It consists mainly on two functions: foldl and foldr. foldl is also known as reduce or inject in other mainstream programming languages.

Both function have an identical signature and differ in how they traverse the data structure. Let’s look at a little example using foldl:

You can observe that foldl is identical to the clojure reduce function:

And the same operation can be done using foldr:

The main difference between foldl and reduce is that foldl has a fixed arity so all parameters are mandatory and foldl is a generic abstraction that can work with other types apart from collections.

As we said previously, the foldl and foldr differ mainly on how they traverse the data structure. Then, for understanding better how they work internally, let’s see a graphical representation of the foldl execution model:

In contrast to the foldr internal execution model that looks like that:

In languages with strict argument evaluation, foldr does not have many applications because when the data structure to fold grows it tends to consume all the stack (causing the well known stack overflow). In case of Clojure, the unique obvious case of using foldr is for small datastructures.

The Foldable abstraction is already implemented for Clojure vectors, lazy seqs and ranges plus the cats maybe, either and validation types. Let see an example how it behaves with maybe:

It there also other fold functions that are implemented in terms of the basic foldl or foldr that can be foldm and foldmap. At this moment, cats comes only with foldm.

The foldm function in analgous to the foldl in terms of how it does the fold operation, with the difference that is aware of the monad context. Or in other terms, it works with reducing function that return monad types.

Let see an example:

The Traversable is a generic abstraction for data structures that can be traversed from left to right, running an Applicative action for each element. Traversables must also be Functors and Foldables.

Note that, since Traversables use the Applicative’s pure operation, the context of the applicative must be set when using the traverse function.

Let’s look at an example: we have a vector with numbers that we want to map to a Maybe value, and we want to aggregate the result in a Maybe. If any of the actions fails (is Nothing) the resulting aggregate will be Nothing, but if all succeed we preserve the vector’s structure inside a Just value.

First of all, we define the function that will transform a number to a Maybe. Our function will wrap the value in a Just if it’s even and in a Nothing if it’s not:

Now that we have a function that maps a value to the Maybe Applicative, we can traverse a vector of numbers and aggregate a Maybe value. The applicatives will be evaluated from left to right using the applicative’s fapply.

Monads are the most discussed programming concept to come from category theory. Like functors and applicatives, monads deal with data in contexts.

Additionally, monads can also transform contexts by unwrapping data, applying functions to it and putting new values in a completely different context.

The monad abstraction consists of two functions: bind and return

As you can see, bind works much like a Functor but with inverted arguments. The main difference is that in a monad, the function is responsible for wrapping a returned value in a context.

One of the key features of the bind function is that any computation executed within the context of bind (monad) knows the context type implicitly. With this, if you apply some computation over some monadic value and you want to return the result in the same container context but don’t know what that container is, you can use return or pure functions:

The return or pure functions, when called with one argument, try to use the dynamic scope context value that’s set internally by the bind function. Therefore, you can’t use them with one argument outside of a bind context.

We now can compose any number of computations using monad bind functions. But observe what happens when the number of computations increases:

This can quickly lead to callback hell. To solve this, cats comes with a powerful macro: mlet

Some monads also have the notion of an identity element analogous to that of Monoid. When calling bind on a identity element for a monad, the same value is returned. This means that whenever we encounter the identity element in a monadic composition it will short-circuit.

For the already familiar Maybe type the identity element is Nothing:

Having an identity element we can make a monadic composition short-circuit using a predicate:

As you can see in the above example the predicate (= a 2) returns either a monadic value (m/return nil) or the identity value for the maybe monad. This can be captured in a function, which is available in cats.core namespace:

The above example could be rewritten as:

Or, using mlet:

MonadPlus is a complementary abstraction for Monads that support an associative binary operation, analogous to that of a Semigroup. If the monad implements the MonadZero and MonadPlus protocols it forms a monoid.

For the Maybe type, mplus acts similarly to a logical OR that treats Nothing values as falsey.

This is one of the two most used monad types (also known as Optional in other programming languages).

The Maybe monad represents encapsulation of an optional value; e.g. it is used as the return type of functions which may or may not return a meaningful value when they are applied. It consists of either an empty constructor (called None or Nothing), or a constructor encapsulating the original data type A (e.g. Just A or Some A).

cats, implements two types:

There are other useful functions for working with maybe monad types in the same namespace. See the API documentation for a full list of them. But here we will explain a little relevant subset of them.

We mentioned above that fmap extracts the value from a functor context. You will also want to extract values wrapped by just and you can do that with from-maybe.

As we said previously, the Just or Nothing instances act like wrappers and in some circumstances you will want extract the plain value from them. cats offers the from-maybe function for that.

The from-maybe function is a specialized version of a more generic one: cats.core/extract. The generic version is a polymorphic function and will also work with different types of different monads.

For interoperability with Clojure and ClojureScript’s IDeref abstraction, maybe values are derrefable.

Either is another type that represents a result of a computation, but (in contrast with maybe) it can return some data with a failed computation result.

In cats it has two constructors:

Like Maybe, Either values can be dereferenced returning the value they contain.

Also known as the Try monad, as popularized by Scala.

It represents a computation that may either result in an exception or return a successfully computed value. Is very similar to the Either monad, but is semantically different.

It consists of two types: Success and Failure. The Success type is a simple wrapper, like Right of the Either monad. But the Failure type is slightly different from Left, because it always wraps an instance of Throwable (or any value in cljs since you can throw arbitrary values in the JavaScript host).

The most common use case of this monad is to wrap third party libraries that use standard Exception based error handling. Under normal circumstances, however, you should use Either instead.

It is an analogue of the try-catch block: it replaces try-catch’s stack-based error handling with heap-based error handling. Instead of having an exception thrown and having to deal with it immediately in the same thread, it disconnects the error handling and recovery.

cats comes with other syntactic sugar macros: try-or-else that returns a default value if a computation fails, and try-or-recover that lets you handle the return value when executing a function with the exception as first parameter.

The types defined for the Exception monad (Success and Failure) also implement the Clojure IDeref interface, which allows library development using monadic composition without forcing a user of that library to use or understand monads.

That is because when you dereference the failure instance, it will reraise the enclosed exception.

Some of the abstractions in cats are implemented for built-in types but you can’t use them directly. First, you must load the cats.builtin namespace:

The mlet syntactic abstraction intends to facilitate the composition of monadic operations.

If you’ve followed along with the documentation you’ve seen many examples of its usage already, let’s see what can mlet do. First of all, mlet turns this let-like bindings:

into a chain of calls to bind:

That makes a lot more natural to write code that uses monads and gives a very familiar let like syntax abstraction that makes the clojure code that uses monads less "strange".

If you are coming from Haskell, mlet is mostly analogous to the do notation.

Since the bindings in the mlet macro run the monadic effects of the right-hand values we cannot just put any value in there and expect to be bound to its left symbol. For cases where we want the regular behavior of let we can inline a :let clause, just like with Clojure’s for:

mlet has support for using guards using a :when clause, analogous to the one used in for. We can filter out values using bind with mlet and :when like the following:

Any monadic type that implements MonadZero can be combined with guards inside mlet bindings. Here is an example with vectors:

One limitation of monadic bind is that all the steps are strictly sequential and happen one at a time. This piece of code illustrates the usage of monadic bind:

In the first call to bind, (just 1) and the anonymous function will be evaluated. The call of the anonymous function performed by the first bind will cause the evaluation of the (just 41) and the next anonymous function, which will be also called to create the final result. Note that (just 1) and (just 41) are independent and thus could be evaluated at the same time.

Here is the mlet version for reference and clarity:

Now let’s see the equivalent using alet:

Note that no return is used, this is because the alet body runs inside the applicative context with fapply. This is roughly what alet desugars to:

Note that now (just 1) and (just 41) are evaluated at the same time. This use of fapply can be called "applicative bind" and in some cases is more efficient than monadic bind. Furthermore, the alet macro splits the bindings into batches that have dependencies only in previous values and evaluates all applicative values in the batch at the same time.

This makes no difference at all for Maybe, but applicatives that have latency in their calculations (for example promises that do an async computation) get a pretty good evaluation strategy, which can minimize overall latency. In the next examples we use the promesa clj/cljs library for emulate asynchronous behavior:

Another example for illustrating dependencies between batches:

The first combinator that cats provides is a curry macro. Given a function, it can convert it to a curried versions of itself. The generated function will accept parameters until all the expected parameters are given.

Let’s see some examples of a curried function in action:

As you can see above, since the original add has a single arity (3) and is fixed (i.e. it doesn’t accept a variable number of arguments), the curry macro was able to generate a curried function with the correct number of parameters.

This doesn’t mean that functions with multiple arities or variadic arguments can’t be curried but an arity for the curried function must be given:

Curried functions are very useful in combination with the applicative’s fapply operation, since we can curry a function and use applicatives for building up results with context-specific effects.

The lift-m macro is a combinator for promoting functions that work on regular values to work on monadic values instead. It uses the monad’s bind operation under the hood and, like curry, can be used without specifying arity if the function we are lifting has a fixed and a single arity:

Like with curry, we must provide an arity in case we are lifting a function that has multiple arities or is variadic:

Note that you can combine both curry and lift-m to get curried functions that work on monadic types using the curry-lift-m macro. The arity is mandatory when using this macro:

Status: Experimental

The cats.labs.test namespace implements monad and applicative instances for generators, which lets you use the cats.core/alet and cats.core/mlet macros for writing generators:

Apart from that, the namespace contains multiple functions for generating test.check properties that verify the laws of Semigroup, Monoid, Functor, Applicative, Monad, MonadZero and MonadPlus.

The implementation of cats' abstractions are tested using generative testing and the cats.labs.test property generation functions.

Status: Experimental

This namespace exposes the ability to use the core.async channel as monadic type and in consequence use it in mlet or alet macros.

Before use it, you should add core.async to your dependencies:

Now, let see some code. This will allow you understand how it can be used and why this integration between cats and core.async matters. At first step we will go to define a function that emulates whatever asynchronous task, that for our case it’s consist in a just sleep operation:

Now, instead of using the go macro, just use a let like bindings with the help of the mlet macro for bind values to asyncrhonous calls:

Here we can observe few things:

The main difference with the default clojure let, is that the bindings are already plain values (not channels). The take! operation is already performed automatically by the mlet. This kind of behavior will make you fully asynchronous code looks like synchronous code.

But, cats also comes with alet that has identical aspect to the previously used mlet macro, but it has some advantages over it. Let see an example:

And here we can observe few things:

The alet is a powerful macro that analyzes the dependencies between bindings and executes the expressions in batches resultin in a very atractive feature for asynchronous calls.

Here an other examples that shows in a clearly way how the batches are executed:

Status: Experimental

This namespace exposes the ability to use the manifold deferred as monadic type and in consequence use it in mlet or alet macros.

Before use it, you should add manifold to your dependencies:

Now, let see some code. This will allow you understand how it can be used and why this integration between cats and manifold matters. At first step we will go to define a function that emulates whatever asynchronous task, that for our case it’s consist in a just sleep operation:

For demostration purposes, let’s define a function that emulates the asyncrhonous call:

Now, the manifold deferreds can participate in the monad/applicative abstractions using mlet and alet respectivelly.

If you are familiar with manifold’s let-flow macro, the cats alet serves for almost identical purpose, with difference that alet is defined as generic abstraction instread of a specific purpose macro.

In contrast to other similar libraries in Clojure, cats doesn’t intend to extend Clojure types that don’t act like containers. For example, Clojure keywords are values but can not be containers so they should not extend any of the previously explained protocols.

Five most important rules:

All contributions to cats should keep these important rules in mind.

Unlike Clojure and other Clojure contributed libraries, cats does not have many restrictions for contributions. Just open an issue or pull request.

For making Emacs' clojure-mode treat alet, mlet et al like a let and indent them correctly, you can use define-clojure-indent like in the following example:

cats is open source and can be found on github.

You can clone the public repository with this command:

For running tests just execute this for clojure:

And this for clojurescript: