DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_CreateEnsemble(3tcl)




Tcl_Ensemble(3)      Tcl Library Procedures       Tcl_Ensemble(3)

_________________________________________________________________


NAME

     Tcl_CreateEnsemble, Tcl_FindEnsemble,  Tcl_GetEnsembleFlags,
     Tcl_GetEnsembleMappingDict,        Tcl_GetEnsembleNamespace,
     Tcl_GetEnsembleUnknownHandler,
     Tcl_GetEnsembleSubcommandList,               Tcl_IsEnsemble,
     Tcl_SetEnsembleFlags,            Tcl_SetEnsembleMappingDict,
     Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler
     - manipulate ensemble commands


SYNOPSIS

     #include <tcl.h>

     Tcl_Command
     Tcl_CreateEnsemble(interp, name, namespacePtr, ensFlags)

     Tcl_Command
     Tcl_FindEnsemble(interp, cmdNameObj, flags)

     int
     Tcl_IsEnsemble(token)

     int
     Tcl_GetEnsembleFlags(interp, token, ensFlagsPtr)

     int
     Tcl_SetEnsembleFlags(interp, token, ensFlags)

     int
     Tcl_GetEnsembleMappingDict(interp, token, dictObjPtr)

     int
     Tcl_SetEnsembleMappingDict(interp, token, dictObj)

     int
     Tcl_GetEnsembleSubcommandList(interp, token, listObjPtr)

     int
     Tcl_SetEnsembleSubcommandList(interp, token, listObj)

     int
     Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)

     int
     Tcl_SetEnsembleUnknownHandler(interp, token, listObj)

     int
     Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)


ARGUMENTS

     Tcl_Interp *interp (in/out)                   The

Tcl                     Last change: 8.5                        1

Tcl_Ensemble(3)      Tcl Library Procedures       Tcl_Ensemble(3)

                                                   interpreter in
                                                   which      the
                                                   ensemble is to
                                                   be created  or
                                                   found.    Also
                                                   where    error
                                                   result    mes-
                                                   sages      are
                                                   written.   The
                                                   functions
                                                   whose    names
                                                   start     with
                                                   Tcl_GetEnsemble
                                                   may   have   a
                                                   NULL  for  the
                                                   interp,    but
                                                   all      other
                                                   functions must
                                                   not.

     const char *name (in)                         The  name   of
                                                   the   ensemble
                                                   command to  be
                                                   created.

     Tcl_Namespace *namespacePtr (in)              The  namespace
                                                   to  which  the
                                                   ensemble  com-
                                                   mand  is to be
                                                   bound, or NULL
                                                   for        the
                                                   current
                                                   namespace.

     int ensFlags (in)                             An ORed set of
                                                   flag      bits
                                                   describing the
                                                   basic   confi-
                                                   guration    of
                                                   the  ensemble.
                                                   Currently only
                                                   one   bit  has
                                                   meaning,
                                                   TCL_ENSEMBLE_PREFIX,
                                                   which       is
                                                   present   when
                                                   the   ensemble
                                                   command should
                                                   also     match
                                                   unambiguous
                                                   prefixes    of
                                                   subcommands.

Tcl                     Last change: 8.5                        2

Tcl_Ensemble(3)      Tcl Library Procedures       Tcl_Ensemble(3)

     Tcl_Obj *cmdNameObj (in)                      A value  hold-
                                                   ing  the  name
                                                   of the  ensem-
                                                   ble command to
                                                   look up.

     int flags (in)                                An ORed set of
                                                   flag bits con-
                                                   trolling   the
                                                   behavior    of
                                                   Tcl_FindEnsemble.
                                                   Currently only
                                                   TCL_LEAVE_ERR_MSG
                                                   is supported.

     Tcl_Command token (in)                        A normal  com-
                                                   mand     token
                                                   that refers to
                                                   an    ensemble
                                                   command,    or
                                                   which you wish
                                                   to   use   for
                                                   testing  as an
                                                   ensemble  com-
                                                   mand        in
                                                   Tcl_IsEnsemble.

     int *ensFlagsPtr (out)                        Pointer  to  a
                                                   variable  into
                                                   which to write
                                                   the    current
                                                   ensemble  flag
                                                   bits;
                                                   currently only
                                                   the        bit
                                                   TCL_ENSEMBLE_PREFIX
                                                   is defined.

     Tcl_Obj *dictObj (in)                         A   dictionary
                                                   value  to  use
                                                   for  the  sub-
                                                   command     to
                                                   implementation
                                                   command prefix
                                                   mapping   dic-
                                                   tionary in the
                                                   ensemble.  May
                                                   be NULL if the
                                                   mapping   dic-
                                                   tionary  is to
                                                   be removed.

Tcl                     Last change: 8.5                        3

Tcl_Ensemble(3)      Tcl Library Procedures       Tcl_Ensemble(3)

     Tcl_Obj **dictObjPtr (out)                    Pointer  to  a
                                                   variable  into
                                                   which to write
                                                   the    current
                                                   ensemble  map-
                                                   ping  diction-
                                                   ary.

     Tcl_Obj *listObj (in)                         A  list  value
                                                   to use for the
                                                   defined   list
                                                   of subcommands
                                                   in  the   dic-
                                                   tionary or the
                                                   unknown   sub-
                                                   commmand
                                                   handler   com-
                                                   mand   prefix.
                                                   May be NULL if
                                                   the subcommand
                                                   list        or
                                                   unknown
                                                   handler are to
                                                   be removed.

     Tcl_Obj **listObjPtr (out)                    Pointer  to  a
                                                   variable  into
                                                   which to write
                                                   the    current
                                                   defiend   list
                                                   of subcommands
                                                   or the current
                                                   unknown
                                                   handler   pre-
                                                   fix.

     Tcl_Namespace **namespacePtrPtr (out)         Pointer  to  a
                                                   variable  into
                                                   which to write
                                                   the  handle of
                                                   the  namespace
                                                   to  which  the
                                                   ensemble    is
                                                   bound.
