annotate base/classes.lisp @ 266:d605fd37b0ee

fix mtp description again - return the string not '(string)

(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
	   :reader chromatic-pitch-number :initarg :number))
  (:documentation "A pitch represented as a number, with chromatic
  pitches having distinct values. FIXME: We should not be using the cl
  symbol NUMBER."))

(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 linked-event (amuse-object)
  ((composition :reader composition
		:writer %set-composition
		:initarg :composition
		:initform nil))
  (:documentation "This provides a composition slot for events. The
  generic function initialize-instance can be specialized on an
  implementation composition to assign the event slots when a
  composition instance is created. Or the slot can be assigned within
  the composition constructor function. FIXME: Not sure about this -
  was there a good reason why events should not know the composition
  they belong to? MTP-events have a slot for composition-id (an
  integer number), but here the slot is intended to be assigned the
  composition object itself. Doing this means that potentially some
  generic functions could loose the extra composition parameter. I
  made this change because of SIA projection related stuff, the only
  function that relies on it in amuse is find-next-event. JF"))

(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"))


;;;=====================================================================
;;; Constituents: collections of more than one event
;;;=====================================================================

(defclass constituent (period) ()
  (:documentation "Base class for constituents"))

(defclass anchored-constituent (anchored-period) ()
  (:documentation "Base class for anchored constituents"))

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

(defclass standard-anchored-constituent (anchored-constituent
					 standard-anchored-period) ()
  (:documentation "Base class for anchored-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 time-ordered-anchored-constituent (anchored-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)
  ;; this won't work if lisp implementation doesn't support extensible
  ;; sequences.
  ())

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

(defclass composition (time-ordered-anchored-constituent) ()
  (:documentation "Base class for compositions. Compositions are
  assumed to be anchord constituents."))

(defclass standard-composition
    (composition standard-time-ordered-anchored-constituent) ()
  (:documentation "Base class for compositions using standard time
  representation. Standard compositions are assumed to be
  anchored."))

(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"))