Cats Documentation

The simplest way to use cats in a Clojure project is by including it as a dependency in your project.clj:

cats is open source and can be found on github.

You can clone the public repository with this command:

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.

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 section should clarify its purpose.

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

If you want to use regular (non-monadic) let bindings inside an mlet block, you can do so using :let and a binding vector inside the mlet bindings:

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.

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:

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 Error in cljs).

The most common use case of this monad is to wrap third party libraries that use standard Exception based error handling. In 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.

The State monad is one of the special cases of monads most commonly used in Haskell. It has several purposes including: lazy computation, composition, and maintaining state without explicit state.

The de-facto monadic type of the state monad is a plain function. A function represents a computation as is (without executing it). Obviously, a function should have some special characteristics to work in monad state composition.

You just saw an example of the low-level primitive state monad. For basic usage you do not need to write your own functions, just use some helpers that cats provides.

Let’s look at one example before explaining the details:

At the moment of evaluation in the previous expression, nothing of what we have defined is executed. But instead of returning the unadorned final value of the computation, a strange/unknown object of type State is returned.

The State type is simply a wrapper for Clojure functions, nothing more.

Now, it’s time to execute the composed computation. We can use one of the following functions exposed by cats for that: run-state, eval-state and exec-state.

The run-state function returns an instance of the Pair type. The Pair type acts like any other seq in Clojure with the exception that it can only contain two values.

TODO

TODO

TODO

TODO

TODO

TODO

TODO

The validation type is similar to the Either or Exception types except that it doesn’t implement a Monad instance. It has two constructors: ok and fail, representing success and failure respectively.

It implements the Applicative protocol, and its intended usage is as an Applicative. Applying Validation values together errs on the side of the failure, and applying failures together aggregates their values using the Semigroup’s mappend function.

Some monads are defined as separated package to avoid additional and unnecesary dependencies to cats. Also, there are some libraries that build higher-level abstractions on top of what cats offers.

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.

cats does not have many restrictions for contributions. Just follow these steps depending on the situation:

Bugfix:

New feature: