Coconut Documentation¶

Using Pip¶

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.

Note: If you have an old version of Coconut installed and you want to upgrade, run pip install --upgrade coconut instead.

If you are encountering errors running pip install coconut, try instead running

COCONUT_PURE_PYTHON=TRUE pip install --user --upgrade coconut

in bash (UNIX) or

cmd /c "set COCONUT_PURE_PYTHON=TRUE&& pip install --user --upgrade coconut"

in cmd (Windows) which will force Coconut to use the pure-Python pyparsing module instead of the faster cPyparsing module. If you are still getting errors, you may want to try using conda instead.

If pip install coconut works, but you cannot access the coconut command, be sure that Coconut’s installation location is in your PATH environment variable. On UNIX, that is /usr/local/bin (without --user) or ${HOME}/.local/bin/ (with --user).

Using Conda¶

If you prefer to use conda instead of pip to manage your Python packages, you can also install Coconut using conda. Just install conda, open up a command-line prompt, and enter

conda config --add channels conda-forge
conda install coconut

which will properly create and build a conda recipe out of Coconut’s conda-forge feedstock.

Optional Dependencies¶

Coconut also has optional dependencies, which can be installed by entering

pip install coconut[name_of_optional_dependency]

or, to install multiple optional dependencies,

pip install coconut[opt_dep_1,opt_dep_2]

The full list of optional dependencies is:

• all: alias for jupyter,watch,jobs,mypy,asyncio (this is the recommended way to install a feature-complete version of Coconut),
• jupyter/ipython: enables use of the --jupyter / --ipython flag,
• watch: enables use of the --watch flag,
• jobs: improves use of the --jobs flag,
• mypy: enables use of the --mypy flag,
• asyncio: enables use of the asyncio library on older Python versions by making use of trollius,
• tests: everything necessary to run Coconut’s test suite,
• docs: everything necessary to build Coconut’s documentation, and
• dev: everything necessary to develop on Coconut, including all of the dependencies above.

Develop Version¶

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

pip install coconut-develop

which will install the most recent working version from Coconut’s develop branch. Optional dependency installation is supported in the same manner as above. 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] [--no-tco] [-c code] [-j processes] [-f]
        [--minify] [--jupyter ...] [--mypy ...] [--argv ...]
        [--tutorial] [--documentation] [--style name]
        [--history-file path] [--recursion-limit limit] [--verbose]
        [--trace]
        [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, --no-write, --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
  --no-tco, --notco     disable tail call optimization
  -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)
  --argv ..., --args ...
                        set sys.argv to source plus remaining args for use in
                        the Coconut script being run
  --tutorial            open Coconut's tutorial in the default web browser
  --documentation       open Coconut's 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')
  --history-file path   Path to history file (or '' for no file) (defaults to
                        COCONUT_HISTORY_FILE environment variable if it
                        exists, otherwise '~\.coconut_history')
  --recursion-limit limit, --recursionlimit limit
                        set maximum recursion depth in compiler (defaults to
                        2000)
  --verbose             print verbose debug output
  --trace               print verbose parsing data (only available in coconut-
                        develop)

Coconut Scripts¶

To run a Coconut file as a script, Coconut provides the command

coconut-run <source> <args>

as an alias for

coconut --run --quiet --target sys <source> --argv <args>

which will quietly compile and run <source>, passing any additional arguments to the script, mimicking how the python command works.

coconut-run can be used in a Unix shebang line to create a Coconut script by adding the following line to the start of your script:

#!/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 on either CPython or PyPy.

To make Coconut built-ins universal across Python versions, Coconut automatically overwrites Python 2 built-ins with their Python 3 counterparts. Additionally, Coconut also overwrites some Python 3 built-ins for optimization and enhancement purposes. If access to the original Python versions of any overwritten built-ins is desired, the old built-ins can be retrieved by prefixing them with py_.

For standard library compatibility, Coconut automatically maps imports under Python 3 names to imports under Python 2 names. Thus, Coconut will automatically take care of any standard library modules that were renamed from Python 2 to Python 3 if just the Python 3 name is used. For modules or objects that only exist in Python 3, however, Coconut has no way of maintaining compatibility.

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

