annotate base/generics.lisp @ 134:5e362d998f29

More documentation

darcs-hash:20070828101524-f76cc-6add2c3c254befc3cf767ac69706865b7830bc6a.gz

(cl:in-package #:amuse) 

;;; Pulling compositions from the database 

(defgeneric get-composition (identifier)
  (:documentation "Returns a composition of type dependant on
  identifier"))

(defgeneric monody (object)
  (:documentation "Returns a monody."))
(defgeneric ensure-monody (object)
  (:documentation "Returns a generalised boolean."))

;;; Getting constituents from compositions
;; IS this the mechanism we want to use
(defgeneric time-signatures (composition)
  (:documentation "Returns all time-signatures in a composition
  Probably shouldn't be exported - can be replaced
  by (get-applicable-time-signature commposition composition)"))
(defgeneric (setf time-signatures) (sequence composition)
  (:documentation "Sets all time-signatures in a composition.
  Is this wanted here?"))
(defgeneric tempi (composition)
  (:documentation "Returns all tempi in a composition Probably
  shouldn't be exported - can be replaced
  by (get-applicable-tempi commposition composition)"))
(defgeneric (setf tempi) (sequence composition)
  (:documentation "Sets all tempi in a composition.
  Is this wanted here?"))
(defgeneric key-signatures (composition)
  (:documentation "Returns all key-signatures in a composition
  Probably shouldn't be exported - can be replaced
  by (get-applicable-key-signature commposition composition)"))
(defgeneric (setf key-signatures) (sequence composition)
  (:documentation "Sets all key sigs in a composition.
  Is this wanted here?"))

;;; Simple Accessors

;; pitch-based

(defgeneric pitch (object &key kind)) ; ? Maybe this returns the pitch
				      ; in its ur form?
(defgeneric chromatic-pitch (pitch-designator))
(defgeneric diatonic-pitch (pitch-designator))
(defgeneric frequency (object)) ;?

(defgeneric octave (pitch-designator)
  (:documentation "Return an integer representing the octave of
pitch-designator where middle c is defined to be the lowest pitch in
octave 4."))

(defgeneric diatonic-pitch-octave (pitch-designator)
  (:documentation "Return an integer representing the diatonic octave
of PITCH-DESIGNATOR."))

(defgeneric diatonic-pitch-accidental (pitch-designator)
  (:documentation "Return an integer representing the inflection of a
diatonic pitch where where negative values indicate numbers of flats,
0 indicates natural and positive values indicate numbers of sharps."))

(defgeneric diatonic-pitch-mp (pitch-designator)
  (:documentation "Return an integer representing the morphetic pitch
\(in MIPS terms) of a diatonic pitch."))
(defgeneric diatonic-pitch-cp (pitch-designator)
  (:documentation "Return an integer representing the chromatic pitch
\(in MIPS terms) of a diatonic pitch."))

(defgeneric middle-c (pitch-designator) 
  (:documentation "Returns the value of middle C in the particular
representation of pitch used by PITCH-DESIGNATOR."))
(defgeneric midi-pitch-number (pitch-designator)
  (:documentation "Takes a pitch-designator (usually a pitched
  event) and returns an integer between 0 and 127 representing
  the chromatic pitch designated (60=middle C, 48 the C below
  that, etc.)"))
(defgeneric asa-pitch-string (pitch-designator)
  (:documentation "Returns a string representing the designated ASA
pitch name which has three parts: a letter name in the set
{A,B,C,D,E,F,G}, an inflection in the set {n,f,s,ff,ss,fff,sss,...}
and an octave number. E.g., Cn4 = Middle C."))
(defgeneric asa-interval-string (pitch-designator)
  (:documentation "Returns a string representing the designated ASA
interval name which has two or three parts: a direction in the set
{r,f} (absent for unisons/primes), a type in the set
{p,ma,mi,a,d,aa,dd,aaa,ddd,...}, and a size number.  E.g. rma2 =
rising major second."))
(defgeneric diatonic-pitch-name (pitch-designator)
  (:documentation "Returns a char in the set
{#\A,#\B,#\C,#\D,#\E,#\F,#\G}, representing the pitch name of
PITCH-DESIGNATOR."))
(defgeneric pitch-class (pitch-designator)
  (:documentation "Takes a pitch-designator (usually a pitched
  event) and returns an integer between 0 and 12 representing
  the octave-independant pitch, with c=0, c#=1, etc.")
  (:method (p) (mod (midi-pitch-number p) 12)))
(defgeneric span (pitch-interval-designator))

;; time

(defgeneric duration (period-designator)
  (:documentation "Returns a value. Probably should only apply do
  periods (rather than designators?)"))
(defgeneric (setf duration) (value period-designator)
  (:documentation "As with duration, should probably work only
  with periods"))
(defgeneric timepoint (moment-designator)
  (:documentation "Returns a value for a moment. Does this make
  any sense on a designator?"))
(defgeneric (setf timepoint) (value moment-designator)
  (:documentation "Sets timepoint. What does this mean for a
  designator?"))
(defgeneric cut-off (anchored-period-designator) ; name?
  (:documentation "Returns a <moment> representing the point at
  which the anchored period has ended. By default, is calculated
  as the result of running time+ on the onset and period of the
  object.")
  (:method (apd) (time+ (moment apd) (floating-period apd))))
(defgeneric crotchet (object) 
  (:documentation "Returns a period, the duration of which represents
a crotchet in the time representation used by object."))

;; others

;; I've given the time-sig accessors general names because it allows
;; for symbols in time-signatures as well as numbers - numerator is an
;; odd accessor if the time sig is C (even in common practice) but
;; its meaning is clear. beat-units-per-bar is clearer, though, I
;; think.

(defgeneric beat-units-per-bar (time-signature)
  (:documentation "In a standard, fraction-like time-signature or
  a symbolic equivalent, this is the numerator."))
(defgeneric time-signature-numerator (time-signature)
  (:method (ts) (beat-units-per-bar ts))
  (:documentation "Not obviously meaningful for non fraction-like
  time signatures"))
(defgeneric beat-units (time-signature)
  (:documentation "In a standard, fraction-like time-signature or
  a symbolic equivalent, this is the denominator (n.b.  the
  difference between this and @code{tactus-duration} is only
  visible for compound time, where this returns the lower portion
  of the time signature, but @code{tactus-duration} returns the
  higher-level unit)."))
(defgeneric time-signature-denominator (time-signature)
  (:method (ts) (beat-units ts))
  (:documentation "Not obviously meaningful for non fraction-like
  time signatures"))
(defgeneric tactus-duration (time-signature)
  ;; basic, but should do?
  (:method (ts)
    (cond
      ((and (not (= (beat-units-per-bar ts) 3))
	    (= (rem (beat-units-per-bar ts) 3) 0))
       ;; compound time
       (* (/ 4 (beat-units ts))
	  3))
      (t (/ 4 (beat-units ts)))))
  (:documentation "Returns a number of crotchets to represent the
  tactus, based on some idea of time signature patterns. Should,
  in future, return a duration rather than a number."))

(defgeneric key-signature-sharps (key-signature)
  (:documentation "Simple query for normal key-signatures."))
(defgeneric key-signature-mode (ks)
  (:documentation "Query that only makes sense for midi-like key
  signatures"))

(defgeneric bpm (tempo)
  (:documentation "Basic tempo query")) ;; in bpm
(defgeneric microseconds-per-crotchet (tempo)
  ;; As used (when rounded) in MIDI
  (:method (tp) (/ 60000000 (bpm tp)))
  (:documentation "Basic tempo query for MIDI. N.B. This will be
  a fraction and must be rounded before being used for output."))

;;; Coerce-type accessors

;; Should I be including these default methods?  Should the accessors
;; be direct slot accessors or the generics I'm using? Should we
;; return the object itself if it already is in the target class?

(defgeneric anchored-period (anchored-period-designator)
  (:method (apd) (make-anchored-period (onset apd) (duration apd)))
  (:documentation "Coerce any anchored period to a plain anchored
  period"))

(defgeneric floating-period (period-designator)
  (:method (pd) (make-floating-period (duration pd)))
  (:documentation "Coerce any period to a floating period"))

(defgeneric moment (moment-designator)
  (:method (md) (make-moment (timepoint md)))
  (:documentation "Coerce any moment(-designator?), including an
  anchored-period to a moment"))

(defgeneric onset (anchored-period-designator)
  (:method (apd) (moment apd))
  (:documentation "Return a moment for the start of an anchored period"))
(defgeneric (setf onset) (value anchored-period-designator))

;;; Time Protocol (or moments?)

;; negative times/durations -> ERROR? 

;; time+: <time>      <duration> -> <time>
;;        <duration>  <time>     -> <time> (same as previous?) 
;;        <duration>  <duration> -> <duration> (or a distinct duration+?) 
;;        <time>      <time>     -> ERROR? 
;; 
;; time-: <time>      <time>     -> <duration>
;;        <time>      <duration> -> <time> 
;;        <duration>  <duration> -> <duration> (or a distinct duration-?) 
;;        <duration>  <time>     -> ERROR? 
;;        <anchored>  <anchored> -> (time- (moment o1) (moment o2)) ? or error?

(defgeneric time+ (object1 object2)
  (:documentation "Addition for time designators"))
(defgeneric time- (object1 object2)
  (:documentation "Subtraction for time designators"))

(defgeneric time> (object1 object2)
  (:documentation "> operator for moment designators"))
(defgeneric time< (object1 object2)
  (:documentation "< operator for moment designators")
  (:method (o1 o2) (time> o2 o1)))
(defgeneric time= (object1 object2)
  (:documentation "= operator for moment designators")) 
(defgeneric time>= (object1 object2)
  (:documentation ">= operator for moment designators")
  (:method (o1 o2) (or (time> o1 o2) (time= o1 o2))))
(defgeneric time<= (object1 object2)
  (:documentation "<= operator for moment designators")
  (:method (o1 o2) (or (time< o1 o2) (time= o1 o2))))
(defgeneric time/= (object1 object2)
  (:documentation "not = operator for moment designators")
  (:method (o1 o2) (not (time= o1 o2))))

;;; Duration protocol 

(defgeneric duration> (object1 object2)
  (:documentation "> operator for period designators"))
(defgeneric duration< (object1 object2)
  (:documentation "< operator for period designators")
  (:method (o1 o2) (duration> o2 o1)))
(defgeneric duration= (object1 object2)
  (:documentation "= operator for period designators")) 
(defgeneric duration>= (object1 object2) 
  (:documentation ">= operator for period designators")
  (:method (o1 o2) (or (duration> o1 o2) (duration= o1 o2))))
(defgeneric duration<= (object1 object2)
  (:documentation "<= operator for period designators")
  (:method (o1 o2) (or (duration< o1 o2) (duration= o1 o2))))
(defgeneric duration/= (object1 object2) 
  (:documentation "not = operator for period designators")
  (:method (o1 o2) (not (duration= o1 o2))))

;; for linear scaling:
(defgeneric duration* (object1 object2)
  (:documentation "Multiplication operator for period
  designators. Intuitively, this makes sense, but it may cause us
  trouble with some implementations in the future."))
(defgeneric duration/ (object1 number)
  (:documentation "Division operator for period designators. This
  may turn out not to mean much. Division is probably useful, but
  we may need to define what we mean with care."))

;;; Pitch protocol 

;; pitch+: <pitch>    <pitch>     -> ERROR
;;         <pitch>    <interval>  -> <pitch> 
;;         <interval> <pitch>     -> <pitch> (same as previous?) 
;;         <interval> <interval>  -> <interval> (or a distinct interval+?) 
;; 
;; pitch-: <pitch>    <pitch>     -> <interval>
;;         <pitch>    <interval>  -> <pitch> 
;;         <interval> <interval>  -> <interval>
;;         <interval> <pitch>     -> ERROR 

(defgeneric pitch+ (object1 object2))
(defgeneric pitch- (object1 object2))

(defgeneric pitch> (object1 object2))
(defgeneric pitch< (object1 object2)
  (:method (o1 o2) (pitch> o2 o1)))
(defgeneric pitch= (object1 object2)) 
(defgeneric pitch>= (object1 object2) 
  (:method (o1 o2) (or (pitch> o1 o2) (pitch= o1 o2))))
(defgeneric pitch<= (object1 object2)
  (:method (o1 o2) (or (pitch< o1 o2) (pitch= o1 o2))))
(defgeneric pitch/= (object1 object2) 
  (:method (o1 o2) (not (pitch= o1 o2))))

;;; Interval protocol (emphasise _pitch_ not _time_ interval?) 

(defgeneric interval> (object1 object2))
(defgeneric interval< (object1 object2)
  (:method (o1 o2) (interval> o2 o1)))
(defgeneric interval= (object1 object2)) 
(defgeneric interval>= (object1 object2) 
  (:method (o1 o2) (or (interval> o1 o2) (interval= o1 o2))))
(defgeneric interval<= (object1 object2)
  (:method (o1 o2) (or (interval< o1 o2) (interval= o1 o2))))
(defgeneric interval/= (object1 object2) 
  (:method (o1 o2) (not (interval= o1 o2))))

;;; Allen's (1984) interval relations 
;;;  . equals already defined as INTERVAL= above 
;;;  . inverses ommitted for now (just use CL:NOT) 
;;;  . can all be defined in terms of MEETS (apparently)

(defgeneric meets (object1 object2))
(defgeneric before (object1 object2))
(defgeneric overlaps (object1 object2))
(defgeneric during (object1 object2))
(defgeneric starts (object1 object2))
(defgeneric ends (object1 object2))

;;; and extensions thereof ...

(defgeneric subinterval (object1 object2)
  (:method (o1 o2) (or (starts o1 o2) (during o1 o2) (ends o1 o2))))

(defgeneric disjoint (object1 object2)
  (:method (o1 o2) 
    (or (before o1 o2) (meets o1 o2) (meets o2 o1) (before o2 o1))))

;;; More time-based functions

(defgeneric period= (object1 object2)
  (:method (x y) nil))

(defgeneric find-overlapping (anchored-period sequence)
  ;; Returns all members of a sequence of period signifiers that overlap
  ;; with the supplied period
  (:method (ap s) (remove-if #'(lambda (x) (amuse:disjoint ap x)) s)))

;; Return the anchored-period representing the intersection of two
;; anchored-period-specifiers.
(defgeneric period-intersection (anchored-period-specifier1
				 anchored-period-specifier2))

(defgeneric inter-onset-interval (moment-designator1 moment-designator2)
  (:method (md1 md2) (time- (moment md2) (moment md1))))


;;; Time Signature 

(defgeneric get-applicable-time-signatures (anchored-period composition)
  (:method (ap c) (find-overlapping ap (time-signatures c)))
  (:documentation "Return a list of time-signatures that are
  relevant to <anchored-period>. The period may contain
  information such as staff position and voicing, and the method
  may use this to filter its response"))

(defgeneric time-signature-equal (ts1 ts2)
  (:documentation "Comparison operator. The definition of
  equality is left open for implementers"))

;;; Tempo 

(defgeneric get-applicable-tempi  (anchored-period composition)
  (:method (ap c) (find-overlapping ap (tempi c)))
  (:documentation "Return a list of tempi that are relevant to
  <anchored-period>. The period may contain information such as
  staff position and voicing, and the method may use this to
  filter its response"))

(defgeneric tempo-equal (t1 t2)
  (:documentation "Comparison operator. The definition of
  equality is left open for implementers"))

;;; Tonality (Key Signature / Mode) 

(defgeneric get-applicable-key-signatures (object1 object2)
  (:documentation "Return a list of key-signatures that are
  relevant to <anchored-period>. The period may contain
  information such as staff position and voicing, and the method
  may use this to filter its response"))

(defgeneric key-signature-equal (ks1 ks2)
  (:documentation "Comparison operator. The definition of
  equality is left open to implementers"))

;;; Dynamics 
;;; Voice 
;;; Boundary Strength (phrasing)