docs/latex/wx/expr.tex

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