• the nonlocal keyword,
• exec used in a context where it must be a function,
• keyword class definition,
• keyword-only function arguments (use pattern-matching function definition instead),
• destructuring assignment with *s (use pattern-matching instead),
• 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),
• := assignment expressions (requires --target 3.8), and
• positional-only function arguments (use pattern-matching function definition instead) (requires --target 3.8).

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 the Python-3-specific syntax detailed above is allowed. 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, 2.6 (will work on any Python >= 2.6 but < 3),
• 2.7 (will work on any Python >= 2.7 but < 3),
• 3, 3.2 (will work on any Python >= 3.2),
• 3.3 (will work on any Python >= 3.3),
• 3.4 (will work on any Python >= 3.4),
• 3.5 (will work on any Python >= 3.5),
• 3.6 (will work on any Python >= 3.6),
• 3.7 (will work on any Python >= 3.7),
• 3.8 (will work on any Python >= 3.8), and
• sys (chooses the target corresponding to the current Python version).

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

strict Mode¶

If the --strict (-s for short) flag is enabled, Coconut will perform additional checks on the code being compiled. It is recommended that you use the --strict flag if you are starting a new Coconut project, as it will help you write cleaner code. Specifically, the extra checks done by --strict are

• disabling deprecated features (making them entirely unavailable to code compiled with --strict),
• warning about unused imports,
• throwing errors on various style problems (see list below).

The style issues which will cause --strict to throw an error are:

• mixing of tabs and spaces (without --strict will show a warning),
• use of from __future__ imports (without --strict will show a warning)
• missing new line at end of file,
• trailing whitespace at end of lines,
• semicolons at end of lines,
• use of the Python-style lambda statement,
• inheriting from object in classes (Coconut does this automatically),
• use of u to denote Unicode strings (all Coconut strings are Unicode strings), and
• use of backslash continuation (use parenthetical continuation instead).

Syntax Highlighting¶

Text editors with support for Coconut syntax highlighting are:

• SublimeText: See SublimeText section below.
• Vim: See coconut.vim.
• Emacs: See coconut-mode.
• Atom: See language-coconut.
• IntelliJ IDEA: See registering file types.
• Any editor that supports Pygments (e.g. Spyder): See Pygments section below.

Alternatively, if none of the above work for you, you can just treat Coconut as Python. Simply set up your editor so it interprets all .coco files as Python and that should highlight most of your code well enough.

highlight_language = "coconut"

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 to enable MyPy integration, though be careful to pass it only as the last argument, since all arguments after --mypy are passed to mypy, not Coconut. You can also call mypy directly on the compiled Coconut if you run coconut --mypy at least once and then add ~/.coconut_stubs to your MYPYPATH.

To explicitly annotate your code with types for MyPy to check, Coconut supports Python 3 function type annotations, Python 3.6 variable type annotations, and even Coconut’s own enhanced type annotation syntax. By default, all type annotations are compiled to Python-2-compatible type comments, which means it all works on any Python version.

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: str = count()[0]
<string>:14: error: Incompatible types in assignment (expression has type "int", variable has type "str")

Sometimes, MyPy will not know how to handle certain Coconut constructs, such as addpattern. For the addpattern case, it is recommended to pass --allow-redefinition to MyPy (i.e. run coconut <args> --mypy --allow-redefinition), though in some cases --allow-redefinition may not be sufficient. In that case, either hide the offending code using TYPE_CHECKING or put a # type: ignore comment on the Coconut line which is generating the line MyPy is complaining about (you can figure out what line this is using --line-numbers) and the comment will be added to every generated line.

Lambdas¶

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

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. Statement lambdas support type annotations for their parameters, while standard lambdas do not.

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))

square = (-> _**2)

import random

get_random_number = (-> random.random())

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.

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 arguments 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 function composition pipes and comparisons, and are left-associative. All operators also support in-place versions. The different operators are:

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

Additionally, all pipe operators support a lambda as the last argument, despite lambdas having a lower precedence. Thus, a |> x -> b |> c is equivalent to a |> (x -> b |> c), not a |> (x -> b) |> c.

Note: To visually spread operations across several lines, just use parenthetical continuation.

obj |> .attribute |> .method(args) |> func$(args) |> .[index]

func(args, obj.attribute.method(args))[index]

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 has three basic function composition operators: .., ..>, and <... Both .. and <.. use math-style “backwards” function composition, where the first function is called last, while ..> uses “forwards” function composition, where the first function is called first. Forwards and backwards function composition pipes cannot be used together in the same expression (unlike normal pipes) and have precedence in-between None-coalescing and normal pipes. The ..> and <.. function composition pipe operators also have ..*> and <*.. forms which are, respectively, the equivalents of |*> and <*| and ..**> and <**.. forms which correspond to |**> and <**|.

