Mercurial > hg > amuse

changeset 123:f57ab0e109fb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More docs darcs-hash:20070730133825-f76cc-ca46fd2ec43676a919ecf67efa80a7881013f405.gz
author David Lewis <d.lewis@gold.ac.uk>
date Mon, 30 Jul 2007 14:38:25 +0100
parents 997bed70ef28
children b0a1760ab0dd
files amuse.asd base/classes.lisp base/generics.lisp
diffstat 3 files changed, 110 insertions(+), 48 deletions(-) [+]
line wrap: on
line diff
--- a/amuse.asd	Fri Jul 27 18:47:37 2007 +0100
+++ b/amuse.asd	Mon Jul 30 14:38:25 2007 +0100
@@ -35,6 +35,6 @@
                       ((:file "package")
                        (:file "classes" :depends-on ("package"))
                        (:file "constructors" :depends-on ("package" "classes"))
-	               (:file "methods" :depends-on ("package" "classes"))
-		       (:file "midifile-import" :depends-on ("package" "classes" "constructors" "methods"))))))))
+	               (:file "midifile-import" :depends-on ("package" "classes" "constructors"))
+		       (:file "methods" :depends-on ("package" "midifile-import" "classes"))))))))
 
--- a/base/classes.lisp	Fri Jul 27 18:47:37 2007 +0100
+++ b/base/classes.lisp	Mon Jul 30 14:38:25 2007 +0100
@@ -2,17 +2,21 @@
 
 ;; collections of more than one event
 
-(defclass constituent (anchored-period) ())
-(defclass time-ordered-constituent (constituent list-slot-sequence)
-  ;; this won't work if lisp implementation doesn't support extensible
-  ;; sequences.
-  ())
-(defclass composition (time-ordered-constituent) ())
-(defclass monody (composition) ())
+(defclass constituent (anchored-period) ()
+  (:documentation "Base class for `constituents'"))
+(defclass time-ordered-constituent (constituent list-slot-sequence) ()
+  (:documentation "Class for ordered sequence. Won't work out of the box if the
+  lisp implementation doesn't support extensible sequences."))
+(defclass composition (time-ordered-constituent) ()
+  (:documentation "Base class for complete compositions."))
+(defclass monody (composition) ()
+  (:documentation "Simple class to indicate suitability for
+  monody-requiring processes"))
 
 ;; types of information-specifiers
 
-(defclass identifier () ()) ;; for composition specification
+(defclass identifier () ()
+  (:documentation "Must be subclassed. Allows specification of compositions"))
 (defclass moment-designator () ()
   (:documentation "Object indicating a point in time"))
 (defclass period-designator () ()
@@ -47,8 +51,8 @@
 (defclass pitch (pitch-designator) ())
 (defclass chromatic-pitch (pitch) 
   ((number :accessor %chromatic-pitch-number :initarg :number))
-  (:documentation "A pitch represented as a number, with higher
-  values representing high pitches."))
+  (: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))
@@ -82,31 +86,36 @@
 ;; events. As such, they can be regarded as anchored-periods with
 ;; properties.
 
-(defclass time-signature (anchored-period) ())
+(defclass time-signature (anchored-period) ()
+  (:documentation "Base class for time signature"))
 
 (defclass basic-time-signature (time-signature)
-  ;; N.B. Can only deal with numeric signatures
   ((numerator :accessor %basic-time-signature-numerator
 	      :initarg :numerator)
    (denominator :accessor %basic-time-signature-denominator
-		:initarg :denominator)))
+		:initarg :denominator))
+  (:documentation "Class with slots for numerator and
+  denominator. Can only deal with numeric signatures."))
 
-(defclass key-signature (anchored-period) ())
+(defclass key-signature (anchored-period) ()
+  (:documentation "Base class for key signature"))
 
 (defclass basic-key-signature (key-signature)
-  ;; Only has line-of-fifths distance from c, so custom signatures
-  ;; won't work
   ((sharp-count :accessor %basic-key-signature-sharp-count
-		:initarg :sharp-count)))
+		:initarg :sharp-count))
+  (:documentation "Simple class - Only has line-of-fifths
+  distance from c, so custom signatures won't work"))
 
 (defclass midi-key-signature (basic-key-signature)
-  ;; mode: 0 = major key; 1 = minor key
   ((mode :accessor %midi-key-signature-mode
-	 :initarg :mode)))
+	 :initarg :mode))
+  (:documentation "MIDI-based flavour of basic key signature,
+  adding a slot for mode: 0 = major key; 1 = minor key"))
 
 (defclass tempo (anchored-period)
-  ;; accel and rit in symbolic encoding will need other structures, as
-  ;; will textual tempo markings.
   ((bpm :accessor %tempo-bpm
-	:initarg :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."))
    
--- a/base/generics.lisp	Fri Jul 27 18:47:37 2007 +0100
+++ b/base/generics.lisp	Mon Jul 30 14:38:25 2007 +0100
@@ -2,7 +2,9 @@
 
 ;;; Pulling compositions from the database 
 
-(defgeneric get-composition (identifier))
+(defgeneric get-composition (identifier)
+  (:documentation "Returns a composition of type dependant on
+  identifier"))
 
 (defgeneric monody (object)
   (:documentation "Returns a monody."))
@@ -96,10 +98,18 @@
 
 ;; time
 
-(defgeneric duration (period-designator))
-(defgeneric (setf duration) (value period-designator))
-(defgeneric timepoint (moment-designator))
-(defgeneric (setf timepoint) (value moment-designator))
+(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
@@ -118,12 +128,22 @@
 ;; its meaning is clear. beat-units-per-bar is clearer, though, I
 ;; think.
 
-(defgeneric beat-units-per-bar (time-signature))
+(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)))
-(defgeneric beat-units (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 numerator (n.b.,
+  tactus-duration is the method of choice for compound time
+  sensitive queries."))
 (defgeneric time-signature-denominator (time-signature)
-  (:method (ts) (beat-units ts)))
+  (: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)
@@ -133,15 +153,24 @@
        ;; compound time
        (* (/ 4 (beat-units ts))
 	  3))
-      (t (/ 4 (beat-units ts))))))
+      (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))
-(defgeneric key-signature-mode (ks))
+(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)) ;; in bpm
+(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))))
+  (: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
 
@@ -150,16 +179,22 @@
 ;; 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))))
+  (: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))))
+  (: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))))
+  (: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)))
+  (: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?)
@@ -310,22 +345,40 @@
 ;;; Time Signature 
 
 (defgeneric get-applicable-time-signatures (anchored-period composition)
-  (:method (ap c) (find-overlapping ap (time-signatures c))))
+  (: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))
+(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))))
+  (: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))
+(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))
+(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))
+(defgeneric key-signature-equal (ks1 ks2)
+  (:documentation "Comparison operator. The definition of
+  equality is left open to implementers"))
 
 ;;; Dynamics 
 ;;; Voice