Software that keeps running while it is broken

%% Three functions, three different stories about failure.
-module(why_specs).
-export([greet/1, find_age/2, start/0]).

%% A spec is a promise to Dialyzer, not to the compiler. It is checked
%% statically by a separate tool, and it is worth writing anyway.
-spec greet(binary()) -> binary().
greet(Name) ->
    <<"Hello, ", Name/binary, "!">>.

%% Erlang returns a tagged tuple instead of raising for an expected miss.
%% The caller has to match on it, so the missing case is hard to forget.
-spec find_age(atom(), [{atom(), integer()}]) -> {ok, integer()} | not_found.
find_age(Name, People) ->
    case lists:keyfind(Name, 1, People) of
        {Name, Age} -> {ok, Age};
        false -> not_found
    end.

%% This one talks to the world. Nothing in the type system stops it, but the
%% process it runs in is isolated, so when it fails it takes nothing else
%% down with it.
-spec start() -> ok.
start() ->
    io:format("~s~n", [greet(<<"world">>)]).

# The version manager everyone ends up using. It handles Erlang and Elixir
# side by side and keeps a per project version in a .tool-versions file.
asdf plugin add erlang
asdf install erlang 27.2
asdf global erlang 27.2

# Or through a package manager, if you do not need to switch versions.
#   macOS         brew install erlang rebar3
#   Debian        apt install erlang
#   Fedora        dnf install erlang
#   Windows       winget install Erlang.ErlangOTP

# rebar3 is the build tool. It is a single self contained escript.
curl -fsSL -o rebar3 https://s3.amazonaws.com/rebar3/rebar3
chmod +x rebar3 && mv rebar3 ~/.local/bin/

erl -version
rebar3 --version

%% Every file is a module, and the module name must match the file name.
-module(hello).

%% Only exported functions can be called from outside. The number after the
%% slash is the arity: how many arguments the function takes.
-export([start/0]).

start() ->
    io:format("Hello from the BEAM.~n"),
    io:format("This node is ~p and I am ~p.~n", [node(), self()]).

# Start the shell. This boots a whole virtual machine, so everything you can
# do in production you can do here.
erl

# Compile a file from the command line instead.
erlc hello.erl        # produces hello.beam
erl -noshell -s hello start -s init stop

# A standalone script, with no compile step and no project around it.
cat > greet.escript <<'SCRIPT'
#!/usr/bin/env escript
main([Name]) -> io:format("hello ~s~n", [Name]);
main(_) -> io:format("usage: greet NAME~n").
SCRIPT
chmod +x greet.escript && ./greet.escript world

1> 2 + 2 * 10.
22
2> X = 42.
42
3> X = 43.
** exception error: no match of right hand side value 43
4> f(X).
ok
5> X = 43.
43
6> Person = #{name => <<"Ada">>, age => 36}.
#{age => 36,name => <<"Ada">>}
7> maps:get(name, Person).
<<"Ada">>
8> c(counter).
{ok,counter}
9> Pid = counter:start().
<0.94.0>
10> counter:add(Pid, 5).
ok
11> counter:value(Pid).
5
12> i().
13> q().

%% Every value in the comparison table, in one module that compiles.
-module(rosetta).
-export([examples/0]).

-record(user, {id, name, admin = false}).

examples() ->
    Count = 42,
    Ratio = 3.14,

    %% An atom is a constant whose name is its value. Lowercase.
    Status = ok,

    %% A string is a list of integers. Convenient, and slow for big text.
    Label = "hi",

    %% A binary is a packed byte array. This is what you want for real text.
    Text = <<"hi">>,

    %% A tuple is a fixed size record of values, usually tagged with an atom.
    Result = {ok, 200},

    %% A list is a linked list. Any element type, and mixing them is allowed.
    Nums = [1, 2, 3],

    %% A map is the dictionary. => inserts or updates, := only updates.
    Ages = #{ada => 36, grace => 45},

    %% A record is a tuple with named fields, resolved at compile time.
    User = #user{id = 1, name = <<"Ada">>},

    %% A process identifier. There is no equivalent in Python or JavaScript.
    Me = self(),

    %% A function value. fun with an end, or a reference to a named function.
    Double = fun(X) -> X * 2 end,
    ToList = fun erlang:integer_to_list/1,

    {Count, Ratio, Status, Label, Text, Result, Nums, Ages, User, Me,
     Double(21), ToList(7)}.

