Initial import to Tizen
[profile/ivi/pocketsphinx.git] / src / libpocketsphinx / dict.h
1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
2 /* ====================================================================
3  * Copyright (c) 1999-2004 Carnegie Mellon University.  All rights
4  * reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  *    notice, this list of conditions and the following disclaimer. 
12  *
13  * 2. Redistributions in binary form must reproduce the above copyright
14  *    notice, this list of conditions and the following disclaimer in
15  *    the documentation and/or other materials provided with the
16  *    distribution.
17  *
18  * This work was supported in part by funding from the Defense Advanced 
19  * Research Projects Agency and the National Science Foundation of the 
20  * United States of America, and the CMU Sphinx Speech Consortium.
21  *
22  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND 
23  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
24  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
25  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
26  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  *
34  * ====================================================================
35  *
36  */
37
38 #ifndef _S3_DICT_H_
39 #define _S3_DICT_H_
40
41 /** \file dict.h
42  * \brief Operations on dictionary. 
43  */
44
45 /* SphinxBase headers. */
46 #include <sphinxbase/hash_table.h>
47
48 /* Local headers. */
49 #include "s3types.h"
50 #include "bin_mdef.h"
51 #include "pocketsphinx_export.h"
52
53 #define S3DICT_INC_SZ 4096
54
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58 #if 0
59 } /* Fool Emacs into not indenting things. */
60 #endif
61
62 /** 
63     \struct dictword_t
64     \brief a structure for one dictionary word. 
65 */
66 typedef struct {
67     char *word;         /**< Ascii word string */
68     s3cipid_t *ciphone; /**< Pronunciation */
69     int32 pronlen;      /**< Pronunciation length */
70     s3wid_t alt;        /**< Next alternative pronunciation id, NOT_S3WID if none */
71     s3wid_t basewid;    /**< Base pronunciation id */
72 } dictword_t;
73
74 /** 
75     \struct dict_t
76     \brief a structure for a dictionary. 
77 */
78
79 typedef struct {
80     int refcnt;
81     bin_mdef_t *mdef;   /**< Model definition used for phone IDs; NULL if none used */
82     dictword_t *word;   /**< Array of entries in dictionary */
83     hash_table_t *ht;   /**< Hash table for mapping word strings to word ids */
84     int32 max_words;    /**< #Entries allocated in dict, including empty slots */
85     int32 n_word;       /**< #Occupied entries in dict; ie, excluding empty slots */
86     int32 filler_start; /**< First filler word id (read from filler dict) */
87     int32 filler_end;   /**< Last filler word id (read from filler dict) */
88     s3wid_t startwid;   /**< FOR INTERNAL-USE ONLY */
89     s3wid_t finishwid;  /**< FOR INTERNAL-USE ONLY */
90     s3wid_t silwid;     /**< FOR INTERNAL-USE ONLY */
91     int nocase;
92 } dict_t;
93
94
95 /**
96  * Initialize a new dictionary.
97  *
98  * If config and mdef are supplied, then the dictionary will be read
99  * from the files specified by the -dict and -fdict options in config,
100  * with case sensitivity determined by the -dictcase option.
101  *
102  * Otherwise an empty case-sensitive dictionary will be created.
103  *
104  * Return ptr to dict_t if successful, NULL otherwise.
105  */
106 dict_t *dict_init(cmd_ln_t *config, /**< Configuration (-dict, -fdict, -dictcase) or NULL */
107                   bin_mdef_t *mdef  /**< For looking up CI phone IDs (or NULL) */
108     );
109
110 /**
111  * Write dictionary to a file.
112  */
113 int dict_write(dict_t *dict, char const *filename, char const *format);
114
115 /** Return word id for given word string if present.  Otherwise return BAD_S3WID */
116 POCKETSPHINX_EXPORT
117 s3wid_t dict_wordid(dict_t *d, const char *word);
118
119 /**
120  * Return 1 if w is a filler word, 0 if not.  A filler word is one that was read in from the
121  * filler dictionary; however, sentence START and FINISH words are not filler words.
122  */
123 int dict_filler_word(dict_t *d,  /**< The dictionary structure */
124                      s3wid_t w     /**< The word ID */
125     );
126
127 /**
128  * Test if w is a "real" word, i.e. neither a filler word nor START/FINISH.
129  */
130 POCKETSPHINX_EXPORT
131 int dict_real_word(dict_t *d,  /**< The dictionary structure */
132                    s3wid_t w     /**< The word ID */
133     );
134
135 /**
136  * Add a word with the given ciphone pronunciation list to the dictionary.
137  * Return value: Result word id if successful, BAD_S3WID otherwise
138  */
139 s3wid_t dict_add_word(dict_t *d,          /**< The dictionary structure. */
140                       char const *word,   /**< The word. */
141                       s3cipid_t const *p, /**< The pronunciation. */
142                       int32 np            /**< Number of phones. */
143     );
144
145 /**
146  * Return value: CI phone string for the given word, phone position.
147  */
148 const char *dict_ciphone_str(dict_t *d, /**< In: Dictionary to look up */
149                              s3wid_t wid,       /**< In: Component word being looked up */
150                              int32 pos          /**< In: Pronunciation phone position */
151     );
152
153 /** Packaged macro access to dictionary members */
154 #define dict_size(d)            ((d)->n_word)
155 #define dict_num_fillers(d)   (dict_filler_end(d) - dict_filler_start(d))
156 /**
157  * Number of "real words" in the dictionary.
158  *
159  * This is the number of words that are not fillers, <s>, or </s>.
160  */
161 #define dict_num_real_words(d)                                          \
162     (dict_size(d) - (dict_filler_end(d) - dict_filler_start(d)) - 2)
163 #define dict_basewid(d,w)       ((d)->word[w].basewid)
164 #define dict_wordstr(d,w)       ((w) < 0 ? NULL : (d)->word[w].word)
165 #define dict_basestr(d,w)       ((d)->word[dict_basewid(d,w)].word)
166 #define dict_nextalt(d,w)       ((d)->word[w].alt)
167 #define dict_pronlen(d,w)       ((d)->word[w].pronlen) 
168 #define dict_pron(d,w,p)        ((d)->word[w].ciphone[p]) /**< The CI phones of the word w at position p */
169 #define dict_filler_start(d)    ((d)->filler_start)
170 #define dict_filler_end(d)      ((d)->filler_end)
171 #define dict_startwid(d)        ((d)->startwid)
172 #define dict_finishwid(d)       ((d)->finishwid)
173 #define dict_silwid(d)          ((d)->silwid)
174 #define dict_is_single_phone(d,w)       ((d)->word[w].pronlen == 1)
175 #define dict_first_phone(d,w)   ((d)->word[w].ciphone[0])
176 #define dict_second_phone(d,w)  ((d)->word[w].ciphone[1])
177 #define dict_second_last_phone(d,w)     ((d)->word[w].ciphone[(d)->word[w].pronlen - 2])
178 #define dict_last_phone(d,w)    ((d)->word[w].ciphone[(d)->word[w].pronlen - 1])
179
180 /* Hard-coded special words */
181 #define S3_START_WORD           "<s>"
182 #define S3_FINISH_WORD          "</s>"
183 #define S3_SILENCE_WORD         "<sil>"
184 #define S3_UNKNOWN_WORD         "<UNK>"
185
186 /**
187  * If the given word contains a trailing "(....)" (i.e., a Sphinx-II style alternative
188  * pronunciation specification), strip that trailing portion from it.  Note that the given
189  * string is modified.
190  * Return value: If string was modified, the character position at which the original string
191  * was truncated; otherwise -1.
192  */
193 int32 dict_word2basestr(char *word);
194
195 /**
196  * Retain a pointer to an dict_t.
197  */
198 dict_t *dict_retain(dict_t *d);
199
200 /**
201  * Release a pointer to a dictionary.
202  */
203 int dict_free(dict_t *d);
204
205 /** Report a dictionary structure */
206 void dict_report(dict_t *d /**< A dictionary structure */
207     );
208
209 #if 0
210 { /* Stop indent from complaining */
211 #endif
212 #ifdef __cplusplus
213 }
214 #endif
215
216 #endif