lily/include/music-iterator.hh

   1 /*
   2   music-iterator.hh -- declare Music_iterator
   3
   4   source file of the GNU LilyPond music typesetter
   5
   6   (c)  1997--2003 Han-Wen Nienhuys <hanwen@cs.uu.nl>
   7 */
   8
   9
  10 #ifndef MUSIC_ITERATOR_HH
  11 #define MUSIC_ITERATOR_HH
  12
  13 #include "lily-proto.hh"
  14 #include "array.hh"
  15 #include "moment.hh"
  16 #include "virtual-methods.hh"
  17 #include "interpretation-context-handle.hh"
  18 #include "smobs.hh"
  19
  20 /**
  21    ---
  22
  23    Music_iterator is an object type that traverses the Music structure and
  24    reports the events it finds to interpretation contexts. It is not yet
  25    user-serviceable.
  26
  27
  28    ---
  29
  30   Conceptually a music-iterator operates on a queue of musical events
  31   that are pending. This queue does not actually exist, but it is a
  32   way of viewing and traversing music-expressions.
  33
  34
  35   ok () -- events left ?
  36
  37   pending_mom () -- time tag of the next event to be processed.
  38     PRECONDITION: this->ok () holds.
  39
  40   process (M) -- process all at M (Precondition: no events exist
  41     before M, this->ok () holds).  Side-effects:
  42
  43     * This removes all events at M from the pending queue.
  44
  45     * Typically this reports the music to an interpretation context,
  46     thus changing the state of the interpretation context.
  47
  48
  49   TODO:
  50
  51   merge pending_moment and process?
  52
  53 */
  54 class Music_iterator
  55 {
  56 protected:
  57   Moment music_length_;
  58   Moment start_mom_;
  59
  60   DECLARE_SMOBS (Music_iterator,dummy);
  61 public:
  62   VIRTUAL_COPY_CONS (Music_iterator);
  63
  64   Moment music_get_length () const;
  65   Moment music_start_mom () const;
  66   Music_iterator ();
  67   Music_iterator (Music_iterator const&);
  68
  69   /**
  70      Do the reporting.  Will try MUSIC_L_ in its own translator first,
  71      then its children. Returns the iterator that succeeded
  72   */
  73   Music_iterator *  try_music (Music  *) const;
  74
  75   /**
  76     The translation unit that we this iterator is reporting  to now.
  77    */
  78   Translator_group* get_outlet () const;
  79
  80   void set_translator (Translator_group*);
  81
  82   /** Get an iterator matching the type of MUS, and use TRANS to find
  83     an accompanying translation unit
  84    */
  85   static SCM get_static_get_iterator (Music * mus);
  86   void init_translator (Music  *, Translator_group *);
  87   void quit ();
  88   void substitute_outlet (Translator_group* from, Translator_group *to);
  89   virtual void derived_substitute (Translator_group*, Translator_group*);
  90   virtual Moment pending_moment () const;
  91   virtual bool ok () const;
  92
  93   virtual bool run_always () const;
  94   virtual void process (Moment until);
  95   virtual void derived_mark ()const;
  96   virtual void construct_children ();
  97
  98   /**
  99     Construct sub-iterators, and set the translator to
 100     report to.
 101    */
 102
 103   DECLARE_SCHEME_CALLBACK(constructor, ());
 104
 105   /**
 106     Get an iterator for MUS, inheriting the translation unit from THIS.
 107    */
 108   SCM get_iterator (Music *) const;
 109
 110   virtual Music_iterator* try_music_in_children (Music *) const;
 111
 112   Music * get_music () const;
 113 protected:
 114   virtual void do_quit();
 115 private:
 116   Interpretation_context_handle handle_;
 117   Music  * music_;
 118 };
 119
 120
 121 #define IMPLEMENT_CTOR_CALLBACK(Class)          \
 122 LY_DEFINE_MEMBER_FUNCTION(Class,constructor, #Class "::constructor",\
 123           0,0,0,\
 124           (),\
 125           "Construct a @code{" #Class "} music iterator")\
 126 {                                               \
 127   SCM val = (new Class)->self_scm();   \
 128   scm_gc_unprotect_object (val);\
 129   return val ;                          \
 130 }                                               \
 131
 132 DECLARE_UNSMOB(Music_iterator, iterator);
 133
 134 #endif // MUSIC_ITERATOR_HH