Cursor objects

The core functionality that @ethdebug/pointers provides is the dereference(pointer: Pointer) function. This function returns a Cursor object.

/**
 * The result of dereferencing a pointer
 */
export interface Cursor {
  view(state: Machine.State): Promise<Cursor.View>;
}

A Cursor represents the closure around some pointer, generating concrete information about data locations and bytes only in consideration of a particular machine state.

Cursor views and regions

Viewing a Cursor with a machine state yields two key results:

• A collection of Cursor.Region objects representing the pointer in terms of fully-evaluated slots, offsets, conditionals, etc.

• A read(region: Cursor.Region): Promise<Data> method for reading bytes from the machine

Importantly, a Cursor.Region is a fully-evaluated Pointer.Region. While the schema allows pointer regions to define their slots, offsets, lengths, etc. using complex expressions that can reference internal variables and other regions, a Cursor.Region represents the runtime result of evaluating all these expressions: a specific range of bytes in a specific data location.

The full listing of namespace Cursor follows:

export namespace Cursor {
  /**
   * The result of viewing a Cursor with a given Machine.State
   */
  export interface View {
    /**
     * A collection of concrete Cursor.Regions; this is a plain array of
     * regions and also provides filtering/lookup of regions by name
     * (according to the scoping rules outlined in the specification)
     */
    regions: Cursor.Regions;

    /**
     * Read bytes from the machine state corresponding to the bytes range
     * for a particular concrete Cursor.Region
     */
    read(region: Cursor.Region): Promise<Data>;
  }

  /**
   * A Pointer region where all dynamic expressions have been replaced with
   * concrete bytes values.
   */
  export type Region<R extends Pointer.Region = Pointer.Region> = {
    [K in keyof R]: K extends "slot" | "offset" | "length"
      ? R[K] extends Pointer.Expression
        ? Data
        : R[K] extends Pointer.Expression | undefined
          ? Data | undefined
          : R[K]
      : R[K];
  }

  /**
   * A collection of concrete regions.
   *
   * This collection serves as a plain array of regions, for simple iteration
   * and whatever filtering.
   *
   * It also provides a couple interfaces of its own for accessing regions by
   * name.
   */
  export type Regions =
    & Cursor.Region[]
    & {
        /**
         * Obtain an ordered list of all regions with a particular name.
         *
         * This is useful, e.g., when looking to concatenate a series of
         * sequential regions that were generated by index from a list
         * collection
         */
        named(name: string): Cursor.Region[];

        /**
         * Retrieve the last concrete region generated with a particular name
         */
        lookup: { [name: string]: Cursor.Region };
      };
}