The .. operator has lower precedence than attribute access, slices, function calls, etc., but higher precedence than all other operations while the ..> pipe operators have a precedence directly higher than normal pipes.

The in-place function composition operators are ..=, ..>=, <..=, ..*>=, <*..=, ..**>, and ..**>.

fog = f..g
f_into_g = f ..> g

# unlike these simple lambdas, Coconut produces pickleable objects
fog = lambda *args, **kwargs: f(g(*args, **kwargs))
f_into_g = lambda *args, **kwargs: g(f(*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.

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 or reiterable built-in).

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

None Coalescing¶

Coconut provides ?? as a None-coalescing operator, similar to the ?? null-coalescing operator in C# and Swift. Additionally, Coconut implements all of the None-aware operators proposed in PEP 505.

Coconut’s ?? operator evaluates to its left operand if that operand is not None, otherwise its right operand. The expression foo ?? bar evaluates to foo as long as it isn’t None, and to bar if it is. The None-coalescing operator is short-circuiting, such that if the left operand is not None, the right operand won’t be evaluated. This allows the right operand to be a potentially expensive operation without incurring any unnecessary cost.

The None-coalescing operator has a precedence in-between infix function calls and composition pipes, and is left-associative.

could_be_none() ?? calculate_default_value()

(lambda result: result if result is not None else calculate_default_value())(could_be_none())

foo = 1
bar = None
foo ??= 10  # foo is still 1
bar ??= 10  # bar is now 10

baz = 0
baz ??= expensive_task()  # right hand side isn't evaluated

could_be_none?.attr     # attribute access
could_be_none?(arg)     # function calling
could_be_none?.method() # method calling
could_be_none?$(arg)    # partial application
could_be_none()?[0]     # indexing
could_be_none()?.attr[index].method()

import functools
(lambda result: None if result is None else result.attr)(could_be_none())
(lambda result: None if result is None else result(arg))(could_be_none())
(lambda result: None if result is None else result.method())(could_be_none())
(lambda result: None if result is None else functools.partial(result, arg))(could_be_none())
(lambda result: None if result is None else result[0])(could_be_none())
(lambda result: None if result is None else result.attr[index].method())(could_be_none())

Expanded Indexing for Iterables¶

Beyond indexing standard Python sequences, Coconut supports indexing into a number of iterables, including range and map, which do not support random access in all Python versions but do in Coconut. In Coconut, indexing into an iterable of this type uses the same syntax as indexing into a sequence in vanilla Python.

range(0, 12, 2)[4]  # 8

map((i->i*2), range(10))[2]  # 4

range(10) |> filter$(i->i>3) |> .[0]  # doesn't work

range(10) |> filter$(i->i>3) |> .$[0]  # works

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)                  => "|>"
↤ (\u21a4)                  => "<|"
*↦ (*\u21a6)                => "|*>"
↤* (\u21a4*)                => "<*|"
**↦ (**\u21a6)              => "|**>"
↤** (\u21a4**)              => "<**|"
× (\xd7)                    => "*"
↑ (\u2191)                  => "**"
÷ (\xf7)                    => "/"
÷/ (\xf7/)                  => "//"
∘ (\u2218)                  => ".."
∘> (\u2218>)                => "..>"
<∘ (<\u2218)                => "<.."
∘*> (\u2218*>)              => "..*>"
<*∘ (<*\u2218)              => "<*.."
∘**> (\u2218**>)            => "..**>"
<**∘ (<**\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)                  => "..."
⋅ (\u22c5)                  => "@" (only matrix multiplication)

data¶

Coconut’s data keyword is used to create immutable, algebraic data types with built-in support for destructuring pattern-matching, fmap, and typed equality.

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 statement syntax looks like:

data <name>(<args>) [from <inherits>]:
    <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, <body> contains the data type’s methods, and <inherits> optionally contains any desired base classes.

Coconut allows data fields in <args> to have defaults and/or type annotations attached to them, and supports a starred parameter at the end to collect extra arguments.

Writing constructors for data types must be done using the __new__ method instead of the __init__ method. For helping to easily write __new__ methods, Coconut provides the makedata built-in.

Subclassing data types can be done easily by inheriting from them either in another data statement or a normal Python class. If a normal class statement is used, making the new subclass immutable will require adding the line

__slots__ = ()

