Coconut¶

Installation¶

At its very core, Coconut is a compiler that turns Coconut code into Python code. That means that anywhere where you can use a Python script, you can also use a compiled Coconut script. To access that core compiler, Coconut comes with a command-line utility, which can

• compile single Coconut files or entire Coconut projects,
• interpret Coconut code on-the-fly, and
• hook into existing Python applications like IPython/ Jupyter.

Installing Coconut, including all the features above, is drop-dead simple. Just

1. install Python,
2. open a command-line prompt,
3. and enter:

pip install coconut

Note: Try re-running the above command with the --user option if you are encountering errors. Be sure that the coconut installation location (/usr/local/bin or ${HOME}/.local/bin/ on UNIX machines) is in your PATH environment variable.

To check that your installation is functioning properly, try entering into the command line

coconut -h

which should display Coconut’s command-line help.

Note: If you’re having trouble installing Coconut, or if anything else mentioned in this tutorial doesn’t seem to work for you, feel free to open an issue and it’ll be addressed as soon as possible.

Using the Interpreter¶

Now that you’ve got Coconut installed, the obvious first thing to do is to play around with it. To launch the Coconut interpreter, just go to the command line and type

coconut

and you should see something like

Coconut Interpreter:
(type "exit()" or press Ctrl-D to end)
>>>

which is Coconut’s way of telling you you’re ready to start entering code for it to evaluate. So let’s do that!

In case you missed it earlier, all valid Python 3 is valid Coconut. That doesn’t mean compiled Coconut will only run on Python 3—in fact, compiled Coconut will run the same on any Python version—but it does mean that only Python 3 code is guaranteed to compile as Coconut code.

That means that if you’re familiar with Python, you’re already familiar with a good deal of Coconut’s core syntax and Coconut’s entire standard library. To show that, let’s try entering some basic Python into the Coconut interpreter.

>>> "hello, world!"
hello, world!
>>> 1 + 1
2

Using the Compiler¶

Of course, while being able to interpret Coconut code on-the-fly is a great thing, it wouldn’t be very useful without the ability to write and compile larger programs. To that end, it’s time to write our first Coconut program: “hello, world!” Coconut-style.

First, we’re going to need to create a file to put our code into. The recommended file extension for Coconut source files is .coco, so let’s create the new file hello_world.coco. After you do that, you should take the time now to set up your text editor to properly highlight Coconut code. For instructions on how to do that, see the documentation on Coconut syntax highlighting.

Now let’s put some code in our hello_world.coco file. Unlike in Python, where headers like

#!/usr/bin/env python
# -*- coding: UTF-8 -*-
from __future__ import print_function, absolute_import, unicode_literals, division

are common and often very necessary, the Coconut compiler will automatically take care of all of that for you, so all you need to worry about is your own code. To that end, let’s add the code for our “hello, world!” program.

In pure Python 3, “hello, world!” is

print("hello, world!")

and while that will work in Coconut, equally as valid is to use a pipeline-style approach, which is what we’ll do, and write

"hello, world!" |> print

which should let you see very clearly how Coconut’s |> operator enables pipeline-style programming: it allows an object to be passed along from function to function, with a different operation performed at each step. In this case, we are piping the object "hello, world!" into the operation print. Now let’s save our simple “hello, world!” program, and try to run it.

Compiling Coconut files and projects with the Coconut command-line utility is incredibly simple. Just type

coconut hello_world.coco

which should give the output

Coconut: Compiling       hello_world.coco ...
Coconut: Compiled to     hello_world.py .

and deposit a new hello_world.py file in the same directory as the hello_world.coco file. You should then be able to run that file with

python hello_world.py

which should produce hello, world! as the output.

Compiling single files is not the only way to use the Coconut command-line utility, however. We can also compile all the Coconut files in a given directory simply by passing that directory as the first argument, which will get rid of the need to run the same Coconut header code in each file by storing it in a __coconut__.py file in the same directory.

The Coconut compiler supports a large variety of different compilation options, the help for which can always be accessed by entering coconut -h into the command line. One of the most useful of these is --linenumbers (or -l for short). Using --linenumbers will add the line numbers of your source code as comments in the compiled code, allowing you to see what line in your source code corresponds to a line in the compiled code where an error is occurring, for ease of debugging.

Using IPython/ Jupyter¶

Although all different types of programming can benefit from using more functional techniques, scientific computing, perhaps more than any other field, lends itself very well to functional programming, an observation the case studies in this tutorial are very good examples of. To that end, Coconut aims to provide extensive support for the established tools of scientific computing in Python.

That means supporting IPython/ Jupyter, as modern Python programming, particularly in the sciences, has gravitated towards the use of IPython (the python kernel for the Jupyter framework) instead of the classic Python shell. Coconut supports being used as a kernel for Jupyter notebooks and consoles, allowing Coconut code to be used alongside powerful IPython features such as %magic commands.

To launch a Jupyter notebook with Coconut as the kernel, use the command

coconut --jupyter notebook

and to launch a Jupyter console, use the command

coconut --jupyter console

or equivalently, --ipython can be substituted for --jupyter in either command.

Case Studies¶

Because Coconut is built to be fundamentally useful, the best way to demo it is to show it in action. To that end, the majority of this tutorial will be showing how to apply Coconut to solve particular problems, which we’ll call case studies.

These case studies are not intended to provide a complete picture of all of Coconut’s features. For that, see Coconut’s comprehensive documentation. Instead, they are intended to show how Coconut can actually be used to solve practical programming problems.

Imperative Method¶

The imperative approach is the way you’d write factorial in a language like C. Imperative approaches involve lots of state change, where variables are regularly modified and loops are liberally used. In Coconut, the imperative approach to the factorial problem looks like this:

def factorial(n):
    """Compute n! where n is an integer >= 0."""
    if n `isinstance` int and n >= 0:
        acc = 1
        for x in range(1, n+1):
            acc *= x
        return acc
    else:
        raise TypeError("the argument to factorial must be an integer >= 0")

# Test cases:
-1 |> factorial |> print  # TypeError
0.5 |> factorial |> print  # TypeError
0 |> factorial |> print  # 1
3 |> factorial |> print  # 6

Before we delve into what exactly is happening here, let’s give it a run and make sure the test cases check out. If we were really writing a Coconut program, we’d want to save and compile an actual file, but since we’re just playing around, let’s try copy-pasting into the interpreter. Here, you should get 1, 6, and then two TypeErrors.

Now that we’ve verified it works, let’s take a look at what’s going on. Since the imperative approach is a fundamentally non-functional method, Coconut can’t help us improve this example very much. Even here, though, the use of Coconut’s infix notation (where the function is put in-between its arguments, surrounded in backticks) in n `isinstance` int makes the code slightly cleaner and easier to read.

Recursive Method¶

The recursive approach is the first of the fundamentally functional approaches, in that it doesn’t involve the state change and loops of the imperative approach. Recursive approaches avoid the need to change variables by making that variable change implicit in the recursive function call. Here’s the recursive approach to the factorial problem in Coconut:

def factorial(n):
    """Compute n! where n is an integer >= 0."""
    case n:
        match 0:
            return 1
        match _ is int if n > 0:
            return n * factorial(n-1)
    else:
        raise TypeError("the argument to factorial must be an integer >= 0")

# Test cases:
-1 |> factorial |> print  # TypeError
0.5 |> factorial |> print  # TypeError
0 |> factorial |> print  # 1
3 |> factorial |> print  # 6

Copy and paste the code and tests into the interpreter. You should get the same test results as you got for the imperative version—but you can probably tell there’s quite a lot more going on here than there. That’s intentional: Coconut is intended for functional programming, not imperative programming, and so its new features are built to be most useful when programming in a functional style.

