The standard library asks awkward questions

Put some weight on the floorboards

I have started making a standard library. It has immediately begun asking questions the demonstrations were too polite to ask.

What happens when a file cannot be opened? What type should an empty collection carry? Does a generic method still know its element type after returning a new value?

A hand-picked example can walk around the compiler’s weak floorboards. A library eventually wants a cupboard placed on every one of them.

Let the call read naturally

Pooka’s library belongs in its own package. The intended imports are small and ordinary:

import pooka/list

main() {
  let doubled = [1, 2, 3]
    |> list.map(fn(n) { n * 2 })
  assert doubled == [2, 4, 6]
}

This is the shape I want library code to invite: the value comes first, and a transformation can follow it through a pipe. The pipe supplies the preceding value as the next function’s first argument. The collection operation still has to do its actual work.

Translate the answer at the boundary

platform operation
  -> Erlang return convention
  -> explicit Pooka success or error value
  -> public library API

A foreign function declaration is part of that contract. Its annotation must describe the value the bridge actually returns.

The BEAM already supplies useful machinery. Erlang can handle platform operations at an FFI boundary, while Pooka gives the resulting values a public API. There is no need to involve another BEAM language merely to reach a file or inspect an environment variable.

That boundary needs translation, not wishful thinking. An Erlang return convention and a Pooka Result are not automatically the same promise. Wrapping a failure in a pleasant function name does not make it stop being a failure.

I also want this library to use the language we are building: generics, immutable classes, pattern matching and functions passed as values. If everything retreats into foreign code, the compiler misses the examination.

The first shelves will be small. More interesting than their size is what happens when somebody puts a real program on them.

— Peregrine Finch