defining-clos-classes

name	defining-clos-classes
description	Use when defining CLOS classes and their constructors in Common Lisp, adding an optional slot to an existing class, or converting a defstruct to a defclass — especially when writing a make-<name> constructor that hides make-instance.

Defining CLOS Classes

Overview

Every data type in these projects is a defclass with a constructor function make-<name> that hides make-instance. The constructor takes &rest restargs so it never duplicates the class's :initform defaults.

When to Use

• Defining a new class and its constructor
• Adding an optional slot to an existing class
• Converting a defstruct to a defclass

Use defclass, not defstruct

defclass integrates with CLOS — generic methods, inheritance, the MOP. A defstruct metaclass cannot be changed later in a live image and does not play cleanly with CLOS extensions.

The constructor pattern (the important part)

(defclass session ()
  ((project-dir :initarg :project-dir :reader session-project-dir)
   (state       :initarg :state       :initform nil :accessor session-state)))

(defun make-session (project-dir &rest restargs &key state)
  (declare (ignore state))
  (apply #'make-instance 'session :project-dir project-dir restargs))

Rules:

• Required slots → required positional parameters of the constructor (project-dir).
• Optional slots → &key parameters, received via &rest restargs and forwarded with apply. List every &key in the lambda list, then (declare (ignore ...)) for each one — for documentation and compile-time checking.
• Never duplicate the :initform default in the constructor. make-instance already uses :initform when a key is absent and the supplied value when it is present. Duplicating the default is the common wrong form (every baseline agent writes it).

Why &rest + apply instead of passing state explicitly

• No default to keep in sync with the class.
• Adding an optional slot costs one line in the &key list and one ignore — the constructor body never changes.
• Absent keys fall through to :initform; present keys override it.

;; Wrong — duplicates the nil default from the class, and the body must be edited for every new slot
(defun make-session (project-dir &key (state nil))
  (make-instance 'session :project-dir project-dir :state state))

Slot accessors

Use :reader / :accessor with :initarg keywords. Name accessors session-<slot> to avoid clashes across classes.

Redefining defstruct → defclass in a live image

A running image cannot just reload the file: the metaclass change is refused and the old accessors stay fboundp. Delete the package first, then force-reload — see using-common-lisp-repl for the exact delete-package + load-system :force recipe.

Common Mistakes

Symptom	Fix
Constructor duplicates the class default (&key (state nil))	Use &rest restargs &key state + (declare (ignore state)) + apply — no duplication
defstruct used where CLOS is expected	Switch to defclass (CLOS methods / inheritance / MOP)
Adding a slot forces editing the constructor body	With &rest restargs, only the &key list and declare ignore change
defstruct → defclass reload errors, or old accessors linger	delete-package first — see using-common-lisp-repl

Related skills

For live-image reload after redefinition: using-common-lisp-repl. For overall file and package style: writing-common-lisp.