# $EPIC: bindctl,v 1.2 2002/08/20 19:42:24 kitambi Exp $
Synopsis:
   $bindctl(FUNCTION <function> <action> [<args]>)
   $bindctl(SEQUENCE <sequence> <action> [<args]>)
   $bindctl(MAP [<sequence>] [<action>])

Technical:
   * This function is a low-level interface to the client's keybindings
     system.
   * There are three top-level arguments which can be passed to the
     function:
     + FUNCTION: Manipulates the functions which key sequences can be bound
       to.
     + SEQUENCE: Manipulates the key sequences themselves.
     + MAP     : Manipulates 'maps' of the key sequences.
   
   * The FUNCTION top-level argument works as follows:
     The first argument is the name of a function to be manipulated.
     The second and following arguments are the action to perform on that
     function.  Unless otherwise noted, the actions return 1 for success,
     and 0 or nothing for failure.
     + CREATE <alias>
       Creates a new function with the given name, and executes the alias
       whenever that function is activated by a key sequence.
     + DESTROY
       Destroys a function with the given name.  Only user-created functions
       may be destroyed.
     + EXISTS
       Returns 1 if the specified function exists, 0 otherwise.
     + GET
       Returns the status of the given function.  If it exists, it will
       return a string of the form "internal <memory-address>" if the
       function is builtin, or "alias <aliasname>" if the function is
       user-created.
     + MATCH
       Returns all functions whose names begin with the given name.
     + PMATCH
       Returns all functions whose names match the given pattern.
     + GETPACKAGE
       Returns the package value of the given function.
     + SETPACKAGE <package>
       Sets the package value of the given function.  Only available for
       user-created functions.
   * The SEQUENCE top-level argument works as follows:
     The first argument is a sequence of keys to be manipulated.  The
     sequence can be given in any form accepted by the /bind command (see
     Key_Bindings(7)).  The second and following arguments are the action
     to perform on that function.  Unless otherwise noted, the actions
     return 1 for success, and 0 or nothing for failure.
     + GET
       Retrieves the function this key sequence is bound to, if any.
     + SET <function> [extra]
       Binds the given sequence to the function, with optional extras.
     + GETPACKAGE
       Returns the package value of the key sequence.
     + SETPACKAGE <package>
       Sets the package value of the given key-sequence, if it is bound to
       something.
   * The MAP top-level argument works as follows:
     The first argument is a sequence of keys to be manipulated.  The
     sequence does not need to terminate in a binding (in fact, it should
     not do so).  The second argument is optional, and specifies an action
     to be performed on the given 'map'.  If the second argument is not
     specified, all the keys bound within the specified map will be
     returned.  To get a list of all keys bound in the client, one can do
     $bindctl(MAP).
     + CLEAR
       This is currently the only command available to MAP, and it causes
       all bindings within the given sequence to be unbound.  For example,
       $bindctl(MAP ^[ CLEAR) will clear out all bindings of the ^[...
       nature.

Practical:
   This function provides a simple access point to modify all changeable
   aspects of the EPIC keybinding system.

Examples:
   $bindctl(FUNCTION CANCEL_ACTION CREATE my_cancel)
     Creates a function called 'CANCEL_ACTION' which can be bound to
     and which, when called, executes the 'my_cancel' alias.
   $bindctl(SEQUENCE ^[ SET CANCEL_ACTION)
     Binds the escape key to the 'CANCEL_ACTION' function.
   $bindctl(MAP ^[ CLEAR)
     Wipes out all key sequences starting with ^[ (but not ^[ itself).

See Also:
   bind(4); Key_Bindings(7)