Let’s take a look at the specifics of the syntax in this example. The first thing we see is case n. This statement starts a case block, in which only match statements can occur. Each match statement will attempt to match its given pattern against the value in the case block. Only the first successful match inside of any given case block will be executed. When a match is successful, any variable bindings in that match will also be performed. Additionally, as is true in this case, match statements can also have if guards that will check the given condition before the match is considered final. Finally, after the case block, an else statement is allowed, which will only be executed if no match statement is.

Specifically, in this example, the first match statement checks whether n matches to 0. If it does, it executes return 1. Then the second match statement checks whether n matches to _ is int, which performs an isinstance check on n against int, then checks whether n > 0, and if those are true, executes return n * factorial(n-1). If neither of those two statements are executed, the else statement triggers and executes raise TypeError("the argument to factorial must be an integer >= 0").

Although this example is very basic, pattern-matching is both one of Coconut’s most powerful and most complicated features. As a general intuitive guide, it is helpful to think assignment whenever you see the keyword match. A good way to showcase this is that all match statements can be converted into equivalent destructuring assignment statements, which are also valid Coconut. In this case, the destructuring assignment equivalent to the factorial function above would be:

def factorial(n):
    """Compute n! where n is an integer >= 0."""
    try:
        0 = n  # destructuring assignment
    except MatchError:
        try:
            _ is int = n  # also destructuring assignment
        except MatchError:
            pass
        else: if n > 0:  # in Coconut, if, match, and try are allowed after else
            return n * factorial(n-1)
    else:
        return 1
    raise TypeError("the argument to factorial must be an integer >= 0")

# Test cases:
-1 |> factorial |> print  # TypeError
0.5 |> factorial |> print  # TypeError
0 |> factorial |> print  # 1
3 |> factorial |> print  # 6

First, copy and paste! While this destructuring assignment equivalent should work, it is much more cumbersome than match statements when you expect that they’ll fail, which is why match statement syntax exists. But the destructuring assignment equivalent illuminates what exactly the pattern-matching is doing, by making it clear that match statements are really just fancy destructuring assignment statements, which are really just fancy normal assignment statements. In fact, to be explicit about using destructuring assignment instead of normal assignment, the match keyword can be put before a destructuring assignment statement to signify it as such.

It will be helpful to, as we continue to use Coconut’s pattern-matching and destructuring assignment statements in further examples, think assignment whenever you see the keyword match.

Up until now, for the recursive method, we have only dealt with pattern-matching, but there’s actually another way that Coconut allows us to improve our factorial function. Coconut performs automatic tail call optimization, which means that whenever a function directly returns a call to another function, Coconut will optimize away the additional call. Thus, we can improve our factorial function by rewriting it to use a tail call:

def factorial(n, acc=1):
    """Compute n! where n is an integer >= 0."""
    case n:
        match 0:
            return acc
        match _ is int if n > 0:
            return factorial(n-1, acc*n)
    else:
        raise TypeError("the argument to factorial must be an integer >= 0")

# Test cases:
-1 |> factorial |> print  # TypeError
0.5 |> factorial |> print  # TypeError
0 |> factorial |> print  # 1
3 |> factorial |> print  # 6

Copy, paste! This new factorial function is equivalent to the original version, with the exception that it will never raise a RuntimeError due to reaching Python’s maximum recursion depth, since Coconut will optimize away the recursive tail call.

Iterative Method¶

The final, and other functional, approach, is the iterative one. Iterative approaches avoid the need for state change and loops by using higher-order functions, those that take other functions as their arguments, like map and reduce, to abstract out the basic operations being performed. In Coconut, the iterative approach to the factorial problem is:

def factorial(n):
    """Compute n! where n is an integer >= 0."""
    case n:
        match 0:
            return 1
        match _ is int if n > 0:
            return range(1, n+1) |> reduce$(*)
    else:
        raise TypeError("the argument to factorial must be an integer >= 0")

# Test cases:
-1 |> factorial |> print  # TypeError
0.5 |> factorial |> print  # TypeError
0 |> factorial |> print  # 1
3 |> factorial |> print  # 6

Copy, paste! This definition differs from the recursive definition only by one line. That’s intentional: because both the iterative and recursive approaches are functional approaches, Coconut can provide a great assist in making the code cleaner and more readable. The one line that differs is this one:

return range(1, n+1) |> reduce$(*)

Let’s break down what’s happening on this line. First, the range function constructs an iterator of all the numbers that need to be multiplied together. Then, it is piped into the function reduce$(*), which does that multiplication. But how? What is reduce$(*).

We’ll start with the base, the reduce function. reduce used to exist as a built-in in Python 2, and Coconut brings it back. reduce is a higher-order function that takes a function on two arguments as its first argument, and an iterator as its second argument, and applies that function to the given iterator by starting with the first element, and calling the function on the accumulated call so far and the next element, until the iterator is exhausted. Here’s a visual representation:

reduce(f, (a, b, c, d))

acc                 iter
                    (a, b, c, d)
a                   (b, c, d)
f(a, b)             (c, d)
f(f(a, b), c)       (d)
f(f(f(a, b), c), d)

return acc

Now let’s take a look at what we do to reduce to make it multiply all the numbers we feed into it together. The Coconut code that we saw for that was reduce$(*). There are two different Coconut constructs being used here: the operator function for multiplication in the form of (*), and partial application in the form of $.

First, the operator function. In Coconut, a function form of any operator can be retrieved by surrounding that operator in parentheses. In this case, (*) is roughly equivalent to lambda x, y: x*y, but much cleaner and neater. In Coconut’s lambda syntax, (*) is also equivalent to (x, y) -> x*y, which we will use from now on for all lambdas, even though both are legal Coconut, because Python’s lambda statement is too ugly and bulky to use regularly. In fact, if Coconut’s --strict mode is enabled, which will force your code to obey certain cleanliness standards, it will raise an error whenever Python lambda statements are used.

Second, the partial application. Think of partial application as lazy function calling, and $ as the lazy-ify operator, where lazy just means “don’t evaluate this until you need to”. In Coconut, if a function call is prefixed by a $, like in this example, instead of actually performing the function call, a new function is returned with the given arguments already provided to it, so that when it is then called, it will be called with both the partially-applied arguments and the new arguments, in that order. In this case, reduce$(*) is equivalent to (*args, **kwargs) -> reduce((*), *args, **kwargs).

Putting it all together, we can see how the single line of code

range(1, n+1) |> reduce$(*)

is able to compute the proper factorial, without using any state or loops, only higher-order functions, in true functional style. By supplying the tools we use here like partial application ($), pipeline-style programming (|>), higher-order functions (reduce), and operator functions ((*)), Coconut enables this sort of functional programming to be done cleanly, neatly, and easily.

addpattern Method¶

While the iterative approach is very clean, there are still some bulky pieces—looking at the iterative version below, you can see that it takes three entire indentation levels to get from the function definition to the actual objects being returned:

def factorial(n):
    """Compute n! where n is an integer >= 0."""
    case n:
        match 0:
            return 1
        match _ is int if n > 0:
            return range(1, n+1) |> reduce$(*)
    else:
        raise TypeError("the argument to factorial must be an integer >= 0")

By making use of the built-in Coconut function addpattern, we can take that from three indentation levels down to one. Take a look:

def factorial(0) = 1

@addpattern(factorial)
def factorial(n is int if n > 0) =
    """Compute n! where n is an integer >= 0."""
    range(1, n+1) |> reduce$(*)

# Test cases:
-1 |> factorial |> print  # MatchError
0.5 |> factorial |> print  # MatchError
0 |> factorial |> print  # 1
3 |> factorial |> print  # 6

Copy, paste! This should work exactly like before, except now it raises MatchError as a fall through instead of TypeError. There are three major new concepts to talk about here: addpattern, of course, assignment funciton notation, and pattern-matching function definition—how both of the functions above are defined.

