Struct CallStack 

pub struct CallStack(pub Vec<StackElem>);

A call stack, saving the history of function calls.

Size

The callstack length is assumed to be smaller at most u32::MAX, which allows to store indices in a more compact way on the eval stack. Any method leading to a push that reaches this size will currently panic.

Tuple Fields

0: Vec<StackElem>

Implementations

impl CallStack

pub fn new() -> Self

pub fn enter_var(&mut self, id: LocIdent, pos: PosIdx)

Push a marker to indicate that a var was entered.

pub fn enter_app(&mut self, pos_table: &PosTable, pos: PosIdx)

Push a marker to indicate that an application was entered.

pub fn enter_fun(&mut self, pos_table: &PosTable, pos: PosIdx)

Push a marker to indicate that during the evaluation an application, the function part was finally evaluated to an expression of the form fun x => body, and that the body of this function was entered.

pub fn enter_field( &mut self, id: LocIdent, pos_record: PosIdx, pos_field: PosIdx, pos_access: PosIdx, )

Push a marker to indicate that a record field was entered.

pub fn group_by_calls( self: &CallStack, pos_table: &PosTable, files: &Files, ) -> (Vec<CallDescr>, Option<CallDescr>)

Process a raw callstack by aggregating elements belonging to the same call. Return a list of call descriptions from the most nested/recent to the least nested/recent, together with the last pending call, if any.

Recall that when a call f arg is evaluated, the following events happen:

1. arg is pushed on the evaluation stack.
2. f is evaluated.
3. Hopefully, the result of this evaluation is a function Func(id, body). arg is popped from the stack, bound to id in the environment, and body is entered.

For error reporting purpose, we want to be able to determine the chain of nested calls leading to the current code path at any moment. To do so, the Nickel abstract machine maintains a callstack via this basic mechanism:

1. When an application is evaluated, push a marker with the position of the application on the callstack.
2. When a function body is entered, push a marker with the position of the original application on the callstack.
3. When a variable is evaluated, push a marker with its name and position on the callstack.
4. When a record field is accessed, push a marker with its name and position on the callstack too.

Both field and variable are useful to determine the name of a called function, when there is one. The resulting stack is not suited to be reported to the user for the following reasons:

1. One call spans several items on the callstack. First the application is entered (pushing an App), then possibly variables or other application are evaluated until we eventually reach a function for the left hand side. Then body of this function is entered (pushing a Fun).
2. Because of currying, multi-ary applications span several objects on the callstack. Typically, (fun x y => x + y) arg1 arg2 spans two App and two Fun elements in the form App1 App2 Fun2 Fun1, where the position span of App1 includes the position span of App2. We want to group them as one call.
3. The callstack includes calls to builtin contracts. These calls are inserted implicitly by the abstract machine and are not written explicitly by the user. Showing them is confusing and clutters the call chain, so we get rid of them too.

This is the role of group_by_calls, which filter out unwanted elements and groups callstack elements into atomic call elements represented by CallDescr.

The final call description list is reversed such that the most nested calls, which are usually the most relevant to understand the error, are printed first.

Arguments

• stdlib_ids: the FileIds of the sources containing standard contracts, to filter their calls out.

pub fn len(&self) -> u32

Return the length of the callstack. Wrapper for callstack.0.len().

pub fn is_empty(&self) -> bool

Return whether the callstack is empty.

pub fn truncate(&mut self, len: usize)

Truncate the callstack at a certain size. Used e.g. to quickly drop the elements introduced during the strict evaluation of the operand of a primitive operator. Wrapper for callstack.0.truncate(len).

Trait Implementations

impl AsRef<Vec<StackElem>> for CallStack

fn as_ref(&self) -> &Vec<StackElem>

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for CallStack

fn clone(&self) -> CallStack

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CallStack

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CallStack

fn default() -> CallStack

Returns the “default value” for a type.

impl From<CallStack> for Vec<StackElem>

fn from(cs: CallStack) -> Self

Converts to this type from the input type.

impl PartialEq for CallStack

fn eq(&self, other: &CallStack) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for CallStack

impl StructuralPartialEq for CallStack