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 The current version of this library no longer uses the {\bf wxList}
  50 internally, 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
 380 \func{}{wxExprDatabase}{\param{wxExprType}{ type}, \param{const wxString\&}{attribute},
 381 \rtfsp\param{int}{ size = 500}, \param{proioErrorHandler}{ handler = 0}}
 382
 383 Construct a new database hashed on a combination of the clause functor and
 384 a named attribute (often an integer identification).
 385
 386 See above for an explanation of the error handler.
 387
 388 \membersection{wxExprDatabase::\destruct{wxExprDatabase}}
 389
 390 \func{}{\destruct{wxExprDatabase}}{\void}
 391
 392 Delete the database and contents.
 393
 394 \membersection{wxExprDatabase::Append}\label{wxexprdatabaseappend}
 395
 396 \func{void}{Append}{\param{wxExpr* }{clause}}
 397
 398 Append a clause to the end of the database. If the database is hashing,
 399 the functor and a user-specified attribute will be hashed upon, giving the
 400 option of random access in addition to linear traversal of the database.
 401
 402 \membersection{wxExprDatabase::BeginFind}\label{wxexprdatabasebeginfind}
 403
 404 \func{void}{BeginFind}{\void}
 405
 406 Reset the current position to the start of the database. Subsequent
 407 \rtfsp\helpref{wxExprDatabase::FindClause}{wxexprdatabasefindclause} calls will move the pointer.
 408
 409 \membersection{wxExprDatabase::ClearDatabase}\label{wxexprdatabasecleardatabase}
 410
 411 \func{void}{ClearDatabase}{\void}
 412
 413 Clears the contents of the database.
 414
 415 \membersection{wxExprDatabase::FindClause}\label{wxexprdatabasefindclause}
 416
 417 Various ways of retrieving clauses from the database. A return
 418 value of NULL indicates no (more) clauses matching the given criteria.
 419 Calling the functions repeatedly retrieves more matching clauses, if any.
 420
 421 \func{wxExpr* }{FindClause}{\param{long}{ id}}
 422
 423 Find a clause based on the special ``id'' attribute.
 424
 425 \func{wxExpr* }{FindClause}{\param{const wxString\&}{ attribute}, \param{const wxString\&}{ value}}
 426
 427 Find a clause which has the given attribute set to the given string or word value.
 428
 429 \func{wxExpr*}{FindClause}{\param{const wxString\&}{ attribute}, \param{long}{ value}}
 430
 431 Find a clause which has the given attribute set to the given integer value.
 432
 433 \func{wxExpr*}{FindClause}{\param{const wxString\&}{ attribute}, \param{float}{ value}}
 434
 435 Find a clause which has the given attribute set to the given floating point value.
 436
 437 \membersection{wxExprDatabase::FindClauseByFunctor}\label{wxexprdatabasefindclausebyfunctor}
 438
 439 \func{wxExpr*}{FindClauseByFunctor}{\param{const wxString\&}{ functor}}
 440
 441 Find the next clause with the specified functor.
 442
 443 \membersection{wxExprDatabase::GetErrorCount}\label{wxexprdatabasegeterrorcount}
 444
 445 \constfunc{int}{GetErrorCount}{\void}
 446
 447 Returns the number of errors encountered during the last read or write operation.
 448
 449 \membersection{wxExprDatabase::HashFind}\label{wxexprdatabasehashfind}
 450
 451 \constfunc{wxExpr*}{HashFind}{\param{const wxString\&}{ functor}, \param{long}{ value}}
 452
 453 Finds the clause with the given functor and with the attribute specified
 454 in the database constructor having the given integer value.
 455
 456 For example,
 457
 458 \begin{verbatim}
 459 // Hash on a combination of functor and integer "id" attribute when reading in
 460 wxExprDatabase db(wxExprInteger, "id");
 461
 462 // Read it in
 463 db.ReadProlog("data");
 464
 465 // Retrieve a clause with specified functor and id
 466 wxExpr *clause = db.HashFind("node", 24);
 467 \end{verbatim}
 468
 469 This would retrieve a clause which is written: {\tt node(id = 24, ..., )}.
 470
 471 \func{wxExpr*}{HashFind}{\param{const wxString\&}{ functor}, \param{const wxString\&}{ value}}
 472
 473 Finds the clause with the given functor and with the attribute specified
 474 in the database constructor having the given string value.
 475
 476 \membersection{wxExprDatabase::Read}\label{wxexprdatabaseread}
 477
 478 \func{bool}{Read}{\param{const wxString\&}{ filename}}
 479
 480 Reads in the given file, returning TRUE if successful.
 481
 482 \membersection{wxExprDatabase::ReadFromString}\label{wxexprdatabasereadfromstring}
 483
 484 \func{bool}{ReadFromString}{\param{const wxString\&}{ buffer}}
 485
 486 Reads a Prolog database from the given string buffer, returning TRUE if
 487 successful.
 488
 489 \membersection{wxExprDatabase::Write}\label{wxexprdatabasewrite}
 490
 491 \func{bool}{Write}{\param{FILE *}{stream}}
 492
 493 \func{bool}{Write}{\param{const wxString\&}{ filename}}
 494
 495 Writes the database as a Prolog-format file.
 496
 497