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 49wxExpr no longer uses the {\bf wxList} internally, 50so 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::WriteClause}\label{wxexprwriteprologclause} 291 292\func{void}{WriteClause}{\param{FILE *}{ stream}} 293 294Writes the clause to the given stream in Prolog format. Not normally needed, since 295the whole {\bf wxExprDatabase} will usually be written at once. The format is: 296functor, open parenthesis, list of comma-separated expressions, close parenthesis, 297full stop. 298 299\membersection{wxExpr::WriteExpr}\label{wxexprwriteexpr} 300 301\func{void}{WriteExpr}{\param{FILE *}{ stream}} 302 303Writes the expression (not clause) to the given stream in Prolog 304format. Not normally needed, since the whole {\bf wxExprDatabase} will 305usually be written at once. Lists are written in square bracketed, 306comma-delimited format. 307 308\membersection{Functions and macros} 309 310Below are miscellaneous functions and macros associated with wxExpr objects. 311 312\func{bool}{wxExprIsFunctor}{\param{wxExpr *}{expr}, \param{const wxString\&}{ functor}} 313 314Checks that the functor of {\it expr} is {\it functor}. 315 316\func{void}{wxExprCleanUp}{\void} 317 318Cleans 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 328Macros to help make wxExpr objects. 329 330\section{\class{wxExprDatabase}}\label{wxexprdatabase} 331 332The {\bf wxExprDatabase} class represents a database, or list, 333of Prolog-like expressions. Instances of this class are used for reading, 334writing 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 351Construct a new, unhashed database, with an optional error handler. The 352error handler must be a function returning a bool and taking an integer and a string 353argument. When an error occurs when reading or writing a database, this function is 354called. The error is given as the first argument (currently one of WXEXPR\_ERROR\_GENERAL, 355WXEXPR\_ERROR\_SYNTAX) and an error message is given as the second argument. If false 356is returned by the error handler, processing of the wxExpr operation stops. 357 358Another way of handling errors is simply to call \helpref{wxExprDatabase::GetErrorCount}{wxexprdatabasegeterrorcount} after 359the operation, to check whether errors have occurred, instead of installing an error handler. 360If the error count is more than zero, \helpref{wxExprDatabase::Write}{wxexprdatabasewrite} and 361\rtfsp\helpref{wxExprDatabase::Read}{wxexprdatabaseread} will return false to 362the application. 363 364For example: 365 366\begin{verbatim} 367bool myErrorHandler(int err, chat *msg) 368{ 369 if (err == WXEXPR_ERROR_SYNTAX) 370 { 371 wxMessageBox(msg, "Syntax error"); 372 } 373 return false; 374} 375 376wxExprDatabase 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 382Construct a new database hashed on a combination of the clause functor and 383a named attribute (often an integer identification). 384 385See above for an explanation of the error handler. 386 387\membersection{wxExprDatabase::\destruct{wxExprDatabase}} 388 389\func{}{\destruct{wxExprDatabase}}{\void} 390 391Delete the database and contents. 392 393\membersection{wxExprDatabase::Append}\label{wxexprdatabaseappend} 394 395\func{void}{Append}{\param{wxExpr* }{clause}} 396 397Append a clause to the end of the database. If the database is hashing, 398the functor and a user-specified attribute will be hashed upon, giving the 399option 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 405Reset 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 412Clears the contents of the database. 413 414\membersection{wxExprDatabase::FindClause}\label{wxexprdatabasefindclause} 415 416Various ways of retrieving clauses from the database. A return 417value of NULL indicates no (more) clauses matching the given criteria. 418Calling the functions repeatedly retrieves more matching clauses, if any. 419 420\func{wxExpr* }{FindClause}{\param{long}{ id}} 421 422Find a clause based on the special ``id'' attribute. 423 424\func{wxExpr* }{FindClause}{\param{const wxString\&}{ attribute}, \param{const wxString\&}{ value}} 425 426Find 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 430Find 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 434Find 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 440Find the next clause with the specified functor. 441 442\membersection{wxExprDatabase::GetErrorCount}\label{wxexprdatabasegeterrorcount} 443 444\constfunc{int}{GetErrorCount}{\void} 445 446Returns 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 452Finds the clause with the given functor and with the attribute specified 453in the database constructor having the given integer value. 454 455For example, 456 457\begin{verbatim} 458// Hash on a combination of functor and integer "id" attribute when reading in 459wxExprDatabase db(wxExprInteger, "id"); 460 461// Read it in 462db.ReadProlog("data"); 463 464// Retrieve a clause with specified functor and id 465wxExpr *clause = db.HashFind("node", 24); 466\end{verbatim} 467 468This 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 472Finds the clause with the given functor and with the attribute specified 473in 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 479Reads 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 485Reads a Prolog database from the given string buffer, returning true if 486successful. 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 494Writes the database as a Prolog-format file. 495 496 497