3.21. kink/TRACE

The companion mod for trace vals.

3.21.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?

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

Trace.have_sym?

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

Trace.sym

Trace.sym returns the sym of the Trace.

Precondition:

• Trace must have a sym

Trace.have_loc?

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

Trace.loc

Trace.loc returns the loc of the Trace.

Precondition:

• 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

Trace.desc returns a str which describes the Trace.

Example:

:LOC.require_from('kink/')
:TRACE.require_from('kink/')

: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)"

stdout.print_line(TRACE.snip.desc.repr)
# => "[..snip..]"

3.21.2. TRACE.trace?(Val)

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

3.21.3. TRACE.snip

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

3.21.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.

Example:

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

3.21.5. TRACE.format_traces(Msg Traces)

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

Preconditions:

• Msg must be a str val

• Traces must be a vec of traces

Example:

:TRACE.require_from('kink/')
:CONTROL.require_from('kink/')

CONTROL.try(
  { 10 / 0 }
  {(:R) raise('must not reach here') }
  {(:Msg :Traces)
    TRACE.format_traces(Msg Traces).each{(:Line)
      stdout.print_line(Line)
    }
  }
)
# Output:
#   exception traces: from oldest to newest
#   [launch]
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L195 C11 try] CONTROL.-->try(
#   [builtin:kink-mods/kink/CONTROL.kn L201 C14 reset] :handler = -->reset('kink/CONTROL-try'){
#   [builtin:kink-mods/kink/CONTROL.kn L202 C10 body] :R = -->body
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L197 C7 start] -->start(Non_opts)
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L132 C19 if_else] Non_opts.empty?.-->if_else(
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L140 C7 _run_script] -->_run_script($script_fun Script_args)
#   [builtin:kink-mods/kink/_launch/LAUNCH_KINK.kn L123 C3 script_fun] -->script_fun(Env)
#   [(stdin) L4 C9 try] CONTROL.-->try(
#   [builtin:kink-mods/kink/CONTROL.kn L201 C14 reset] :handler = -->reset('kink/CONTROL-try'){
#   [builtin:kink-mods/kink/CONTROL.kn L202 C10 body] :R = -->body
#   [(stdin) L5 C8 op_div] { 10 -->/ 0 }
#   exception message: Num.op_div: zero division: 10 is divided by 0