dissect

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

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