trivial-inspect

A portable toolkit for building inspectors

trivial-inspect exposes a set of utils useful in building inspectors akin to standard inspect and describe. The goal is to provide as much information as possible. Including the implementation-specific info.

Getting Started

Library user setup

If you want to use the library without hacking on it, clone the Git repository to where ASDF can find it:

  git clone https://codeberg.org/aartaka/trivial-inspect ~/.local/share/common-lisp/source/

And then load "trivial-inspect" in the REPL:

  (asdf:load-system "trivial-inspect")
  ;; or, if you use Quicklisp
  (ql:quickload "trivial-inspect")

Contributor/developer setup

In case you want to hack on (#| TMPL_VAR name |#), all the dependencies are bundled as submodules, you need to do a recursive clone

  git clone --recursive https://codeberg.org/aartaka/(#| TMPL_VAR name |#)

In case you initially cloned the repository without submodules, do

  git submodule update --init -- deps/

After that, you can run

• an Emacs-friendly development server: make slynk or make swank
• REPL with all the dependencies and trivial-inspect preloaded: make repl

You can also use the bundled guix.scm to install it on Guix.

APIs

Two main entry points of this library are fields and description:

fields (object) -> fields

fields returns a list of inspect properties for a given object Each property is a list of

• Index
• Property name (either index, keyword, or some standard library symbol, usually a getter function)
• Value of the property
• And optional setter to override this property. A function of two arguments—new value and old value.

  (trivial-inspect:fields #'identity)
  ;; ((0 :self #) (1 :id 1407351035)
  ;;  (2 class-of # #)
  ;;  (3 type-of compiled-function) (4 :name identity) (5 :arguments (sb-impl::thing))
  ;;  (6 compiled-function-p t) (7 :ftype (function # #))
  ;;  (8 :expression nil)
  ;;  (9 lambda-list-keywords (&allow-other-keys &aux &body &environment &key sb-int:&more &optional &rest &whole))
  ;;  (10 call-arguments-limit 1073741824) (11 lambda-parameters-limit 1073741824))
  (trivial-inspect:fields nil)
  ;; ((0 :self nil) (1 :id 1342177559)
  ;;  (2 class-of # nil)
  ;;  (3 type-of null) (4 length 0)
  ;;  (5 symbol-name "NIL") (6 symbol-package #)
  ;;  (7 :visibility :external #)
  ;;  (8 symbol-value nil #) (9 symbol-plist nil))
  (trivial-inspect:fields (find-class 'standard-object))
  ;; ((0 :self #) (1 :id 68721940739)
  ;;  (2 class-of #
  ;;   #)
  ;;  (3 :slot-definitions
  ;;   (# # ..)))

description (object &optional stream)

description returns/prints a human-readable description of the given object. Quite opinionated, but optimized for maximum useful info (if you have an idea for a better format, I'm open to discussion!) Usually includes type and printable representation, possibly followed by prettified fields and other info.

  (trivial-inspect:description #'+ t)
  ;; Compiled-function + (&REST NUMBERS)
  ;;  : (&REST NUMBER) -> (VALUES NUMBER &OPTIONAL)
  ;; Return the sum of its arguments. With no args, returns 0.
  (trivial-inspect:description 'standard-class t)
  ;; Symbol STANDARD-CLASS (EXTERNAL to COMMON-LISP) [class]
  (trivial-inspect:description (find-class 'standard-class) t)
  ;; Standard-class #

Customization Points

function-lambda-expression returns wildly different results across implementations and often misses the metadata for even simple functions. Thus the need for re-implementation and improvement. *function-lambda-expression-fn* allows providing your own function-lambda-expression implementation in case you find the implementation-specific one lacking in some way.

*documentation-fn* serves the same purpose, but for documentation. It's less likely to be useful, but is included anyway. Who knows, maybe you come up with a better documentation function incorporating function arglists, class slots etc. Do come up with it, everyone in the community will benefit from that!