]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/expr.tex
Doc updates.
[wxWidgets.git] / docs / latex / wx / expr.tex
... / ...
CommitLineData
1\section{\class{wxExpr}}\label{wxexpr}
2
3The {\bf wxExpr} class is the building brick of expressions similar to Prolog
4clauses, or objects. It can represent an expression of type long integer, float, string, word,
5or list, and lists can be nested.
6
7\wxheading{Derived from}
8
9None
10
11\wxheading{Include files}
12
13<wx/wxexpr.h>
14
15\wxheading{See also}
16
17\helpref{wxExpr overview}{exproverview}, \helpref{wxExprDatabase}{wxexprdatabase}
18
19\latexignore{\rtfignore{\wxheading{Members}}}
20
21\membersection{wxExpr::wxExpr}\label{wxexprconstr}
22
23\func{}{wxExpr}{\param{const wxString\&}{functor}}
24
25Construct a new clause with this form, supplying the functor name. A clause is an object
26that will appear in the data file, with a list of attribute/value pairs.
27
28\func{}{wxExpr}{\param{wxExprType}{ type}, \param{const wxString\&}{ wordOrString = ``"}}
29
30Construct a new empty list, or a word (will be output with no quotes), or a string, depending on the
31value of {\it type}.
32
33{\it type} can be {\bf wxExprList}, {\bf wxExprWord}, or {\bf wxExprString}. If {\it type} is wxExprList,
34the value of {\it wordOrString} will be ignored.
35
36\func{}{wxExpr}{\param{long}{ value}}
37
38Construct an integer expression.
39
40\func{}{wxExpr}{\param{float}{ value}}
41
42Construct a floating point expression.
43
44\func{}{wxExpr}{\param{wxList* }{value}}
45
46Construct a list expression. The list's nodes' data should
47themselves be {\bf wxExpr}s.
48
49The current version of this library no longer uses the {\bf wxList}
50internally, so this constructor turns the list into its internal
51format (assuming a non-nested list) and then deletes the supplied
52list.
53
54\membersection{wxExpr::\destruct{wxExpr}}
55
56\func{}{\destruct{wxExpr}}{\void}
57
58Destructor.
59
60\membersection{wxExpr::AddAttributeValue}\label{wxexpraddattributevalue}
61
62Use these on clauses ONLY. Note that the functions for adding strings
63and words must be differentiated by function name which is why
64they are missing from this group (see \helpref{wxExpr::AddAttributeValueString}{wxexpraddattributevaluestring} and
65\rtfsp\helpref{wxExpr::AddAttributeValueWord}{wxexpraddattributevalueword}).
66
67\func{void}{AddAttributeValue}{\param{const wxString\&}{ attribute}, \param{float }{value}}
68
69Adds an attribute and floating point value pair to the clause.
70
71\func{void}{AddAttributeValue}{\param{const wxString\&}{ attribute}, \param{long }{value}}
72
73Adds an attribute and long integer value pair to the clause.
74
75\func{void}{AddAttributeValue}{\param{const wxString\&}{ attribute}, \param{wxList* }{value}}
76
77Adds an attribute and list value pair to the clause, converting the list into
78internal form and then deleting {\bf value}. Note that the list should not contain
79nested lists (except if in internal {\bf wxExpr} form.)
80
81\func{void}{AddAttributeValue}{\param{const wxString\&}{ attribute}, \param{wxExpr* }{value}}
82
83Adds an attribute and wxExpr value pair to the clause. Do not delete\rtfsp
84{\it value} once this function has been called.
85
86\membersection{wxExpr::AddAttributeValueString}\label{wxexpraddattributevaluestring}
87
88\func{void}{AddAttributeValueString}{\param{const wxString\&}{ attribute}, \param{const wxString\&}{ value}}
89
90Adds an attribute and string value pair to the clause.
91
92\membersection{wxExpr::AddAttributeValueStringList}\label{wxexpraddattributevaluestringlist}
93
94\func{void}{AddAttributeValueStringList}{\param{const wxString\&}{ attribute}, \param{wxList* }{value}}
95
96Adds an attribute and string list value pair to the clause.
97
98Note that the list passed to this function is a list of strings, NOT a list
99of {\bf wxExpr}s; it gets turned into a list of {\bf wxExpr}s
100automatically. This is a convenience function, since lists of strings
101are often manipulated in C++.
102
103\membersection{wxExpr::AddAttributeValueWord}\label{wxexpraddattributevalueword}
104
105\func{void}{AddAttributeValueWord}{\param{const wxString\&}{ attribute}, \param{const wxString\&}{ value}}
106
107Adds an attribute and word value pair to the clause.
108
109\membersection{wxExpr::Append}\label{wxexprappend}
110
111\func{void}{Append}{\param{wxExpr*}{ value}}
112
113Append the {\bf value} to the end of the list. `this' must be a list.
114
115\membersection{wxExpr::Arg}\label{wxexprarg}
116
117\constfunc{wxExpr* }{Arg}{\param{wxExprType}{ type}, \param{int}{ n}}
118
119Get nth arg of the given clause (starting from 1). NULL is returned if
120the expression is not a clause, or {\it n} is invalid, or the given type
121does not match the actual type. See also \helpref{wxExpr::Nth}{wxexprnth}.
122
123\membersection{wxExpr::Insert}\label{wxexprinsert}
124
125\func{void}{Insert}{\param{wxExpr* }{value}}
126
127Insert the {\bf value} at the start of the list. `this' must be a list.
128
129\membersection{wxExpr::GetAttributeValue}\label{wxexprgetattributevalue}
130
131These functions are the easiest way to retrieve attribute values, by
132passing a pointer to variable. If the attribute is present, the
133variable will be filled with the appropriate value. If not, the
134existing value is left alone. This style of retrieving attributes
135makes it easy to set variables to default values before calling these
136functions; no code is necessary to check whether the attribute is
137present or not.
138
139\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{wxString\&}{ value}}
140
141Retrieve a string (or word) value.
142
143\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{float\& }{value}}
144
145Retrieve a floating point value.
146
147\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{int\& }{value}}
148
149Retrieve an integer value.
150
151\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{long\& }{value}}
152
153Retrieve a long integer value.
154
155\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{wxExpr**}{ value}}
156
157Retrieve a wxExpr pointer.
158
159\membersection{wxExpr::GetAttributeValueStringList}\label{wxexprgetattributestringlist}
160
161\constfunc{void}{GetAttributeValueStringList}{\param{const wxString\&}{attribute}, \param{wxList* }{value}}
162
163Use this on clauses ONLY. See above for comments on this style of
164attribute value retrieval. This function expects to receive a pointer to
165a new list (created by the calling application); it will append strings
166to the list if the attribute is present in the clause.
167
168\membersection{wxExpr::AttributeValue}\label{wxexprattributevalue}
169
170\constfunc{wxExpr*}{AttributeValue}{\param{const wxString\&}{ word}}
171
172Use this on clauses ONLY. Searches the clause for an attribute
173matching {\it word}, and returns the value associated with it.
174
175\membersection{wxExpr::Copy}\label{wxexprcopy}
176
177\constfunc{wxExpr*}{Copy}{\void}
178
179Recursively copies the expression, allocating new storage space.
180
181\membersection{wxExpr::DeleteAttributeValue}\label{wxexprdeletattributevalue}
182
183\func{void}{DeleteAttributeValue}{\param{const wxString\&}{ attribute}}
184
185Use this on clauses only. Deletes the attribute and its value (if any) from the
186clause.
187
188\membersection{wxExpr::Functor}\label{wxexprfunctor}
189
190\constfunc{wxString}{Functor}{\void}
191
192Use this on clauses only. Returns the clause's functor (object name).
193
194\membersection{wxExpr::GetClientData}\label{wxexprgetclientdata}
195
196\constfunc{wxObject*}{GetClientData}{\void}
197
198Retrieve arbitrary data stored with this clause. This can be useful when
199reading in data for storing a pointer to the C++ object, so when another
200clause makes a reference to this clause, its C++ object can be retrieved.
201See \helpref{wxExpr::SetClientData}{wxexprsetclientdata}.
202
203\membersection{wxExpr::GetFirst}\label{wxexprgetfirst}
204
205\constfunc{wxExpr*}{GetFirst}{\void}
206
207If this is a list expression (or clause), gets the first element in the list.
208
209See also \helpref{wxExpr::GetLast}{wxexprgetlast}, \helpref{wxExpr::GetNext}{wxexprgetnext}, \helpref{wxExpr::Nth}{wxexprnth}.
210
211\membersection{wxExpr::GetLast}\label{wxexprgetlast}
212
213\constfunc{wxExpr*}{GetLast}{\void}
214
215If this is a list expression (or clause), gets the last element in the list.
216
217See also \helpref{wxExpr::GetFirst}{wxexprgetfirst}, \helpref{wxExpr::GetNext}{wxexprgetnext}, \helpref{wxExpr::Nth}{wxexprnth}.
218
219\membersection{wxExpr::GetNext}\label{wxexprgetnext}
220
221\constfunc{wxExpr*}{GetNext}{\void}
222
223If this is a node in a list (any wxExpr may be a node in a list), gets the
224next element in the list.
225
226See also \helpref{wxExpr::GetFirst}{wxexprgetfirst}, \helpref{wxExpr::GetLast}{wxexprgetlast}, \helpref{wxExpr::Nth}{wxexprnth}.
227
228\membersection{wxExpr::IntegerValue}\label{wxexprintegervalue}
229
230\constfunc{long}{IntegerValue}{\void}
231
232Returns the integer value of the expression.
233
234\membersection{wxExpr::Nth}\label{wxexprnth}
235
236\constfunc{wxExpr*}{Nth}{\param{int}{ n}}
237
238Get nth arg of the given list expression (starting from 0). NULL is returned if
239the expression is not a list expression, or {\it n} is invalid. See also \helpref{wxExpr::Arg}{wxexprarg}.
240
241Normally, you would use attribute-value pairs to add and retrieve data
242from objects (clauses) in a data file. However, if the data gets complex,
243you may need to store attribute values as lists, and pick them apart
244yourself.
245
246\membersection{wxExpr::RealValue}\label{wxexprrealvalue}
247
248\constfunc{float}{RealValue}{\void}
249
250Returns the floating point value of the expression.
251
252\membersection{wxExpr::SetClientData}\label{wxexprsetclientdata}
253
254\func{void}{SetClientData}{\param{wxObject *}{data}}
255
256Associate arbitrary data with this clause. This can be useful when
257reading in data for storing a pointer to the C++ object, so when another
258clause makes a reference to this clause, its C++ object can be retrieved.
259See \helpref{wxExpr::GetClientData}{wxexprgetclientdata}.
260
261\membersection{wxExpr::StringValue}\label{wxexprstringvalue}
262
263\constfunc{wxString}{StringValue}{\void}
264
265Returns the string value of the expression.
266
267\membersection{wxExpr::Type}\label{wxexprtype}
268
269\constfunc{wxExprType}{Type}{\void}
270
271Returns the type of the expression. {\bf wxExprType} is defined as follows:
272
273\begin{verbatim}
274typedef enum {
275 wxExprNull,
276 wxExprInteger,
277 wxExprReal,
278 wxExprWord,
279 wxExprString,
280 wxExprList
281} wxExprType;
282\end{verbatim}
283
284\membersection{wxExpr::WordValue}\label{wxexprwordvalue}
285
286\constfunc{wxString}{WordValue}{\void}
287
288Returns the word value of the expression.
289
290\membersection{wxExpr::WriteLispExpr}\label{wxexprwritelistexpr}
291
292\func{void}{WriteLispExpr}{\param{ostream\&}{ stream}}
293
294Writes the expression or clause to the given stream in LISP format.
295Not normally needed, since the whole {\bf wxExprDatabase} will usually
296be written at once. Lists are enclosed in parentheses will no commas.
297
298\membersection{wxExpr::WritePrologClause}\label{wxexprwriteprologclause}
299
300\func{void}{WritePrologClause}{\param{ostream\&}{ stream}}
301
302Writes the clause to the given stream in Prolog format. Not normally needed, since
303the whole {\bf wxExprDatabase} will usually be written at once. The format is:
304functor, open parenthesis, list of comma-separated expressions, close parenthesis,
305full stop.
306
307\membersection{wxExpr::WriteExpr}\label{wxexprwriteexpr}
308
309\func{void}{WriteExpr}{\param{ostream\&}{ stream}}
310
311Writes the expression (not clause) to the given stream in Prolog
312format. Not normally needed, since the whole {\bf wxExprDatabase} will
313usually be written at once. Lists are written in square bracketed,
314comma-delimited format.
315
316\membersection{Functions and macros}
317
318Below are miscellaneous functions and macros associated with wxExpr objects.
319
320\func{bool}{wxExprIsFunctor}{\param{wxExpr *}{expr}, \param{const wxString\&}{ functor}}
321
322Checks that the functor of {\it expr} is {\it functor}.
323
324\func{void}{wxExprCleanUp}{\void}
325
326Cleans up the wxExpr system (YACC/LEX buffers) to avoid memory-checking warnings as the program exits.
327
328\begin{verbatim}
329#define wxMakeInteger(x) (new wxExpr((long)x))
330#define wxMakeReal(x) (new wxExpr((float)x))
331#define wxMakeString(x) (new wxExpr(PrologString, x))
332#define wxMakeWord(x) (new wxExpr(PrologWord, x))
333#define wxMake(x) (new wxExpr(x))
334\end{verbatim}
335
336Macros to help make wxExpr objects.
337
338\section{\class{wxExprDatabase}}\label{wxexprdatabase}
339
340The {\bf wxExprDatabase} class represents a database, or list,
341of Prolog-like expressions. Instances of this class are used for reading,
342writing and creating data files.
343
344\wxheading{Derived from}
345
346\helpref{wxList}{wxlist}\\
347\helpref{wxObject}{wxobject}
348
349\wxheading{See also}
350
351\helpref{wxExpr overview}{exproverview}, \helpref{wxExpr}{wxexpr}
352
353\latexignore{\rtfignore{\wxheading{Members}}}
354
355\membersection{wxExprDatabase::wxExprDatabase}\label{wxexprdatabaseconstr}
356
357\func{void}{wxExprDatabase}{\param{proioErrorHandler}{ handler = 0}}
358
359Construct a new, unhashed database, with an optional error handler. The
360error handler must be a function returning a bool and taking an integer and a string
361argument. When an error occurs when reading or writing a database, this function is
362called. The error is given as the first argument (currently one of WXEXPR\_ERROR\_GENERAL,
363WXEXPR\_ERROR\_SYNTAX) and an error message is given as the second argument. If FALSE
364is returned by the error handler, processing of the wxExpr operation stops.
365
366Another way of handling errors is simply to call \helpref{wxExprDatabase::GetErrorCount}{wxexprdatabasegeterrorcount} after
367the operation, to check whether errors have occurred, instead of installing an error handler.
368If the error count is more than zero, \helpref{wxExprDatabase::Write}{wxexprdatabasewrite} and
369\rtfsp\helpref{wxExprDatabase::Read}{wxexprdatabaseread} will return FALSE to
370the application.
371
372For example:
373
374\begin{verbatim}
375bool myErrorHandler(int err, chat *msg)
376{
377 if (err == WXEXPR_ERROR_SYNTAX)
378 {
379 wxMessageBox(msg, "Syntax error");
380 }
381 return FALSE;
382}
383
384wxExprDatabase database(myErrorHandler);
385\end{verbatim}
386
387
388\func{}{wxExprDatabase}{\param{wxExprType}{ type}, \param{const wxString\&}{attribute},
389\rtfsp\param{int}{ size = 500}, \param{proioErrorHandler}{ handler = 0}}
390
391Construct a new database hashed on a combination of the clause functor and
392a named attribute (often an integer identification).
393
394See above for an explanation of the error handler.
395
396\membersection{wxExprDatabase::\destruct{wxExprDatabase}}
397
398\func{}{\destruct{wxExprDatabase}}{\void}
399
400Delete the database and contents.
401
402\membersection{wxExprDatabase::Append}\label{wxexprdatabaseappend}
403
404\func{void}{Append}{\param{wxExpr* }{clause}}
405
406Append a clause to the end of the database. If the database is hashing,
407the functor and a user-specified attribute will be hashed upon, giving the
408option of random access in addition to linear traversal of the database.
409
410\membersection{wxExprDatabase::BeginFind}\label{wxexprdatabasebeginfind}
411
412\func{void}{BeginFind}{\void}
413
414Reset the current position to the start of the database. Subsequent
415\rtfsp\helpref{wxExprDatabase::FindClause}{wxexprdatabasefindclause} calls will move the pointer.
416
417\membersection{wxExprDatabase::ClearDatabase}\label{wxexprdatabasecleardatabase}
418
419\func{void}{ClearDatabase}{\void}
420
421Clears the contents of the database.
422
423\membersection{wxExprDatabase::FindClause}\label{wxexprdatabasefindclause}
424
425Various ways of retrieving clauses from the database. A return
426value of NULL indicates no (more) clauses matching the given criteria.
427Calling the functions repeatedly retrieves more matching clauses, if any.
428
429\func{wxExpr* }{FindClause}{\param{long}{ id}}
430
431Find a clause based on the special ``id'' attribute.
432
433\func{wxExpr* }{FindClause}{\param{const wxString\&}{ attribute}, \param{const wxString\&}{ value}}
434
435Find a clause which has the given attribute set to the given string or word value.
436
437\func{wxExpr*}{FindClause}{\param{const wxString\&}{ attribute}, \param{long}{ value}}
438
439Find a clause which has the given attribute set to the given integer value.
440
441\func{wxExpr*}{FindClause}{\param{const wxString\&}{ attribute}, \param{float}{ value}}
442
443Find a clause which has the given attribute set to the given floating point value.
444
445\membersection{wxExprDatabase::FindClauseByFunctor}\label{wxexprdatabasefindclausebyfunctor}
446
447\func{wxExpr*}{FindClauseByFunctor}{\param{const wxString\&}{ functor}}
448
449Find the next clause with the specified functor.
450
451\membersection{wxExprDatabase::GetErrorCount}\label{wxexprdatabasegeterrorcount}
452
453\constfunc{int}{GetErrorCount}{\void}
454
455Returns the number of errors encountered during the last read or write operation.
456
457\membersection{wxExprDatabase::HashFind}\label{wxexprdatabasehashfind}
458
459\constfunc{wxExpr*}{HashFind}{\param{const wxString\&}{ functor}, \param{long}{ value}}
460
461Finds the clause with the given functor and with the attribute specified
462in the database constructor having the given integer value.
463
464For example,
465
466\begin{verbatim}
467// Hash on a combination of functor and integer "id" attribute when reading in
468wxExprDatabase db(wxExprInteger, "id");
469
470// Read it in
471db.ReadProlog("data");
472
473// Retrieve a clause with specified functor and id
474wxExpr *clause = db.HashFind("node", 24);
475\end{verbatim}
476
477This would retrieve a clause which is written: {\tt node(id = 24, ..., )}.
478
479\func{wxExpr*}{HashFind}{\param{const wxString\&}{ functor}, \param{const wxString\&}{ value}}
480
481Finds the clause with the given functor and with the attribute specified
482in the database constructor having the given string value.
483
484\membersection{wxExprDatabase::Read}\label{wxexprdatabaseread}
485
486\func{bool}{Read}{\param{const wxString\&}{ filename}}
487
488Reads in the given file, returning TRUE if successful.
489
490\membersection{wxExprDatabase::ReadFromString}\label{wxexprdatabasereadfromstring}
491
492\func{bool}{ReadFromString}{\param{const wxString\&}{ buffer}}
493
494Reads a Prolog database from the given string buffer, returning TRUE if
495successful.
496
497\membersection{wxExprDatabase::WriteLisp}\label{wxexprdatabasewritelisp}
498
499\func{bool}{WriteLisp}{\param{ostream\& }{stream}}
500
501Writes the database as a LISP-format file.
502
503\membersection{wxExprDatabase::Write}\label{wxexprdatabasewrite}
504
505\func{bool}{Write}{\param{ostream\& }{stream}}
506
507\func{bool}{Write}{\param{const wxString\&}{ filename}}
508
509Writes the database as a Prolog-format file.
510
511