Introspection for AAFID(tm) Entities.
$Revision: 1.3 $ $Date: 1999/09/03 17:22:55 $

 ======================================================================
 This file is Copyright 1998,1999 by the Purdue Research Foundation and
 may only be used under license.  For terms of the license, see the
 file named COPYRIGHT included with this software release.
 AAFID is a trademark of the Purdue Research Foundation.
 All rights reserved.
 ======================================================================

(Note: this feature is not yet implemented. Feedback is appreciated.)

This feature would provide AAFID entities with the ability to provide
information about the commands they implement, what each one of them
does, and the parameters that each command receives. It might also
provide a detailed description for each of the parameters, and its
contents. This would allow a user interface to ask the user for the
data that will go into the parameters using meaningful terms, and not
in Perl syntax.

Something like this.

%COMMANDS=(SET_FILES => 
	   {Description => "Set the permission for a set of files",
	    Parameters =>
	      {Permission => '[%oct(Permission, "Mode bits to assign")\{,"%str(Filename)\}+]'
	      }
	   },
	   REMOVE_FILES =>
	   (
	    "Remove files",
	    (Files => '[\{%str(Filename)\}+]')
	   )
	  )
	
In general:

%COMMANDS=(COMMAND1 =>
	   {Description => "Command_1 description",
	    Parameters =>
	      {Param1 => '<description string for Param1>',
	       Param2 => '<description string for Param2>',
	       Param3 => '<etc>'
	      }
	   },
	   COMMAND2 =>
	   {Description => "Command_2 description",
	    Parameters =>
	      {ParamA => '<description string for ParamA>',
	       ParamB => '<etc>'
	      }
	   },
	   ETC =>
	   {Description => "ETC description",
	    # This takes no parameters
	   }
	  );

The parameter description string contains a string representation of a
Perl data structure. The following characters and strings have special
meanings:

%type(Name[,"Description"])
   Represents a simple data element of type 'type', with the given
   Name and optional Description. 'type' can be one of:
     str        - String
     int	- Integer number
     flt	- Floating point number
     oct	- Octal number
     hex	- Hexadecimal number
     boo        - Boolean value (1 for True, 0 for False)
     any	- Any of the above
   
\{ \}
   Used to group a substring

*
   Zero or more repetitions of the previous element or group

+
   One or more repetitions of the previous element or group

?
   One or more occurrences of the previous element or group

@
   A Perl list made of repetitions of the previous element or group.
   This is, one or more repetitions, separated by commas.

All other characters are taken literally to build the string representation
of a Perl data structure, and thus must be valid according to Perl syntax.

Examples:

- A list of numbers, each of which is a Unix mode bits mask:
    %oct(Mode,"File permissions")@

- A list of user names
    %str(user, "User name")@

- A mode specification, followed by a list of filenames.
    %oct(mode, "File permissions"),%str(File, "File name")@

- A reference to the above list.
    [%oct(mode, "File permissions"),%str(File, "File name")@]

- A reference to a list where each element is a reference to a
  two-element list, containing a mode and a filename.
    [\{[%oct(Mode, "File permissions"),%str(File, "File name")]\}@]
