Tcl_SetEnsembleMappingDict man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

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	 ORed set of flag bits
						     describing the basic con‐
						     figuration	 of the ensem‐
						     ble. Currently  only  one
						     bit      has     meaning,
						     TCL_ENSEMBLE_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
						     implementation    command
						     prefix mapping dictionary
						     in	 the  ensemble. May be
						     NULL if the mapping  dic‐
						     tionary 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
       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 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
	      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 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
	      ensemble'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 │
	      obtained	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
	      refer to an ensemble).

SEE ALSO
       namespace(n), Tcl_DeleteCommandFromToken(3)

KEYWORDS
       command, ensemble

Tcl				      8.5		       Tcl_Ensemble(3)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net