I've now added the documentation files.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@11 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
1998-05-20 14:25:30 +00:00
parent bbf1f0e5cf
commit a660d684ed
340 changed files with 51526 additions and 0 deletions
--- a/docs/latex/wx/expr.tex
+++ b/docs/latex/wx/expr.tex
@@ -0,0 +1,505 @@
+\section{\class{wxExpr}}\label{wxexpr}
+
+The {\bf wxExpr} class is the building brick of expressions similar to Prolog
+clauses, or objects. It can represent an expression of type long integer, float, string, word,
+or list, and lists can be nested.
+
+\wxheading{Derived from}
+
+None
+
+\wxheading{See also}
+
+\helpref{wxExpr overview}{exproverview}, \helpref{wxExprDatabase}{wxexprdatabase}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxExpr::wxExpr}\label{wxexprconstr}
+
+\func{}{wxExpr}{\param{const wxString\&}{functor}}
+
+Construct a new clause with this form, supplying the functor name. A clause is an object
+that will appear in the data file, with a list of attribute/value pairs.
+
+\func{}{wxExpr}{\param{wxExprType}{ type}, \param{const wxString\&}{ wordOrString = ``"}}
+
+Construct a new empty list, or a word (will be output with no quotes), or a string, depending on the
+value of {\it type}.
+
+{\it type} can be {\bf wxExprList}, {\bf wxExprWord}, or {\bf wxExprString}. If {\it type} is wxExprList,
+the value of {\it wordOrString} will be ignored.
+
+\func{}{wxExpr}{\param{long}{ value}}
+
+Construct an integer expression.
+
+\func{}{wxExpr}{\param{float}{ value}}
+
+Construct a floating point expression.
+
+\func{}{wxExpr}{\param{wxList* }{value}}
+
+Construct a list expression. The list's nodes' data should
+themselves be {\bf wxExpr}s.
+
+The current version of this library no longer uses the {\bf wxList}
+internally, so this constructor turns the list into its internal
+format (assuming a non-nested list) and then deletes the supplied
+list.
+
+\membersection{wxExpr::\destruct{wxExpr}}
+
+\func{}{\destruct{wxExpr}}{\void}
+
+Destructor.
+
+\membersection{wxExpr::AddAttributeValue}\label{wxexpraddattributevalue}
+
+Use these on clauses ONLY. Note that the functions for adding strings
+and words must be differentiated by function name which is why
+they are missing from this group (see \helpref{wxExpr::AddAttributeValueString}{wxexpraddattributevaluestring} and
+\rtfsp\helpref{wxExpr::AddAttributeValueWord}{wxexpraddattributevalueword}).
+
+\func{void}{AddAttributeValue}{\param{const wxString\&}{ attribute}, \param{float }{value}}
+
+Adds an attribute and floating point value pair to the clause.
+
+\func{void}{AddAttributeValue}{\param{const wxString\&}{ attribute}, \param{long }{value}}
+
+Adds an attribute and long integer value pair to the clause.
+
+\func{void}{AddAttributeValue}{\param{const wxString\&}{ attribute}, \param{wxList* }{value}}
+
+Adds an attribute and list value pair to the clause, converting the list into
+internal form and then deleting {\bf value}. Note that the list should not contain
+nested lists (except if in internal {\bf wxExpr} form.)
+
+\func{void}{AddAttributeValue}{\param{const wxString\&}{ attribute}, \param{wxExpr* }{value}}
+
+Adds an attribute and wxExpr value pair to the clause. Do not delete\rtfsp
+{\it value} once this function has been called.
+
+\membersection{wxExpr::AddAttributeValueString}\label{wxexpraddattributevaluestring}
+
+\func{void}{AddAttributeValueString}{\param{const wxString\&}{ attribute}, \param{const wxString\&}{ value}}
+
+Adds an attribute and string value pair to the clause.
+
+\membersection{wxExpr::AddAttributeValueStringList}\label{wxexpraddattributevaluestringlist}
+
+\func{void}{AddAttributeValueStringList}{\param{const wxString\&}{ attribute}, \param{wxList* }{value}}
+
+Adds an attribute and string list value pair to the clause.
+
+Note that the list passed to this function is a list of strings, NOT a list
+of {\bf wxExpr}s; it gets turned into a list of {\bf wxExpr}s
+automatically. This is a convenience function, since lists of strings
+are often manipulated in C++.
+
+\membersection{wxExpr::AddAttributeValueWord}\label{wxexpraddattributevalueword}
+
+\func{void}{AddAttributeValueWord}{\param{const wxString\&}{ attribute}, \param{const wxString\&}{ value}}
+
+Adds an attribute and word value pair to the clause.
+
+\membersection{wxExpr::Append}\label{wxexprappend}
+
+\func{void}{Append}{\param{wxExpr*}{ value}}
+
+Append the {\bf value} to the end of the list. `this' must be a list.
+
+\membersection{wxExpr::Arg}\label{wxexprarg}
+
+\constfunc{wxExpr* }{Arg}{\param{wxExprType}{ type}, \param{int}{ n}}
+
+Get nth arg of the given clause (starting from 1). NULL is returned if
+the expression is not a clause, or {\it n} is invalid, or the given type
+does not match the actual type. See also \helpref{wxExpr::Nth}{wxexprnth}.
+
+\membersection{wxExpr::Insert}\label{wxexprinsert}
+
+\func{void}{Insert}{\param{wxExpr* }{value}}
+
+Insert the {\bf value} at the start of the list. `this' must be a list.
+
+\membersection{wxExpr::GetAttributeValue}\label{wxexprgetattributevalue}
+
+These functions are the easiest way to retrieve attribute values, by
+passing a pointer to variable. If the attribute is present, the
+variable will be filled with the appropriate value.  If not, the
+existing value is left alone.  This style of retrieving attributes
+makes it easy to set variables to default values before calling these
+functions; no code is necessary to check whether the attribute is
+present or not.
+
+\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{wxString\&}{ value}}
+
+Retrieve a string (or word) value.
+
+\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{float\& }{value}}
+
+Retrieve a floating point value.
+
+\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{int\& }{value}}
+
+Retrieve an integer value.
+
+\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{long\& }{value}}
+
+Retrieve a long integer value.
+
+\constfunc{bool}{GetAttributeValue}{\param{const wxString\&}{ attribute}, \param{wxExpr**}{ value}}
+
+Retrieve a wxExpr pointer.
+
+\membersection{wxExpr::GetAttributeValueStringList}\label{wxexprgetattributestringlist}
+
+\constfunc{void}{GetAttributeValueStringList}{\param{const wxString\&}{attribute}, \param{wxList* }{value}}
+
+Use this on clauses ONLY. See above for comments on this style of
+attribute value retrieval. This function expects to receive a pointer to
+a new list (created by the calling application); it will append strings
+to the list if the attribute is present in the clause.
+
+\membersection{wxExpr::AttributeValue}\label{wxexprattributevalue}
+
+\constfunc{wxExpr*}{AttributeValue}{\param{const wxString\&}{ word}}
+
+Use this on clauses ONLY. Searches the clause for an attribute
+matching {\it word}, and returns the value associated with it.
+
+\membersection{wxExpr::Copy}\label{wxexprcopy}
+
+\constfunc{wxExpr*}{Copy}{\void}
+
+Recursively copies the expression, allocating new storage space.
+
+\membersection{wxExpr::DeleteAttributeValue}\label{wxexprdeletattributevalue}
+
+\func{void}{DeleteAttributeValue}{\param{const wxString\&}{ attribute}}
+
+Use this on clauses only. Deletes the attribute and its value (if any) from the
+clause.
+
+\membersection{wxExpr::Functor}\label{wxexprfunctor}
+
+\constfunc{wxString}{Functor}{\void}
+
+Use this on clauses only. Returns the clause's functor (object name).
+
+\membersection{wxExpr::GetClientData}\label{wxexprgetclientdata}
+
+\constfunc{wxObject*}{GetClientData}{\void}
+
+Retrieve arbitrary data stored with this clause. This can be useful when
+reading in data for storing a pointer to the C++ object, so when another
+clause makes a reference to this clause, its C++ object can be retrieved.
+See \helpref{wxExpr::SetClientData}{wxexprsetclientdata}.
+
+\membersection{wxExpr::GetFirst}\label{wxexprgetfirst}
+
+\constfunc{wxExpr*}{GetFirst}{\void}
+
+If this is a list expression (or clause), gets the first element in the list.
+
+See also \helpref{wxExpr::GetLast}{wxexprgetlast}, \helpref{wxExpr::GetNext}{wxexprgetnext}, \helpref{wxExpr::Nth}{wxexprnth}.
+
+\membersection{wxExpr::GetLast}\label{wxexprgetlast}
+
+\constfunc{wxExpr*}{GetLast}{\void}
+
+If this is a list expression (or clause), gets the last element in the list.
+
+See also \helpref{wxExpr::GetFirst}{wxexprgetfirst}, \helpref{wxExpr::GetNext}{wxexprgetnext}, \helpref{wxExpr::Nth}{wxexprnth}.
+
+\membersection{wxExpr::GetNext}\label{wxexprgetnext}
+
+\constfunc{wxExpr*}{GetNext}{\void}
+
+If this is a node in a list (any wxExpr may be a node in a list), gets the
+next element in the list.
+
+See also \helpref{wxExpr::GetFirst}{wxexprgetfirst}, \helpref{wxExpr::GetLast}{wxexprgetlast}, \helpref{wxExpr::Nth}{wxexprnth}.
+
+\membersection{wxExpr::IntegerValue}\label{wxexprintegervalue}
+
+\constfunc{long}{IntegerValue}{\void}
+
+Returns the integer value of the expression.
+
+\membersection{wxExpr::Nth}\label{wxexprnth}
+
+\constfunc{wxExpr*}{Nth}{\param{int}{ n}}
+
+Get nth arg of the given list expression (starting from 0). NULL is returned if
+the expression is not a list expression, or {\it n} is invalid. See also \helpref{wxExpr::Arg}{wxexprarg}.
+
+Normally, you would use attribute-value pairs to add and retrieve data
+from objects (clauses) in a data file. However, if the data gets complex,
+you may need to store attribute values as lists, and pick them apart
+yourself.
+
+\membersection{wxExpr::RealValue}\label{wxexprrealvalue}
+
+\constfunc{float}{RealValue}{\void}
+
+Returns the floating point value of the expression.
+
+\membersection{wxExpr::SetClientData}\label{wxexprsetclientdata}
+
+\func{void}{SetClientData}{\param{wxObject *}{data}}
+
+Associate arbitrary data with this clause. This can be useful when
+reading in data for storing a pointer to the C++ object, so when another
+clause makes a reference to this clause, its C++ object can be retrieved.
+See \helpref{wxExpr::GetClientData}{wxexprgetclientdata}.
+
+\membersection{wxExpr::StringValue}\label{wxexprstringvalue}
+
+\constfunc{wxString}{StringValue}{\void}
+
+Returns the string value of the expression.
+
+\membersection{wxExpr::Type}\label{wxexprtype}
+
+\constfunc{wxExprType}{Type}{\void}
+
+Returns the type of the expression. {\bf wxExprType} is defined as follows:
+
+\begin{verbatim}
+typedef enum {
+    wxExprNull,
+    wxExprInteger,
+    wxExprReal,
+    wxExprWord,
+    wxExprString,
+    wxExprList
+} wxExprType;
+\end{verbatim}
+
+\membersection{wxExpr::WordValue}\label{wxexprwordvalue}
+
+\constfunc{wxString}{WordValue}{\void}
+
+Returns the word value of the expression.
+
+\membersection{wxExpr::WriteLispExpr}\label{wxexprwritelistexpr}
+
+\func{void}{WriteLispExpr}{\param{ostream\&}{ stream}}
+
+Writes the expression or clause to the given stream in LISP format.
+Not normally needed, since the whole {\bf wxExprDatabase} will usually
+be written at once. Lists are enclosed in parentheses will no commas.
+
+\membersection{wxExpr::WritePrologClause}\label{wxexprwriteprologclause}
+
+\func{void}{WritePrologClause}{\param{ostream\&}{ stream}}
+
+Writes the clause to the given stream in Prolog format. Not normally needed, since
+the whole {\bf wxExprDatabase} will usually be written at once. The format is:
+functor, open parenthesis, list of comma-separated expressions, close parenthesis,
+full stop.
+
+\membersection{wxExpr::WriteExpr}\label{wxexprwriteexpr}
+
+\func{void}{WriteExpr}{\param{ostream\&}{ stream}}
+
+Writes the expression (not clause) to the given stream in Prolog
+format. Not normally needed, since the whole {\bf wxExprDatabase} will
+usually be written at once. Lists are written in square bracketed,
+comma-delimited format.
+
+\membersection{Functions and macros}
+
+Below are miscellaneous functions and macros associated with wxExpr objects.
+
+\func{bool}{wxExprIsFunctor}{\param{wxExpr *}{expr}, \param{const wxString\&}{ functor}}
+
+Checks that the functor of {\it expr} is {\it functor}.
+
+\func{void}{wxExprCleanUp}{\void}
+
+Cleans up the wxExpr system (YACC/LEX buffers) to avoid memory-checking warnings as the program exits.
+
+\begin{verbatim}
+#define wxMakeInteger(x) (new wxExpr((long)x))
+#define wxMakeReal(x)    (new wxExpr((float)x))
+#define wxMakeString(x)  (new wxExpr(PrologString, x))
+#define wxMakeWord(x)    (new wxExpr(PrologWord, x))
+#define wxMake(x)        (new wxExpr(x))
+\end{verbatim}
+
+Macros to help make wxExpr objects.
+
+\section{\class{wxExprDatabase}}\label{wxexprdatabase}
+
+The {\bf wxExprDatabase} class represents a database, or list,
+of Prolog-like expressions.  Instances of this class are used for reading,
+writing and creating data files.
+
+\wxheading{Derived from}
+
+\helpref{wxList}{wxlist}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{See also}
+
+\helpref{wxExpr overview}{exproverview}, \helpref{wxExpr}{wxexpr}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxExprDatabase::wxExprDatabase}\label{wxexprdatabaseconstr}
+
+\func{void}{wxExprDatabase}{\param{proioErrorHandler}{ handler = 0}}
+
+Construct a new, unhashed database, with an optional error handler. The
+error handler must be a function returning a bool and taking an integer and a string
+argument. When an error occurs when reading or writing a database, this function is
+called. The error is given as the first argument (currently one of WXEXPR\_ERROR\_GENERAL,
+WXEXPR\_ERROR\_SYNTAX) and an error message is given as the second argument. If FALSE
+is returned by the error handler, processing of the wxExpr operation stops.
+
+Another way of handling errors is simply to call \helpref{wxExprDatabase::GetErrorCount}{wxexprdatabasegeterrorcount} after
+the operation, to check whether errors have occurred, instead of installing an error handler.
+If the error count is more than zero, \helpref{wxExprDatabase::Write}{wxexprdatabasewrite} and
+\rtfsp\helpref{wxExprDatabase::Read}{wxexprdatabaseread} will return FALSE to
+the application.
+
+For example:
+
+\begin{verbatim}
+bool myErrorHandler(int err, chat *msg)
+{
+  if (err == WXEXPR_ERROR_SYNTAX)
+  {
+    wxMessageBox(msg, "Syntax error");
+  }
+  return FALSE;
+}
+
+wxExprDatabase database(myErrorHandler);
+\end{verbatim}
+
+
+\func{}{wxExprDatabase}{\param{wxExprType}{ type}, \param{const wxString\&}{attribute},
+\rtfsp\param{int}{ size = 500}, \param{proioErrorHandler}{ handler = 0}}
+
+Construct a new database hashed on a combination of the clause functor and
+a named attribute (often an integer identification).
+
+See above for an explanation of the error handler.
+
+\membersection{wxExprDatabase::\destruct{wxExprDatabase}}
+
+\func{}{\destruct{wxExprDatabase}}{\void}
+
+Delete the database and contents.
+
+\membersection{wxExprDatabase::Append}\label{wxexprdatabaseappend}
+
+\func{void}{Append}{\param{wxExpr* }{clause}}
+
+Append a clause to the end of the database. If the database is hashing,
+the functor and a user-specified attribute will be hashed upon, giving the
+option of random access in addition to linear traversal of the database.
+
+\membersection{wxExprDatabase::BeginFind}\label{wxexprdatabasebeginfind}
+
+\func{void}{BeginFind}{\void}
+
+Reset the current position to the start of the database. Subsequent
+\rtfsp\helpref{wxExprDatabase::FindClause}{wxexprdatabasefindclause} calls will move the pointer.
+
+\membersection{wxExprDatabase::ClearDatabase}\label{wxexprdatabasecleardatabase}
+
+\func{void}{ClearDatabase}{\void}
+
+Clears the contents of the database.
+
+\membersection{wxExprDatabase::FindClause}\label{wxexprdatabasefindclause}
+
+Various ways of retrieving clauses from the database. A return
+value of NULL indicates no (more) clauses matching the given criteria.
+Calling the functions repeatedly retrieves more matching clauses, if any.
+
+\func{wxExpr* }{FindClause}{\param{long}{ id}}
+
+Find a clause based on the special ``id'' attribute.
+
+\func{wxExpr* }{FindClause}{\param{const wxString\&}{ attribute}, \param{const wxString\&}{ value}}
+
+Find a clause which has the given attribute set to the given string or word value.
+
+\func{wxExpr*}{FindClause}{\param{const wxString\&}{ attribute}, \param{long}{ value}}
+
+Find a clause which has the given attribute set to the given integer value.
+
+\func{wxExpr*}{FindClause}{\param{const wxString\&}{ attribute}, \param{float}{ value}}
+
+Find a clause which has the given attribute set to the given floating point value.
+
+\membersection{wxExprDatabase::FindClauseByFunctor}\label{wxexprdatabasefindclausebyfunctor}
+
+\func{wxExpr*}{FindClauseByFunctor}{\param{const wxString\&}{ functor}}
+
+Find the next clause with the specified functor.
+
+\membersection{wxExprDatabase::GetErrorCount}\label{wxexprdatabasegeterrorcount}
+
+\constfunc{int}{GetErrorCount}{\void}
+
+Returns the number of errors encountered during the last read or write operation.
+
+\membersection{wxExprDatabase::HashFind}\label{wxexprdatabasehashfind}
+
+\constfunc{wxExpr*}{HashFind}{\param{const wxString\&}{ functor}, \param{long}{ value}}
+
+Finds the clause with the given functor and with the attribute specified
+in the database constructor having the given integer value.
+
+For example,
+
+\begin{verbatim}
+// Hash on a combination of functor and integer "id" attribute when reading in
+wxExprDatabase db(wxExprInteger, "id");
+
+// Read it in
+db.ReadProlog("data");
+
+// Retrieve a clause with specified functor and id
+wxExpr *clause = db.HashFind("node", 24);
+\end{verbatim}
+
+This would retrieve a clause which is written: {\tt node(id = 24, ..., )}.
+
+\func{wxExpr*}{HashFind}{\param{const wxString\&}{ functor}, \param{const wxString\&}{ value}}
+
+Finds the clause with the given functor and with the attribute specified
+in the database constructor having the given string value.
+
+\membersection{wxExprDatabase::Read}\label{wxexprdatabaseread}
+
+\func{bool}{Read}{\param{const wxString\&}{ filename}}
+
+Reads in the given file, returning TRUE if successful.
+
+\membersection{wxExprDatabase::ReadFromString}\label{wxexprdatabasereadfromstring}
+
+\func{bool}{ReadFromString}{\param{const wxString\&}{ buffer}}
+
+Reads a Prolog database from the given string buffer, returning TRUE if
+successful.
+
+\membersection{wxExprDatabase::WriteLisp}\label{wxexprdatabasewritelisp}
+
+\func{bool}{WriteLisp}{\param{ostream\& }{stream}}
+
+Writes the database as a LISP-format file.
+
+\membersection{wxExprDatabase::Write}\label{wxexprdatabasewrite}
+
+\func{bool}{Write}{\param{ostream\& }{stream}}
+
+Writes the database as a Prolog-format file.
+
+