Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tcl_Ensemble(3)		    Tcl	Library	Procedures	       Tcl_Ensemble(3)

______________________________________________________________________________

NAME
       Tcl_CreateEnsemble,	 Tcl_FindEnsemble,	 Tcl_GetEnsembleFlags,
       Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace,  Tcl_GetEnsemble-
       UnknownHandler,	    Tcl_GetEnsembleSubcommandList,     Tcl_IsEnsemble,
       Tcl_SetEnsembleFlags,  Tcl_SetEnsembleMappingDict,  Tcl_SetEnsembleSub-
       commandList,  Tcl_SetEnsembleUnknownHandler  - manipulate ensemble com-
       mands

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 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_GetEnsem-
						     ble  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  command is
						     to	be bound, or NULL  for
						     the current namespace.

       int ensFlags (in)			     An	 ORed set of flag bits
						     describing	the basic con-
						     figuration	 of the	ensem-
						     ble. Currently  only  one
						     bit  has meaning, TCL_EN-
						     SEMBLE_PREFIX,  which  is
						     present when the ensemble
						     command should also match
						     unambiguous  prefixes  of
						     subcommands.

       Tcl_Obj *cmdNameObj (in)			     A value holding the  name
						     of	 the  ensemble command
						     to	look up.

       int flags (in)				     An	ORed set of flag  bits
						     controlling  the behavior
						     of	Tcl_FindEnsemble. Cur-
						     rently		  only
						     TCL_LEAVE_ERR_MSG is sup-
						     ported.

       Tcl_Command token (in)			     A	normal	command	 token
						     that refers to an	ensem-
						     ble command, or which you
						     wish to use  for  testing
						     as	an ensemble command 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 subcommand	to im-
						     plementation command pre-
						     fix mapping dictionary in
						     the ensemble. May be NULL
						     if	the mapping dictionary
						     is	to be removed.

       Tcl_Obj **dictObjPtr (out)		     Pointer   to  a  variable
						     into which	to  write  the
						     current  ensemble mapping
						     dictionary.

       Tcl_Obj *listObj	(in)			     A list value to  use  for
						     the  defined list of sub-
						     commands in  the  dictio-
						     nary  or the unknown sub-
						     commmand handler  command
						     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 cur-
						     rent 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 to execute.

       Ensembles are created using Tcl_CreateEnsemble, which takes four	 argu-
       ments: the interpreter to work within, the name of the ensemble to cre-
       ate, 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 PROPERTIES.

       Given  the  name	of an ensemble command,	the token for that command may
       be retrieved using Tcl_FindEnsemble. If the given command name (in cmd-
       NameObj)	does not refer to an ensemble command, the result of the func-
       tion is NULL and	(if the	TCL_LEAVE_ERR_MSG bit is set in	flags) an  er-
       ror 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 prefixes 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  to-
	      ken 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 ensemble 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 en-
	      semble's bound namespace.	Defaults to  NULL.  May	 be  read  and
	      written using Tcl_GetEnsembleMappingDict and Tcl_SetEnsembleMap-
	      pingDict 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  dictionary   obtained	  from
	      Tcl_GetEnsembleMappingDict should	always be treated as immutable
	      even if it is unshared.  All command names in 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  dic-
	      tionary  (see  above)  or	(if that is also NULL) from the	set of
	      commands exported	by the bound namespace.	May be read and	 writ-
	      ten  using Tcl_GetEnsembleSubcommandList and Tcl_SetEnsembleSub-
	      commandList 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_GetEnsem-
	      bleSubcommandList	 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  subcommand  when
	      the subcommand is	unknown	to the ensemble	(according to the cur-
	      rent 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_GetEnsembleUn-
	      knownHandler 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  dictionary	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 re-
	      fer to an	ensemble).

SEE ALSO
       namespace(n), Tcl_DeleteCommandFromToken(3)

Tcl				      8.5		       Tcl_Ensemble(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_CreateEnsemble.tcl85&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help