Click above to get retro games delivered to your door ever month!

 Symbol Class - Overview
------------------------------------------------------------------------------

    The Symbol class allows messages to be treated as objects.  This allows
    messages to be sent to an object without hard-coding the name of the
    message to be sent.

    The following code fragment illustrates how the Symbol class can be
    used.  It allows the user to select a message from an array of message
    strings, and sends the selected message to the self object.

    METHOD move( nDistance )
        LOCAL i, nOpt, oMsg
        LOCAL acMessages := { "goNorth", "goSouth", "goEast", "goWest" }

        // Display a menu of the messages available
        // A 2-D array would allow us to map more readable prompts to the
        // message names, but this is not necessary for this example
        CLEAR
        FOR i := 1 TO 4
            @ i, 0 PROMPT acMessages[i]
        NEXT i

        // allow user to select a message
        MENU TO nOpt

        IF nOpt <> 0
            // create a Symbol object referring to the selected message
            oMsg := Symbol():new( acMessages[nOpt] )

            // using the predefined perform message, send the selected
            // message to self with one parameter, nDistance.
            self:perform( oMsg, nDistance )
        ENDIF
    RETURN

    As can be seen in the above example, the Symbol class is designed to
    work with the predefined perform message (see also).

    The Symbol class is very useful when designing data driven (or table
    driven) systems.  It allows message names to be stored in data files
    and manipulated like any other data, but still to be sent to objects as
    messages when necessary.

    The reason the class is called Symbol as opposed to Message is
    that each Symbol object corresponds to an entry in the Clipper symbol
    table.  It can be used for purposes other than sending messages.  The
    Symbol exec method is an example of this, causing the function with
    the same name as the receiving Symbol object to be executed.

    A special feature of the Symbol class is that it does not require that
    symbol names be specified as a string.  For example, to create a Symbol
    object referring to a message called foo, we can use either of the
    following two syntaxes:

        oMsg := Symbol():new( "foo" )
    or:
        oMsg := Symbol():foo()

    Even though foo is not a message in the Symbol class, whenever the
    Symbol class is sent a message it does not recognize, it reacts by
    returning a Symbol object referring to that message.  The only message
    for which this will not work is new, since it is defined as a Symbol
    class message.  To obtain a Symbol object referring to the new
    message, use:

        oMsg := Symbol():new( "new" )

    The ability to create symbols without requiring strings can be useful
    in examples like the one given earlier.  We could create an array of
    Symbol objects and corresponding menu descriptions as follows:

        aMenu := { { "Move North", Symbol():goNorth() }, ;
                   { "Move South", Symbol():goSouth() }, ;
                   { "Move West",  Symbol():goWest()  }, ;
                   { "Move East",  Symbol():goEast()  } }

    Since we know the names of the messages we want (ie. they are not
    coming from a data file), we have included them directly in the program
    code above, rather than storing them in character strings.  We could
    then use the above array as follows:

        FOR i := 1 to LEN(aMenu)
            @ i, 0 PROMPT aMenu[i][1]
        NEXT i

        MENU TO nOpt

        self:perform( aMenu[i][2], nDistance )

    The Symbol class has many possible uses.  A file is provided on the
    Class(y) distribution disk called SYMTEST.PRG which demonstrates some
    more esoteric ways to use the class.