1trivial-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.

2Getting Started

Clone the Git repository:

  git clone --recursive https://github.com/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)

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

3APIs

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

3.1fields (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 #<function identity>) (1 :id 1407351035)
  ;;  (2 class-of #<sb-pcl:system-class common-lisp:function> #<function # {100A28547B}>)
  ;;  (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 #<built-in-class common-lisp:null> nil)
  ;;  (3 type-of null) (4 length 0)
  ;;  (5 symbol-name "NIL") (6 symbol-package #<package "COMMON-LISP">)
  ;;  (7 :visibility :external #<function # {100CFF5F0B}>)
  ;;  (8 symbol-value nil #<function # {100CFF5F2B}>) (9 symbol-plist nil))
  (trivial-inspect:fields (find-class 'standard-object))
  ;; ((0 :self #<standard-class common-lisp:standard-object>) (1 :id 68721940739)
  ;;  (2 class-of #<standard-class common-lisp:standard-class>
  ;;   #<function (lambda (trivial-inspect::new-value trivial-inspect::_) :in trivial-inspect:fields) {1003A7BAEB}>)
  ;;  (3 :slot-definitions
  ;;   (#<sb-mop:standard-effective-slot-definition sb-pcl::%type> #<sb-mop:standard-effective-slot-definition sb-pcl::source> ..)))

3.2description (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 #<STANDARD-CLASS COMMON-LISP:STANDARD-CLASS>

4Customization 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!