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_GetEnsem-
       bleParameterList, Tcl_GetEnsembleUnknownHandler,	Tcl_GetEnsembleSubcom-
       mandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMapping-
       Dict,	Tcl_SetEnsembleParameterList,	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_GetEnsembleParameterList(interp, token, listObjPtr)

       int
       Tcl_SetEnsembleParameterList(interp, token, listObj)

       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	OR'ed 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	OR'ed 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  list	of formal pre-
						     subcommand	   parameters,
						     the  defined list of sub-
						     commands in  the  dictio-
						     nary  or the unknown sub-
						     command  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  list  of	formal
						     pre-subcommand    parame-
						     ters, the defined 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.

       formal pre-subcommand parameter list (read-write)
	      A	list of	formal parameter names (the names only being used when
	      generating error messages) that come at invocation of the	ensem-
	      ble between the name of the ensemble and	the  subcommand	 argu-
	      ment. NULL (the default) is equivalent to	the empty list.	May be
	      read   and   written   using   Tcl_GetEnsembleParameterList  and
	      Tcl_SetEnsembleParameterList 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 ob-
	      tained  from  Tcl_GetEnsembleParameterList  should   always   be
	      treated as immutable even	if it is unshared.

       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).

REFERENCE COUNT	MANAGEMENT
       Tcl_FindEnsemble	does not modify	the reference count of its  cmdNameObj
       argument;  it  only  reads. Note	however	that this function may set the
       interpreter result; if that is the only place that is holding a	refer-
       ence to the object, it will be deleted.

       The     ensemble	   property    getters	  (Tcl_GetEnsembleMappingDict,
       Tcl_GetEnsembleParameterList,	Tcl_GetEnsembleSubcommandList,	   and
       Tcl_GetEnsembleUnknownHandler) do not manipulate	the reference count of
       the  values  they  provide out; if those	are non-NULL, they will	have a
       reference count of at least 1.  Note that these functions may  set  the
       interpreter result.

       The     ensemble	   property    setters	  (Tcl_SetEnsembleMappingDict,
       Tcl_SetEnsembleParameterList,	Tcl_SetEnsembleSubcommandList,	   and
       Tcl_SetEnsembleUnknownHandler)  will  increment	the reference count of
       the new value of	the property they  are	given  if  they	 succeed  (and
       decrement the reference count of	the old	value of the property, if rel-
       evant).	If  the	property setters return	TCL_ERROR, the reference count
       of the Tcl_Obj argument is left unchanged.

SEE ALSO
       namespace(n), Tcl_DeleteCommandFromToken(3)

KEYWORDS
       command,	ensemble

Tcl				      8.5		       Tcl_Ensemble(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_SetEnsembleSubcommandList.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help