which will need to be put in the subclass body before any method or attribute definitions.

data vector2(x:int=0, y:int=0):
    def __abs__(self):
        return (self.x**2 + self.y**2)**.5

v = vector2(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
vector2() |> print

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

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

data vector(*pts):
    """Immutable arbitrary-length vector."""

    def __abs__(self) =
        self.pts |> map$(pow$(?, 2)) |> sum |> pow$(?, 0.5)

    def __add__(self, other) =
        vector(*other_pts) = other
        assert len(other_pts) == len(self.pts)
        map((+), self.pts, other_pts) |*> vector

    def __neg__(self) =
        self.pts |> map$((-)) |*> vector

    def __sub__(self, other) =
        self + -other

match¶

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

match <pattern> [not] 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
    | pattern "is" exprs            # type-checking
    | pattern "and" pattern         # match all
    | pattern "or" pattern          # match any
    | "{" pattern_pairs             # dictionaries
        ["," "**" NAME] "}"
    | ["s"] "{" pattern_consts "}"  # sets
    | "(" patterns ")"              # sequences can be in tuple form
    | "[" patterns "]"              #  or in list form
    | "(|" patterns "|)"            # lazy lists
    | ("(" | "[")                   # star splits
        patterns
        "*" middle
        patterns
      (")" | "]")
    | (                             # 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
    | ([STRING "+"] NAME            # complex string matching
        ["+" STRING])
)

def factorial(value):
    match 0 in value:
        return 1
    else: match n is int in value if n > 0:  # Coconut allows nesting of statements on the same line
        return n * factorial(n-1)
    else:
        raise TypeError("invalid argument to factorial of: "+repr(value))

3 |> factorial |> print

data point(x, y):
    def transform(self, other):
        match point(x, y) in other:
            return point(self.x + x, self.y + y)
        else:
            raise TypeError("arg to transform must be a point")

point(1,2) |> point(3,4).transform |> print
point(1,2) |> (==)$(point(1,2)) |> print

class Tree
data Empty() from Tree
data Leaf(n) from Tree
data Node(l, r) from Tree

def depth(Tree()) = 0

@addpattern(depth)
def depth(Tree(n)) = 1

@addpattern(depth)
def depth(Tree(l, r)) = 1 + max([depth(l), depth(r)])

Empty() |> depth |> print
Leaf(5) |> depth |> print
Node(Leaf(2), Node(Empty(), Leaf(3))) |> depth |> print

def duplicate_first([x] + xs as l) =
    [x] + l

[1,2,3] |> duplicate_first |> print

def sieve([head] :: tail) =
    [head] :: sieve(n for n in tail if n % head)

@addpattern(sieve)
def sieve((||)) = []

case¶

Coconut’s case statement is an extension of Coconut’s match statement for performing multiple match statements against the same value, where only one of them should succeed. Unlike lone match statements, only one match statement inside of a case block will ever succeed, and thus more general matches should be put below more specific ones.

Each pattern in a case block is checked until a match is found, and then the corresponding body is executed, and the case block terminated. The syntax for case blocks is

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

where <pattern> is any match pattern, <value> is the item to match against, <cond> is an optional additional check, and <body> is simply code that is executed if the header above it succeeds. Note the absence of an in in the match statements: that’s because the <value> in case <value> is taking its place.

def classify_sequence(value):
    out = ""        # unlike with normal matches, only one of the patterns
    case value:     #  will match, and out will only get appended to once
        match ():
            out += "empty"
        match (_,):
            out += "singleton"
        match (x,x):
            out += "duplicate pair of "+str(x)
        match (_,_):
            out += "pair"
        match _ is (tuple, list):
            out += "sequence"
    else:
        raise TypeError()
    return out

[] |> classify_sequence |> print
() |> classify_sequence |> print
[1] |> classify_sequence |> print
(1,1) |> classify_sequence |> print
(1,2) |> classify_sequence |> print
(1,1,1) |> classify_sequence |> print

match data¶

In addition to normal data statements, Coconut also supports pattern-matching data statements that enable the use of Coconut’s pattern-matching syntax to define the data type’s constructor. Pattern-matching data types look like

[match] data <name>(<patterns>) [from <base class>]:
    <body>

where <patterns> are exactly as in pattern-matching functions.

It is important to keep in mind that pattern-matching data types vary from normal data types in a variety of ways. First, like pattern-matching functions, they raise MatchError instead of TypeError when passed the wrong arguments. Second, pattern-matching data types will not do any special handling of starred arguments. Thus,

data vec(*xs)

when iterated over will iterate over all the elements of xs, but

match data vec(*xs)

when iterated over will only give the single element xs.

data namedpt(name is str, x is int, y is int):
    def mag(self) = (self.x**2 + self.y**2)**0.5

where¶

Coconut’s where statement is extremely straightforward. The syntax for a where statement is just

<stmt> where:
    <body>

where <body> is composed entirely of assignment statements. The where statement just executes each assignment statement in <body> then evaluates the base <stmt>.

c = a + b where:
    a = 1
    b = 2

a = 1
b = 2
c = a + b

Backslash-Escaping¶

In Coconut, the keywords data, match, case, where, async (keyword in Python 3.5), and await (keyword in Python 3.5) are also valid variable names. While Coconut can disambiguate these two use cases, when using one of these keywords as a variable name, a backslash is allowed in front to be explicit about using a keyword as a variable name (in particular, to let syntax highlighters know).

\data = 5
print(\data)

data = 5
print(data)

Statement Lambdas¶

The statement lambda syntax is an extension of the normal lambda syntax to support statements, not just expressions.

The syntax for a statement lambda is

def (arguments) -> statement; statement; ...

where arguments can be standard function arguments or pattern-matching function definition arguments and statement can be an assignment statement or a keyword statement. If the last statement (not followed by a semicolon) is an expression, it will automatically be returned.

Statement lambdas also support implicit lambda syntax such that def -> _ is equivalent to def (_=None) -> _.

L |> map$(def (x) -> y = 1/x; y*(1 - y))

def _lambda(x):
    y = 1/x
    return y*(1 - y)
map(_lambda, L)

f = def (c: str) -> print(c)

g = def (a: int, b: int) -> a ** b

Lazy Lists¶

Coconut supports the creation of lazy lists, where the contents in the list will be treated as an iterator and not evaluated until they are needed. Lazy lists can be created in Coconut simply by simply surrounding a comma-seperated list of items with (| and |) (so-called “banana brackets”) instead of [ and ] for a list or ( and ) for a tuple.

Lazy lists use the same machinery as iterator chaining to make themselves lazy, and thus the lazy list (| x, y |) is equivalent to the iterator chaining expression (x,) :: (y,), although the lazy list won’t construct the intermediate tuples.

(| print("hello,"), print("world!") |) |> consume

Implicit Partial Application¶

Coconut supports a number of different syntactical aliases for common partial application use cases. These are:

.attr           =>      operator.attrgetter("attr")
.method(args)   =>      operator.methodcaller("method", args)
obj.            =>      getattr$(obj)
func$           =>      ($)$(func)
seq[]           =>      operator.getitem$(seq)
iter$[]         =>      # the equivalent of seq[] for iterators
.[a:b:c]        =>      operator.itemgetter(slice(a, b, c))
.$[a:b:c]       =>      # the equivalent of .[a:b:c] for iterators

1 |> "123"[]
mod$ <| 5 <| 3

"123"[1]
mod(5, 3)

Operator Functions¶

Coconut uses a simple operator function short-hand: surround an operator with parentheses to retrieve its function. Similarly to iterator comprehensions, if the operator function is the only argument to a function, the parentheses of the function call can also serve as the parentheses for the operator function.

(|>)        => # pipe forward
(<|)        => # pipe backward
(|*>)       => # multi-arg pipe forward
(<*|)       => # multi-arg pipe backward
(|**>)      => # keyword arg pipe forward
(<**|)      => # keyword arg pipe backward
(..), (<..) => # backward function composition
(..>)       => # forward function composition
(<*..)      => # multi-arg backward function composition
(..*>)      => # multi-arg forward function composition
(<**..)     => # keyword arg backward function composition
(..**>)     => # keyword arg forward function composition
(.)         => (getattr)
(::)        => (itertools.chain)  # will not evaluate its arguments lazily
($)         => (functools.partial)
($[])       => # iterator slicing operator
(+)         => (operator.add)
(-)         => # 1 arg: operator.neg, 2 args: operator.sub
(*)         => (operator.mul)
(**)        => (operator.pow)
(/)         => (operator.truediv)
(//)        => (operator.floordiv)
(%)         => (operator.mod)
(&)         => (operator.and_)
(^)         => (operator.xor)
(|)         => (operator.or_)
(<<)        => (operator.lshift)
(>>)        => (operator.rshift)
(<)         => (operator.lt)
(>)         => (operator.gt)
(==)        => (operator.eq)
(<=)        => (operator.le)
(>=)        => (operator.ge)
(!=)        => (operator.ne)
(~)         => (operator.inv)
(@)         => (operator.matmul)
(not)       => (operator.not_)
(and)       => # boolean and
(or)        => # boolean or
(is)        => (operator.is_)
(in)        => (operator.contains)
(assert)    => # assert function

(range(0, 5), range(5, 10)) |*> map$(+) |> list |> print

import operator
print(list(map(operator.add, range(0, 5), range(5, 10))))

Implicit Function Application¶

Coconut supports implicit function application of the form f x y, which is compiled to f(x, y) (note: not f(x)(y) as is common in many languages with automatic currying). Implicit function application has a lower precedence than .. function composition and a higher precedence than **.

Supported arguments to implicit function application are highly restricted, and must be either variables/attributes or non-string constants (e.g. f x 1 will work but f x [1], f x (1+2), and f "abc" will not). Strings are disallowed due to conflicting with Python’s implicit string concatenation. Implicit function application is only intended for simple use cases—for more complex cases, use either standard function application or pipes.

def f(x, y) = (x, y)
print (f 5 10)

def p1(x) = x + 1
print..p1 5

def f(x, y): return (x, y)
print(f(100, 5+6))

def p1(x): return x + 1
print(p1(5))

Enhanced Type Annotation¶

Since Coconut syntax is a superset of Python 3 syntax, it supports Python 3 function type annotation syntax and Python 3.6 variable type annotation syntax. By default, Coconut compiles all type annotations into Python-2-compatible type comments. If you want to keep the type annotations instead, simply pass a --target that supports them.

Since not all supported Python versions support the typing module, Coconut provides the TYPE_CHECKING built-in for hiding your typing imports and TypeVar definitions from being executed at runtime. Furthermore, when compiling type annotations to Python 3 syntax, Coconut wraps annotation in strings to prevent them from being evaluated at runtime.

Additionally, Coconut adds special syntax for making type annotations easier and simpler to write. When inside of a type annotation, Coconut treats certain syntax constructs differently, compiling them to type annotations instead of what they would normally represent. Specifically, Coconut applies the following transformations:

<type>?
    => typing.Optional[<type>]
<type>[]
    => typing.Sequence[<type>]
<type>$[]
    => typing.Iterable[<type>]
() -> <ret>
    => typing.Callable[[], <ret>]
<arg> -> <ret>
    => typing.Callable[[<arg>], <ret>]
(<args>) -> <ret>
    => typing.Callable[[<args>], <ret>]
-> <ret>
    => typing.Callable[..., <ret>]

where typing is the Python 3.5 built-in typing module.

Note: <type>[] does not map onto typing.List[<int>] but onto typing.Sequence[<int>]. There are two reasons that this design choice was made. When writing in an idiomatic functional style, assignment should be rare and tuples should be common. Using Sequence covers both cases, accommodating tuples and lists and preventing indexed assignment. When an indexed assignment is attempted into a variable typed with Sequence, MyPy will generate an error:

foo: int[] = [0, 1, 2, 3, 4, 5]
foo[0] = 1   # MyPy error: "Unsupported target for indexed assignment"

If you want to use List instead (if you want to support indexed assignment), use the standard Python 3.5 variable type annotation syntax: foo: List[<type>].

def int_map(
    f: int -> int,
    xs: int[],
) -> int[] =
    xs |> map$(f) |> list

import typing  # unlike this typing import, Coconut produces universal code
def int_map(
    f,  # type: typing.Callable[[int], int]
    xs,  # type: typing.Sequence[int]
):
    # type: (...) -> typing.Sequence[int]
    return list(map(f, xs))

Set Literals¶

Coconut allows an optional s to be prepended in front of Python set literals. While in most cases this does nothing, in the case of the empty set it lets Coconut know that it is an empty set and not an empty dictionary. Additionally, an f is also supported, in which case a Python frozenset will be generated instead of a normal set.

empty_frozen_set = f{}

empty_frozen_set = frozenset()

Imaginary Literals¶

In addition to Python’s <num>j or <num>J notation for imaginary literals, Coconut also supports <num>i or <num>I, to make imaginary literals more readable if used in a mathematical context.

imagnumber ::= (floatnumber | intpart) ("j" | "J" | "i" | "I")

3.14i   10.i    10i     .001i   1e100i  3.14e-10i

3 + 4i |> abs |> print

print(abs(3 + 4j))

Tail Call Optimization¶

Coconut will perform automatic tail call optimization and tail recursion elimination on any function that meets the following criteria:

1. it must directly return (using either return or assignment function notation) a call to itself (tail recursion elimination, the most powerful optimization) or another function (tail call optimization),
2. it must not be a generator (uses yield) or an asynchronous function (uses async).

Note: Tail call optimization (though not tail recursion elimination) will work even for 1) mutual recursion and 2) pattern-matching functions split across multiple definitions using addpattern.

