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