MUTILS

A collection of Common Lisp utilities provided as modules.

The modules provided are small enough to fit in a single file and Common Lisp package, and an ASDF system definition may not be justified for them.

Usage

In your ASDF system, depend-on :mutils, and then use :require to pick the modules to load.

Example:

(asdf:defsystem :mutils-example
  :depends-on (:mutils 
                 (:require :lisp-critic-warnings)
                 (:require :auto-gensym)))

Modules

Modules are single Lisp files that follow a format similar to Emacs Packages.

They start with a commented section:

• The first line is header with the module name and a short description.
• Then a Copyright and license, followed by some module properties, like author, version, requirements, and more.
• A commentary section with a long description of the module, with usage instructions and examples.

Then a section with the module source code:

• require calls are placed at the top.
• The definition of a package and the source code of the module.
• A provide call at the end of the file.

The template looks like this:

;;; <module name> --- <module short description>

;; Copyright (C) 2023 <author>. All rights reserved.

;; This work is licensed under the terms of the <license> license.  
;; For a copy, see <https://opensource.org/licenses/<license>>.

;; Author: <author> <email>
;; Version: <module version>
;; Requires: <required modules separated by comma>

;;; Commentary:

;; <long module description with usage instructions and examples>

;;; Code:

(require :<requirementA>)
(require :<requirementB>)

(defpackage :<module-package>
  (:use :cl))

(in-package :<module-package>)

... <module source code> ...

(provide :<module-name>)

An example module:

;;; plump-xpath --- xpath extension for plump.

;; Copyright (C) 2023 Mariano Montone. All rights reserved.

;; This work is licensed under the terms of the MIT license.  
;; For a copy, see <https://opensource.org/licenses/MIT>.

;; Author: Mariano Montone <marianomontone@gmail.com>
;; Version: 0.1
;; Requires: plump, xpath

;;; Commentary:

;; xpath extension for plump.

;;; Code:

(require :plump)
(require :xpath)

(defpackage :plump-xpath
  (:use :cl))

(in-package :plump-xpath)

...

(provide :plump-xpath)

Contributing

I welcome contributions of new modules. If you are interested in mutils shipping yours, create a pull request or attach your file with the module.

Modules should be general purpose and be compact enough to fit into a single file and package. Although they can also depend on other modules.

The module file should follow the format described in this document.

Modules api (mutils package)

describe-module

(module-name)

Print a description of module.

describe-modules

()

Print a description of available mutils modules.

list-modules

(&optional (return :name))

List mutils modules. RETURN can be:

• :name . Just returns the name of the modules, as a keyword. Default.
• :details. Parses the modules and returns its details.

parse-lisp-module-file

(file)

Parse a Lisp module file.

Returns the name of the module, its short description, its properties (author, requirements, keywords, etc.), its long description/comment with instructions of usage, etc.

List of modules

• clhs-linker - Replace Lisp terms in a file by hyperlinks to Common Lisp HyperSpec.
• compiler-hooks - Provides hooks for Common Lisp compilation api.
• compiler-info - Provides compiler info (specially from declarations) in a portable way.
• debug-print - A reader macro package for debug printing.
• def-properties - Portable extractor of information from Common Lisp definitions.
• directory-module-loader - Loader of Lisp module files from directories.
• estimated-time-progress - Progress display with estimated time.
• html2who - Parse HTML and create cl-who source code.
• hunchentoot-errors - Augments Hunchentoot error pages and logs with request and session information.
• hunchentoot-trace-acceptor - A Hunchentoot acceptor for tracing HTTP requests.
• if-star - The if* macro used in Allegro.
• image-dimensions-reader - Get image dimensions (PNG/JPG) without loading the file.
• lisp-critic-warnings - Signal compiler warnings with lisp-critic critiques.
• muprotocols - An implementation of protocols that plays nicely with Common Lisp type system.
• mutils-docs - Documentation generator for mutils.
• mutils-utils - General purpose utilities.
• plump-xpath - xpath extension for plump.
• quicksearch - Search Engine Interface for Common Lisp.
• type-annotations - Support for inline type annotations.
• who-templates - Templating system with CL-WHO. Supports inheritance.