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