/*
 * $Id: command.txt,v 1.11 2001/09/11 10:15:24 vszakats Exp $
 */

/*
 * 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$
 *      OOP Command
 *  $ONELINER$
 *      Define a Class for Object Oriented Programming
 *  $SYNTAX$
 *      [CREATE] CLASS <ClassName> [ <FROM, INHERIT> <SuperClass1> [,<SuperClassN>] ]  [STATIC]
 *  $ARGUMENTS$
 *      <ClassName>  Name of the class to define. By tradition, Harbour
 *                   classes start with "T" to avoid collisions with user-
 *                   created classes.
 *
 *      <SuperClass1...n> The Parent class(es) to use for inheritance.
 *                   Harbour supports Multiple Inheritance.
 *
 *      STATIC       This clause causes the class function to be declared
 *                   as a static function. It will therefore not be available outside the current module.
 *
 *  $DESCRIPTION$
 *      CLASS creates a class from which you can create objects.
 *      The CLASS command begins the class specification, in which the DATA
 *      elements (also known as instance variables) and METHODS of the
 *      class are named. The following scoping commands may also appear.
 *      They control the default scope of DATA and METHOD commands that follow them.
 *
 *      <fixed>
 *         EXPORTED: 
 *         VISIBLE: 
 *         HIDDEN: 
 *         PROTECTED: 
 *      </fixed>
 *      The class specification ends with the END CLASS command.
 *
 *      Classes can inherit from multiple <SuperClasses>, and the chain of
 *      inheritance can extend to many levels.
 *
 *      A program uses a Class by calling the Class Constructor, usually 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.
 *
 *      Harbour's OOP syntax and implementation supports Scoping (Protect, Hidden and Readonly)
 *      and Delegating, and is largely compatible with Class(y)(tm), TopClass(tm)
 *      and Visual Objects(tm).
 *  $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$
 *      CLASS is a Harbour extension.
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      HBClass(),Object Oriented Programming,DATA,METHOD
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      DATA
 *  $CATEGORY$
 *      OOP Command
 *  $ONELINER$
 *      Alternate syntax for VAR: instance variable for the objects.
 *  $SYNTAX$
 *      DATA <DataName1> [,<DataNameN>] [ AS <type> ] [ INIT <uValue> ]
 *      [[EXPORTED | VISIBLE] | [PROTECTED] | [HIDDEN]] [READONLY | RO]
 *  $ARGUMENTS$
 *      <DataName1>  Name of the DATA

 *      <type>       Optional data type specification from the following:
 *                   Character, Numeric, Date, Logical, Codeblock, Nil.

 *      <uValue>     Optional initial value when creating a new object.
 *
 *      EXPORTED     Specifies that this DATA is accessible to functions and
 *                   methods outside of the class.  VISIBLE is a synonym for EXPORTED.
 *
 *      PROTECTED    Specifies that this DATA is only accessible to functions and methods within this class and its subclasses.
 *
 *      HIDDEN       Specifies that this DATA is only accessible to the
 *                   class where it was defined, and is not inherited by the
 *                   subclasses.

 *      READONLY     Restricts assignment to the variable. If specified with
 *                   the EXPORTED clause, assignment is only permitted from the current
 *                   class and its subclasses.  If specified with the PROTECTED clause,
 *                   assignment is only permitted from the current class.
 *                   RO is a synonym for READONLY.

 *  $DESCRIPTION$
 *      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.
 *
 *      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.
 *
 *      Use the "INIT <uValue>" clause to initialize that DATA to <uValue>
 *      whenever a new object is created.
 *
 *      VAR can be a synonym for DATA, or it can use a slightly different
 *      syntax for compatibility with other dialects.

 *  $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
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      DATA is a Harbour extension.
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      Object Oriented Programming,CLASS,METHOD,CLASSDATA,VAR
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      CLASSDATA
 *  $CATEGORY$
 *      OOP Command
 *  $ONELINER$
 *      Define a CLASSDATA variable for a class (NOT for an Object!)
 *  $SYNTAX$
 *      CLASSDATA <DataName1> [,<DataNameN>] [ AS <type> ] [ INIT <uValue> ]
 *  $ARGUMENTS$
 *      <DataName1>  Name of the DATA

 *      <type>       Optional data type specification from the following:
 *                      Character, Numeric, Date, Logical, Codeblock, Nil

 *      <uValue>     Optional initial value at program startup
 *  $DESCRIPTION$
 *      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.
 *
 *      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.
 *      Use the "INIT <uValue>" clause to initialize that DATA to <uValue>
 *      whenever the class is first used.
 *  $EXAMPLES$
       <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *         CLASSDATA lRegistered AS LOGICAL
 *      ENDCLASS
        </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      CLASSDATA is a Harbour extension.
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      Object Oriented Programming,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      METHOD
 *  $CATEGORY$
 *      OOP 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$
 *      <MethodName>  Name of the method to define

 *      <params,...>  Optional parameter list
 *  $DESCRIPTION$
 *      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:
 *
 *         METHOD <MethodName>( [<params,...>] ) CLASS <ClassName>
 *
 *      Methods can reference the current object with the keyword "Self:" or
 *      its shorthand version "::".
 *
 *      CLAUSES:
 *
 *      CONSTRUCTOR  Defines a special method Class Constructor method,
 *                   used to create objects.  This is usually the
 *                   New() method. Constructors always return the new
 *                   object.
 *
 *      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.
 *
 *      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:
 *
 *          METHOD <MethodName> BLOCK {|Self,<arg1>,<arg2>, ...,<argN>|...}
 *
 *      EXTERN       If an external function does what the method needs,
 *                   use this clause to make an optimized call to that
 *                   function directly.
 *
 *      SETGET       For calculated Data. The name of the method can be
 *                   manipulated like a Data element to Set or Get a value.
 *
 *      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.
 *
 *      OPERATOR     Operator Overloading for classes.
 *                   See example Tests/TestOp.prg for details.
 *
 *      CLASS <ClassName>
 *                   Use this syntax only for defining a full method after
 *                   the ENDCLASS command.
 *  $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$
        <fixed>
 *      TestOp.prg
         </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      METHOD is a Harbour extension.
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      HBClass(),Object Oriented Programming,DATA,CLASS
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      MESSAGE
 *  $CATEGORY$
 *      OOP Command
 *  $ONELINER$
 *      Route a method call to another Method
 *  $SYNTAX$
 *      MESSAGE <MessageName>   METHOD <MethodName>( [<params,...>] )
 *      MESSAGE <MessageName>() METHOD <MethodName>( [<params,...>] )
 *  $ARGUMENTS$
 *      <MessageName>  The pseudo-method name to define

 *      <MethodName>   The method to create and call when <MessageName>
 *                     is invoked.

 *      <params,...>   Optional parameter list for the method
 *  $DESCRIPTION$
 *      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.
 *
 *      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).
 *
 *      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().
 *  $EXAMPLES$
    <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *         METHOD New( ) CONSTRUCTOR
 *         MESSAGE BeginPaint METHOD xBeginPaint()
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      MESSAGE is a Harbour extension.
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      METHOD,DATA,CLASS,Object Oriented Programming
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      ERROR HANDLER
 *  $CATEGORY$
 *      OOP Command
 *  $ONELINER$
 *      Designate a method as an error handler for the class
 *  $SYNTAX$
 *      ERROR HANDLER <MethodName>( [<params,...>] )
 *  $ARGUMENTS$
 *      <MethodName>  Name of the method to define

 *      <params,...>  Optional parameter list
 *  $DESCRIPTION$
 *      ERROR HANDLER names the method that should handle errors for the
 *      class being defined.
 *  $EXAMPLES$
    <fixed>
 *      CLASS TWindow
 *         ERROR HANDLER  MyErrHandler()
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      ERROR HANDLER is a Harbour extension.
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      Object Oriented Programming,ON ERROR,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      ON ERROR
 *  $CATEGORY$
 *      OOP Command
 *  $ONELINER$
 *      Designate a method as an error handler for the class
 *  $SYNTAX$
 *      ON ERROR <MethodName>( [<params,...>] )
 *  $ARGUMENTS$
 *      <MethodName>  Name of the method to define

 *      <params,...>  Optional parameter list
 *  $DESCRIPTION$
 *      ON ERROR is a synonym for ERROR HANDLER.
 *      It names the method that should handle errors for the
 *      class being defined.
 *  $EXAMPLES$
    <fixed>
 *      CLASS TWindow
 *         ON ERROR  MyErrHandler()
 *      ENDCLASS
    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      ON ERROR is a Harbour extension.
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      Object Oriented Programming,ERROR HANDLER,CLASS,METHOD,DATA
 *  $END$
 */

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