Portable toolkit for interactive inspectors.

trivial-inspect

* 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
Clone the Git repository:
#+begin_src sh
  git clone --recursive https://github.com/aartaka/trivial-inspect ~/.local/share/common-lisp/source/
#+end_src

And then load ~:trivial-inspect~ in the REPL:
#+begin_src lisp
  (asdf:load-system :trivial-inspect)
  ;; or, if you use Quicklisp
  (ql:quickload :trivial-inspect)
#+end_src

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.

#+begin_src lisp
  (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> ..)))
#+end_src

** 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.

#+begin_src lisp
  (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>
#+end_src

* Customization Points

~function-lambda-expression~ returns wildly different results across implementations and often misses the metadata for even simple functions. Thus the need for [[https://github.com/aartaka/graven-image/blob/master/source/function-lambda-expression.lisp][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!


trivial-inspect

Upstream URL

Author

License

trivial-inspect

Version:

License:

Authors:

Dependencies:

Dependencies (1)

Dependents (0)