First, assignment function notation. This one’s pretty straightforward. If a function is defined with an = instead of a :, the last line is required to be an expression, and is automatically returned.

Second, pattern-matching function definition. Pattern-matching function definition does exactly that—pattern-matches against all the arguments that are passed to the function. There are a couple of things to watch out for when using pattern-matching function definition, however. First, that if the pattern doesn’t match (if for example the wrong number of arguments are passed), your function will raise a MatchError, and second, that keyword arguments aren’t allowed. Finally, like destructuring assignment, if you want to be more explicit about using pattern-matching function definition, you can add a match before the def.

Third, addpattern. addpattern takes one argument, a previously-defined pattern-matching function, and returns a decorator that decorates a new pattern-matching function by adding the new pattern as an additional case to the old patterns. Thus, addpattern can be thought of as doing exactly what it says—it adds a new pattern to an existing pattern-matching function.

Finally, not only can we rewrite the imperative approach using addpattern, as we did above, we can also rewrite the recursive approach using addpattern, like so:

def factorial(0) = 1

@addpattern(factorial)
def factorial(n is int if n > 0) =
    """Compute n! where n is an integer >= 0."""
    n * factorial(n - 1)

# Test cases:
-1 |> factorial |> print  # MatchError
0.5 |> factorial |> print  # MatchError
0 |> factorial |> print  # 1
3 |> factorial |> print  # 6

Copy, paste! It should work exactly like before, except, as above, with TypeError replaced by MatchError.

Sorting a Sequence¶

First up is quick_sort for lists. We’re going to use a recursive addpattern-based approach to tackle this problem—a similar approach to the very last factorial function we wrote. That’s because since we’re not going to write quick_sort in a tail-recursive style, we can’t use tail_recursive, and thus there’s no reason to write the whole thing as one function and we might as well use addpattern to reduce the amount of indentation we’re going to need. Without further ado, here’s our implementation of quick_sort for lists:

def quick_sort([]) = []

@addpattern(quick_sort)
def quick_sort([head] + tail) =
    """Sort the input sequence using the quick sort algorithm."""
    (quick_sort([x for x in tail if x < head])
        + [head]
        + quick_sort([x for x in tail if x >= head]))

# Test cases:
[] |> quick_sort |> print  # []
[3] |> quick_sort |> print  # [3]
[0,1,2,3,4] |> quick_sort |> print  # [0,1,2,3,4]
[4,3,2,1,0] |> quick_sort |> print  # [0,1,2,3,4]
[3,0,4,2,1] |> quick_sort |> print  # [0,1,2,3,4]

Copy, paste! Only one new feature here: head-tail pattern-matching. Here, we see the head-tail pattern [head] + tail, which more generally just follow the form of a list or tuple added to a variable. When this appears in any pattern-matching context, the value being matched against will be treated as a sequence, the list or tuple matched against the beginning of that sequence, and the rest of it bound to the variable. In this case, we use the head-tail pattern to remove the head so we can use it as the pivot for splitting the rest of the list.

Sorting an Iterator¶

Now it’s time to try quick_sort for iterators. Our method for tackling this problem is going to be a combination of the recursive and iterative approaches we used for the factorial problem, in that we’re going to be lazily building up an iterator, and we’re going to be doing it recursively. Here’s the code:

def quick_sort(l):
    """Sort the input iterator, using the quick sort algorithm, and without using any data until necessary."""
    match [head] :: tail in l:
        tail, tail_ = tee(tail)
        yield from (quick_sort((x for x in tail if x < head))
            :: (head,)
            :: quick_sort((x for x in tail_ if x >= head))
            )

# Test cases:
[] |> quick_sort |> list |> print  # []
[3] |> quick_sort |> list |> print  # [3]
[0,1,2,3,4] |> quick_sort |> list |> print  # [0,1,2,3,4]
[4,3,2,1,0] |> quick_sort |> list |> print  # [0,1,2,3,4]
[3,0,4,2,1] |> quick_sort |> list |> print  # [0,1,2,3,4]

Copy, paste! This quick_sort algorithm works uses a bunch of new constructs, so let’s go over them.

First, the :: operator, which appears here both in pattern-matching and by itself. In essence, the :: operator is lazy + for iterators. On its own, it takes two iterators and concatenates, or chains, them together, and it does this lazily, not evaluating anything until its needed, so it can be used for making infinite iterators. In pattern-matching, it inverts that operation, destructuring the beginning of an iterator into a pattern, and binding the rest of that iterator to a variable.

Which brings us to the second new thing, match ... in ... notation. The notation

match pattern in item:
    <body>
else:
    <else>

is shorthand for

case item:
    match pattern:
        <body>
else:
    <else>

that avoids the need for an additional level of indentation when only one match is being performed.

The third new construct is the built-in function tee. tee solves a problem for functional programming created by the implementation of Python’s iterators: whenever an element of an iterator is accessed, it’s lost. tee solves this problem by splitting an iterator in two (or more if the optional argument n is passed) independent iterators that both use the same underlying iterator to access their data, thus when an element of one is accessed, it isn’t lost in the other.

Finally, although it’s not a new construct, since it exists in Python 3, the use of yield from here deserves a mention. In Python, yield is the statement used to construct iterators, functioning much like return, with the exception that multiple yields can be encountered, and each one will produce another element. yield from is very similar, except instead of adding a single element to the produced iterator, it adds another whole iterator.

Putting it all together, here’s our quick_sort function again:

def quick_sort(l):
    """Sort the input iterator, using the quick sort algorithm, and without using any data until necessary."""
    match [head] :: tail in l:
        tail, tail_ = tee(tail)
        yield from (quick_sort((x for x in tail if x < head))
            :: (head,)
            :: quick_sort((x for x in tail_ if x >= head))
            )

The function first attempts to split l into an initial element and a remaining iterator. If l is the empty iterator, that match will fail, and it will fall through, yielding the empty iterator. Otherwise, we make a copy of the rest of the iterator, and yield the join of (the quick sort of all the remaining elements less than the initial element), (the initial element), and (the quick sort of all the remaining elements greater than the initial element).

The advantages of the basic approach used here, heavy use of iterators and recursion, as opposed to the classical imperative approach, are numerous. First, our approach is more clear and more readable, since it is describing what quick_sort is instead of how quick_sort could be implemented. Second, our approach is lazy in that our quick_sort won’t evaluate any data until it needs it. Finally, and although this isn’t relevant for quick_sort it is relevant in many other cases, an example of which we’ll see later in this tutorial, our approach allows for working with infinite series just like they were finite.

And Coconut makes programming in such an advantageous functional approach significantly easier. In this example, Coconut’s pattern-matching lets us easily split the given iterator, and Coconut’s :: iterator joining operator lets us easily put it back together again in sorted order.

2-Vector¶

Coconut’s data statement brings the power and utility of immutable, algebraic data types to Python, and it is this that we will be using to construct our vector type. The demonstrate the syntax of data statements, we’ll start by defining a simple 2-vector. Our vector will have one special method __abs__ which will compute the vector’s magnitude, defined as the square root of the sum of the squares of the elements. Here’s our 2-vector:

data vector2(x, y):
    """Immutable 2-vector."""
    def __abs__(self) =
        """Return the magnitude of the 2-vector."""
        (self.x**2 + self.y**2)**0.5

# Test cases:
vector2(1, 2) |> print  # vector2(x=1, y=2)
vector2(3, 4) |> abs |> print  # 5
v = vector2(2, 3)
v.x = 7  # AttributeError

Copy, paste! This example shows the basic syntax of data statements:

data <name>(<attributes>):
    <body>

where <name> and <body> are the same as the equivalent class definition, but <attributes> are the different attributes of the data type, in order that the constructor should take them as arguments. In this case, vector2 is a data type of two attributes, x and y, with one defined method, __abs__, that computes the magnitude. As the test cases show, we can then create, print, but not modify instances of vector2.

