journal
A library for logging, tracing, testing and persistence.

HTML documentation: https://melisgl.github.io/mgl-pax-world/journal-manual.html

Repository: https://github.com/melisgl/journal

Author: Gabor Melis

Distinguishing features

As a logging facility

  • Nested contexts and single messages
  • Customizable content and format
  • Human- or machine-readable output

#68200.234: ("some-context") #68200.234: Informative log message #68200.250: => NIL

See Logging for a complete example.

Compared to TRACE

  • Ability to handle non-local exits
  • Customizable content and format
  • Optional timestamps, internal real- and run-time

(FOO 2.1) (1+ 2.1) => 3.1 =E "SIMPLE-ERROR" "The assertion (INTEGERP 3.1) failed."

See Tracing for a complete example.

As a test framework

  • White-box testing based on execution traces
  • Isolation of external dependencies
  • Record-and-replay testing

(define-file-bundle-test (test-user-registration :directory "registration") (let ((username (replayed ("ask-username") (format t "Please type your username: ") (read-line)))) (add-user username) (assert (user-exists-p username))))

See Testing for a complete example.

As a solution for persistence

  • Event Sourcing: replay interactions with the external world
  • Unchanged control flow
  • Easy to implement history, undo

(defun my-resumable-autosaving-game-with-history () (with-bundle (bundle) (play-guess-my-number)))

See Persistence for a complete example.

MIT-LICENSE, Logging, Debugging, Test Framework, Persistence