- Added maximization features, with corresponding plugins. Added painting feature...
[mldemos:mldemos.git] / _3rdParty / dlib / tokenizer / tokenizer_kernel_abstract.h
1 // Copyright (C) 2005  Davis E. King (davis@dlib.net)\r
2 // License: Boost Software License   See LICENSE.txt for the full license.\r
3 #undef DLIB_TOKENIZER_KERNEl_ABSTRACT_\r
4 #ifdef DLIB_TOKENIZER_KERNEl_ABSTRACT_\r
5 \r
6 #include <string>\r
7 #include <ioswfd>\r
8 \r
9 namespace dlib\r
10 {\r
11 \r
12     class tokenizer \r
13     {\r
14         /*!\r
15             INITIAL VALUE\r
16                 stream_is_set() == false\r
17                 get_identifier_head() == "_" + lowercase_letters() + uppercase_letters()\r
18                 get_identifier_body() == "_" + lowercase_letters() + uppercase_letters() + \r
19                                          numbers()\r
20 \r
21             WHAT THIS OBJECT REPRESENTS\r
22                 This object represents a simple tokenizer for textual data.\r
23 \r
24             BUFFERING\r
25                 This object is allowed to buffer data from the input stream.\r
26                 Thus if you clear it or switch streams (via calling set_stream())\r
27                 any buffered data will be lost.\r
28 \r
29             TOKENS\r
30                 When picking out tokens the tokenizer will always extract the \r
31                 longest token it can.  For example, if faced with the string \r
32                 "555" it will consider the three 5s to be a single NUMBER \r
33                 token not three smaller NUMBER tokens.\r
34 \r
35                 Also note that no characters in the input stream are discarded.\r
36                 They will all be returned in the text of some token.  \r
37                 Additionally, each character will never be returned more than once.  \r
38                 This means that if you concatenated all returned tokens it would exactly\r
39                 reproduce the contents of the input stream.\r
40 \r
41                 The tokens are defined as follows:\r
42 \r
43                 END_OF_LINE\r
44                     This is a single character token and is always the '\n' \r
45                     character.\r
46 \r
47                 END_OF_FILE\r
48                     This token represents the end of file.  It doesn't have any\r
49                     actual characters associated with it.  \r
50 \r
51                 IDENTIFIER\r
52                     This is a multi-character token.  It is defined as a string that\r
53                     begins with a character from get_identifier_head() and is \r
54                     followed by any number of characters from get_identifier_body().\r
55                        \r
56                 NUMBER\r
57                     This is a multi-character token.  It is defined as a sequence of\r
58                     numbers. \r
59 \r
60                 WHITE_SPACE\r
61                     This is a multi character token.  It is defined as a sequence of\r
62                     one or more spaces, carrage returns, and tabs.  I.e. It is\r
63                     composed of characters from the following string " \r\t".\r
64 \r
65                 CHAR\r
66                     This is a single character token.  It matches anything that isn't\r
67                     part of one of the above tokens.                    \r
68         !*/\r
69 \r
70     public:\r
71 \r
72         enum \r
73         {\r
74             END_OF_LINE,\r
75             END_OF_FILE,\r
76             IDENTIFIER,\r
77             CHAR,\r
78             NUMBER,\r
79             WHITE_SPACE\r
80         };\r
81 \r
82         tokenizer (        \r
83         );\r
84         /*!\r
85             ensures                \r
86                 - #*this is properly initialized\r
87             throws\r
88                 - std::bad_alloc\r
89         !*/\r
90 \r
91         virtual ~tokenizer (\r
92         );\r
93         /*!\r
94             ensures\r
95                 - any resources associated with *this have been released\r
96         !*/\r
97 \r
98         void clear(\r
99         );\r
100         /*!\r
101             ensures\r
102                 - #*this has its initial value\r
103             throws\r
104                 - std::bad_alloc\r
105                     If this exception is thrown then #*this is unusable \r
106                     until clear() is called and succeeds.\r
107         !*/\r
108 \r
109         void set_stream (\r
110             std::istream& in\r
111         );\r
112         /*!\r
113             ensures\r
114                 - #*this will read data from in and tokenize it\r
115                 - #stream_is_set() == true\r
116                 - #get_stream() == in\r
117         !*/\r
118 \r
119         bool stream_is_set (\r
120         ) const;\r
121         /*!\r
122             ensures\r
123                 - returns true if a stream has been associated with *this by calling\r
124                   set_stream()\r
125         !*/\r
126 \r
127         std::istream& get_stream (\r
128         ) const;\r
129         /*!\r
130             requires\r
131                 - stream_is_set() == true\r
132             ensures\r
133                 - returns a reference to the istream object that *this is reading \r
134                   from.\r
135         !*/\r
136 \r
137         void get_token (\r
138             int& type,\r
139             std::string& token\r
140         );\r
141         /*!\r
142             requires\r
143                 - stream_is_set() == true\r
144             ensures\r
145                 - #token == the next token from the input stream get_stream()\r
146                 - #type == the type of the token in #token\r
147             throws\r
148                 - bad_alloc\r
149                     If this exception is thrown then the call to this function will \r
150                     have no effect on *this but the values of #type and #token will be \r
151                     undefined.  Additionally, some characters may have been read\r
152                     from the stream get_stream() and lost.\r
153         !*/\r
154 \r
155         int peek_type (\r
156         ) const;\r
157         /*!\r
158             requires\r
159                 - stream_is_set() == true\r
160             ensures\r
161                 - returns the type of the token that will be returned from\r
162                   the next call to get_token()\r
163             throws\r
164                 - bad_alloc\r
165                     If this exception is thrown then the call to this function will \r
166                     have no effect on *this.  However, some characters may have been \r
167                     read from the stream get_stream() and lost.\r
168         !*/\r
169 \r
170         const std::string& peek_token (\r
171         ) const;\r
172         /*!\r
173             requires\r
174                 - stream_is_set() == true\r
175             ensures\r
176                 - returns the text of the token that will be returned from\r
177                   the next call to get_token()\r
178             throws\r
179                 - bad_alloc\r
180                     If this exception is thrown then the call to this function will \r
181                     have no effect on *this.  However, some characters may have been \r
182                     read from the stream get_stream() and lost.\r
183         !*/\r
184 \r
185         void set_identifier_token (\r
186             const std::string& head,\r
187             const std::string& body\r
188         );\r
189         /*!\r
190             requires\r
191                 - head.find_first_of(" \r\t\n0123456789") == std::string::npos\r
192                   (i.e. head doesn't contain any characters from the string\r
193                   " \r\t\n0123456789").\r
194                 - body.find_frst_of(" \r\t\n") == std::string::npos\r
195                   (i.e. body doesn't contain any characters from the string " \r\t\n").\r
196             ensures\r
197                 - #get_identifier_head() == head\r
198                 - #get_identifier_body() == body\r
199             throws\r
200                 - std::bad_alloc\r
201                     If this exception is thrown then #*this is unusable \r
202                     until clear() is called and succeeds.\r
203         !*/\r
204 \r
205         const std::string get_identifier_head (\r
206         ) const;\r
207         /*!\r
208             ensures\r
209                 - returns a string containing the characters that can be the start\r
210                   of an IDENTIFIER token.\r
211             throws\r
212                 - std::bad_alloc\r
213                     If this exception is thrown then the call to this function\r
214                     has no effect.\r
215         !*/\r
216 \r
217         const std::string get_identifier_body (\r
218         ) const;\r
219         /*!\r
220             ensures\r
221                 - returns a string containing the characters that can appear in the\r
222                   body of an IDENTIFIER token.\r
223             throws\r
224                 - std::bad_alloc\r
225                     If this exception is thrown then the call to this function\r
226                     has no effect.\r
227         !*/\r
228 \r
229         const std::string lowercase_letters (\r
230         ) const;\r
231         /*!\r
232             ensures\r
233                 - returns "abcdefghijklmnopqrstuvwxyz"\r
234             throws\r
235                 - std::bad_alloc\r
236                     If this exception is thrown then the call to this function\r
237                     has no effect.\r
238         !*/\r
239 \r
240         const std::string uppercase_letters (\r
241         ) const;\r
242         /*!\r
243             ensures\r
244                 - returns "ABCDEFGHIJKLMNOPQRSTUVWXYZ"\r
245             throws\r
246                 - std::bad_alloc\r
247                     If this exception is thrown then the call to this function\r
248                     has no effect.\r
249         !*/\r
250 \r
251         const std::string numbers (\r
252         ) const;\r
253         /*!\r
254             ensures\r
255                 - returns "0123456789"\r
256             throws\r
257                 - std::bad_alloc\r
258                     If this exception is thrown then the call to this function\r
259                     has no effect.\r
260         !*/\r
261 \r
262         void swap (\r
263             tokenizer& item\r
264         );\r
265         /*!\r
266             ensures\r
267                 - swaps *this and item\r
268         !*/ \r
269 \r
270     private:\r
271 \r
272         // restricted functions\r
273         tokenizer(const tokenizer&);        // copy constructor\r
274         tokenizer& operator=(const tokenizer&);    // assignment operator\r
275 \r
276     };    \r
277 \r
278     inline void swap (\r
279         tokenizer& a, \r
280         tokenizer& b \r
281     ) { a.swap(b); }   \r
282     /*!\r
283         provides a global swap function\r
284     !*/\r
285 \r
286 }\r
287 \r
288 #endif // DLIB_TOKENIZER_KERNEl_ABSTRACT_\r
289 \r