n-Vector Constructor¶

Now that we’ve got the 2-vector under our belt, let’s move to back to our original, more complicated problem: n-vectors, that is, vectors of arbitrary length. We’re going to try to make our n-vector support all the basic vector operations, but we’ll start out with just the data definition and the constructor:

data vector(pts):
    """Immutable n-vector."""
    def __new__(cls, *pts):
        """Create a new vector from the given pts."""
        if len(pts) == 1 and pts[0] `isinstance` vector:
            return pts[0]  # vector(v) where v is a vector should return v
        else:
            return pts |> tuple |> datamaker(cls)  # accesses base constructor

# Test cases:
vector(1, 2, 3) |> print  # vector(pts=(1, 2, 3))
vector(4, 5) |> vector |> print  # vector(pts=(4, 5))

Copy, paste! The big new thing here is how to write data constructors. Since data types are immutable, __init__ construction won’t work. Instead, a different special method __new__ is used, which must return the newly constructed instance, and unlike most methods, takes the class not the object as the first argument. Since __new__ needs to return a fully constructed instance, in almost all cases access to the underlying data constructor will be necessary. To achieve this, Coconut provides the built-in function datamaker, which takes a data type, often the first argument to __new__, and returns its underlying data constructor.

In this case, the constructor checks whether nothing but another vector was passed, in which case it returns that, otherwise it returns the result of creating a tuple of the arguments and passing that to the underlying constructor, the form of which is vector(pts), thus assigning the tuple to the pts attribute.

n-Vector Methods¶

Now that we have a constructor for our n-vector, it’s time to write its methods. First up is __abs__, which should compute the vector’s magnitude. This will be slightly more complicated than with the 2-vector, since we have to make it work over an arbitrary number of pts. Fortunately, we can use Coconut’s pipeline-style programming and partial application to make it simple:

    def __abs__(self) =
        """Return the magnitude of the vector."""
        self.pts |> map$(pow$(?, 2)) |> sum |> pow$(?, 0.5)

The basic algorithm here is map square over each element, sum them all, then square root the result. The one new construct used here is the use of a ? in partial application, which simply allows skipping an argument from being partially applied and deferring it to when the function is called. In this case, the ? lets us partially apply the exponent instead of the base in pow (we could also have equivalently used (**)).

