annotate base/classes.lisp @ 217:d8f650e3796e

Rationalise base and geerdes classes, constructors and methods.

Ignore-this: d9d4d88566a6d110844d91d4c70513cd

Towards a more standardised interface. Some of these changes (generalised
constructors and reader functions) are necessary for amuse-database-admin
functionality and some other CHARM-like things.

darcs-hash:20090716154406-16a00-8a9b4fb1fc1f5ba75af66a1bbd87e1bb68e02493.gz

committer: Jamie Forth <[e-mail]>

(cl:in-package #:amuse)

;; top-level amuse object

(defclass amuse-object () ())

;; types of information-specifiers

(defclass identifier (amuse-object) ()
  (:documentation "DEPRECATED: Base class to allow specification of
  composition to get. Must be subclassed.")) ; FIXME: Why deprecated?

(defclass constituent-identifier (identifier) ()
  (:documentation "Base class to allow specification of
  constituents"))

(defclass composition-identifier (constituent-identifier) ()
  (:documentation "Base class to allow specification of
  compositions constituents"))

(defclass event-identifier (identifier) ()
  (:documentation "Base class to allow specification of events."))

(defclass moment (amuse-object) ()
  (:documentation "Object indicating a point in time"))
(defclass period (amuse-object) ()
  (:documentation "Object indicating a region of time"))
(defclass anchored-period (moment period) ()
  (:documentation "Object indicating a region of time starting at
  a specific point in time"))
(defclass pitch (amuse-object) ()
  (:documentation "Object indicating some sort of pitch"))
(defclass pitch-interval (amuse-object) ()
  (:documentation "Object indicating a distance in pitch space"))

;; time-related classes

(defclass standard-moment (moment) 
  ((time :accessor %moment-time :initarg :time))
  (:documentation "A moment that has time represented on a
  continuous, progressive number line"))

(defclass standard-period (period) 
  ((interval :accessor %period-interval :initarg :interval))
  (:documentation "A period that places time intervals
  on a progressive number-line"))

(defclass standard-anchored-period (standard-period standard-moment anchored-period) ()
  (:documentation "Number-line-based anchored period"))

;; pitch-related classes

(defclass frequency-pitch (pitch) ())

(defclass chromatic-pitch (pitch)
  ((number :accessor %chromatic-pitch-number :initarg :number))
  (:documentation "A pitch represented as a number, with
  chromatic pitches having distinct values."))
(defclass diatonic-pitch (pitch)
  ((cp :initarg :cp :accessor %p-pc :reader diatonic-pitch-cp)
   (mp :initarg :mp :accessor %p-pm :reader diatonic-pitch-mp))
  (:documentation "A diatonic pitch, represented using MIPS: cp is an
integer representing chromatic pitch (An0 = 0, middle C = 39); mp is
an integer representing the morphetic pitch (An0 = 0, middle C =
23)."))

(defclass chromatic-pitch-interval (pitch-interval)
  ((span :accessor %chromatic-pitch-interval-span :initarg :span))
  (:documentation "An interval represented as a number, recording
  the number of ascending chromatic pitches between two pitches."))

(defclass diatonic-pitch-interval (pitch-interval)
  ((span :accessor %diatonic-pitch-interval-span :initarg :span :reader span))
  (:documentation "How is this inplemented?"))

;; events

(defclass event (anchored-period) ()
  (:documentation "Notelike object"))
(defclass pitched-event (event pitch) ()
  (:documentation "Event with pitch information"))
(defclass standard-pitched-event (pitched-event
				  standard-anchored-period) ()
  (:documentation "Event with pitch information"))
(defclass chromatic-pitched-event (pitched-event chromatic-pitch) ()
  (:documentation "Event with chromatic pitch information"))
(defclass standard-chromatic-pitched-event (chromatic-pitched-event
					    standard-anchored-period) ()
  (:documentation "Event with chromatic pitch information and
  standard-period"))
(defclass diatonic-pitched-event (pitched-event diatonic-pitch) ()
  (:documentation "Event with diatonic pitch information"))
(defclass standard-diatonic-pitched-event (diatonic-pitched-event
					   standard-anchored-period) ()
  (:documentation "Event with diatonic pitch information and
  standard-period"))
(defclass percussive-event (event) ()
  (:documentation "Unpitched percussion Event. There's an issue
with this name - is there a reason why this is unpitched
necessarily, or why I'm not counting piano, etc in this? Perhaps
what I mean is that it should be renamed unpitched-event?
Actually, is this necessary? Isn't this just an event?"))
(defclass standard-percussive-event (event standard-anchored-period) ()
  (:documentation "Unpitched percussion Event. There's an issue
with this name - is there a reason why this is unpitched
necessarily, or why I'm not counting piano, etc in this? Perhaps
what I mean is that it should be renamed unpitched-event?
Actually, is this necessary? Isn't this just an event?
Timbral/instrumental information will be generalised later but is
less agreed-on than pitch."))

;;; Range-based `constituents'
;; Whilst these are all constituents in the CHARM sense, their
;; properties apply to a timed range rather than to a set of
;; events. As such, they can be regarded as anchored-periods with
;; properties.

(defclass time-signature (amuse-object) ()
  (:documentation "Abstract class for time signature"))

(defclass time-signature-period (time-signature anchored-period) ()
  (:documentation "Abstract class for time signatures in time"))

(defclass standard-time-signature (time-signature)
  ((numerator :accessor %basic-time-signature-numerator
	      :initarg :numerator)
   (denominator :accessor %basic-time-signature-denominator
		:initarg :denominator))
  (:documentation "Class with slots for numerator and
  denominator. Can only deal with numeric signatures."))

(defclass standard-time-signature-period (standard-time-signature
					  time-signature-period
					  standard-anchored-period)
  ()
  (:documentation "STANDARD-TIME-SIGNATURE on a time number line"))

(defclass key-signature (amuse-object) ()
  (:documentation "Base class for key signature"))

(defclass key-signature-period (key-signature anchored-period) ()
  (:documentation "Abstract class for time signatures in time"))

(defclass standard-key-signature (key-signature)
  ((sharp-count :accessor %basic-key-signature-sharp-count
                :initarg :sharp-count))
  (:documentation "Simple class - Only has line-of-fifths
  distance from c, so custom signatures won't work"))

(defclass standard-key-signature-period (standard-key-signature
					 key-signature-period
					 standard-anchored-period)
  ()
  (:documentation "STANDARD-KEY-SIGNATURE on a time number line"))

(defclass midi-key-signature (standard-key-signature)
  ((mode :accessor %midi-key-signature-mode
	 :initarg :mode))
  (:documentation "MIDI-based flavour of basic key signature,
  adding a slot for mode: 0 = major key; 1 = minor key"))

(defclass midi-key-signature-period (standard-key-signature-period
					 midi-key-signature)
  ()
  (:documentation "MIDI-KEY-SIGNATURE on a time number line"))

(defclass tempo (amuse-object) ()
  (:documentation "Abstract class for tempo"))
(defclass tempo-period (tempo anchored-period) ()
  (:documentation "Abstract class for tempo associated with a
  time period"))
(defclass standard-tempo (tempo)
  ((bpm :accessor %tempo-bpm
	:initarg :bpm))
  (:documentation "Rather literal reading of absolute tempo.
  accel and rit in symbolic encoding will need other structures,
  as will textual tempo markings."))
(defclass standard-tempo-period (standard-tempo
				 tempo-period
				 standard-anchored-period)
  ()
  (:documentation "Tempo associated with a standard-anchored-period"))
   
;; collections of more than one event

(defclass constituent (anchored-period) ()
  (:documentation "Base class for constituents"))
(defclass standard-constituent (constituent standard-anchored-period) ()
  (:documentation "Base class for constituents using standard
  time representation"))

(defclass time-ordered-constituent (constituent list-slot-sequence)
  ;; this won't work if lisp implementation doesn't support extensible
  ;; sequences.
  ())
(defclass standard-time-ordered-constituent (time-ordered-constituent
					     standard-constituent
					     list-slot-sequence)
  ;; this won't work if lisp implementation doesn't support extensible
  ;; sequences.
  ())


(defclass composition (time-ordered-constituent) ()
  (:documentation "Base class for compositions"))

(defclass standard-composition (composition
				standard-time-ordered-constituent) ()
  (:documentation "Base class for compositions using standard
  time representation"))
(defclass monody (composition) ()
  (:documentation "Class for indicating suitability for analysis
  requiring a monody"))
(defclass standard-monody (monody standard-composition) ())

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; Experimental:
;;

(defclass clef (amuse-object) ()
  (:documentation "Abstract class for clef implementations"))

(defclass clef-period (clef anchored-period)  ()
  (:documentation "Abstract class for clef implementations in time"))

(defclass standard-clef (clef)
  ((type :accessor %standard-clef-type
         :initarg :type)
   (line :accessor %standard-clef-line
         :initarg :line)
   (octave-shift :accessor %standard-clef-octave-shift
                 :initarg :octave-shift
                 :initform nil))
  (:documentation "Class of clef with slots for type (a keyword
  from :F, :G and :C, probably), line (counting from the lowest line =
  1) and octave shift (nil or a positive or negative integer
  representing transposition up or down"))

(defclass standard-clef-period (standard-clef clef-period standard-anchored-period)
  ()
  (:documentation "Standard clef on a timeline"))