If you are encountering a RuntimeError due to maximum recursion depth, it is highly recommended that you rewrite your function to meet either the criteria above for tail call optimization, or the corresponding criteria for recursive_iterator, either of which should prevent such errors.

# unlike in Python, this function will never hit a maximum recursion depth error
def factorial(n, acc=1):
    case n:
        match 0:
            return acc
        match _ is int if n > 0:
            return factorial(n-1, acc*n)

# unlike in Python, neither of these functions will ever hit a maximum recursion depth error
def is_even(0) = True
@addpattern(is_even)
def is_even(n is int if n > 0) = is_odd(n-1)

def is_odd(0) = False
@addpattern(is_odd)
def is_odd(n is int if n > 0) = is_even(n-1)

x = 1
foo = lambda: x
print(foo())  # 1
x = 2         # Directly alter the values in the namespace enclosing foo
print(foo())  # 2 (!)

Assignment Functions¶

Coconut allows for assignment function definition that automatically returns the last line of the function body. An assignment function is constructed by substituting = for : after the function definition line. Thus, the syntax for assignment function definition is either

def <name>(<args>) = <expr>

for one-liners or

def <name>(<args>) =
    <stmts>
    <expr>

for full functions, where <name> is the name of the function, <args> are the functions arguments, <stmts> are any statements that the function should execute, and <expr> is the value that the function should return.

