Support the 'format' option for 'traceback'

Author: chrzaszcz

README.md

@@ -350,7 +350,7 @@ Possible [options](https://hexdocs.pm/erlang_doctor/0.3.1/tr.html#t:tb_options/0
 - `order` - `top_down` (default), `bottom_up` - call order in each tracaback; only for the `list` format.
 - `limit` - positive integer or `infinity` (default) - limits the number of matched traces. The actual number of tracebacks returned can be smaller unless `output => all`
 
-There are also functions `tr:traceback/1` and `tr:traceback/2`. They set `limit` to one and return only one trace if it exists. The options for `tr:traceback/2` are the same as for `tr:traceback/2` except `limit` and `format` (which are not supported). Additionally, it is possible to pass a [`tr`](https://hexdocs.pm/erlang_doctor/0.3.1/tr.html#t:tr/0) record (or an index) as the first argument to `tr:traceback/1` or `tr:traceback/2` to obtain the traceback for the provided trace event.
+There are also functions `tr:traceback/1` and `tr:traceback/2`. They set `limit` to one and return only one trace if it exists. The options for `tr:traceback/2` are the same as for `tr:traceback/2` except `limit`. Additionally, it is possible to pass a [`tr`](https://hexdocs.pm/erlang_doctor/0.3.1/tr.html#t:tr/0) record (or an index) as the first argument to `tr:traceback/1` or `tr:traceback/2` to obtain the traceback for the provided trace event.
 
 ### Trace ranges for filtered traces: `ranges`
 

src/tr.erl

@@ -379,25 +379,25 @@ traceback(Pred) ->
 %% @doc Returns traceback of the first matching trace from {@link tr_source()}.
 %%
 %% Fails if no trace is matched.
-%% The options `limit' and `format' do not apply.
--spec traceback(pred(tr()) | index() | tr(), tb_options()) -> [tr()].
+%% The `limit' option does not apply.
+-spec traceback(pred(tr()) | index() | tr(), tb_options()) -> [tr()] | tr() | tb_tree().
 traceback(Index, Options) when is_integer(Index) ->
     traceback(fun(#tr{index = I}) -> Index =:= I end, Options);
 traceback(T = #tr{}, Options) ->
     traceback(fun(Tr) -> Tr =:= T end, Options);
 traceback(PredF, Options) when is_function(PredF, 1) ->
-    [TB] = tracebacks(PredF, Options#{limit => 1, format => list}),
-    TB.
+    [Result] = tracebacks(PredF, Options#{limit => 1}),
+    Result.
 
 %% @doc Returns tracebacks of all matching traces from `tab()'.
 %%
 %% @see tracebacks/2
--spec tracebacks(pred(tr())) -> [[tr()]] | [tb_tree()].
+-spec tracebacks(pred(tr())) -> [[tr()]].
 tracebacks(PredF) ->
     tracebacks(PredF, #{}).
 
 %% @doc Returns tracebacks of all matching traces from {@link tr_source()}.
--spec tracebacks(pred(tr()), tb_options()) -> [[tr()]] | [tb_tree()].
+-spec tracebacks(pred(tr()), tb_options()) -> [[tr()]] | [tr()] | [tb_tree()].
 tracebacks(PredF, Options) when is_map(Options) ->
     Tab = maps:get(tab, Options, tab()),
     Output = maps:get(output, Options, shortest),

test/tr_SUITE.erl

@@ -55,9 +55,11 @@ groups() ->
                   tb_longest,
                   tb_all,
                   tb_all_limit,
+                  tb_trees,
                   tb_tree,
                   tb_tree_longest,
-                  tb_roots]},
+                  tb_roots,
+                  tb_root]},
      {util, [contains,
              match,
              do,
@@ -454,17 +456,28 @@ tb_all_limit(_Config) ->
                   [#tr{data = [0]}, #tr{data = [2]}, #tr{data = [3]}, #tr{data = [4]}],
                   [#tr{data = [2]}, #tr{data = [3]}, #tr{data = [4]}]], TBs).
 
-tb_tree(_Config) ->
+tb_trees(_Config) ->
     tr:trace([{?MODULE, fib, 1}]),
     ?MODULE:fib(4),
     wait_for_traces(18),
     tr:stop_tracing(),
     TBs = tr:tracebacks(fun(#tr{event = return, data = N}) when N < 2 -> true end,
-                               #{format => tree}),
+                        #{format => tree}),
     ct:pal("~p~n", [TBs]),
     ?assertMatch([{#tr{data = [4]}, [{#tr{data = [3]}, [#tr{data = [2]},
                                                         #tr{data = [1]}]},
-                                     #tr{data = [2]}]}], TBs).
+                                      #tr{data = [2]}]}], TBs).
+
+tb_tree(_Config) ->
+    tr:trace([{?MODULE, fib, 1}]),
+    ?MODULE:fib(4),
+    wait_for_traces(18),
+    tr:stop_tracing(),
+    TB = tr:traceback(fun(#tr{event = return, data = N}) when N < 2 -> true end,
+                          #{format => tree}),
+    ct:pal("~p~n", [TB]),
+    ?assertMatch({#tr{data = [4]}, [{#tr{data = [3]}, [{#tr{data = [2]},
+                                                        [#tr{data = [1]}]}]}]}, TB).
 
 tb_tree_longest(_Config) ->
     tr:trace([{?MODULE, fib, 1}]),
@@ -488,17 +501,27 @@ tb_roots(_Config) ->
     wait_for_traces(18),
     tr:stop_tracing(),
 
+    Pred = fun(#tr{event = return, data = N}) when N < 2 -> true end,
+
     %% Option 1: call root/1 or roots/1 on a tree
-    TBs = tr:tracebacks(fun(#tr{event = return, data = N}) when N < 2 -> true end,
-                               #{format => tree}),
+    TBs = tr:tracebacks(Pred, #{format => tree}),
     Roots = tr:roots(TBs),
     ct:pal("Roots: ~p~n", [Roots]),
     ?assertMatch([#tr{data = [4]}], Roots),
     ?assertEqual(hd(Roots), tr:root(hd(TBs))),
 
     %% Option 2: directly use the root format
-    ?assertEqual(Roots, tr:tracebacks(fun(#tr{event = return, data = N}) when N < 2 -> true end,
-                                      #{format => root})).
+    ?assertEqual(Roots, tr:tracebacks(Pred, #{format => root})).
+tb_root(_Config) ->
+    tr:trace([{?MODULE, fib, 1}]),
+    ?MODULE:fib(4),
+    wait_for_traces(18),
+    tr:stop_tracing(),
+
+    Pred = fun(#tr{event = return, data = N}) when N < 2 -> true end,
+
+    Root = tr:traceback(Pred, #{format => root}),
+    ?assertMatch(#tr{data = [4]}, Root).
 
 simple_total(_Config) ->
     tr:trace([{?MODULE, factorial, 1}]),