3.19. kink/TRACE

The companion mod for trace vals.

3.19.1. type trace

A trace val is an element of a stack trace.

A trace val consists of the following components. Both are optional.

• sym: a str val; usually the sym of the called fun.

• loc: a loc val; usually the loc where the invocation occurred.


Trace.snip? returns whether the Trace is a SNIP trace, which contains neither a sym nor a loc.


Trace.have_sym? returns whether the Trace has a sym.


Trace.sym returns the sym of the Trace.


• Trace must have a sym


Trace.have_loc? returns whether the Trace has a loc.


Trace.loc returns the loc of the Trace.


• Trace must have a loc.

Trace.op_eq(Arg_trace) Trace.op_ne(Arg_trace)

Trace.op_eq and op_ne returns whether the two traces are equal.

Two traces are equal when and only when:

• Both have a sym and a loc, the syms are equal and the locs are equal, or

• Both have a sym and no loc, and the syms are equal, or

• Both have a loc and no sym, and the locs are equal, or

• Both do not have a sym or a loc


Trace.desc returns a str which describes the Trace.



:Loc <- LOC.new('foo.kn' 'foo(bar)' 4)

stdout.print_line(TRACE.new{(:T) T.sym('bar') T.loc(Loc) }.desc.repr)
# => "[foo.kn L1 C5 bar] foo(-->bar)"

stdout.print_line(TRACE.new{(:T) T.sym('bar') }.desc.repr)
# => "[bar]"

stdout.print_line(TRACE.new{(:T) T.loc(Loc) }.desc.repr)
# => "[foo.kn L1 C5] foo(-->bar)"

# => "[..snip..]"

3.19.2. TRACE.trace?(Val)

TRACE.trace? returns whether the Val is a trace val.

3.19.3. TRACE.snip

TRACE.snip returns the snip trace, which contains neither a sym nor a loc.

3.19.4. TRACE.new(...[$config = {}])

TRACE.new makes a trace.

$config is called with a Conf, to configure the trace.

The Conf has two methods.

• Conf.sym(Sym): gives the sym of the trace.

• Conf.loc(Loc): gives the loc of the trace.


:Trace <- TRACE.new{(:T)
  T.loc(LOC.new('foo.kn' '10+20' 2))
stdout.print_line(Trace.repr) # => Trace(op_add Loc(foo.kn L1 C3))

3.19.5. TRACE.format_traces(Msg Traces)

TRACE.format returns an iter of lines describing Msg and Traces of an exception.


• Msg must be a str val

• Traces must be a vec of traces


{ 10 / 0 }.try(
  {(:R) raise('must not reach here') }
  {(:Msg :Traces)
    TRACE.format_traces(Msg Traces).each{(:Line)
# Output:
#   [launch]
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L192 C5 try] }.-->try(
#   [reset]
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L191 C5 start] -->start(Non_opts)
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L127 C19 if_else] Non_opts.empty?.-->if_else(
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L135 C7 _run_script] -->_run_script($script_fun Script_args)
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L121 C3 script_fun] -->script_fun(Env)
#   [(stdin) L2 C15 try] { 10 / 0 }.-->try(
#   [reset]
#   [(stdin) L2 C9 op_div] { 10 -->/ 0 }.try(
#   exception message: Num.op_div: zero division: 10 is divided by 0