Edinburgh Speech Tools 2.4-release
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
51typedef EST_Val (*EST_Item_featfunc)(EST_Item *s);
52extern val_type val_type_featfunc;
53const EST_Item_featfunc featfunc(const EST_Val &v);
54EST_Val est_val(const EST_Item_featfunc f);
55
56class EST_Relation;
57class ling_class_init;
58
59
60/** A class for containing individual linguistic objects such as
61words or phones.
62
63These contain two types of information. This first is specific to the
64\Ref{EST_Relation} we are viewing this ling item from, the second part
65consists of a set of features. These features may be shared by
66instances of this ling item in different <link
67linkend="est-relation">EST_Relation</link> within the same <link
68linkend="est-utterance">EST_Utterances</link>
69
70The shared part of an <link linkend="est-item">EST_Item</link> is
71represented by the class EST_Item_Content. It should not normally be
72accessed by the general users as reverse links from the contents to
73each of the EST_Items it is part of are held ensure the
74integrity of the structures. Changing these without maintain the
75appropriate links is unlikely to be stable.
76
77We believe this structure is the most efficient for the most natural
78use we envisage. Traversal of the items ....
79
80*/
81
83{
84 private:
85 EST_Item_Content *p_contents;
86 EST_Relation *p_relation;
87 // In general (when we need it)
88 // EST_TKVL <EST_String, EST_Item *> arcs;
89 // but specifically
90 EST_Item *n;
91 EST_Item *p;
92 EST_Item *u;
93 EST_Item *d;
94
95 void unref_contents();
96 void ref_contents();
97 void copy(const EST_Item &s);
98
99 // Internal manipulation functions
100 // Get the daughters of node, removing reference to them
101 EST_Item *grab_daughters(void);
102 /* Get the contents, removing reference to them, this doesn't
103 delete the contents if this item is the only reference */
104 EST_Item_Content *grab_contents(void);
105
106protected:
107 static void class_init(void);
108
109 public:
110 /**@name Constructor Functions */
111 //@{
112 /// Default constructor
113 EST_Item();
114 /// Copy constructor only makes reference to contents
115 EST_Item(const EST_Item &item);
116 /// Includes reference to relation
118 /// Most common form of construction
119 EST_Item(EST_Relation *rel, EST_Item *si);
120 /// Deletes it and references to it in its contents
121 ~EST_Item();
122 //@}
123
124
125 /**@name Feature access functions.
126 These functions are wrap-around functions to the basic access
127 functions in the \Ref{EST_Features} class. In all these
128 functions, if the optional argument <parameter>m} is set to 1, an
129 error is thrown if the feature does not exist*/
130
131 //@{
132 /** return the value of the feature <parameter>name</parameter>
133 cast as a float */
134 const float F(const EST_String &name) const {return f(name).Float();}
135
136 /** return the value of the feature <parameter>name</parameter> cast
137 as a float, returning <parameter>def</parameter> if not found.*/
138 const float F(const EST_String &name,float def) const
139 {return f(name,def).Float();}
140
141 /** return the value of the feature <parameter>name</parameter>
142 cast as a EST_String */
143 const EST_String S(const EST_String &name) const {return f(name).string();}
144
145 /** return the value of the feature <parameter>name</parameter>
146 cast as a EST_String,
147 returning <parameter>def</parameter> if not found.
148 */
149 const EST_String S(const EST_String &name, const EST_String &def) const
150 {return f(name, def).string();}
151
152 /** return the value of the feature <parameter>name</parameter>
153 cast as a int */
154 const int I(const EST_String &name) const {return f(name).Int();}
155
156 /** return the value of the feature <parameter>name</parameter> cast as a int
157 returning <parameter>def</parameter> if not found.*/
158 const int I(const EST_String &name, int def) const
159 {return f(name, def).Int();}
160
161 /** return the value of the feature <parameter>name</parameter>
162 cast as a EST_Features */
163 EST_Features &A(const EST_String &name) const {return *feats(f(name));}
164
165 /** return the value of the feature <parameter>name</parameter>
166 cast as a EST_Features,
167 returning <parameter>def</parameter> if not found.
168 */
169 EST_Features &A(const EST_String &name,EST_Features &def) const
170 {EST_Features *ff = new EST_Features(def);
171 return *feats(f(name, est_val(ff)));}
172 //@}
173
174 /**@name Feature setting functions.
175 A separate function is provided for each permissible value type
176 */
177 //@{
178 /** set feature <parameter>name</parameter> to <parameter>val</parameter> */
179 void set(const EST_String &name, int ival)
180 { EST_Val pv(ival);features().set_path(name, pv); }
181
182 /** set feature <parameter>name</parameter> to <parameter>val</parameter> */
183 void set(const EST_String &name, float fval)
184 { EST_Val pv(fval); features().set_path(name,pv); }
185
186 /** set feature <parameter>name</parameter> to <parameter>val</parameter> */
187 void set(const EST_String &name, double fval)
188 { EST_Val pv((float)fval);features().set_path(name,pv); }
189
190 /** set feature <parameter>name</parameter> to <parameter>val</parameter> */
191 void set(const EST_String &name, const EST_String &sval)
192 { EST_Val pv(sval);features().set_path(name,pv); }
193
194 /** set feature <parameter>name</parameter> to <parameter>val</parameter> */
195 void set(const EST_String &name, const char *cval)
196 { EST_Val pv(cval);features().set_path(name,pv); }
197
198 /** set feature <parameter>name</parameter> to <parameter>val</parameter>,
199 a function registered in
200 the feature function list. */
201 void set_function(const EST_String &name, const EST_String &funcname)
202 { features().set_function(name,funcname); }
203
204 /** set feature <parameter>name</parameter> to <parameter>f</parameter>,
205 a set of features, which is copied into the object.
206 */
207 void set(const EST_String &name, EST_Features &f)
208 { EST_Features *ff = new EST_Features(f);
209 features().set_path(name, est_val(ff)); }
210
211 /** set feature <parameter>name</parameter> to <parameter>f</parameter>,
212 whose type is EST_Val.
213 */
214 void set_val(const EST_String &name, const EST_Val &sval)
215 { features().set_path(name,sval); }
216 //@}
217
218 /**@name Utility feature functions
219 */
220 //@{
221 /** remove feature <parameter>name</parameter> */
222 void f_remove(const EST_String &name)
223 { features().remove(name); }
224
225 /** find all the attributes whose values are functions, and
226 replace them with their evaluation. */
227 void evaluate_features();
228
229 /** TRUE if feature is present, FALSE otherwise */
230 int f_present(const EST_String &name) const
231 {
232 if (p_contents)
233 return features().present(name);
234 else
235 return FALSE; }
236
237 // Number of items (including this) until no next item.
238 int length() const;
239 //@}
240
241 // get contents from item
242 EST_Item_Content *contents() const { return p_contents;}
243 // used by tree manipulation functions
244 void set_contents(EST_Item_Content *li);
245
246 // These should be deleted.
247 // The item's name
248 const EST_String name() const
249 { return f("name",0).string(); }
250
251 // Set item's name
252 void set_name(const EST_String &name) const
253 { p_contents->set_name(name); }
254
255 // Shouldn't normally be needed, except for iteration
256 EST_Features &features() const { return p_contents->f; }
257
258 const EST_Val f(const EST_String &name) const
259 {
260 EST_Val v;
261 for (v=p_contents->f.val_path(name);
262 v.type() == val_type_featfunc && featfunc(v) != NULL;
263 v=(featfunc(v))((EST_Item *)(void *)this));
264 if (v.type() == val_type_featfunc)
265 EST_error("NULL %s function",(const char *)name);
266 return v;
267 }
268
269#if 0
270 const EST_Val &f(const EST_String &name, const EST_Val &def) const
271 {
272 if (this == 0)
273 return def;
274 else
275 {
276 const EST_Val *v;
277 for (v=&(p_contents->f.val_path(name, def));
278 v->type() == val_type_featfunc && featfunc(*v) != NULL;
279 v=&(featfunc(*v))((EST_Item *)(void *)this));
280 if (v->type() == val_type_featfunc)
281 v = &def;
282 return *v;
283 }
284 }
285#endif
286
287 const EST_Val f(const EST_String &name, const EST_Val &def) const
288 {
289 EST_Val v;
290 for (v=p_contents->f.val_path(name, def);
291 v.type() == val_type_featfunc && featfunc(v) != NULL;
292 v=(featfunc(v))((EST_Item *)(void *)this));
293 if (v.type() == val_type_featfunc)
294 v = def;
295 return v;
296 }
297
298 /**@name Cross relational access */
299 //@{
300
301 /// View item from another relation (const char *) method
302 EST_Item *as_relation(const char *relname) const
303 { return p_contents->Relation(relname); }
304
305 /// TRUE if this item is in named relation
306 int in_relation(const EST_String &relname) const
307 { return p_contents->in_relation(relname); }
308
309 /// Access to the relation links
310 EST_TKVL<EST_String, EST_Val> &relations() {return p_contents->relations;}
311
312 /// The relation name of this particular item
313 const EST_String &relation_name() const;
314
315 /// The relation of this particular item
317 { return (this == 0) ? 0 : p_relation; }
318
319 /// True if li is the same item ignoring its relation viewpoint
320 int same_item(const EST_Item *li) const
321 { return contents() && li->contents() && (contents() == li->contents()); }
322 //@}
323
324 // The remaining functions should not be accessed, they are should be
325 // regarded as private member functions
326
327 // Splice together a broken list.
328
329 static void splice(EST_Item *a, EST_Item *b)
330 { if(a !=NULL) a->n = b; if (b != NULL) b->p=a; }
331
332 // Internal traversal - not recommended - use relation traversal functions
333 // As these functions must be safe to NULL arguments they now (gcc6)
334 // cannot refer to this, so alway require an explicit pointer to the object
335 // These four are the only ones that require access to private fields
336 friend EST_Item *inext(const EST_Item *i);
337 friend EST_Item *iprev(const EST_Item *i);
338 friend EST_Item *idown(const EST_Item *i);
339 friend EST_Item *iup(const EST_Item *i);
340
341 // Insert a new item after this, with li's contents
342 EST_Item *insert_after(EST_Item *li=0);
343 // Insert a new item before this, with li's contents
344 EST_Item *insert_before(EST_Item *li=0);
345 // Insert a new item below this, with li's contents (see tree methods)
346 EST_Item *insert_below(EST_Item *li=0);
347 // Insert a new item above this, with li's contents (see tree methods)
348 EST_Item *insert_above(EST_Item *li=0);
349
350 // Append a new daughter to this, with li's contents
351 EST_Item *append_daughter(EST_Item *li=0);
352 // Prepend a new daughter to this, with li's contents
353 EST_Item *prepend_daughter(EST_Item *li=0);
354 // Insert a new parent above this, with li's contents
355 EST_Item *insert_parent(EST_Item *li=0);
356
357 // Delete this item and all its occurrences in other relations
358 void unref_all();
359
360 // Verification, double links are consistent (used after reading in)
361 int verify() const;
362
363 friend int i_same_item(const EST_Item *l1,const EST_Item *l2);
364 friend int move_item(EST_Item *from, EST_Item *to);
365 friend int merge_item(EST_Item *from, EST_Item *to);
366 friend int move_sub_tree(EST_Item *from, EST_Item *to);
367 friend int exchange_sub_trees(EST_Item *from,EST_Item *to);
368
369 EST_Item &operator=(const EST_Item &s);
370 friend ostream& operator << (ostream &s, const EST_Item &a);
371 friend bool operator !=(const EST_Item &a, const EST_Item &b)
372 { return !i_same_item(&a,&b); }
373 friend bool operator ==(const EST_Item &a, const EST_Item &b)
374 { return i_same_item(&a,&b); }
375
376 friend class EST_Relation;
377 friend class ling_class_init;
378};
379
380inline int i_same_item(const EST_Item *l1,const EST_Item *l2)
381{
382 return l1->contents() && l2->contents() &&
383 (l1->contents() == l2->contents());
384}
385
386
387inline EST_Item *as(const EST_Item *n,const char *relname)
388{ if (n != 0) return n->as_relation(relname);
389 return 0;}
390
391EST_Item *inext(const EST_Item *i);
392EST_Item *iprev(const EST_Item *i);
393EST_Item *idown(const EST_Item *i);
394EST_Item *iup(const EST_Item *i);
395
396EST_Item *last(const EST_Item *x);
397EST_Item *first(const EST_Item *x);
398EST_Item *top(const EST_Item *x);
399EST_Item *bottom(const EST_Item *x);
400
401EST_Item *next_item(const EST_Item *node);
402EST_Item *first_leaf(const EST_Item *node);
403EST_Item *next_leaf(const EST_Item *node);
404EST_Item *last_leaf(const EST_Item *node);
405
406// Relation structure functions
407#include "ling_class/EST_Relation_list.h"
408#include "ling_class/EST_Relation_tree.h"
409#include "ling_class/EST_Relation_mls.h"
410
411void remove_item(EST_Item *l, const char *relname);
412
413void copy_node_tree(EST_Item *from, EST_Item *to);
414void copy_node_tree_contents(EST_Item *from, EST_Item *to);
415
416void evaluate(EST_Item *a,EST_Features &f);
417
418#include "ling_class/EST_FeatureFunctionPackage.h"
419
420// Feature function support
421void EST_register_feature_function_package(const char *name, void (*init_fn)(EST_FeatureFunctionPackage &p));
422
423void register_featfunc(const EST_String &name, const EST_Item_featfunc func);
424const EST_Item_featfunc get_featfunc(const EST_String &name,int must=0);
425EST_String get_featname(const EST_Item_featfunc func);
426
427#define EST_register_feature_functions(PACKAGE) \
428 do { \
429 extern void register_ ## PACKAGE ## _feature_functions(EST_FeatureFunctionPackage &p); \
430 EST_register_feature_function_package( #PACKAGE , register_ ## PACKAGE ## _feature_functions); \
431 } while(0)
432
433
434#endif
void set_path(const EST_String &name, const EST_Val &sval)
void remove(const EST_String &name)
Definition: EST_Features.h:246
void set_function(const EST_String &name, const EST_String &f)
int present(const EST_String &name) const
const EST_Val & val_path(const EST_String &path) const
EST_Features f
General features for this item.
void set_name(const EST_String &s)
set name
void set(const EST_String &name, double fval)
Definition: EST_Item.h:187
int in_relation(const EST_String &relname) const
TRUE if this item is in named relation.
Definition: EST_Item.h:306
const int I(const EST_String &name) const
Definition: EST_Item.h:154
const float F(const EST_String &name, float def) const
Definition: EST_Item.h:138
EST_Relation * relation(void) const
The relation of this particular item.
Definition: EST_Item.h:316
void set(const EST_String &name, int ival)
Definition: EST_Item.h:179
EST_TKVL< EST_String, EST_Val > & relations()
Access to the relation links.
Definition: EST_Item.h:310
const EST_String S(const EST_String &name, const EST_String &def) const
Definition: EST_Item.h:149
const int I(const EST_String &name, int def) const
Definition: EST_Item.h:158
void set(const EST_String &name, EST_Features &f)
Definition: EST_Item.h:207
const EST_String S(const EST_String &name) const
Definition: EST_Item.h:143
void set(const EST_String &name, const EST_String &sval)
Definition: EST_Item.h:191
EST_Features & A(const EST_String &name, EST_Features &def) const
Definition: EST_Item.h:169
EST_Features & A(const EST_String &name) const
Definition: EST_Item.h:163
void evaluate_features()
Definition: EST_Item.cc:175
const EST_String & relation_name() const
The relation name of this particular item.
Definition: EST_Item.cc:199
const float F(const EST_String &name) const
Definition: EST_Item.h:134
void set(const EST_String &name, float fval)
Definition: EST_Item.h:183
void set_val(const EST_String &name, const EST_Val &sval)
Definition: EST_Item.h:214
void set_function(const EST_String &name, const EST_String &funcname)
Definition: EST_Item.h:201
void f_remove(const EST_String &name)
Definition: EST_Item.h:222
void set(const EST_String &name, const char *cval)
Definition: EST_Item.h:195
EST_Item * as_relation(const char *relname) const
View item from another relation (const char *) method.
Definition: EST_Item.h:302
EST_Item()
Default constructor.
Definition: EST_Item.cc:81
int f_present(const EST_String &name) const
Definition: EST_Item.h:230
~EST_Item()
Deletes it and references to it in its contents.
Definition: EST_Item.cc:108
int same_item(const EST_Item *li) const
True if li is the same item ignoring its relation viewpoint.
Definition: EST_Item.h:320
const EST_String & string(void) const
Definition: EST_Val.h:150
const int Int(void) const
Definition: EST_Val.h:130
const val_type type(void) const
Definition: EST_Val.h:126
const float Float(void) const
Definition: EST_Val.h:138