_________________________________________________________________


DESCRIPTION

     An ensemble is a command, bound  to  some  namespace,  which
     consists of a collection of subcommands implemented by other
     Tcl commands. The first argument to the ensemble command  is
     always interpreted as a selector that states what subcommand

Tcl                     Last change: 8.5                        4

Tcl_Ensemble(3)      Tcl Library Procedures       Tcl_Ensemble(3)

     to execute.

     Ensembles are created using Tcl_CreateEnsemble, which  takes
     four  arguments: the interpreter to work within, the name of
     the ensemble to create, the namespace within the interpreter
     to  bind  the  ensemble  to, and the default set of ensemble
     flags. The result of the function is the command  token  for
     the  ensemble,  which  may  be used to further configure the
     ensemble using the API described below in  ENSEMBLE  PROPER-
     TIES.

     Given the name of an ensemble command, the  token  for  that
     command  may  be  retrieved  using  Tcl_FindEnsemble. If the
     given command name (in cmdNameObj)  does  not  refer  to  an
     ensemble command, the result of the function is NULL and (if
     the TCL_LEAVE_ERR_MSG bit is set in flags) an error  message
     is left in the interpreter result.

     A command token may be checked to see if  it  refers  to  an
     ensemble  using  Tcl_IsEnsemble. This returns 1 if the token
     refers to an ensemble, or 0 otherwise.

  ENSEMBLE PROPERTIES
     Every ensemble has four read-write properties  and  a  read-
     only property. The properties are:

     flags (read-write)
          The set of flags for the ensemble, expressed as a  bit-
          field.    Currently,    the   only   public   flag   is
          TCL_ENSEMBLE_PREFIX which is set when unambiguous  pre-
          fixes  of  subcommands  are permitted to be resolved to
          implementations as well as exact matches. The flags may
          be  read  and  written  using  Tcl_GetEnsembleFlags and
          Tcl_SetEnsembleFlags respectively. The result  of  both
          of  those  functions  is  a Tcl result code (TCL_OK, or
          TCL_ERROR if the token does not refer to an ensemble).

     mapping dictionary (read-write)
          A dictionary containing a mapping from subcommand names
          to lists of words to use as a command prefix (replacing
          the first two words of the command which are the ensem-
          ble command itself and the subcommand name), or NULL if
          every subcommand is to be mapped to  the  command  with
          the  same  unqualified  name  in  the  ensemble's bound
          namespace. Defaults to NULL. May be  read  and  written
          using           Tcl_GetEnsembleMappingDict          and
          Tcl_SetEnsembleMappingDict respectively. The result  of
          both  of  those functions is a Tcl result code (TCL_OK,
          or TCL_ERROR if the token does not refer to  an  ensem-
          ble)     and     the     dictionary    obtained    from
          Tcl_GetEnsembleMappingDict should always be treated  as
          immutable even if it is unshared.  All command names in

Tcl                     Last change: 8.5                        5

Tcl_Ensemble(3)      Tcl Library Procedures       Tcl_Ensemble(3)

          prefixes set  via  Tcl_SetEnsembleMappingDict  must  be
          fully qualified.

     subcommand list (read-write)
          A list of all the subcommand names for the ensemble, or
          NULL  if  this is to be derived from either the keys of
          the mapping dictionary (see above) or (if that is  also
          NULL)  from  the  set of commands exported by the bound
          namespace.   May   be   read    and    written    using
          Tcl_GetEnsembleSubcommandList                       and
          Tcl_SetEnsembleSubcommandList respectively. The  result
          of  both  of  those  functions  is  a  Tcl  result code
          (TCL_OK, or TCL_ERROR if the token does not refer to an
          ensemble)     and     the     list     obtained    from
          Tcl_GetEnsembleSubcommandList should always be  treated
          as immutable even if it is unshared.

     unknown subcommand handler command prefix (read-write)
          A list of words to prepend on the front of any  subcom-
          mand  when  the  subcommand  is unknown to the ensemble
          (according to the current prefix  handling  rule);  see
          the  namespace  ensemble  command  for more details. If
          NULL, the default behavior - generate a suitable  error
          message  -  will  be used when an unknown subcommand is
          encountered.   May   be   read   and   written    using
          Tcl_GetEnsembleUnknownHandler                       and
          Tcl_SetEnsembleUnknownHandler respectively. The  result
          of  both  functions  is  a  Tcl result code (TCL_OK, or
          TCL_ERROR if the token does not refer to  an  ensemble)
          and         the        list        obtained        from
          Tcl_GetEnsembleUnknownHandler should always be  treated
          as immutable even if it is unshared.

     bound namespace (read-only)
          The namespace to which the ensemble is bound; when  the
          namespace  is  deleted,  so  too will the ensemble, and
          this namespace is also  the  namespace  whose  list  of
          exported  commands is used if both the mapping diction-
          ary and the subcommand list properties are NULL. May be
          read using Tcl_GetEnsembleNamespace which returns a Tcl
          result code (TCL_OK, or TCL_ERROR if the token does not
          refer to an ensemble).


SEE ALSO

     namespace(n), Tcl_DeleteCommandFromToken(3)

Tcl                     Last change: 8.5                        6


Man(1) output converted with man2html