Skip to content

Pipes

x |> f() means f(x). The value on the left becomes the first argument of the call on the right. Pipes let you write a series of calls from top to bottom, instead of nesting them inside each other. Most Nomi code is written this way.

fn double(x: Int) -> Int
    x * 2
end

fn add(x: Int, y: Int) -> Int
    x + y
end

fn main()
    5 |> double() |> dbg

    5 |> add(3) |> dbg
end

When the call takes more arguments, you write the rest in the parentheses. 5 |> add(3) is add(5, 3).

Fine print

  • A stage is a call. 5 |> double is a pipe stage is a call: write `double()` , since a name without parentheses is a function value.
  • A lambda or a capture is a stage only after then or tap. 5 |> fn n -> n * 2 is an error that suggests then.
  • A variant stage names its enum: 5 |> Shape.Dot(). A bare .Dot() works only where the pipeline’s type is expected, as in s: Shape = 5 |> .Dot().
  • |> if and |> case may prefix the call that computes their operand: input |> case parse_id() is input |> parse_id() |> case, each above the same arms.

Spec: Pipes, Keyword stages.

A longer pipeline puts one stage on each line:

fn main()
    [1, 2, 3]
    |> Iter.map(fn n -> n * n)
    |> Iter.to_list()
    |> dbg
end

A pipeline reads best when it starts with the data and ends where the result is used. Here is the same calculation written both ways:

fn main()
    // inside-out
    dbg Iter.count(Iter.filter([1, 2, 3, 4, 5], &(&1 > 2)))

    // pipeline
    [1, 2, 3, 4, 5]
    |> Iter.filter(&(&1 > 2))
    |> Iter.count()
    |> dbg
end

Both give 3. The nested version runs from the inside out, so you read it backwards. The pipeline runs in the order you read it.

fn main()
    "  ada  "
    |> String.trim()
    |> then fn name -> "Hello, ${name}!"
    |> dbg
end

then calls a lambda, or a capture, with the piped value and passes on what it returns. Use it for a small step that no named function does. The lambda’s body ends at the next |>, so the stages after it are still part of the pipeline.

Fine print

  • A then capture may use &1 more than once, positional or named. The piped value is computed once: 3 |> then &add(&1, b: &1) is 6.
  • A second parameter is an error: the stage passes one value.
  • A lambda’s parameter is out of scope after its body ends. Using it in a later stage is an error whose help says to write the body below the ->, closed by end.
fn main()
    total =
        [3, 4]
        |> then fn xs ->
            xs |> Iter.map(&(&1 * 2)) |> Iter.sum()
        end
        |> then &(&1 + 1)

    dbg total // 15
end

Spec: The then stage.

A call stage takes the piped value as its first argument. To pass it as another argument, write the then stage with a capture, whose &1 is the piped value:

fn divide(x: Int, y: NonZeroInt) -> Int
    x / y
end

fn main()
    10 |> then &divide(100, &1) |> dbg
    100 |> then &divide(y: 4, x: &1) |> dbg
end

10 |> then &divide(100, &1) is divide(100, 10). A named argument can be &1 too: 100 |> then &divide(y: 4, x: &1) is divide(100, 4). The stage passes one value, so the capture takes one parameter. A bare &1 in a call stage, as in 10 |> divide(100, &1), is an error that suggests the then stage.

import std::io

fn main()
    shout =
        "go north now"
        |> String.words()
        |> tap fn words -> io.print("got ${Iter.count(words)} words")
        |> Iter.map(String.uppercase)
        |> String.join(" ")

    io.print(shout)
end

tap calls a lambda with the piped value and then passes the same value on. Use it for a side effect, such as logging. The lambda must return Unit. A function works by name too: |> tap io.print.

If a tap lambda returns some other value, the compiler reports an error and suggests then, because tap would throw that value away. To look at a value while debugging, a bare dbg stage is shorter. Use tap for effects the program keeps.

Fine print

  • A tap body may end in dbg, as a Unit function body may.
  • A ? inside the lambda exits the lambda, so its result is a Result or Maybe, not Unit, and the stage is rejected.
  • tap? is an error: tap passes its input on, so there is nothing for the ? to propagate. Use then?.

Spec: The tap stage.

A bare dbg stage prints the value and passes it on. A stage that starts with not negates the stage’s result: name |> not String.is_empty() is not String.is_empty(name).

A ? after a stage unwraps its Maybe or Result. It passes on the value inside a Some or an Ok. On None or Err, it returns that from the function straight away:

fn parse(text: String) -> Maybe<Int>
    text
    |> String.trim()
    |> String.to_int()?
    |> then &(&1 * 2)
    |> Some()
end

fn main()
    dbg parse("  21  ")
    dbg parse("abc")
end

When a then lambda’s result is what can fail, write then?: |> then? fn n -> half(n) passes on the value inside, or returns the None or Err from the function.

An assertion can check the result of a whole pipeline:

test "pipeline result is true"
    assert "  Ada Lovelace  "
        |> String.trim()
        |> String.contains("Ada")
end

if and case can take the piped value as well. Here the value becomes the first argument of String.contains, the call that computes the if condition. The case matches its arms against the piped value:

fn main()
    "Ada"
    |> if String.contains("A") then
        "initialed"
    else
        "plain"
    end
    |> dbg

    Some("Ada")
    |> case
        Some(name) -> "named ${name}"
        None       -> "missing"
    end
    |> dbg
end

Every example that uses Pipes

Scalars & Strings is next.