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--2002 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 "cxx-function-smob.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   get_pending_events (M) -- return all events starting at M (pre: no events
  49     before M). No side-effects
  50
  51   skip (M) -- remove all events starting before M (leave the ones that
  52     start M).  no side-effects on interpretation context
  53
  54
  55   TODO:
  56
  57   merge pending_moment and process?
  58
  59 */
  60 class Music_iterator
  61 {
  62 protected:
  63   Moment music_length_;
  64   Moment start_mom_;
  65 public:
  66   VIRTUAL_COPY_CONS (Music_iterator);
  67
  68   Moment music_length_mom () const;
  69   Moment music_start_mom () const;
  70   Music_iterator ();
  71   Music_iterator (Music_iterator const&);
  72   virtual ~Music_iterator ();
  73
  74   /**
  75      Do the reporting.  Will try MUSIC_L_ in its own translator first,
  76      then its children. Returns the iterator that succeeded
  77   */
  78   Music_iterator *  try_music (Music  *) const;
  79
  80   /**
  81     The translation unit that we this iterator is reporting  to now.
  82    */
  83   Translator_group* report_to () const;
  84
  85   void set_translator (Translator_group*);
  86
  87   /** Get an iterator matching the type of MUS, and use TRANS to find
  88     an accompanying translation unit
  89    */
  90   static Music_iterator* get_static_get_iterator (Music * mus);
  91   void init_translator (Music  *, Translator_group *);
  92
  93   virtual Moment pending_moment () const;
  94   virtual bool ok () const;
  95   virtual SCM get_pending_events (Moment until)const;
  96   virtual void process (Moment until);
  97   virtual void skip (Moment until);
  98
  99   /**
 100     Construct sub-iterators, and set the translator to
 101     report to.
 102    */
 103   virtual void construct_children ();
 104   static SCM constructor_cxx_function;
 105
 106   /**
 107     Get an iterator for MUS, inheriting the translation unit from THIS.
 108    */
 109   Music_iterator* get_iterator (Music *) const;
 110
 111   virtual Music_iterator* try_music_in_children (Music *) const;
 112
 113   Music * get_music () const;
 114 private:
 115   Interpretation_context_handle handle_;
 116   Music  * music_;
 117 };
 118
 119
 120 /*
 121   implement Class::constructor, a SCM function that
 122   returns an encapsulated factory function.
 123  */
 124 #define IMPLEMENT_CTOR_CALLBACK(Class)          \
 125 static void *                                           \
 126 Class ## _ctor (SCM)                            \
 127 {                                               \
 128   return new Class ;                            \
 129 }                                               \
 130 SCM Class :: constructor_cxx_function;\
 131 void                                            \
 132 Class ## _constructor_init ()                           \
 133 {                                               \
 134   SCM s = smobify_cxx_function (& Class ## _ctor);      \
 135   scm_permanent_object (s);\
 136   gh_define (#Class "::constructor", s);\
 137   Class :: constructor_cxx_function = s;\
 138 }\
 139 ADD_SCM_INIT_FUNC (Class ## _ctor_init, Class ## _constructor_init);
 140
 141
 142
 143
 144
 145
 146
 147 #endif // MUSIC_ITERATOR_HH