Next up is vector addition. The goal here is to add two vectors of equal length by adding their components. To do this, we’re going to make use of Coconut’s ability to perform pattern-matching, or in this case destructuring assignment, to data types, like so:

    def __add__(self, other) =
        """Add two vectors together."""
        vector(other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((+), self.pts, other_pts) |*> vector

There are a couple of new constructs here, but the main notable one is the destructuring assignment statement vector(other_pts) = other which showcases the syntax for pattern-matching against data types: it mimics exactly the original data declaration of that data type. In this case, vector(other_pts) = other will only match a vector, raising a MatchError otherwise, and if it does match a vector, will assign the vector’s pts attribute to the variable other_pts.

The other new construct used here is the |*>, or star-pipe, operator, which functions exactly like the normal pipe, except that instead of calling the function with one argument, it calls it with as many arguments as there are elements in the sequence passed into it. The difference between |*> and |> is exactly analogous to the difference between f(args) and f(*args).

Next is vector subtraction, which is just like vector addition, but with (-) instead of (+):

    def __sub__(self, other) =
        """Subtract one vector from another."""
        vector(other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((-), self.pts, other_pts) |*> vector

One thing to note here is that unlike the other operator functions, (-) can either mean negation or subtraction, the meaning of which will be inferred based on how many arguments are passed, 1 for negation, 2 for subtraction. To show this, we’ll use the same (-) function to implement vector negation, which should simply negate each element:

    def __neg__(self) =
        """Retrieve the negative of the vector."""
        self.pts |> map$((-)) |*> vector

Our next method will be equality. We’re again going to use data pattern-matching to implement this, but this time inside of a match statement instead of with destructuring assignment, since we want to return False not raise an error if the match fails. Here’s the code:

    def __eq__(self, other):
        """Compare whether two vectors are equal."""
        match vector(=self.pts) in other:
            return True
        else:
            return False

The only new construct here is the use of =self.pts in the match statement. This construct is used to perform a check inside of the pattern-matching, making sure the match only succeeds if other.pts == self.pts.

The last method we’ll implement is multiplication. This one is a little bit tricky, since mathematically, there are a whole bunch of different ways to multiply vectors. For our purposes, we’re just going to look at two: between two vectors of equal length, we want to compute the dot product, defined as the sum of the corresponding elements multiplied together, and between a vector and a scalar, we want to compute the scalar multiple, which is just each element multiplied by that scalar. Here’s our implementation:

    def __mul__(self, other):
        """Scalar multiplication and dot product."""
        match vector(other_pts) in other:
            assert len(other_pts) == len(self.pts)
            return map((*), self.pts, other_pts) |> sum  # dot product
        else:
            return self.pts |> map$((*)$(other)) |*> vector  # scalar multiple
    def __rmul__(self, other) =
        """Necessary to make scalar multiplication commutative."""
        self * other

The first thing to note here is that unlike with addition and subtraction, where we wanted to raise an error if the vector match failed, here, we want to do scalar multiplication if the match fails, so instead of using destructuring assignment, we use a match statement. The second thing to note here is the combination of pipeline-style programming, partial application, operator functions, and higher-order functions we’re using to compute the dot product and scalar multiple. For the dot product, we map multiplication over the two vectors, then sum the result. For the scalar multiple, we take the original points, map multiplication by the scalar over them, then use them to make a new vector.

Finally, putting everything together:

data vector(pts):
    """Immutable n-vector."""
    def __new__(cls, *pts):
        """Create a new vector from the given pts."""
        if len(pts) == 1 and pts[0] `isinstance` vector:
            return pts[0]  # vector(v) where v is a vector should return v
        else:
            return pts |> tuple |> datamaker(cls)  # accesses base constructor
    def __abs__(self) =
        """Return the magnitude of the vector."""
        self.pts |> map$(pow$(?, 2)) |> sum |> pow$(?, 0.5)
    def __add__(self, other) =
        """Add two vectors together."""
        vector(other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((+), self.pts, other_pts) |*> vector
    def __sub__(self, other) =
        """Subtract one vector from another."""
        vector(other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((-), self.pts, other_pts) |*> vector
    def __neg__(self) =
        """Retrieve the negative of the vector."""
        self.pts |> map$((-)) |*> vector
    def __eq__(self, other):
        """Compare whether two vectors are equal."""
        match vector(=self.pts) in other:
            return True
        else:
            return False
    def __mul__(self, other):
        """Scalar multiplication and dot product."""
        match vector(other_pts) in other:
            assert len(other_pts) == len(self.pts)
            return map((*), self.pts, other_pts) |> sum  # dot product
        else:
            return self.pts |> map$((*)$(other)) |*> vector  # scalar multiplication
    def __rmul__(self, other) =
        """Necessary to make scalar multiplication commutative."""
        self * other

# Test cases:
vector(1, 2, 3) |> print  # vector(pts=(1, 2, 3))
vector(4, 5) |> vector |> print  # vector(pts=(4, 5))
vector(3, 4) |> abs |> print  # 5
vector(1, 2) + vector(2, 3) |> print  # vector(pts=(3, 5))
vector(2, 2) - vector(0, 1) |> print  # vector(pts=(2, 1))
-vector(1, 3) |> print  # vector(pts=(-1, -3))
(vector(1, 2) == "string") |> print  # False
(vector(1, 2) == vector(3, 4)) |> print  # False
(vector(2, 4) == vector(2, 4)) |> print  # True
2*vector(1, 2) |> print  # vector(pts=(2, 4))
vector(1, 2) * vector(1, 3) |> print  # 7

Copy, paste! Now that was a lot of code. But looking it over, it looks clean, readable, and concise, and it does precisely what we intended it to do: create an algebraic data type for an immutable n-vector that supports the basic vector operations. And we did the whole thing without needing any imperative constructs like state or loops—pure functional programming.

diagonal_line¶

Thus, our first function diagonal_line(n) should construct an iterator of all the points, represented as coordinate tuples, in the nth diagonal, starting with (0, 0) as the 0th diagonal. Like we said at the start of this case study, this is where we I let go and you take over. Using all the tools of functional programming that Coconut provides, give diagonal_line a shot. When you’re ready to move on, scroll down.

Here are some tests that you can use:

diagonal_line(0) `isinstance` (list, tuple) |> print  # False (should be an iterator)
diagonal_line(0) |> list |> print  # [(0, 0)]
diagonal_line(1) |> list |> print  # [(0, 1), (1, 0)]

Hint: the nth diagonal should contain n+1 elements, so try starting with range(n+1) and then transforming it in some way.

That wasn’t so bad, now was it? Now, let’s take a look at my solution:

def diagonal_line(n) = range(n+1) |> map$((i) -> (i, n-i))

Pretty simple, huh? We take range(n+1), and use map to transform it into the right sequence of tuples.

linearized_plane¶

Now that we’ve created our diagonal lines, we need to join them together to make the full linearized plane, and to do that we’re going to write the function linearized_plane(). linearized_plane should produce an iterator that goes through all the points in the plane, in order of all the points in the first diagonal(0), then the second diagonal(1), and so on. linearized_plane is going to be, by necessity, an infinite iterator, since it needs to loop through all the points in the plane, which have no end. To help you accomplish this, remember that the :: operator is lazy, and won’t evaluate its operands until they’re needed, which means it can be used to construct infinite iterators. When you’re ready to move on, scroll down.

Tests:

# Note: these tests use $[] notation, which we haven't introduced yet
#  but will introduce later in this case study; for now, just run the
#  tests, and make sure you get the same result as is in the comment
linearized_plane()$[0] |> print  # (0, 0)
linearized_plane()$[:3] |> list |> print  # [(0, 0), (0, 1), (1, 0)]

Hint: instead of defining the function as linearized_plane(), try defining it as linearized_plane(n=0), where n is the diagonal to start at, and use recursion to build up from there.

That was a little bit rougher than the first one, but hopefully still not too bad. Let’s compare to my solution:

def linearized_plane(n=0) = diagonal_line(n) :: linearized_plane(n+1)

As you can see, it’s a very fundamentally simple solution: just use :: and recursion to join all the diagonals together in order.

vector_field¶

Now that we have a function that builds up all the points we need, it’s time to turn them into vectors, and to do that we’ll define the new function vector_field(), which should turn all the tuples in linearized_plane into vectors, using the n-vector class we defined earlier.

Tests:

# You'll need to bring in the vector class from earlier to make these work
vector_field()$[0] |> print  # vector(pts=(0, 0))
vector_field()$[2:3] |> list |> print  # [vector(pts=(1, 0))]

Hint: Remember, the way we defined vector it takes the components as separate arguments, not a single tuple.

We’re making good progress! Before we move on, check your solution against mine:

def vector_field() = linearized_plane() |> map$((xy) -> vector(*xy))

All we’re doing is taking our linearized_plane and mapping vector over it, but making sure to call vector with each element of the tuple as a separate argument.

Applications¶

Now that we’ve built all the functions we need for our vector field, it’s time to put it all together and test it. Feel free to substitute in your versions of the functions below:

data vector(pts):
    """Immutable n-vector."""
    def __new__(cls, *pts):
        """Create a new vector from the given pts."""
        if len(pts) == 1 and pts[0] `isinstance` vector:
            return pts[0]  # vector(v) where v is a vector should return v
        else:
            return pts |> tuple |> datamaker(cls)  # accesses base constructor
    def __abs__(self) =
        """Return the magnitude of the vector."""
        self.pts |> map$(pow$(?, 2)) |> sum |> pow$(?, 0.5)
    def __add__(self, other) =
        """Add two vectors together."""
        vector(other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((+), self.pts, other_pts) |*> vector
    def __sub__(self, other) =
        """Subtract one vector from another."""
        vector(other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((-), self.pts, other_pts) |*> vector
    def __neg__(self) =
        """Retrieve the negative of the vector."""
        self.pts |> map$((-)) |*> vector
    def __eq__(self, other):
        """Compare whether two vectors are equal."""
        match vector(=self.pts) in other:
            return True
        else:
            return False
    def __mul__(self, other):
        """Scalar multiplication and dot product."""
        match vector(other_pts) in other:
            assert len(other_pts) == len(self.pts)
            return map((*), self.pts, other_pts) |> sum  # dot product
        else:
            return self.pts |> map$((*)$(other)) |*> vector  # scalar multiplication
    def __rmul__(self, other) =
        """Necessary to make scalar multiplication commutative."""
        self * other

def diagonal_line(n) = range(n+1) |> map$((i) -> (i, n-i))
def linearized_plane(n=0) = diagonal_line(n) :: linearized_plane(n+1)
def vector_field() = linearized_plane() |> map$((xy) -> vector(*xy))

# Test cases:
diagonal_line(0) `isinstance` (list, tuple) |> print  # False (should be an iterator)
diagonal_line(0) |> list |> print  # [(0, 0)]
diagonal_line(1) |> list |> print  # [(0, 1), (1, 0)]
linearized_plane()$[0] |> print  # (0, 0)
linearized_plane()$[:3] |> list |> print  # [(0, 0), (0, 1), (1, 0)]
vector_field()$[0] |> print  # vector(pts=(0, 0))
vector_field()$[2:3] |> list |> print  # [vector(pts=(1, 0))]

Copy, paste! Once you’ve made sure everything is working correctly if you substituted in your own functions, take a look at the last 4 tests. You’ll notice that they use a new notation, similar to the notation for partial application we saw earlier, but with brackets instead of parentheses. This is the notation for iterator slicing. Similar to how partial application was lazy function calling, iterator slicing is lazy sequence slicing. Like with partial application, it is helpful to think of $ as the lazy-ify operator, in this case turning normal Python slicing, which is evaluated immediately, into lazy iterator slicing, which is evaluated only when the elements in the slice are needed.

With that in mind, now that we’ve built our vector field, it’s time to use iterator slicing to play around with it. Try doing something cool to our vector fields like

• create a magnitude_field where each point is that vector’s magnitude
• combine entire vector fields together with map and the vector addition and multiplication methods we wrote earlier

then use iterator slicing to take out portions and examine them.

__truediv__¶

Vector division is just scalar division, so we’re going to write a __truediv__ method that takes self as the first argument and other as the second argument, and returns a new vector the same size as self with every element divided by other. For an extra challenge, try writing this one in one line using assignment function notation.

Tests:

vector(3, 4) / 1 |> print  # vector(pts=(3.0, 4.0))
vector(2, 4) / 2 |> print  # vector(pts=(1.0, 2.0))

Hint: Look back at how we implemented scalar multiplication.

Here’s my solution for you to check against:

    def __truediv__(self, other) = self.pts |> map$((x) -> x/other) |*> vector

.unit¶

Next up, .unit. We’re going to write a unit method that takes just self as its argument and returns a new vector the same size as self with each element divided by the magnitude of self, which we can retrieve with abs. This should be a very simple one-line function.

Tests:

vector(0, 1).unit() |> print  # vector(pts=(0.0, 1.0))
vector(5, 0).unit() |> print  # vector(pts=(1.0, 0.0))

Here’s my solution:

    def unit(self) = self / abs(self)

.angle¶

This one is going to be a little bit more complicated. For starters, the mathematical formula for the angle between two vectors is the math.acos of the dot product of those vectors’ respective unit vectors, and recall that we already implemented the dot product of two vectors when we wrote __mul__. So, .angle should take self as the first argument and other as the second argument, and if other is a vector, use that formula to compute the angle between self and other, or if other is not a vector, .angle should raise a MatchError. To accomplish this, we’re going to want to use destructuring assignment to check that other is indeed a vector.

Tests:

import math
vector(2, 0).angle(vector(3, 0)) |> print  # 0.0
print(vector(1, 0).angle(vector(0, 2)), math.pi/2)  # should be the same
vector(1, 2).angle(5)  # MatchError

Hint: Look back at how we checked whether the argument to factorial was an integer using destructuring assignment.

Here’s my solution—take a look:

    def angle(self, other is vector) = math.acos(self.unit() * other.unit())

And now it’s time to put it all together. Feel free to substitute in your own versions of the methods we just defined.

import math  # necessary for math.acos in .angle

data vector(pts):
    """Immutable n-vector."""
    def __new__(cls, *pts):
        """Create a new vector from the given pts."""
        if len(pts) == 1 and pts[0] `isinstance` vector:
            return pts[0]  # vector(v) where v is a vector should return v
        else:
            return pts |> tuple |> datamaker(cls)  # accesses base constructor
    def __abs__(self) =
        """Return the magnitude of the vector."""
        self.pts |> map$(pow$(?, 2)) |> sum |> pow$(?, 0.5)
    def __add__(self, other) =
        """Add two vectors together."""
        vector(other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((+), self.pts, other_pts) |*> vector
    def __sub__(self, other) =
        """Subtract one vector from another."""
        vector(other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((-), self.pts, other_pts) |*> vector
    def __neg__(self) =
        """Retrieve the negative of the vector."""
        self.pts |> map$((-)) |*> vector
    def __eq__(self, other):
        """Compare whether two vectors are equal."""
        match vector(=self.pts) in other:
            return True
        else:
            return False
    def __mul__(self, other):
        """Scalar multiplication and dot product."""
        match vector(other_pts) in other:
            assert len(other_pts) == len(self.pts)
            return map((*), self.pts, other_pts) |> sum  # dot product
        else:
            return self.pts |> map$((*)$(other)) |*> vector  # scalar multiplication
    def __rmul__(self, other) =
        """Necessary to make scalar multiplication commutative."""
        self * other
     # New one-line functions necessary for finding the angle between vectors:
    def __truediv__(self, other) = self.pts |> map$((x) -> x/other) |*> vector
    def unit(self) = self / abs(self)
    def angle(self, other is vector) = math.acos(self.unit() * other.unit())

# Test cases:
vector(3, 4) / 1 |> print  # vector(pts=(3.0, 4.0))
vector(2, 4) / 2 |> print  # vector(pts=(1.0, 2.0))
vector(0, 1).unit() |> print  # vector(pts=(0.0, 1.0))
vector(5, 0).unit() |> print  # vector(pts=(1.0, 0.0))
vector(2, 0).angle(vector(3, 0)) |> print  # 0.0
print(vector(1, 0).angle(vector(0, 2)), math.pi/2)  # should be the same
vector(1, 2).angle(5)  # MatchError

One note of warning here: be careful not to leave a blank line when substituting in your methods, or the interpreter will cut off the code for the vector there. This isn’t a problem in normal Coconut code, only here because we’re copy-and-pasting into the command line.

Copy, paste! If everything is working, I’d recommend going back to playing around with vector_field applications using our new methods.

Lazy Lists¶

First up is lazy lists. Lazy lists are lazily-evaluated iterator literals, similar in their laziness to Coconut’s :: operator, in that any expressions put inside a lazy list won’t be evaluated until that element of the lazy list is needed. The syntax for lazy lists is exactly the same as the syntax for normal lists, but with “banana brackets” ((| and |)) instead of normal brackets, like so:

abc = (| a, b, c |)

Function Composition¶

Next is function composition. In Coconut, this is accomplished through the .. operator, which takes two functions and composes them, creating a new function equivalent to (*args, **kwargs) -> f1(f2(*args, **kwargs)). This can be useful in combination with partial application for piecing together multiple higher-order functions, like so:

zipsum = map$(sum)..zip

Function composition also gets rid of the need for lots of parentheses when chaining function calls, like so:

(plus1..square)(3) == 10

Implicit Partials¶

Last is implicit partials. Coconut supports a number of different “incomplete” expressions that will evaluate to a function that takes in the part necessary to complete them, that is, an implicit partial application function. The different allowable expressions are:

.attr
.method(args)
obj.
func$
seq[]
iter$[]
.[slice]
.$[slice]

Further Reading¶

And that’s it for this tutorial! But that’s hardly it for Coconut. All of the features examined in this tutorial, as well as a bunch of others, are documented in detail in Coconut’s comprehensive documentation.

Also, if you have any other questions not covered in this tutorial, feel free to ask around at Coconut’s Gitter, a GitHub-integrated chat room for Coconut developers.

Finally, Coconut is a new, growing language, and if you’d like to get involved in the development of Coconut, all the code is available completely open-source on Coconut’s GitHub. Contributing is a simple as forking the code, making your changes, and proposing a pull request.

Installation¶

Since Coconut is hosted on the Python Package Index, it can be installed easily using pip. Simply install Python, open up a command-line prompt, and enter

pip install coconut

which will install Coconut and its required dependencies. Coconut also has some optional dependencies, which can be installed by entering

pip install coconut[all]

which will enable the use of Coconut’s --jobs, --watch, --jupyter, and --mypy flags. To install the optional dependencies only for a particular flag, simply put the flag name in place of all.

Alternatively, if you want to test out Coconut’s latest and greatest, enter

pip install coconut-develop

which will install the most recent working development build (optional dependency installation is also supported in the same manner as above if you want). For more information on the current development build, check out the development version of this documentation. Be warned: coconut-develop is likely to be unstable—if you find a bug, please report it by creating a new issue.

Usage¶

coconut [-h] [-v] [-t version] [-i] [-p] [-a] [-l] [-k] [-w] [-r] [-n]
        [-d] [-q] [-s] [-c code] [-j processes] [-f] [--minify]
        [--jupyter ...] [--mypy ...] [--tutorial] [--documentation]
        [--style name] [--recursion-limit limit] [--verbose]
        [source] [dest]

source              path to the Coconut file/folder to compile
dest                destination directory for compiled files (defaults to
                    the source directory)

-h, --help          show this help message and exit
-v, --version       print Coconut and Python version information
-t version, --target version
                    specify target Python version (defaults to universal)
-i, --interact      force the interpreter to start (otherwise starts if no
                    other command is given) (implies --run)
-p, --package       compile source as part of a package (defaults to only
                    if source is a directory)
-a, --standalone    compile source as standalone files (defaults to only
                    if source is a single file)
-l, --line-numbers, --linenumbers
                    add line number comments for ease of debugging
-k, --keep-lines, --keeplines
                    include source code in comments for ease of debugging
-w, --watch         watch a directory and recompile on changes
-r, --run           execute compiled Python
-n, --nowrite       disable writing compiled Python
-d, --display       print compiled Python
-q, --quiet         suppress all informational output (combine with
                    --display to write runnable code to stdout)
-s, --strict        enforce code cleanliness standards
-c code, --code code
                    run Coconut passed in as a string (can also be piped
                    into stdin)
-j processes, --jobs processes
                    number of additional processes to use (defaults to 0)
                    (pass 'sys' to use machine default)
-f, --force         force overwriting of compiled Python (otherwise only
                    overwrites when source code or compilation parameters
                    change)
--minify            reduce size of compiled Python
--jupyter ..., --ipython ...
                    run Jupyter/IPython with Coconut as the kernel
                    (remaining args passed to Jupyter)
--mypy ...          run MyPy on compiled Python (remaining args passed to
                    MyPy) (implies --package)
--tutorial          open the Coconut tutorial in the default web browser
--documentation     open the Coconut documentation in the default web
                    browser
--style name        Pygments syntax highlighting style (or 'none' to
                    disable) (defaults to COCONUT_STYLE environment
                    variable, if it exists, otherwise 'default')
--recursion-limit limit, --recursionlimit limit
                    set maximum recursion depth in compiler (defaults to
                    2000)
--verbose           print verbose debug output

Coconut Scripts¶

To run a Coconut file as a script, Coconut provides the command coconut-run as an alias for coconut --run --quiet that also passes all additional command-line arguments to the script being run. coconut-run will quietly compile the file if it’s been changed or use the existing compiled Python if it hasn’t and then run that. coconut-run can be used in a Unix shebang to create a Coconut script with the following line:

#!/usr/bin/env coconut-run

Naming Source Files¶

Coconut source files should, so the compiler can recognize them, use the extension .coco (preferred), .coc, or .coconut. When Coconut compiles a .coco (or .coc / .coconut) file, it will compile to another file with the same name, except with .py instead of .coco, which will hold the compiled code. If an extension other than .py is desired for the compiled files, such as .pyde for Python Processing, then that extension can be put before .coco in the source file name, and it will be used instead of .py for the compiled files. For example, name.coco will compile to name.py, whereas name.pyde.coco will compile to name.pyde.

Compilation Modes¶

Files compiled by the coconut command-line utility will vary based on compilation parameters. If an entire directory of files is compiled (which the compiler will search recursively for any folders containing .coco, .coc, or .coconut files), a __coconut__.py file will be created to house necessary functions (package mode), whereas if only a single file is compiled, that information will be stored within a header inside the file (standalone mode). Standalone mode is better for single files because it gets rid of the overhead involved in importing __coconut__.py, but package mode is better for large packages because it gets rid of the need to run the same Coconut header code again in every file, since it can just be imported from __coconut__.py.

By default, if the source argument to the command-line utility is a file, it will perform standalone compilation on it, whereas if it is a directory, it will recursively search for all .coco (or .coc / .coconut) files and perform package compilation on them. Thus, in most cases, the mode chosen by Coconut automatically will be the right one. But if it is very important that no additional files like __coconut__.py be created, for example, then the command-line utility can also be forced to use a specific mode with the --package (-p) and --standalone (-a) flags.

Compatible Python Versions¶

While Coconut syntax is based off of Python 3, Coconut code compiled in universal mode (the default --target), and the Coconut compiler, should run on any Python version >= 2.6 on the 2.x branch or >= 3.2 on the 3.x branch.

Note: The tested against implementations are CPython 2.6, 2.7, 3.2, 3.3, 3.4, 3.5 and PyPy 2.7, 3.2.

As part of Coconut’s cross-compatibility efforts, Coconut adds in new Python 3 built-ins and overwrites Python 2 built-ins to use the Python 3 versions where possible. Additionally, Coconut also overrides some Python 3 built-ins for optimization purposes. If access to the Python versions is desired, the old built-ins can be retrieved by prefixing them with py_.

Finally, while Coconut will try to compile Python-3-specific syntax to its universal equivalent, the follow constructs have no equivalent in Python 2, and require a target of at least 3 to be specified to be used:

• destructuring assignment with *s (use Coconut pattern-matching instead),
• the nonlocal keyword,
• exec used in a context where it must be a function,
• keyword class definition,
• tuples and lists with * unpacking or dicts with ** unpacking (requires --target 3.5),
• @ as matrix multiplication (requires --target 3.5),
• async and await statements (requires --target 3.5), and
• formatting f strings (requires --target 3.6).

Allowable Targets¶

If the version of Python that the compiled code will be running on is known ahead of time, a target should be specified with --target. The given target will only affect the compiled code and whether or not certain Python-3-specific syntax is allowed, detailed below. Where Python 3 and Python 2 syntax standards differ, Coconut syntax will always follow Python 3 across all targets. The supported targets are:

• universal (default) (will work on any of the below),
• 2, 26 (will work on any Python >= 2.6 but < 3),
• 27 (will work on any Python >= 2.7 but < 3),
• 3, 32 (will work on any Python >= 3.2),
• 33, 34 (will work on any Python >= 3.3),
• 35 (will work on any Python >= 3.5),
• 36 (will work on any Python >= 3.6),
• sys (chooses the specific target corresponding to the current version).

Note: Periods are ignored in target specifications, such that the target 2.7 is equivalent to the target 27.

strict Mode¶

If the --strict (or -s) flag is enabled, Coconut will throw errors on various style problems. These are

• mixing of tabs and spaces (without --strict will show a Warning),
• missing new line at end of file (without --strict will show a Warning),
• use of from __future__ imports (without --strict will show a Warning)
• trailing whitespace at end of lines,
• semicolons at end of lines,
• use of the Python-style lambda statement,
• use of u to denote Unicode strings, and
• use of backslash continuations (use parenthetical continuation instead).

It is recommended that you use the --strict (or -s) flag if you are starting a new Coconut project, as it will help you write cleaner code.

IPython/ Jupyter Support¶

If you prefer IPython (the python kernel for the Jupyter framework) to the normal Python shell, Coconut can be used as a Jupyter kernel or IPython extension.

MyPy Integration¶

Coconut has the ability to integrate with MyPy to provide optional static type-checking, including for all Coconut built-ins.

Simply pass --mypy (be careful to pass it only as the last argument), use standard Python 3 type annotation syntax, and Coconut will take care of the rest. By default, Coconut compiles Python 3 type annotations into mypy --py2 compatible type comments. If you want to keep the Python 3 type annotations instead, simply pass --target 3.

In addition to function argument type annotation, Coconut also supports variable type annotation using the new Python 3.6 syntax, which compiles to mypy --py2 compatible type comments unless --target 3.6 is specified.

Coconut even supports --mypy in the interpreter, which will intelligently scan each new line of code, in the context of previous lines, for newly-introduced MyPy errors. For example:

>>> a = count()[0]  # type: str
<string>:14: error: Incompatible types in assignment (expression has type "int", variable has type "str")

Lambdas¶

Coconut provides the simple, clean -> operator as an alternative to Python’s lambda statements. The syntax for the -> operator is (arguments) -> expression. The operator has the same precedence as the old statement, which means it will often be necessary to surround the lambda in parentheses.

Additionally, Coconut also supports an implicit usage of the -> operator of the form (-> expression), which is equivalent to ((_=None) -> expression), which allows an implicit lambda to be used both when no arguments are required, and when one argument (assigned to _) is required.

Note: If normal lambda syntax is insufficient, Coconut also supports an extended lambda syntax in the form of statement lambdas.

def <lambda>(arguments):
    return expression

dubsums = map((x, y) -> 2*(x+y), range(0, 10), range(10, 20))
dubsums |> list |> print

dubsums = map(lambda x, y: 2*(x+y), range(0, 10), range(10, 20))
print(list(dubsums))

Partial Application¶

Coconut uses a $ sign right after a function’s name but before the open parenthesis used to call the function to denote partial application. It has the same precedence as subscription.

Coconut’s partial application also supports the use of a ? to skip partially applying an argument, deferring filling in that argument until the partially-applied function is called. This is useful if you want to partially apply argument(s) that aren’t first in the argument order.

def partial(func, *args, **keywords):
    def newfunc(*fargs, **fkeywords):
        newkeywords = keywords.copy()
        newkeywords.update(fkeywords)
        return func(*(args + fargs), **newkeywords)
    newfunc.func = func
    newfunc.args = args
    newfunc.keywords = keywords
    return newfunc

expnums = range(5) |> map$(pow$(?, 2))
expnums |> list |> print

# unlike this simple lambda, $ produces a pickleable object
expnums = map(lambda x: pow(x, 2), range(5))
print(list(expnums))

Pipeline¶

Coconut uses pipe operators for pipeline-style function application. All the operators have a precedence in-between infix calls and comparisons and are left-associative. All operators also support in-place versions. The different operators are:

(|>)    => pipe forward
(|*>)   => multiple-argument pipe forward
(<|)    => pipe backward
(<*|)   => multiple-argument pipe backward

def sq(x) = x**2
(1, 2) |*> (+) |> sq |> print

import operator
def sq(x): return x**2
print(sq(operator.add(1, 2)))

Compose¶

Coconut uses the .. operator for function composition. It has a precedence in-between subscription and exponentiation. The in-place operator is ..=.

fog = f..g

# unlike this simple lambda, .. produces a pickleable object
fog = lambda *args, **kwargs: f(g(*args, **kwargs))

Chain¶

Coconut uses the :: operator for iterator chaining. Coconut’s iterator chaining is done lazily, in that the arguments are not evaluated until they are needed. It has a precedence in-between bitwise or and infix calls. The in-place operator is ::=.

def chain(*iterables):
    # chain('ABC', 'DEF') --> A B C D E F
    for it in iterables:
        for element in it:
            yield element

def N(n=0) = (n,) :: N(n+1) # no infinite loop because :: is lazy

(range(-10, 0) :: N())$[5:15] |> list |> print

Iterator Slicing¶

Coconut uses a $ sign right after an iterator before a slice to perform iterator slicing. Coconut’s iterator slicing works much the same as Python’s sequence slicing, and looks much the same as Coconut’s partial application, but with brackets instead of parentheses. It has the same precedence as subscription.

Iterator slicing works just like sequence slicing, including support for negative indices and slices, and support for slice objects in the same way as can be done with normal slicing. Iterator slicing makes no guarantee, however, that the original iterator passed to it be preserved (to preserve the iterator, use Coconut’s tee function).

Coconut’s iterator slicing is very similar to Python’s itertools.islice, but unlike itertools.islice, Coconut’s iterator slicing supports negative indices, and will preferentially call an object’s __getitem__, if it exists. Coconut’s iterator slicing is also optimized to work well with all of Coconut’s built-in objects, only computing the elements of each that are actually necessary to extract the desired slice.

map((x)->x*2, range(10**100))$[-1] |> print

Unicode Alternatives¶

Coconut supports Unicode alternatives to many different operator symbols. The Unicode alternatives are relatively straightforward, and chosen to reflect the look and/or meaning of the original symbol.

→ (\u2192)                  => "->"
↦ (\u21a6)                  => "|>"
*↦ (*\u21a6)                => "|*>"
↤ (\u21a4)                  => "<|"
↤* (\u21a4*)                => "<*|"
⋅ (\u22c5)                  => "*"
↑ (\u2191)                  => "**"
÷ (\xf7)                    => "/"
÷/ (\xf7/)                  => "//"
∘ (\u2218)                  => ".."
− (\u2212)                  => "-" (only subtraction)
⁻ (\u207b)                  => "-" (only negation)
¬ (\xac)                    => "~"
≠ (\u2260) or ¬= (\xac=)    => "!="
≤ (\u2264)                  => "<="
≥ (\u2265)                  => ">="
∧ (\u2227) or ∩ (\u2229)    => "&"
∨ (\u2228) or ∪ (\u222a)    => "|"
⊻ (\u22bb) or ⊕ (\u2295)    => "^"
« (\xab)                    => "<<"
» (\xbb)                    => ">>"
… (\u2026)                  => "..."
× (\xd7)                    => "@" (only matrix multiplication)

data¶

The syntax for data blocks is a cross between the syntax for functions and the syntax for classes. The first line looks like a function definition, but the rest of the body looks like a class, usually containing method definitions. This is because while data blocks actually end up as classes in Python, Coconut automatically creates a special, immutable constructor based on the given arguments.

Coconut data blocks create immutable classes derived from collections.namedtuple and made immutable with __slots__. Coconut data statement syntax looks like:

data <name>(<args>):
    <body>

<name> is the name of the new data type, <args> are the arguments to its constructor as well as the names of its attributes, and <body> contains the data type’s methods.

Subclassing data types can be done easily by inheriting from them in a normal Python class, although to make the new subclass immutable, the line

__slots__ = ()

will need to be added to the subclass before any method or attribute definitions.

data vector(x, y):
    def __abs__(self):
        return (self.x**2 + self.y**2)**.5

v = vector(3, 4)
v |> print # all data types come with a built-in __repr__
v |> abs |> print
v.x = 2 # this will fail because data objects are immutable

data Empty(): pass
data Leaf(n): pass
data Node(l, r): pass

def size(Empty()) = 0

@addpattern(size)
def size(Leaf(n)) = 1

@addpattern(size)
def size(Node(l, r)) = size(l) + size(r)

size(Node(Empty(), Leaf(10))) == 1

import collections
class vector(collections.namedtuple("vector", "x, y")):
    __slots__ = ()
    def __abs__(self):
        return (self.x**2 + self.y**2)**.5

v = vector(3, 4)
print(v)
print(abs(v))
v.x = 2

import collections
class Empty(collections.namedtuple("Empty", "")):
    __slots__ = ()
class Leaf(collections.namedtuple("Leaf", "n")):
    __slots__ = ()
class Node(collections.namedtuple("Node", "l, r")):
    __slots__ = ()

def size(tree):
    if isinstance(tree, Empty):
        return 0
    elif isinstance(tree, Leaf):
        return 1
    elif isinstance(tree, Node):
        return size(tree[0]) + size(tree[1])
    else:
        raise MatchError()

size(Node(Empty(), Leaf(10))) == 1

match¶

Coconut provides fully-featured, functional pattern-matching through its match statements.

match <pattern> in <value> [if <cond>]:
    <body>
[else:
    <body>]

pattern ::= (
    "(" pattern ")"                 # parentheses
    | "None" | "True" | "False"     # constants
    | "=" NAME                      # check
    | NUMBER                        # numbers
    | STRING                        # strings
    | [pattern "as"] NAME           # capture
    | NAME "(" patterns ")"         # data types
    | "(" patterns ")"              # sequences can be in tuple form
    | "[" patterns "]"              #  or in list form
    | "(|" patterns "|)"            # lazy lists
    | "{" pattern_pairs "}"         # dictionaries
    | ["s"] "{" pattern_consts "}"  # sets
    | ("(" | "[")                   # star splits
        patterns,
        "*" middle,
        patterns
      (")" | "]")                       # must both be parens or brackets
    | (                             # head-tail splits
        "(" patterns ")"
        | "[" patterns "]"
      ) "+" pattern
    | pattern "+" (                 # init-last splits
        "(" patterns ")"
        | "[" patterns "]"
      )
    | (                             # head-last splits
        "(" patterns ")"
        | "[" patterns "]"
      ) "+" pattern "+" (
        "(" patterns ")"                # this match must be the same
        | "[" patterns "]"              #  construct as the first match
      )
    | (                             # iterator splits
        "(" patterns ")"
        | "[" patterns "]"
        | "(|" patterns "|)"
      ) "::" pattern
    | pattern "is" exprs            # type-checking
    | pattern "and" pattern         # match all
    | pattern "or" pattern          # match any
    )

def factorial(value):
    match 0 in value:
        return 1
    else: match n is int in value if n > 0: # possible because of Coconut's
        return n * factorial(n-1)           #   enhanced else statements
    else:
        raise TypeError("invalid argument to factorial of: "+repr(value))

3 |> factorial |> print