Note: Assignment function definition can be combined with infix and/or pattern-matching function definition.

def binexp(x) = 2**x
5 |> binexp |> print

def binexp(x): return 2**x
print(binexp(5))

Pattern-Matching Functions¶

Coconut pattern-matching functions are just normal functions where the arguments are patterns to be matched against instead of variables to be assigned to. The syntax for pattern-matching function definition is

[match] def <name>(<arg>, <arg>, ... [if <cond>]):
    <body>

where <arg> is defined as

[*|**] <pattern> [= <default>]

where <name> is the name of the function, <cond> is an optional additional check, <body> is the body of the function, <pattern> is defined by Coconut’s match statement, and <default> is the optional default if no argument is passed. The match keyword at the beginning is optional, but is sometimes necessary to disambiguate pattern-matching function definition from normal function definition, which will always take precedence.

If <pattern> has a variable name (either directly or with as), the resulting pattern-matching function will support keyword arguments using that variable name. If pattern-matching function definition fails, it will raise a MatchError object just like destructuring assignment.

Note: Pattern-matching function definition can be combined with assignment and/or infix function definition.

def last_two(_ + [a, b]):
    return a, b
def xydict_to_xytuple({"x":x is int, "y":y is int}):
    return x, y

range(5) |> last_two |> print
{"x":1, "y":2} |> xydict_to_xytuple |> print

