Edinburgh Speech Tools  2.1-release
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
EST_Item.h
1 /*************************************************************************/
2 /* */
3 /* Centre for Speech Technology Research */
4 /* University of Edinburgh, UK */
5 /* Copyright (c) 1998 */
6 /* All Rights Reserved. */
7 /* Permission is hereby granted, free of charge, to use and distribute */
8 /* this software and its documentation without restriction, including */
9 /* without limitation the rights to use, copy, modify, merge, publish, */
10 /* distribute, sublicense, and/or sell copies of this work, and to */
11 /* permit persons to whom this work is furnished to do so, subject to */
12 /* the following conditions: */
13 /* 1. The code must retain the above copyright notice, this list of */
14 /* conditions and the following disclaimer. */
15 /* 2. Any modifications must be clearly marked as such. */
16 /* 3. Original authors' names are not deleted. */
17 /* 4. The authors' names are not used to endorse or promote products */
18 /* derived from this software without specific prior written */
19 /* permission. */
20 /* THE UNIVERSITY OF EDINBURGH AND THE CONTRIBUTORS TO THIS WORK */
21 /* DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING */
22 /* ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT */
23 /* SHALL THE UNIVERSITY OF EDINBURGH NOR THE CONTRIBUTORS BE LIABLE */
24 /* FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES */
25 /* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN */
26 /* AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, */
27 /* ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF */
28 /* THIS SOFTWARE. */
29 /* */
30 /*************************************************************************/
31 /* Author : Alan W Black */
32 /* Date : February 1998 */
33 /* --------------------------------------------------------------------- */
34 /* */
35 /* General class for representing linguistic information within a */
36 /* EST_Relation. This consists of two parts, the relation specific */
37 /* part and the information content part. The information content */
38 /* part may be shared between multiple EST_Items. */
39 /* */
40 /* This is typically used to represent things like words, phones but */
41 /* more abstract entities like NPs and nodes in metrical trees. */
42 /* */
43 /*************************************************************************/
44 #ifndef __EST_ITEM_H__
45 #define __EST_ITEM_H__
46 
47 #include "EST_String.h"
48 #include "EST_Features.h"
49 #include "ling_class/EST_Item_Content.h"
50 
51 typedef EST_Val (*EST_Item_featfunc)(EST_Item *s);
52 extern val_type val_type_featfunc;
53 const EST_Item_featfunc featfunc(const EST_Val &v);
54 EST_Val est_val(const EST_Item_featfunc f);
55 
56 class EST_Relation;
57 class ling_class_init;
58 
59 
60 /** @class EST_Item
61  @ingroup estlingclasses
62 
63 A class for containing individual linguistic objects such as
64 words or phones.
65 
66 These contain two types of information. This first is specific to the
67 \ref EST_Relation we are viewing this ling item from, the second part
68 consists of a set of features. These features may be shared by
69 instances of this ling item in different EST_Relation
70 within the same EST_Utterance.
71 
72 The shared part of an EST_Item is
73 represented by the class EST_Item_Content. It should not normally be
74 accessed by the general users as reverse links from the contents to
75 each of the EST_Items it is part of are held ensure the
76 integrity of the structures. Changing these without maintain the
77 appropriate links is unlikely to be stable.
78 
79 We believe this structure is the most efficient for the most natural
80 use we envisage. Traversal of the items ....
81 
82 */
83 class EST_Item
84 {
85  private:
86  EST_Item_Content *p_contents;
87  EST_Relation *p_relation;
88  // In general (when we need it)
89  // EST_TKVL <EST_String, EST_Item *> arcs;
90  // but specifically
91  EST_Item *n;
92  EST_Item *p;
93  EST_Item *u;
94  EST_Item *d;
95 
96  void unref_contents();
97  void ref_contents();
98  void copy(const EST_Item &s);
99 
100  // Internal manipulation functions
101  // Get the daughters of node, removing reference to them
102  EST_Item *grab_daughters(void);
103  /* Get the contents, removing reference to them, this doesn't
104  delete the contents if this item is the only reference */
105  EST_Item_Content *grab_contents(void);
106 
107 protected:
108  static void class_init(void);
109 
110  public:
111  /**@name Constructor Functions */
112  ///@{
113  /// Default constructor
114  EST_Item();
115  /// Copy constructor only makes reference to contents
116  EST_Item(const EST_Item &item);
117  /// Includes reference to relation
118  EST_Item(EST_Relation *rel);
119  /// Most common form of construction
120  EST_Item(EST_Relation *rel, EST_Item *si);
121  /// Deletes it and references to it in its contents
122  ~EST_Item();
123  ///@}
124 
125 
126  /**@name Feature access functions.
127  These functions are wrap-around functions to the basic access
128  functions in the \ref EST_Features class. In all these
129  functions, if the optional argument `m` is set to 1, an
130  error is thrown if the feature does not exist*/
131 
132  ///@{
133  /** return the value of the feature `name`
134  cast as a float */
135  const float F(const EST_String &name) const {return f(name).Float();}
136 
137  /** return the value of the feature `name` cast
138  as a float, returning `def` if not found.*/
139  const float F(const EST_String &name,float def) const
140  {return f(name,def).Float();}
141 
142  /** return the value of the feature `name`
143  cast as a EST_String */
144  const EST_String S(const EST_String &name) const {return f(name).string();}
145 
146  /** return the value of the feature `name`
147  cast as a EST_String,
148  returning `def` if not found.
149  */
150  const EST_String S(const EST_String &name, const EST_String &def) const
151  {return f(name, def).string();}
152 
153  /** return the value of the feature `name`
154  cast as a int */
155  const int I(const EST_String &name) const {return f(name).Int();}
156 
157  /** return the value of the feature `name` cast as a int
158  returning `def` if not found.*/
159  const int I(const EST_String &name, int def) const
160  {return f(name, def).Int();}
161 
162  /** return the value of the feature `name`
163  cast as a EST_Features */
164  EST_Features &A(const EST_String &name) const {return *feats(f(name));}
165 
166  /** return the value of the feature `name`
167  cast as a EST_Features,
168  returning `def` if not found.
169  */
170  EST_Features &A(const EST_String &name,EST_Features &def) const
171  {EST_Features *ff = new EST_Features(def);
172  return *feats(f(name, est_val(ff)));}
173  ///@}
174 
175  /**@name Feature setting functions.
176  A separate function is provided for each permissible value type
177  */
178  ///@{
179  /** set feature `name` to `val` */
180  void set(const EST_String &name, int ival)
181  { EST_Val pv(ival);features().set_path(name, pv); }
182 
183  /** set feature `name` to `val` */
184  void set(const EST_String &name, float fval)
185  { EST_Val pv(fval); features().set_path(name,pv); }
186 
187  /** set feature `name` to `val` */
188  void set(const EST_String &name, double fval)
189  { EST_Val pv((float)fval);features().set_path(name,pv); }
190 
191  /** set feature `name` to `val` */
192  void set(const EST_String &name, const EST_String &sval)
193  { EST_Val pv(sval);features().set_path(name,pv); }
194 
195  /** set feature `name` to `val` */
196  void set(const EST_String &name, const char *cval)
197  { EST_Val pv(cval);features().set_path(name,pv); }
198 
199  /** set feature `name` to `val`,
200  a function registered in
201  the feature function list. */
202  void set_function(const EST_String &name, const EST_String &funcname)
203  { features().set_function(name,funcname); }
204 
205  /** set feature `name` to `f`,
206  a set of features, which is copied into the object.
207  */
208  void set(const EST_String &name, EST_Features &f)
209  { EST_Features *ff = new EST_Features(f);
210  features().set_path(name, est_val(ff)); }
211 
212  /** set feature `name` to `f`,
213  whose type is EST_Val.
214  */
215  void set_val(const EST_String &name, const EST_Val &sval)
216  { features().set_path(name,sval); }
217  ///@}
218 
219  /**@name Utility feature functions
220  */
221  ///@{
222  /** remove feature `name` */
223  void f_remove(const EST_String &name)
224  { features().remove(name); }
225 
226  /** find all the attributes whose values are functions, and
227  replace them with their evaluation. */
228  void evaluate_features();
229 
230  /** TRUE if feature is present, FALSE otherwise */
231  int f_present(const EST_String &name) const
232  {return features().present(name); }
233 
234  // Number of items (including this) until no next item.
235  int length() const;
236  ///@}
237 
238  // get contents from item
239  EST_Item_Content *contents() const { return (this == 0) ? 0 : p_contents;}
240  // used by tree manipulation functions
241  void set_contents(EST_Item_Content *li);
242 
243  // These should be deleted.
244  // The item's name
245  const EST_String name() const
246  { return (this == 0) ? EST_String::Empty : f("name",0).string(); }
247 
248  // Set item's name
249  void set_name(const EST_String &name) const
250  { if (this != 0) p_contents->set_name(name); }
251 
252  // Shouldn't normally be needed, except for iteration
253  EST_Features &features() const { return p_contents->f; }
254 
255  const EST_Val f(const EST_String &name) const
256  {
257  EST_Val v;
258  if (this == 0)
259  {
260  EST_error("item is null so has no %s feature",(const char *)name);
261  }
262  else
263  {
264  for (v=p_contents->f.val_path(name);
265  v.type() == val_type_featfunc && featfunc(v) != NULL;
266  v=(featfunc(v))((EST_Item *)(void *)this));
267  if (v.type() == val_type_featfunc)
268  EST_error("NULL %s function",(const char *)name);
269  }
270  return v;
271  }
272 
273 #if 0
274  const EST_Val &f(const EST_String &name, const EST_Val &def) const
275  {
276  if (this == 0)
277  return def;
278  else
279  {
280  const EST_Val *v;
281  for (v=&(p_contents->f.val_path(name, def));
282  v->type() == val_type_featfunc && featfunc(*v) != NULL;
283  v=&(featfunc(*v))((EST_Item *)(void *)this));
284  if (v->type() == val_type_featfunc)
285  v = &def;
286  return *v;
287  }
288  }
289 #endif
290 
291  const EST_Val f(const EST_String &name, const EST_Val &def) const
292  {
293  if (this == 0)
294  return def;
295  else
296  {
297  EST_Val v;
298  for (v=p_contents->f.val_path(name, def);
299  v.type() == val_type_featfunc && featfunc(v) != NULL;
300  v=(featfunc(v))((EST_Item *)(void *)this));
301  if (v.type() == val_type_featfunc)
302  v = def;
303  return v;
304  }
305  }
306 
307  /**@name Cross relational access */
308  ///@{
309 
310  /// View item from another relation (const char *) method
311  EST_Item *as_relation(const char *relname) const
312  { return (this == 0) ? 0 : p_contents->Relation(relname); }
313 
314  /// TRUE if this item is in named relation
315  int in_relation(const EST_String &relname) const
316  { return (this == 0) ? 0 : p_contents->in_relation(relname); }
317 
318  /// Access to the relation links
319  EST_TKVL<EST_String, EST_Val> &relations() {return p_contents->relations;}
320 
321  /// The relation name of this particular item
322  const EST_String &relation_name() const;
323 
324  /// The relation of this particular item
325  EST_Relation *relation(void) const
326  { return (this == 0) ? 0 : p_relation; }
327 
328  /// True if li is the same item ignoring its relation viewpoint
329  int same_item(const EST_Item *li) const
330  { return contents() && li->contents() && (contents() == li->contents()); }
331  ///@}
332 
333  // The remaining functions should not be accessed, they are should be
334  // regarded as private member functions
335 
336  // Splice together a broken list.
337 
338  static void splice(EST_Item *a, EST_Item *b)
339  { if(a !=NULL) a->n = b; if (b != NULL) b->p=a; }
340 
341  // Internal traversal - nnot recommended - use relation traversal functions
342  //
343  EST_Item *next() const { return this == 0 ? 0 : n; }
344  //
345  EST_Item *prev() const { return this == 0 ? 0 : p; }
346  //
347  EST_Item *down() const { return this == 0 ? 0 : d; }
348  //
349  EST_Item *up() const { return this == 0 ? 0 : u; }
350  // Last item (most next) at this level
351  EST_Item *last() const;
352  // First item (most prev) at this level
353  EST_Item *first() const;
354  // Highest (most up)
355  EST_Item *top() const;
356  // Lowest (most down)
357  EST_Item *bottom() const;
358  // First item which has no down, within the descendants of this item
359  EST_Item *first_leaf() const;
360  // Next item which has no down, following above this item if necessary
361  EST_Item *next_leaf() const;
362  // Last item which has no down, following above this item if necessary
363  EST_Item *last_leaf() const;
364  // Next item in pre order (root, daughters, siblings)
365  EST_Item *next_item() const;
366 
367 
368  // Insert a new item after this, with li's contents
369  EST_Item *insert_after(EST_Item *li=0);
370  // Insert a new item before this, with li's contents
371  EST_Item *insert_before(EST_Item *li=0);
372  // Insert a new item below this, with li's contents (see tree methods)
373  EST_Item *insert_below(EST_Item *li=0);
374  // Insert a new item above this, with li's contents (see tree methods)
375  EST_Item *insert_above(EST_Item *li=0);
376 
377  // Append a new daughter to this, with li's contents
378  EST_Item *append_daughter(EST_Item *li=0);
379  // Prepend a new daughter to this, with li's contents
380  EST_Item *prepend_daughter(EST_Item *li=0);
381  // Insert a new parent above this, with li's contents
382  EST_Item *insert_parent(EST_Item *li=0);
383 
384  // Delete this item and all its occurrences in other relations
385  void unref_all();
386 
387  // Verification, double links are consistent (used after reading in)
388  int verify() const;
389 
390  friend int i_same_item(const EST_Item *l1,const EST_Item *l2);
391  friend int move_item(EST_Item *from, EST_Item *to);
392  friend int merge_item(EST_Item *from, EST_Item *to);
393  friend int move_sub_tree(EST_Item *from, EST_Item *to);
394  friend int exchange_sub_trees(EST_Item *from,EST_Item *to);
395 
396  EST_Item &operator=(const EST_Item &s);
397  friend ostream& operator << (ostream &s, const EST_Item &a);
398  friend bool operator !=(const EST_Item &a, const EST_Item &b)
399  { return !i_same_item(&a,&b); }
400  friend bool operator ==(const EST_Item &a, const EST_Item &b)
401  { return i_same_item(&a,&b); }
402 
403  friend class EST_Relation;
404  friend class ling_class_init;
405 };
406 
407 inline int i_same_item(const EST_Item *l1,const EST_Item *l2)
408 {
409  return l1->contents() && l2->contents() &&
410  (l1->contents() == l2->contents());
411 }
412 
413 
414 inline EST_Item *as(const EST_Item *n,const char *relname)
415  { return n->as_relation(relname); }
416 
417 // Relation structure functions
418 #include "ling_class/EST_Relation_list.h"
419 #include "ling_class/EST_Relation_tree.h"
420 #include "ling_class/EST_Relation_mls.h"
421 
422 inline EST_Item *next_item(const EST_Item *node)
423  { return node->next_item(); }
424 
425 void remove_item(EST_Item *l, const char *relname);
426 
427 void copy_node_tree(EST_Item *from, EST_Item *to);
428 void copy_node_tree_contents(EST_Item *from, EST_Item *to);
429 
430 void evaluate(EST_Item *a,EST_Features &f);
431 
432 
433 #include "ling_class/EST_FeatureFunctionPackage.h"
434 
435 // Feature function support
436 void EST_register_feature_function_package(const char *name, void (*init_fn)(EST_FeatureFunctionPackage &p));
437 
438 void register_featfunc(const EST_String &name, const EST_Item_featfunc func);
439 const EST_Item_featfunc get_featfunc(const EST_String &name,int must=0);
440 EST_String get_featname(const EST_Item_featfunc func);
441 
442 #define EST_register_feature_functions(PACKAGE) \
443  do { \
444  extern void register_ ## PACKAGE ## _feature_functions(EST_FeatureFunctionPackage &p); \
445  EST_register_feature_function_package( #PACKAGE , register_ ## PACKAGE ## _feature_functions); \
446  } while(0)
447 
448 
449 #endif
void set_function(const EST_String &name, const EST_String &funcname)
Definition: EST_Item.h:202
void evaluate_features()
Definition: EST_Item.cc:172
const int I(const EST_String &name, int def) const
Definition: EST_Item.h:159
void set_function(const EST_String &name, const EST_String &f)
int same_item(const EST_Item *li) const
True if li is the same item ignoring its relation viewpoint.
Definition: EST_Item.h:329
int in_relation(const EST_String &relname) const
TRUE if this item is in named relation.
Definition: EST_Item.h:315
~EST_Item()
Deletes it and references to it in its contents.
Definition: EST_Item.cc:108
const int Int(void) const
Definition: EST_Val.h:135
const float Float(void) const
Definition: EST_Val.h:143
void set(const EST_String &name, double fval)
Definition: EST_Item.h:188
EST_Item * as_relation(const char *relname) const
View item from another relation (const char *) method.
Definition: EST_Item.h:311
EST_Features f
General features for this item.
void set_path(const EST_String &name, const EST_Val &sval)
EST_Item()
Default constructor.
Definition: EST_Item.cc:81
const val_type type(void) const
Definition: EST_Val.h:131
void set(const EST_String &name, int ival)
Definition: EST_Item.h:180
const EST_String & relation_name() const
The relation name of this particular item.
Definition: EST_Item.cc:196
EST_TKVL< EST_String, EST_Val > & relations()
Access to the relation links.
Definition: EST_Item.h:319
void set(const EST_String &name, float fval)
Definition: EST_Item.h:184
void set_val(const EST_String &name, const EST_Val &sval)
Definition: EST_Item.h:215
void remove(const EST_String &name)
Definition: EST_Features.h:247
int present(const EST_String &name) const
const EST_Val & val_path(const EST_String &path) const
void set(const EST_String &name, EST_Features &f)
Definition: EST_Item.h:208
const EST_String & string(void) const
Definition: EST_Val.h:155
EST_Relation * relation(void) const
The relation of this particular item.
Definition: EST_Item.h:325
void set_name(const EST_String &s)
set name
const int I(const EST_String &name) const
Definition: EST_Item.h:155
EST_Features & A(const EST_String &name) const
Definition: EST_Item.h:164
const float F(const EST_String &name, float def) const
Definition: EST_Item.h:139
EST_Features & A(const EST_String &name, EST_Features &def) const
Definition: EST_Item.h:170
const EST_String S(const EST_String &name, const EST_String &def) const
Definition: EST_Item.h:150
void set(const EST_String &name, const EST_String &sval)
Definition: EST_Item.h:192
const EST_String S(const EST_String &name) const
Definition: EST_Item.h:144
const float F(const EST_String &name) const
Definition: EST_Item.h:135
void f_remove(const EST_String &name)
Definition: EST_Item.h:223
static const EST_String Empty
Constant empty string.
Definition: EST_String.h:116
void set(const EST_String &name, const char *cval)
Definition: EST_Item.h:196
int f_present(const EST_String &name) const
Definition: EST_Item.h:231