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