### ===========================================================================
### -package  : SimpleSubcommand
# -version    : 0.2
# -purpose    : Subcommand procedures handling.
# -overview   :
#     This package allows to handle subcommand procedures, that is, procedures
#  with a name (the base command) and a first argument (the subcommand)
#  followed by an optional list of arguments.  Procedures are provided to
#  create, delete, copy, rename and get information about subcommand
#  procedures.
#
# -usage      :
#     Subcommand procedures are create via K<::Simple::Subcommand::create>. 
#  Such subcommand procedures behave similarly to the built-in Tcl commands
#  with subcommands (such as K<string> or K<array>):  
#
#  * They are called simply by providing the command and subcommand name, such
#    as "foo bar".  Nevertheless, it is slightly faster to use "foo\ bar" or
#    "{foo bar}" as a level of distpach is avoided. 
#
#  * When called with no subcommand, an error is thrown informing of the
#    allowed subcommands. 
#
#  * When called with an incorrect number of arguments for a particular
#    subcommand an error is thrown informing of the argument list for that
#    subcommand.
#
#     Subcommand procedures can be deleted via K<::Simple::Subcommand::delete>
#  or renamed via K<::Simple::Subcommand::rename>.  The
#  K<::Simple::Subcommand::information> procedure provides several subcommands
#  to query information about subcommand procedures:  K<exists> and
#  K<subcommands>.  Refer to the description of each procedure below for
#  further information.
#
# -keywords   : procedure command subcommand
# -variables  :
#
#  { BaseCommandTag   -string %BASE-COMMAND%
#                                    "The base command tag. A procedure is
#                                     considered a base command procedure if
#                                     its body contains this tring"}
#
# -commands   :
#
#  * K<create> procedure arguments body
#    Creates a subcommand procedure.
#
#  * K<::Simple::Subcommand::delete> procedure
#    Deletes a subcommand procedure.
#
#  * K<::Simple::Subcommand::move> sourceProcedure targetProcedure
#    Renames a subcommand procedure.
#
#  * K<::Simple::Subcommand::copy> sourceProcedure targetProcedure
#    Copies a subcommand procedure.
#
#  * K<::Simple::Subcommand::information exists> command
#    Returns whether a procedure is a base command procedure.
#
#  * K<::Simple::Subcommand::information subcommands> command
#    Returns a base command procedure subcommand list.
#
#  * K<::Simple::Subcommand::configure>
#    Configures the package options.
#
#  * K<::Simple::Subcommand::cget>
#    Gets the package options.
#
# -examples   :
#
#  # Install the package
#  package require SimplePackage
#  ::Simple::Package::require-and-install SimpleSubcommand
#  
#  # Create some subcommands
#  proc-sub {foo bar} arg1 {}
#  proc-sub {foo gee} arg1 {}
#  
#  # Assess whether foo is a subcommand base command
#  # This displays the following:
#  #    Yes, foo is a subcommand base command
#  if {[::Simple::Subcommand::information exists foo]} {
#     puts {Yes, foo is a subcommand base command}
#  } else {
#     puts {No, foo is not a subcommand base command}
#  }
#  
#  # Display the list of subcommands for foo
#  # This displays the following:
#  #    gee bar
#  puts [::Simple::Subcommand::information subcommands foo]
#  
#  # Delete the "foo bar" subcommand
#  ::Simple::Subcommand::delete {foo bar}
#  
#  # Display the list of subcommands for foo
#  # This displays the following:
#  #    gee
#  puts [::Simple::Subcommand::information subcommands foo]
#  
#  # Rename the "foo gee" subcommand to "foo bar"
#  ::Simple::Subcommand::move {foo gee} {foo bar}
#  
#  # Display the list of subcommands for foo
#  # This displays the following:
#  #    bar
#  puts [::Simple::Subcommand::information subcommands foo]
#  
#  # Rename the "foo bar" subcommand to "zoo fii"
#  ::Simple::Subcommand::move {foo bar} {zoo fii}
#  
#  # Assess whether foo is a subcommand base command
#  # This displays the following:
#  #    No, foo is not a subcommand base command
#  if {[::Simple::Subcommand::information exists foo]} {
#     puts {Yes, foo is a subcommand base command}
#  } else {
#     puts {No, foo is not a subcommand base command}
#  }
#
# -details    : 
#  * Subcommand procedures are implemented with the aid of a base procedure
#    named as the command.  That is, if a subcommand procedure named K<foo
#    bar> is created, two procedures are actually cretated:  the subcommand
#    procedure itself (named "foo bar") and the base command (named "foo"). 
#    The base command simply acts as a dispatcher for the actual subcommand
#    procedures.  It also catches the subcommand procedure errors and throws
#    explanation errors when appropriate.
#
#  * For this reason, it is slightly faster to invoke a subcommand procedure
#    as "{foo bar}" or "foo\ bar" instead of "foo bar", as the dispatch from
#    the base command is avoided.
#
#  more esoteric features of the P<opt> package such as argument names
# -history    :
#  23-apr-2000   First public release, version 0.2
#
# -copyright  :
#  Copyright (C) 1999, 2000, Juan C. Gil (jgil@gmv.es)
#
### ===========================================================================