-module(terms).
-export([atoms/0, numbers/0, strings/0, tuples/0, lists_of/0, maps_of/0,
         binaries/0, comparison/0]).

%% Atoms are constants. They cost one word and comparing them is a pointer
%% comparison, which is why Erlang tags everything with them.
atoms() ->
    [ok, error, undefined, 'an atom with spaces', true, false].

%% Integers are arbitrary precision. There is no overflow to worry about.
numbers() ->
    Big = 1 bsl 200,
    [17, -3, 2#1010, 16#ff, $A, 3.5, Big div 3].

%% "abc" is exactly [97, 98, 99]. That is worth knowing before it surprises
%% you in the shell.
strings() ->
    Chars = "abc",
    Same = [$a, $b, $c],
    {Chars =:= Same, length(Chars)}.

%% Tuples are fixed size and fast to read by position. Tagging them with an
%% atom in the first slot is the convention that makes matching readable.
tuples() ->
    Point = {point, 3, 4},
    {point, X, Y} = Point,
    {X, Y, element(2, Point), tuple_size(Point)}.

lists_of() ->
    L = [1, 2, 3],
    { [0 | L]              %% cons, cheap
    , L ++ [4]             %% append, walks the left list, so avoid in a loop
    , lists:reverse(L)
    , lists:sum(L)
    , length(L)
    }.

%% Maps are the modern dictionary. => works whether or not the key exists,
%% := demands that it does, which turns a typo into an immediate crash.
maps_of() ->
    M = #{name => <<"Ada">>, age => 36},
    Older = M#{age := 37},
    WithEmail = M#{email => <<"ada@example.com">>},
    { maps:get(name, M)
    , maps:get(nickname, M, none)   %% with a default
    , maps:is_key(age, M)
    , maps:keys(Older)
    , maps:size(WithEmail)
    }.

%% Binaries are contiguous memory. Pattern matching on them is how Erlang
%% parses network protocols in a few lines.
binaries() ->
    Bin = <<"hello world">>,
    <<First:5/binary, " ", Rest/binary>> = Bin,
    Packet = <<1:8, 4096:16, 7:8>>,
    <<Version:8, Length:16, Type:8>> = Packet,
    {First, Rest, byte_size(Bin), Version, Length, Type}.

%% Every term is comparable, and the order between types is fixed:
%% number < atom < reference < fun < port < pid < tuple < map < list < binary
comparison() ->
    lists:sort([<<"bin">>, [1, 2], {a, b}, ok, 42, #{}]).

-module(matching).
-export([bind/0, destructure/1, http_message/1, describe/1, first_error/1,
         area/1]).

%% = is not assignment. It asserts that both sides match, and binds any
%% unbound variables on the way. Binding a variable twice to different values
%% is a badmatch error, not an overwrite.
bind() ->
    X = 1,
    1 = X,          %% fine, both sides are 1
    {ok, Value} = {ok, 42},
    Value.

%% Taking a value apart is the same operation as testing its shape.
destructure(Response) ->
    case Response of
        {ok, #{body := Body, status := 200}} -> {success, Body};
        {ok, #{status := Status}} -> {unexpected, Status};
        {error, timeout} -> retry;
        {error, Reason} -> {give_up, Reason}
    end.

%% Function clauses are pattern matching spread across several definitions.
%% The runtime tries them top to bottom.
http_message(200) -> "OK";
http_message(404) -> "Not Found";
http_message(500) -> "Server Error";
http_message(Code) when is_integer(Code) -> "Status " ++ integer_to_list(Code).

%% Matching on list shapes. [H | T] splits off the first element.
describe([]) -> "nothing";
describe([X]) -> "just " ++ X;
describe([X, Y]) -> X ++ " and " ++ Y;
describe([X | Rest]) -> X ++ " and " ++ integer_to_list(length(Rest)) ++ " more".

%% A variable used twice in one pattern means "these two must be equal".
%% Nothing else in mainstream languages does this.
first_error([{error, Reason}, {error, Reason} | _]) -> {repeated, Reason};
first_error([{error, Reason} | _]) -> {first, Reason};
first_error([_ | Rest]) -> first_error(Rest);
first_error([]) -> none.

%% Guards restrict a clause further. Only a fixed set of side effect free
%% tests is allowed in one, which is why they can never fail halfway.
area({circle, R}) when R > 0 -> math:pi() * R * R;
area({rectangle, W, H}) when W > 0, H > 0 -> W * H;
area({square, S}) when S > 0 -> S * S.

1> {ok, Value} = {ok, 42}.
{ok,42}
2> Value.
42
3> {ok, Other} = {error, timeout}.
** exception error: no match of right hand side value {error,timeout}
4> [Head | Tail] = [1, 2, 3].
[1,2,3]
5> {Head, Tail}.
{1,[2,3]}
6> <<Version:8, Rest/binary>> = <<1, "payload">>.
<<1,112,97,121,108,111,97,100>>
7> {Version, Rest}.
{1,<<"payload">>}
8> #{name := Name} = #{name => <<"Ada">>, age => 36}.
#{age => 36,name => <<"Ada">>}
9> Name.
<<"Ada">>
10> [First, First | _] = [a, a, b].
[a,a,b]
11> [First, First | _] = [a, b, c].
** exception error: no match of right hand side value [a,b,c]

-module(functions).
-export([double/1, area/2, classify/1, bmi_tell/2, cylinder_area/2,
         add_one_to_all/1, apply_twice/2, make_adder/1, pipeline/1]).

double(X) -> X * 2.

%% Arguments are positional and the arity is part of the name. area/2 and
%% area/3 are two different functions that happen to share a spelling.
area(Width, Height) -> Width * Height.

%% Guards choose between clauses. They run left to right and the first that
%% holds wins. A comma in a guard means and, a semicolon means or.
classify(N) when N < 0 -> negative;
classify(0) -> zero;
classify(N) when N < 10 -> small;
classify(_) -> large.

%% There is no `where`. Intermediate values are just variables, and since
%% each one is bound exactly once, reading top to bottom always tells the
%% truth about what they hold.
bmi_tell(Weight, Height) ->
    Bmi = Weight / (Height * Height),
    Verdict =
        if
            Bmi =< 18.5 -> underweight;
            Bmi =< 25.0 -> normal;
            true -> overweight      %% `true` is the else branch
        end,
    {Verdict, Bmi}.

cylinder_area(Radius, Height) ->
    Side = 2 * math:pi() * Radius * Height,
    Cap = math:pi() * Radius * Radius,
    Side + 2 * Cap.

add_one_to_all(Numbers) ->
    lists:map(fun(N) -> N + 1 end, Numbers).

%% Functions are values. A fun can be passed, stored in a map, or sent to
%% another process on another machine.
apply_twice(Fun, Value) -> Fun(Fun(Value)).

%% A fun closes over the variables around it, which is how you get something
%% that behaves like partial application.
make_adder(N) ->
    fun(X) -> X + N end.

%% There is no composition operator, so a pipeline is either nested calls or
%% a fold over a list of funs.
pipeline(Value) ->
    Steps = [fun(X) -> X * 2 end, fun(X) -> X + 1 end, fun integer_to_list/1],
    lists:foldl(fun(Step, Acc) -> Step(Acc) end, Value, Steps).

-module(lists_demo).
-export([basics/0, comprehensions/0, pythagorean/0, initials/1, folds/1,
         keyfind_demo/0, higher_order/0]).

basics() ->
    Primes = [2, 3, 5, 7, 11],
    { [1 | Primes]                  %% cons is O(1)
    , lists:nth(2, Primes)          %% indexing is O(n), so avoid it in loops
    , lists:seq(1, 10)
    , lists:seq(10, 1, -1)
    , lists:sublist(Primes, 3)
    , lists:last(Primes)
    }.

%% A comprehension is a generator, some filters and an expression. It reads
%% the same way as the Python version and compiles to a plain recursion.
comprehensions() ->
    Squares = [N * N || N <- lists:seq(1, 10)],
    Evens = [N || N <- lists:seq(1, 20), N rem 2 =:= 0],

    %% A pattern in a generator quietly skips anything that does not match,
    %% which is the neatest way to filter and destructure at once.
    People = [{ada, 36}, {grace, 45}, unknown, {alan, 41}],
    Names = [Name || {Name, _Age} <- People],

    {Squares, Evens, Names}.

pythagorean() ->
    [{A, B, C}
     || C <- lists:seq(1, 20),
        B <- lists:seq(1, C),
        A <- lists:seq(1, B),
        A * A + B * B =:= C * C].

initials(Sentence) ->
    [Char || [Char | _] <- string:tokens(Sentence, " ")].

%% foldl is the workhorse. foldr exists but builds the whole call stack, so
%% for anything long reach for foldl and reverse at the end if order matters.
folds(Numbers) ->
    Sum = lists:foldl(fun(X, Acc) -> X + Acc end, 0, Numbers),
    Max = lists:foldl(fun erlang:max/2, hd(Numbers), Numbers),
    Reversed = lists:foldl(fun(X, Acc) -> [X | Acc] end, [], Numbers),
    {Sum, Max, Reversed}.

%% Lists of tagged tuples are everywhere in Erlang, and the keyX functions
%% are how you work with them.
keyfind_demo() ->
    People = [{ada, 36}, {grace, 45}],
    { lists:keyfind(ada, 1, People)
    , lists:keyfind(alan, 1, People)          %% false, not an exception
    , lists:keystore(alan, 1, People, {alan, 41})
    , lists:keydelete(ada, 1, People)
    , proplists:get_value(age, [{age, 36}], 0)
    }.

higher_order() ->
    Words = ["ada", "grace", "alan", "barbara"],
    { lists:map(fun string:to_upper/1, Words)
    , lists:filter(fun(W) -> length(W) =< 4 end, Words)
    , lists:any(fun(W) -> length(W) > 6 end, Words)
    , lists:all(fun(W) -> length(W) > 2 end, Words)
    , lists:sort(fun(A, B) -> length(A) =< length(B) end, Words)
    , lists:partition(fun(W) -> length(W) =< 4 end, Words)
    , lists:zip([1, 2, 3], [a, b, c])
    }.

-module(recursion).
-export([factorial/1, sum/1, sum_tail/1, reverse/1, quicksort/1, fib/1,
         collatz/1, count_down/1]).

%% The base case first, then the case that makes the problem smaller.
factorial(0) -> 1;
factorial(N) when N > 0 -> N * factorial(N - 1).

%% Body recursive: the addition happens after the recursive call returns, so
%% the stack grows with the length of the list.
sum([]) -> 0;
sum([Head | Tail]) -> Head + sum(Tail).

%% Tail recursive: the recursive call is the last thing that happens, so the
%% BEAM reuses the same stack frame. This runs in constant space over a list
%% of any length, and it is the shape almost all Erlang loops take.
sum_tail(Numbers) -> sum_tail(Numbers, 0).

sum_tail([], Acc) -> Acc;
sum_tail([Head | Tail], Acc) -> sum_tail(Tail, Head + Acc).

%% The accumulator replaces the variable you would have mutated. Building the
%% result backwards and reversing once at the end is idiomatic and fast.
reverse(List) -> reverse(List, []).

reverse([], Acc) -> Acc;
reverse([Head | Tail], Acc) -> reverse(Tail, [Head | Acc]).

%% Readable rather than fast, exactly like the Haskell one liner. For real
%% work call lists:sort/1, which is a well tuned merge sort.
quicksort([]) -> [];
quicksort([Pivot | Rest]) ->
    quicksort([X || X <- Rest, X =< Pivot])
        ++ [Pivot]
        ++ quicksort([X || X <- Rest, X > Pivot]).

fib(N) -> fib(N, 0, 1).

fib(0, A, _B) -> A;
fib(N, A, B) when N > 0 -> fib(N - 1, B, A + B).

collatz(1) -> [1];
collatz(N) when N rem 2 =:= 0 -> [N | collatz(N div 2)];
collatz(N) -> [N | collatz(3 * N + 1)].

%% A loop that only does side effects still returns something. ok is the
%% conventional "nothing useful to say" value.
count_down(0) ->
    io:format("liftoff~n"),
    ok;
count_down(N) when N > 0 ->
    io:format("~p...~n", [N]),
    count_down(N - 1).

-module(shapes).
-export([new_user/2, promote/1, describe/1, update_settings/2, totals/1,
         to_map/1, from_map/1]).

%% A record is a tuple with named fields. The names are erased at compile
%% time, so access is as fast as element/2 and costs nothing at runtime.
-record(user, {id, name, email, admin = false}).

%% A map is checked at runtime and can grow new keys. Records are for fixed
%% internal structures, maps for anything that crosses a boundary.
new_user(Id, Name) ->
    #user{id = Id, name = Name, email = undefined}.

%% Updating a record copies it with some fields changed. The original is
%% still there, unchanged, for anyone else holding it.
promote(User) ->
    User#user{admin = true}.

describe(#user{name = Name, admin = true}) ->
    io_lib:format("~s (admin)", [Name]);
describe(#user{name = Name}) ->
    io_lib:format("~s", [Name]).

%% := requires the key to exist already, so a typo crashes here instead of
%% quietly adding a field nobody reads.
update_settings(Settings, Changes) ->
    maps:fold(fun(Key, Value, Acc) -> Acc#{Key := Value} end, Settings, Changes).

totals(Orders) ->
    lists:foldl(
        fun(#{item := Item, cost := Cost}, Acc) ->
            maps:update_with(Item, fun(Old) -> Old + Cost end, Cost, Acc)
        end,
        #{},
        Orders
    ).

%% Converting between the two is a couple of lines, and worth writing at the
%% edges of a system so records stay internal.
to_map(#user{id = Id, name = Name, email = Email, admin = Admin}) ->
    #{id => Id, name => Name, email => Email, admin => Admin}.

from_map(#{id := Id, name := Name} = Map) ->
    #user{
        id = Id,
        name = Name,
        email = maps:get(email, Map, undefined),
        admin = maps:get(admin, Map, false)
    }.

-module(errors).
-export([tagged/1, raising/1, catching/1, cleanup/1, custom/1, crash_it/0]).

%% Style one, and the one to reach for first: return a tagged tuple. An
%% expected failure is a value, so the caller has to match on it.
tagged(Input) ->
    case string:to_integer(Input) of
        {error, Reason} -> {error, Reason};
        {Number, _Rest} when Number < 0 -> {error, negative};
        {Number, _Rest} -> {ok, Number}
    end.

%% Style two: raise. There are three classes, and they mean different things.
%%   error : a bug. Something the code did not expect.
%%   exit  : this process is finished, deliberately.
%%   throw : a non local return, for control flow inside one module.
raising(bug) -> error(badarg);
raising(done) -> exit(normal);
raising(escape) -> throw({not_found, here});
raising(fine) -> ok.

%% try catches all three, and the pattern is Class:Reason:Stacktrace.
catching(Input) ->
    try raising(Input) of
        Result -> {returned, Result}
    catch
        error:Reason:Stack ->
            {caught_error, Reason, length(Stack)};
        exit:Reason ->
            {caught_exit, Reason};
        throw:Thrown ->
            {caught_throw, Thrown}
    end.

%% after always runs, whether or not something was raised. Use it to close
%% what you opened.
cleanup(Path) ->
    {ok, Handle} = file:open(Path, [read]),
    try
        file:read_line(Handle)
    after
        file:close(Handle)
    end.

%% Attaching context to a raise. The stacktrace keeps the original site.
custom(Value) ->
    try
        check(Value)
    catch
        error:Reason:Stack ->
            erlang:raise(error, {validation_failed, Value, Reason}, Stack)
    end.

check(Value) when is_integer(Value), Value > 0 -> ok;
check(_) -> error(not_a_positive_integer).

%% The fourth option, and often the right one: do not handle it. Let the
%% process die and let its supervisor start a clean one. Code that only
%% handles the cases it understands stays much shorter.
crash_it() ->
    {ok, Value} = {error, whatever},
    Value.

-module(processes).
-export([start/0, loop/1, call/2, cast/2, ping_pong/0, pong/0, spawn_many/1]).

%% spawn returns a process identifier immediately. The new process runs
%% ?MODULE:loop(0) and has its own heap, its own stack and its own mailbox.
%% It costs about 300 words to create, so making a million of them is a
%% design decision rather than a stunt.
start() ->
    spawn(?MODULE, loop, [0]).

%% This is the entire pattern for stateful code in Erlang: a function that
%% waits for a message, works out the new state, and calls itself with it.
%% The state is an argument, so nothing else can reach in and change it.
loop(Count) ->
    receive
        {increment, N} ->
            loop(Count + N);
        {value, From, Ref} ->
            From ! {reply, Ref, Count},
            loop(Count);
        stop ->
            ok
    after 300000 ->
        %% An idle timeout. Without one, a forgotten process waits forever.
        io:format("counter idle for five minutes, stopping~n"),
        ok
    end.

%% Asking for an answer means sending a message and waiting for the reply.
%% The unique reference is what stops an old, late reply from being mistaken
%% for this one, and the timeout is what stops the caller hanging forever.
%% Getting all three details right every time is why gen_server exists.
call(Pid, Request) ->
    Ref = make_ref(),
    Pid ! {Request, self(), Ref},
    receive
        {reply, Ref, Reply} -> {ok, Reply}
    after 5000 ->
        {error, timeout}
    end.

%% Fire and forget. The send always succeeds, even if the process is dead.
cast(Pid, Message) ->
    Pid ! Message,
    ok.

%% receive scans the mailbox for the first message that matches any clause,
%% which is why this works no matter what order the two messages arrive in.
ping_pong() ->
    Pong = spawn(?MODULE, pong, []),
    Pong ! {ping, self()},
    receive
        pong -> {ok, Pong}
    after 1000 ->
        {error, no_reply}
    end.

pong() ->
    receive
        {ping, From} ->
            From ! pong,
            pong();
        stop ->
            ok
    end.

%% A hundred thousand processes on a laptop, in well under a second.
spawn_many(N) ->
    Parent = self(),
    Started = erlang:monotonic_time(millisecond),
    [spawn(fun() -> Parent ! {done, self()} end) || _ <- lists:seq(1, N)],
    collect(N),
    erlang:monotonic_time(millisecond) - Started.

collect(0) -> ok;
collect(N) ->
    receive
        {done, _Pid} -> collect(N - 1)
    end.