Witchcraft is a library providing common algebraic and categorical abstractions to Elixir. Monoids, functors, monads, arrows, categories, and more.

Build Status Inline docs Deps Status hex.pm version API Docs license

README

Table of Contents

Quick Start

def deps do
  [{:witchcraft, "1.0.0-beta"}]
end

# ...

use Witchcraft

Library Family

Quark    TypeClass
    ↘    ↙
   Witchcraft
       ↓
     Algae
  • Quark: Standard combinators (id, compose, &c)
  • TypeClass: Used internally to generate type classes
  • Algae: Algebraic data types that implement Witchcraft type classes

Type Class Hierarchy

Semigroupoid  Semigroup  Setoid   Foldable   Functor -----------┐
     ↓           ↓         ↓         ↓     ↙   ↓   ↘           |
  Category     Monoid     Ord    Traversable  Apply  Bifunctor  |
     ↓                                       ↙    ↘             ↓
   Arrow                            Applicative   Chain       Extend
                                             ↘    ↙             ↓
                                              Monad           Comonad

It is very common to want everything in a chain. You can import the entire chain with use. For example, you can import the entire library with:

use Witchcraft.Monad

Any options that you pass to use will be propagated all the way down the chain

use Witchcraft.Monad, except: [~>: 2]

Some modules override Kernel operators and functions. While this is generally safe, if you would like to skip all overrides, pass override_kernel: false as an option

use Witchcraft.Foldable, override_kernel: false

Operators

FamilyFunctionOperator
Setoidequivalent?==
nonequivalent?!=
Ordgreater_than?>
lesser_than?<
Monoidappend<>
Functorlift~>
pipe_ap~>>
chain>>>
reverse_lift<~
ap<<~
reverse_chain<<<

| Semigroupoid | compose | <|> | | | pipe_compose | <~> | | Arrow | product | ^^^ | | | fanout | &&& |

Values

Beginner Friendliness

You shouldn’t have to learn another language just to understand powerful abstractions! By enabling people to use a language that they already know, and is already in the same ballpark in terms of values (emphasis on immutability, &c), we can teach and learn faster.

As much as possible, keep things friendly and well explained. Concrete examples are available via doctests.

Consistency & Ethos

Elixir does a lot of things differently from other functional languages. The idea of a data “subject” being piped though functions is conceptually different from pure composition of functions that are later applied. Witchcraft honours the Elixir way, and operators point in the direction that data travels.

Some functions in the Elixir standard library have been expanded to work with more types while keeping the basic idea the same. For example, <> has been expanded to work on any monoid (such as integers, lists, bitstrings, and so on).

All operators have named equivalents, and auto-currying variants of higher order functions are left at separate names so you can performance tune as needed (currying is helpful for more abstract code). With a few exceptions (we’re looking at you, Applicative), pipe-ordering is maintained.

Pragmatism

Convincing a company to use a language like Haskell or PureScript can be challenging. Elixir is gaining a huge amount of interest. Many people have been able to introduce these concepts into companies using Scala, so we should be able to do the same here.

All functions are compatible with regular Elixir code, and no types are enforced aside from what is used in protocol dispatch. Any struct can be made into a Witchcraft class instance (given that it conforms to the properties).

Haskell Translation Table

Haskell PreludeWitchcraft
flip ($)|>/2
.<|>/2
<<<<|>/2
>>><~>/2
<><>/2
<$><~/2
flip (<$>)~>/2
fmaplift/2
liftAlift/2
liftA2lift/3
liftA3lift/4
liftMlift/2
liftM2lift/3
liftM3lift/4
apap/2
<*><<~/2
<**>~>>/2
*>then/2
<*following/2
pureof/2
returnof/2
>>then/2
>>=>>>/2
=<<<<</2
***^^^/2
&&&&&&/2

Hierarchy

Having a clean slate, we have been able to use a clean of typeclasses. This is largely taken from the Fantasy Land Specification and Edward Kmett’s semigroupoids package.

As usual, all Applicatives are Functors, and all Monads are Applicatives. This grants us the ability to reuse functions in their child classes. For example, of can be used for both pure and return, lift/* can handle both liftA* and liftM*, and so on.

Credits

A big thank you to Brandon Labbé for creating the project logo.

Robot Overlord sponsors much of the development of Witchcraft, and dogfoods the library in real-world applications.