# dissect

1.0.0

A lib for introspecting the call stack and active restarts.

## About Dissect

Dissect is a small library for introspecting the call stack and active restarts.

## Supported Implementations

Since the call stack and restart inspection are not part of ANSI CL, pretty much all of Dissect is implementation-dependant. Currently the following implementations are supported:

- ABCL
- Allegro
- CCL
- CLISP
- ECL
- SBCL

## How To

Retrieving a list of restart objects is done through `restarts`. Similarly, the current stack can be seen with `stack`. Returned by both are a list of objects, from which you can read out information. Depending on the implementation, additional slots may be included.

    (dissect:stack)
    ; => (#<CCL-CALL [0] CALL-CHECK-REGS | ccl:l1;l1-readloop.lisp.newest:827> #<CCL-CALL [1] CHEAP-EVAL | ...)

    (dissect:restarts)
    ; => (#<CCL-RESTART [SWANK::RETRY] "Retry SLIME REPL evaluation request."> #<CCL-RESTART [ABORT] ...)

    (dissect:form (first (dissect:stack)))
    ; => (DEFUN CALL-CHECK-REGS (FN &REST ARGS) ...)

    (dissect:restart (first (dissect:restarts)))
    ; => CCL:SIMPLE-RESTART

You can also get a fancy print of calls, restarts, conditions, or the current state using `present`:

    (dissect:present T)

    (handler-bind ((error #'dissect:present))
      (error "Hello!"))

Sometimes having the full stack shown gives you a lot of noise and uninteresting information. To limit this --and thus make the stacks dissect returns cleaner-- you can use `with-truncated-stack` and `with-capped-stack`. Those will ensure that only frames above and below the respective macros are shown. Similarly, those can easily lead to completely empty stack reports, so make sure to only use them where you are absolutely sure that you will not need the information anymore.

When you need to capture the current environment because for later processing, you can use `capture-environment`. This will return an object that contains the current stack, restarts, thread, and an optional condition object. Using this, the entire environment surrounding an error can be saved. `present` also works with an `environment` object.

## System Information

Version: 1.0.0
Author: Nicolas Hafner
License: Artistic
Homepage: https://github.com/Shinmera/dissect

## Definition Index

- ### DISSECT

  - ORG.TYMOONNEXT.DISSECT
  Source
  No documentation provided.
  - EXTERNAL CLASS

    #### CALL

    Source

        Class container for stack frame information.

        See POS
        See CALL
        See ARGS
        See FILE
        See LINE
        See FORM

  - EXTERNAL CLASS

    #### ENVIRONMENT

    Source

        Container class for a current "environment".

        An instance of this class is intended to represent most of the runtime
        environment present at a particular point. It is useful for stashing away
        debug information for inspection at a later date.

        See CAPTURE-ENVIRONMENT
        See ENVIRONMENT-CONDITION
        See ENVIRONMENT-STACK
        See ENVIRONMENT-RESTARTS
        See ENVIRONMENT-THREAD

  - EXTERNAL CLASS

    #### RESTART

    Source

        Class container for restart information.

        See NAME
        See REPORT
        See RESTART
        See OBJECT
        See INTERACTIVE
        See TEST
        See INVOKE

  - EXTERNAL CLASS

    #### UNAVAILABLE-ARGUMENT

    Source

        Used to represent an argument that isn't available in the environment.

        Instances of this class are printed as #<Unavailable>

  - EXTERNAL CLASS

    #### UNKNOWN-ARGUMENTS

    Source

        Used to represent an unknown list of arguments.

        Instances of this class are printed as #<Unknown Arguments>

  - EXTERNAL FUNCTION

    #### CAPTURE-ENVIRONMENT

    - &OPTIONAL
    - CONDITION
    Source

        Capture the current environment into an environment object.

        See ENVIRONMENT

  - EXTERNAL FUNCTION

    #### PRESENT

    - THING
    - &OPTIONAL
    - (DESTINATION T)
    Source

        Prints a neat representation of THING to DESTINATION.

        DESTINATION can be one of the following types:
          (eql NIL)  --- The representation is printed and returned as a string.
          (eql T)    --- The representation is printed to *STANDARD-OUTPUT*.
          STREAM     --- The representation is printed to the stream.

        THING can be one of the following types:
          RESTART      --- Restarts are presented as:
                             [NAME] REPORT
          CALL         --- Calls are presented as:
                             POS (CALL ARGS..)
          ENVIRONMENT  --- Environments are presented as a multiline description
                           of all the parts it references (condition, stack,
                           restarts, thread).
          CONDITION    --- Conditions are presented as:
                             CONDITION
                               [Condition of type TYPE]
          (EQL T)      --- Presents the environment at point using
                           CAPTURE-ENVIRONMENT.
          LIST         --- The list can contain either restarts or calls. In both
                           cases the behaviour is to output a header line, followed
                           by the presentation of each item in the list on its own
                           line.

        Internally the function PRESENT-OBJECT is used to perform the actual
        printing.

        See RESTART
        See CALL
        See ENVIRONMENT
        See CONDITION
        See CAPTURE-ENVIRONMENT
        See PRESENT-OBJECT

  - EXTERNAL FUNCTION

    #### RESTARTS

    Source

        Returns a list of RESTART objects describing the currently available restarts.

        Returns an empty list on unsupported platforms.

        See RESTART

  - EXTERNAL FUNCTION

    #### STACK

    Source

        Returns a list of CALL objects describing the stack from the point where this function was called.

        This excludes the call to STACK itself.
        Any calls above a WITH-CAPPED-STACK form, and below a WITH-TRUNCATED-STACK
        form are also excluded.

        Returns an empty list on unsupported platforms.

        See CALL
        See WITH-TRUNCATED-STACK
        See WITH-CAPPED-STACK

  - EXTERNAL GENERIC-FUNCTION

    #### ARGS

    - OBJECT

        Returns a list of arguments that were used in the frame call.

        If the arguments list is not available, this may also return an instance
        of UNKNOWN-ARGUMENTS. The values in the list may be instances of
        UNAVAILABLE-ARGUMENT if the argument is unknown or could not be captured
        for some reason.

        See UNKNOWN-ARGUMENTS
        See UNAVAILABLE-ARGUMENT
        See CALL

  - EXTERNAL GENERIC-FUNCTION

    #### CALL

    - OBJECT

        Returns the stack call function.

        Can be either a function object or the name of a global function.

        See CALL

  - EXTERNAL GENERIC-FUNCTION

    #### ENVIRONMENT-CONDITION

    - OBJECT

        Returns the condition stored in the environment (if any).

        See CL:CONDITION
        See ENVIRONMENT

  - EXTERNAL GENERIC-FUNCTION

    #### ENVIRONMENT-RESTARTS

    - OBJECT

        Returns a list of restarts stored in the environment (if any).

        See CL:RESTART
        See ENVIRONMENT

  - EXTERNAL GENERIC-FUNCTION

    #### ENVIRONMENT-STACK

    - OBJECT

        Returns a list of calls stored in the environment (if any).

        See CALL
        See ENVIRONMENT

  - EXTERNAL GENERIC-FUNCTION

    #### ENVIRONMENT-THREAD

    - OBJECT

        Returns the thread stored in the environment (if any).

        See SB-THREAD:THREAD
        See THREADS:THREAD
        See MP:PROCESS
        See MT:THREAD
        See CCL:PROCESS
        See PROCESS:PROCESS
        See THREAD:THREAD
        See ENVIRONMENT

  - EXTERNAL GENERIC-FUNCTION

    #### FILE

    - OBJECT

        If possible, returns the file the called function is defined in.

        See CALL

  - EXTERNAL GENERIC-FUNCTION

    #### FORM

    - OBJECT

        If possible, returns the actual definition form of the function.

        See CALL

  - EXTERNAL GENERIC-FUNCTION

    #### INVOKE

    - RESTART
    - &REST
    - ARGS
    Source

        Invoke the restart that the restart object references.

        See RESTART

  - EXTERNAL GENERIC-FUNCTION

    #### LINE

    - OBJECT

        If possible, returns the line number in the file where the function is defined.

        See CALL

  - EXTERNAL GENERIC-FUNCTION

    #### NAME

    - OBJECT

        Returns the restart's symbol. Use this for INVOKE-RESTART.

        See RESTART

  - EXTERNAL GENERIC-FUNCTION

    #### OBJECT

    - OBJECT

        Returns the platform-internal restart object.

        See RESTART

  - EXTERNAL GENERIC-FUNCTION

    #### POS

    - OBJECT

        Returns the position of the call on the stack.

        See CALL

  - EXTERNAL GENERIC-FUNCTION

    #### PRESENT-OBJECT

    - THING
    - STREAM
    Source

        Internal generic function for pretty printing.

        See PRESENT

  - EXTERNAL GENERIC-FUNCTION

    #### REPORT

    - OBJECT

        Returns the report string describing the restart's effects.

        See RESTART

  - EXTERNAL GENERIC-FUNCTION

    #### RESTART

    - OBJECT

        Returns a symbol to the restart-function or a direct function-object.

        See RESTART

  - EXTERNAL MACRO

    #### WITH-CAPPED-STACK

    - &BODY
    - BODY
    Source

        Calls BODY in an environment where a call to STACK will not report frames further up.

        See STACK

  - EXTERNAL MACRO

    #### WITH-TRUNCATED-STACK

    - &BODY
    - BODY
    Source

        Calls BODY in an environment where a call to STACK will not report frames further down.

        See STACK