addpattern Functions¶

Coconut provides the addpattern def syntax as a shortcut for the full

@addpattern(func)
match def func(...):
  ...

syntax using the addpattern decorator.

def factorial(0) = 1
addpattern def factorial(n) = n * factorial(n - 1)

Infix Functions¶

Coconut allows for infix function calling, where an expression that evaluates to a function is surrounded by backticks and then can have arguments placed in front of or behind it. Infix calling has a precedence in-between chaining and None-coalescing, and is left-associative. Additionally, infix notation supports a lambda as the last argument, despite lambdas having a lower precedence. Thus, a `func` b -> c is equivalent to func(a, b -> c).

Coconut also supports infix function definition to make defining functions that are intended for infix usage simpler. The syntax for infix function definition is

def <arg> `<name>` <arg>:
    <body>

where <name> is the name of the function, the <arg>s are the function arguments, and <body> is the body of the function. If an <arg> includes a default, the <arg> must be surrounded in parentheses.

Note: Infix function definition can be combined with assignment and/or pattern-matching function definition.

def a `mod` b = a % b
(x `mod` 2) `print`

def mod(a, b): return a % b
print(mod(x, 2))

Dotted Function Definition¶

Coconut allows for function definition using a dotted name to assign a function as a method of an object as specified in PEP 542.

