/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Brian Hays <bhays@abacuslaw.com>
 *    Documentation for the commands
 *
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      CLASS
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Define a Class for Object Oriented Programming
 *  $SYNTAX$
 *      CLASS <ClassName> [ <FROM, INHERIT> <SuperClass> ]
 *  $ARGUMENTS$
 *      <par><ClassName>  Name of the class to define. By tradition, Harbour
 *                   classes start with "T" to avoid collisions with user-
 *                   created classes.  </par>
 *      <par><SuperClass> The Parent class to use for inheritance   </par>
 *  $DESCRIPTION$
 *      <par>CLASS creates a class from which you can create objects.
 *      Each Class is defined in a separate .PRG file dedicated to that
 *      purpose. You cannot create more than one class in a .PRG.
 *      After the CLASS command begins the definition, the DATA
 *      elements (also known as instance variables) and METHODS of the
 *      class are named.  </par>
 *
 *      <par>Classes can inherit from a single <SuperClass>, but the chain of
 *      inheritance can extend to many levels.  </par>
 *
 *      <par>A program uses a Class by calling the Class Constructor, the
 *      New() method, to create an object. That object is usually assigned
 *      to a variable, which is used to access the DATA elements and
 *      methods.  </par>
 *  $EXAMPLES$
    <fixed>
 *      CLASS TBColumn
 *
 *         DATA Block      // Code block to retrieve data for the column
 *         DATA Cargo      // User-definable variable
 *         DATA ColorBlock // Code block that determines color of data items
 *         DATA ColSep     // Column separator character
 *         DATA DefColor   // Array of numeric indexes into the color table
 *         DATA Footing    // Column footing
 *         DATA FootSep    // Footing separator character
 *         DATA Heading    // Column heading
 *         DATA HeadSep    // Heading separator character
 *         DATA Width      // Column display width
 *         DATA ColPos     // Temporary column position on screen
 *
 *         METHOD New()    // Constructor
 *
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      <par>CLASS is a Harbour extension.  </par>
 *  $PLATFORMS$
 *      <par>All  </par>
 *  $SEEALSO$
 *      TClass(),Object Oriented Programming,DATA,METHOD
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      DATA
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Define a DATA instance variable for the objects of a class
 *  $SYNTAX$
 *      DATA <DataName1> [,<DataNameN>] [ AS <type> ] [ INIT <uValue> ]
 *  $ARGUMENTS$
 *      <par><DataName1>  Name of the DATA  </par>
 *      <par><type>       Optional data type specification from the following:
 *                      Character, Numeric, Date, Logical, Codeblock, Nil  </par>
 *      <par><uValue>     Optional initial value when creating a new object  </par>
 *  $DESCRIPTION$
 *      <par>DATA elements can also be thought of as the "properties" of an
 *      object. They can be of any data type, including codeblock.
 *      Once an object has been created, the DATA elements are referenced
 *      with the colon (:) as in  MyObject:Heading := "Last name".
 *      Usually a class also defines methods to manipulate the DATA.  </par>
 *
 *      <par>You can use the "AS <type>" clause to enforce that the DATA is
 *      maintained as a certain type. Otherwise it will take on the type of
 *      whatever value is first assigned to it.  </par>
 *
 *      <par>Use the "INIT <uValue>" clause to initialize that DATA to <uValue>
 *      whenever a new object is created.  </par>
 *  $EXAMPLES$
    <fixed>
 *      CLASS TBColumn
 *
 *         DATA Block      // Code block to retrieve data for the column
 *         DATA Cargo      // User-definable variable
 *         DATA ColorBlock // Code block that determines color of data items
 *         DATA ColSep     // Column separator character
 *         DATA DefColor   // Array of numeric indexes into the color table
 *         DATA Footing    // Column footing
 *         DATA FootSep    // Footing separator character
 *         DATA Heading    // Column heading
 *         DATA HeadSep    // Heading separator character
 *         DATA Width      // Column display width
 *         DATA ColPos     // Temporary column position on screen
 *
 *         METHOD New()    // Constructor
 *
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      <par>DATA is a Harbour extension.  </par>
 *  $PLATFORMS$
 *      <par>All  </par>
 *  $SEEALSO$
 *      Object Oriented Programming,CLASS,METHOD,CLASSDATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      CLASSDATA
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Define a CLASSDATA variable for a class (NOT for an Object!)
 *  $SYNTAX$
 *      CLASSDATA <DataName1> [,<DataNameN>] [ AS <type> ] [ INIT <uValue> ]  </par>
 *  $ARGUMENTS$
 *      <par><DataName1>  Name of the DATA  </par>
 *      <par><type>       Optional data type specification from the following:
 *                      Character, Numeric, Date, Logical, Codeblock, Nil  </par>
 *      <par><uValue>     Optional initial value at program startup  </par>
 *  $DESCRIPTION$
 *      <par>CLASSDATA variables can also be thought of as the "properties" of an
 *      entire class. Each CLASSDATA exists only once, no matter how many
 *      objects are created. A common usage is for a counter that is
 *      incremented whenever an object is created and decremented when one
 *      is destroyed, thus monitoring the number of objects in existance
 *      for this class.  </par>
 *      <par>You can use the "AS <type>" clause to enforce that the CLASSDATA is
 *      maintained as a certain type. Otherwise it will take on the type of
 *      whatever value is first assigned to it.  </par>
 *      <par>Use the "INIT <uValue>" clause to initialize that DATA to <uValue>
 *      whenever the class is first used.  </par>
 *  $EXAMPLES$
   <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *         CLASSDATA lRegistered AS LOGICAL
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      <par>CLASSDATA is a Harbour extension.  </par>
 *  $PLATFORMS$
 *      <par>All                                </par>
 *  $SEEALSO$
 *      Object Oriented Programming,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      METHOD
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Declare a METHOD for a class in the class header
 *  $SYNTAX$
 *      METHOD <MethodName>( [<params,...>] ) [ CONSTRUCTOR ]
 *      METHOD <MethodName>( [<params,...>] ) INLINE <Code,...>
 *      METHOD <MethodName>( [<params,...>] ) BLOCK  <CodeBlock>
 *      METHOD <MethodName>( [<params,...>] ) EXTERN <FuncName>([<args,...>])
 *      METHOD <MethodName>( [<params,...>] ) SETGET
 *      METHOD <MethodName>( [<params,...>] ) VIRTUAL
 *      METHOD <MethodName>( [<param>] )      OPERATOR <op>
 *      METHOD <MethodName>( [<params,...>] ) CLASS <ClassName>
 *  $ARGUMENTS$
 *      <par><MethodName>  Name of the method to define  </par>
 *      <par><params,...>  Optional parameter list  </par>
 *  $DESCRIPTION$
 *      <par>Methods are "class functions" which do the work of the class.
 *      All methods must be defined in the class header between the
 *      CLASS and ENDCLASS commands.  If the body of a method is not fully
 *      defined here, the full body is written below the ENDCLASS command
 *      using this syntax:                     </par>
 *
 *         <par>METHOD <MethodName>( [<params,...>] ) CLASS <ClassName>  </par>
 *
 *      <par>Methods can reference the current object with the keyword "Self:" or
 *      its shorthand version "::".  </par>
 *                                   
 *      <par>CLAUSES:  </par>
 *
 *      <par>CONSTRUCTOR  Defines a special method Class Constructor method,
 *                   used to create objects.  This is usually the
 *                   New() method. Constructors always return the new
 *                   object.  </par>
 *
 *      <par>INLINE       Fast and easy to code, INLINE lets you define the
 *                   code for the method immediately within the definition
 *                   of the Class. Any methods not declared INLINE or BLOCK
 *                   must be fully defined after the ENDCLASS command.
 *                   The <Code,...> following INLINE receives a parameter
 *                   of Self. If you need to receive more parameters, use
 *                   the BLOCK clause instead.  </par>
 *
 *      <par>BLOCK        Use this clause when you want to declare fast 'inline'
 *                   methods that need parameters. The first parameter to
 *                   <CodeBlock> must be Self, as in:  </par>
 *
 *          <par>METHOD <MethodName> BLOCK {|Self,<arg1>,<arg2>, ...,<argN>|...}  </par>
 *
 *      <par>EXTERN       If an external function does what the method needs,
 *                   use this clause to make an optimized call to that
 *                   function directly.  </par>
 * 
 *      <par>SETGET       For calculated Data. The name of the method can be
 *                   manipulated like a Data element to Set or Get a value.  </par>
 *
 *      <par>VIRTUAL      Methods that do nothing. Useful for Base classes where
 *                   the child class will define the method's behavior, or
 *                   when you are first creating and testing a Class.  </par>
 *
 *      <par>OPERATOR     Operator Overloading for classes.
 *                   See example Tests/TestOp.prg for details.         </par>
 *
 *      <par>CLASS <ClassName>   </par>
 *                   <par>Use this syntax only for defining a full method after
 *                   the ENDCLASS command.  </par>
 *  $EXAMPLES$
    <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *         METHOD New( ) CONSTRUCTOR
 *         METHOD Capture() INLINE  SetCapture( ::hWnd )
 *         METHOD End() BLOCK  { | Self, lEnd | If( lEnd := ::lValid(),;
 *                                 ::PostMsg( WM_CLOSE ),), lEnd }
 *         METHOD EraseBkGnd( hDC )
 *         METHOD cTitle( cNewTitle ) SETGET
 *         METHOD Close() VIRTUAL
 *      ENDCLASS
 *
 *      METHOD New( ) CLASS TWindow
 *         local nVar, cStr
 *         ... <code> ...
 *         ... <code> ...
 *      RETURN Self
    </fixed>
 *  $TESTS$
 *      TestOp.prg
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      <par>METHOD is a Harbour extension.      </par>
 *  $PLATFORMS$
 *      <par>All  </par>
 *  $SEEALSO$
 *      TClass(),Object Oriented Programming,DATA,CLASS
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      MESSAGE
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Route a method call to another Method
 *  $SYNTAX$
 *      MESSAGE <MessageName>   METHOD <MethodName>( [<params,...>] )
 *      MESSAGE <MessageName>() METHOD <MethodName>( [<params,...>] )
 *  $ARGUMENTS$
 *      <par><MessageName>  The pseudo-method name to define  </par>
 *      <par><MethodName>   The method to create and call when <MessageName>
 *                     is invoked.  </par>
 *      <par><params,...>   Optional parameter list for the method  </par>
 *  $DESCRIPTION$
 *      <par>The MESSAGE command is a seldom-used feature that lets you re-route
 *      a call to a method with a different name. This can be necessary if
 *      a method name conflicts with a public function that needs to be
 *      called from within the class methods.  </par>
 *
 *      <par>For example, your app may have a public function called BeginPaint()
 *      that is used in painting windows. It would also be natural to have a
 *      Window class method called :BeginPaint() that the application can
 *      call. But within the class method you would not be able to call the
 *      public function because internally methods are based on static
 *      functions (which hide public functions of the same name).  </par>
 *
 *      <par>The MESSAGE command lets you create the true method with a different
 *      name (::xBeginPaint()), yet still allow the ::BeginPaint() syntax
 *      to call ::xBeginPaint().  This is then free to call the public
 *      function BeginPaint().  </par>
 *  $EXAMPLES$
    <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *         METHOD New( ) CONSTRUCTOR
 *         MESSAGE BeginPaint METHOD xBeginPaint()
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      <par>MESSAGE is a Harbour extension.  </par>
 *  $PLATFORMS$
 *      <par>All  </par>
 *  $SEEALSO$
 *      METHOD,DATA,CLASS,Object Oriented Programming
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      ERROR HANDLER
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Designate a method as an error handler for the class
 *  $SYNTAX$
 *      ERROR HANDLER <MethodName>( [<params,...>] )
 *  $ARGUMENTS$
 *      <par><MethodName>  Name of the method to define  </par>
 *      <par><params,...>  Optional parameter list  </par>
 *  $DESCRIPTION$
 *      <par>ERROR HANDLER names the method that should handle errors for the
 *      class being defined.  </par>
 *  $EXAMPLES$
    <fixed>
 *      CLASS TWindow
 *         ERROR HANDLER  MyErrHandler()
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      <par>ERROR HANDLER is a Harbour extension.  </par>
 *  $PLATFORMS$
 *      <par>All      </par>
 *  $SEEALSO$
 *      Object Oriented Programming,ON ERROR,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      ON ERROR
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Designate a method as an error handler for the class
 *  $SYNTAX$
 *      ON ERROR <MethodName>( [<params,...>] )
 *  $ARGUMENTS$
 *      <par><MethodName>  Name of the method to define  </par>
 *      <par><params,...>  Optional parameter list  </par>
 *  $DESCRIPTION$
 *      <par>ON ERROR is a synonym for ERROR HANDLER.
 *      It names the method that should handle errors for the
 *      class being defined.  </par>
 *  $EXAMPLES$
    <fixed>
 *      CLASS TWindow
 *         ON ERROR  MyErrHandler()
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      <par>ON ERROR is a Harbour extension.  </par>
 *  $PLATFORMS$
 *      <par>All  </par>
 *  $SEEALSO$
 *      Object Oriented Programming,ERROR HANDLER,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      ENDCLASS
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      End the declaration of a class.
 *  $SYNTAX$
 *      ENDCLASS 
 *  $DESCRIPTION$
 *      <par>ENDCLASS marks the end of a class declaration.  </par>
 *      <par>It is usually followed by the class methods that are not INLINE.  </par>
 *  $EXAMPLES$
     <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *      ENDCLASS
     </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      <par>ON ERROR is a Harbour extension.  </par>
 *  $PLATFORMS$
 *      <par>All  </par>
 *  $SEEALSO$
 *      Object Oriented Programming,CLASS,METHOD,DATA
 *  $END$
 */
