# `!`-notation, brought to Rust

This crate provides `bang!` macro, similar to [`!`-notation in Idris2](https://idris2.readthedocs.io/en/latest/tutorial/interfaces.html#notation).
With it, the following expression:

``` rust
bang!(!x + !y + z)
```

Gets desugared into

``` rust
x.and_then(|x| {
    y.and_then(|y| {
        x + y + z
    })
})
```

## What problem does this solve?

Rust provides neat containers to make error-handling easy and convenient.
However, sometimes one, like myself, can find themselves in a peculiar situation.

Suppose there is some function that produces an `Option`:

``` rust
fn some_func(x1: T1, x2: T2, x3: T3) -> Option<u32>
```

And you even have the arguments prepared to call the function.
However, there's a catch: the arguments were also produced in some way that made them wrapped in `Option`.
So, we only have `x1: Option<T1>`, `x2: Option<T2>` and `x3: Option<T3>` in our hands.
This, of course, prompts us to write something along the lines of:

``` rust
x1.and_then(|x1| {
    x2.and_then(|x2| {
        x3.and_then(|x3| {
            some_func(x1, x2, x3)
        })
    })
});
```

This looks horrible and requires us to write a lot of pointless symbols!
Luckily, programming language [Idris2](https://github.com/idris-lang/Idris2) (which I greatly adore) provides a nice solution to this problem.
It has a nice piece of syntactic sugar called [!-notation](https://idris2.readthedocs.io/en/latest/tutorial/interfaces.html#notation).
In Idris, the expression prefixed with `!` is lifted as high as possible and bound to a fresh name.
Then the original expression is replaced with this newly bound name.
Following the Idris documentation, it transforms the following expression

``` idris
f !(g !(print y) !x)
```

into

``` idris
do y' <- print y
   x' <- x
   g' <- g y' x'
   f g'
```

This crate provides a procedural macro that performs a similar transformation in Rust. Simply import it:
``` rust
use bang_notation::bang;
```

And then we could replace the unreadable mess we had originally written with a concise:

``` rust
bang!(some_func(!x1, !x2, !x3))
```

It would get desugared to the chain of `and_then`s we initially came up with.

## What can you use this with?

In Idris, `!`-notation can be used with arbitrary monads.
This Rust version aims to be as general as possible.
It is supposed to work with any type that provides `and_then` method with a suitable signature.
If you found any example where this doesn't work, let me know!

## Is this any better than `?` operator?

Yes! AFAIK, currently `?` operator works only with `Option` and `Result` types.
There is an [experimental `Try` trait](https://doc.rust-lang.org/std/ops/trait.Try.html) that could be used to overload `?` operator,
but it provides semantics different to `!`-notation in this crate.
Unlike `?`, `!`-notation is applicable to arbitrary types that provide a suitable interface for `and_then`.
As an example, you might want to take a look at `list001` test that uses a custom-written `List` monad.

## In what order are values bound?

The expressions marked with `!` are bound left-to-right, in order they are written in the source code.
In case of nested expressions marked with `!`, the inner expressions are bound first.
After that, they are replaced with new names in the outer expression, and the outer expression is bound.