def MyClass.my_method(self):
    ...

def my_method(self):
    ...
MyClass.my_method = my_method

Destructuring Assignment¶

Coconut supports significantly enhanced destructuring assignment, similar to Python’s tuple/list destructuring, but much more powerful. The syntax for Coconut’s destructuring assignment is

[match] <pattern> = <value>

where <value> is any expression and <pattern> is defined by Coconut’s match statement. The match keyword at the beginning is optional, but is sometimes necessary to disambiguate destructuring assignment from normal assignment, which will always take precedence. Coconut’s destructuring assignment is equivalent to a match statement that follows the syntax:

match <pattern> in <value>:
    pass
else:
    err = MatchError(<error message>)
    err.pattern = "<pattern>"
    err.value = <value>
    raise err

If a destructuring assignment statement fails, then instead of continuing on as if a match block had failed, a MatchError object will be raised describing the failure.

_ + [a, b] = [0, 1, 2, 3]
print(a, b)

Decorators¶

Unlike Python, which only supports a single variable or function call in a decorator, Coconut supports any expression.

@ wrapper1 .. wrapper2$(arg)
def func(x) = x**2

def wrapper(func):
    return wrapper1(wrapper2(arg, func))
@wrapper
def func(x):
    return x**2

Statement Nesting¶

Coconut supports the nesting of compound statements on the same line. This allows the mixing of match and if statements together, as well as compound try statements.

if invalid(input_list):
    raise Exception()
else: match [head] + tail in input_list:
    print(head, tail)
else:
    print(input_list)

from collections.abc import Sequence
if invalid(input_list):
    raise Exception()
elif isinstance(input_list, Sequence):
    head, tail = inputlist[0], inputlist[1:]
    print(head, tail)
else:
    print(input_list)

except Statements¶

Python 3 requires that if multiple exceptions are to be caught, they must be placed inside of parentheses, so as to disallow Python 2’s use of a comma instead of as. Coconut allows commas in except statements to translate to catching multiple exceptions without the need for parentheses, since, as in Python 3, as is always required to bind the exception to a name.

try:
    unsafe_func(arg)
except SyntaxError, ValueError as err:
    handle(err)

try:
    unsafe_func(arg)
except (SyntaxError, ValueError) as err:
    handle(err)

Implicit pass¶

Coconut supports the simple class name(base) and data name(args) as aliases for class name(base): pass and data name(args): pass.

class Tree
data Empty from Tree
data Leaf(item) from Tree
data Node(left, right) from Tree

In-line global And nonlocal Assignment¶

Coconut allows for global or nonlocal to precede assignment to a variable or list of variables to make that assignment global or nonlocal, respectively.

global state_a, state_b = 10, 100

global state_a, state_b; state_a, state_b = 10, 100

Code Passthrough¶

Coconut supports the ability to pass arbitrary code through the compiler without being touched, for compatibility with other variants of Python, such as Cython or Mython. Anything placed between \( and the corresponding close parenthesis will be passed through, as well as any line starting with \\, which will have the additional effect of allowing indentation under it.

\\cdef f(x):
    return x |> g

cdef f(x):
    return g(x)

Enhanced Parenthetical Continuation¶

Since Coconut syntax is a superset of Python 3 syntax, Coconut supports the same line continuation syntax as Python. That means both backslash line continuation and implied line continuation inside of parentheses, brackets, or braces will all work.

In Python, however, there are some cases (such as multiple with statements) where only backslash continuation, and not parenthetical continuation, is supported. Coconut adds support for parenthetical continuation in all these cases.

Supporting parenthetical continuation everywhere allows the PEP 8 convention, which avoids backslash continuation in favor of implied parenthetical continuation, to always be possible to follow. From PEP 8:

The preferred way of wrapping long lines is by using Python’s implied line continuation inside parentheses, brackets and braces. Long lines can be broken over multiple lines by wrapping expressions in parentheses. These should be used in preference to using a backslash for line continuation.

Note: Passing --strict will enforce the PEP 8 convention by disallowing backslash continuations.

with (open('/path/to/some/file/you/want/to/read') as file_1,
      open('/path/to/some/file/being/written', 'w') as file_2):
    file_2.write(file_1.read())