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

FreeBSD Manual Pages

  
 
  

home | help
define(n)			TclOO Commands			     define(n)

______________________________________________________________________________

NAME
       oo::define, oo::objdefine - define and configure	classes	and objects

SYNOPSIS
       package require TclOO

       oo::define class	defScript
       oo::define class	subcommand arg ?arg ...?
       oo::objdefine object defScript
       oo::objdefine object subcommand arg ?arg	...?
______________________________________________________________________________

DESCRIPTION
       The oo::define command is used to control the configuration of classes,
       and the oo::objdefine command is	used to	control	the  configuration  of
       objects (including classes as instance objects),	with the configuration
       being applied to	the entity named in the	class or the object  argument.
       Configuring a class also	updates	the configuration of all subclasses of
       the class and all objects that are instances of that class or which mix
       it in (as modified by any per-instance configuration). The way in which
       the configuration is done is controlled by either the  defScript	 argu-
       ment  or	by the subcommand and following	arg arguments; when the	second
       is present, it is exactly as if all the arguments from  subcommand  on-
       wards are made into a list and that list	is used	as the defScript argu-
       ment.

   CONFIGURING CLASSES
       The following commands are supported in the defScript  for  oo::define,
       each of which may also be used in the subcommand	form:

       constructor argList bodyScript
	      This  creates or updates the constructor for a class. The	formal
	      arguments	to the constructor (defined using the same  format  as
	      for  the	Tcl proc command) will be argList, and the body	of the
	      constructor will be bodyScript. When the body of the constructor
	      is evaluated, the	current	namespace of the constructor will be a
	      namespace	that is	unique to the object being constructed.	Within
	      the constructor, the next	command	should be used to call the su-
	      perclasses' constructors.	If bodyScript is the empty string, the
	      constructor will be deleted.

       deletemethod name ?name ...?
	      This  deletes  each of the methods called	name from a class. The
	      methods must have	previously existed in that class. Does not af-
	      fect  the	superclasses of	the class, nor does it affect the sub-
	      classes or instances of the class	(except	when they have a  call
	      chain  through the class being modified) or the class object it-
	      self.

       destructor bodyScript
	      This creates or updates the destructor for a class.  Destructors
	      take  no	arguments,  and	 the  body  of	the destructor will be
	      bodyScript. The destructor is called when	objects	of  the	 class
	      are deleted, and when called will	have the object's unique name-
	      space as the current namespace. Destructors should use the  next
	      command  to  call	 the  superclasses' destructors. Note that de-
	      structors	are not	called in all situations (e.g. if  the	inter-
	      preter is	destroyed). If bodyScript is the empty string, the de-
	      structor will be deleted.
	      Note that	errors during the evaluation of	a destructor  are  not
	      returned	to  the	code that causes the destruction of an object.
	      Instead, they are	passed to the currently-defined	 bgerror  han-
	      dler.

       export name ?name ...?
	      This  arranges  for  each	 of the	named methods, name, to	be ex-
	      ported (i.e. usable outside an instance through the instance ob-
	      ject's  command) by the class being defined. Note	that the meth-
	      ods themselves may be actually defined by	a superclass; subclass
	      exports override superclass visibility, and may in turn be over-
	      ridden by	instances.

       filter ?-slotOperation? ?methodName ...?
	      This slot	(see SLOTTED DEFINITIONS below)	sets  or  updates  the |
	      list  of method names that are used to guard whether method call
	      to instances of the class	may be called and  what	 the  method's
	      results  are.  Each  methodName  names a single filtering	method
	      (which may be exposed or not exposed); it	is not an error	for  a
	      non-existent  method  to	be  named since	they may be defined by
	      subclasses.  By default, this slot works by appending.	       |

       forward name cmdName ?arg ...?
	      This creates or updates a	 forwarded  method  called  name.  The
	      method  is  defined  be forwarded	to the command called cmdName,
	      with additional arguments, arg etc., added  before  those	 argu-
	      ments  specified	by  the	caller of the method. The cmdName will
	      always be	resolved using the  rules  of  the  invoking  objects'
	      namespaces,  i.e., when cmdName is not fully-qualified, the com-
	      mand will	be searched for	in each	object's namespace, using  the
	      instances'  namespace's  path, or	by looking in the global name-
	      space.  The method will be exported if name starts with a	lower-
	      case letter, and non-exported otherwise.

       method name argList bodyScript
	      This creates or updates a	method that is implemented as a	proce-
	      dure-like	script.	The name of the	method is name,	the formal ar-
	      guments  to the method (defined using the	same format as for the
	      Tcl proc command)	will be	argList, and the body  of  the	method
	      will  be	bodyScript.  When the body of the method is evaluated,
	      the current namespace of the method will be a namespace that  is
	      unique  to  the  current	object.	The method will	be exported if
	      name starts with a lower-case letter,  and  non-exported	other-
	      wise; this behavior can be overridden via	export and unexport.

       mixin ?-slotOperation? ?className ...?
	      This  slot  (see	SLOTTED	DEFINITIONS below) sets	or updates the |
	      list of additional classes that are to be	mixed into all the in-
	      stances  of  the	class  being  defined. Each className argument
	      names a single class that	is to be mixed in.  By	default,  this |
	      slot works by replacement.

       renamemethod fromName toName
	      This  renames  the  method called	fromName in a class to toName.
	      The method must have previously existed in the class, and	toName
	      must  not	 previously  refer to a	method in that class. Does not
	      affect the superclasses of the class, nor	 does  it  affect  the
	      subclasses  or  instances	 of the	class (except when they	have a
	      call chain through the class being modified), or the  class  ob-
	      ject itself. Does	not change the export status of	the method; if
	      it was exported before, it will be afterwards.

       self subcommand arg ...

       self script
	      This command is equivalent to calling oo::objdefine on the class
	      being  defined  (see CONFIGURING OBJECTS below for a description
	      of the supported values of subcommand). It follows the same gen-
	      eral  pattern of argument	handling as the	oo::define and oo::ob-
	      jdefine commands,	and "oo::define	cls self subcommand ..."   op-
	      erates identically to "oo::objdefine cls subcommand ...".

       superclass ?-slotOperation? ?className ...?
	      This  slot (see SLOTTED DEFINITIONS below) allows	the alteration |
	      of the superclasses of the class being defined.  Each  className
	      argument	names  one class that is to be a superclass of the de-
	      fined class. Note	that objects must not be  changed  from	 being
	      classes to being non-classes or vice-versa, that an empty	parent
	      class is equivalent to oo::object, and that the  parent  classes
	      of  oo::object  and  oo::class may not be	modified.  By default, |
	      this slot	works by replacement.

       unexport	name ?name ...?
	      This arranges for	each of	the named methods, name, to be not ex-
	      ported  (i.e.  not  usable  outside the instance through the in-
	      stance object's command, but instead just	through	the my command
	      visible  in  each	 object's context) by the class	being defined.
	      Note that	the methods themselves may be actually	defined	 by  a
	      superclass;  subclass  unexports override	superclass visibility,
	      and may be overridden by instance	unexports.

       variable	?-slotOperation? ?name ...?
	      This slot	(see SLOTTED DEFINITIONS below)	arranges for  each  of |
	      the  named  variables  to	be automatically made available	in the |
	      methods, constructor and destructor declared by the class	 being |
	      defined.	Each variable name must	not have any namespace separa- |
	      tors and must not	look like an array access. All variables  will |
	      be  actually  present in the instance object on which the	method |
	      is executed. Note	that the variable lists	declared by  a	super- |
	      class or subclass	are completely disjoint, as are	variable lists |
	      declared by instances; the list of variable names	 is  just  for |
	      methods  (and  constructors  and	destructors)  declared by this |
	      class. By	default, this slot works by appending.

   CONFIGURING OBJECTS
       The following commands are supported in the  defScript  for  oo::objde-
       fine, each of which may also be used in the subcommand form:

       class className
	      This allows the class of an object to be changed after creation.
	      Note that	the class's constructors are not called	when  this  is
	      done, and	so the object may well be in an	inconsistent state un-
	      less additional configuration work is done.

       deletemethod name ?name ...
	      This deletes each	of the methods called name from	an object. The
	      methods  must  have previously existed in	that object (e.g., be-
	      cause it was created through oo::objdefine method). Does not af-
	      fect  the	 classes  that the object is an	instance of, or	remove
	      the exposure of those class-provided methods in the instance  of
	      that class.

       export name ?name ...?
	      This  arranges  for  each	 of the	named methods, name, to	be ex-
	      ported (i.e. usable outside the object through the object's com-
	      mand)  by	 the object being defined. Note	that the methods them-
	      selves may be actually defined by	a class	or superclass;	object
	      exports override class visibility.

       filter ?-slotOperation? ?methodName ...?
	      This  slot  (see	SLOTTED	DEFINITIONS below) sets	or updates the |
	      list of method names that	are used to  guard  whether  a	method
	      call  to	the object may be called and what the method's results
	      are.  Each methodName names a single filtering method (which may
	      be  exposed  or not exposed); it is not an error for a non-exis-
	      tent method to be	named. Note that the actual  list  of  filters
	      also depends on the filters set upon any classes that the	object
	      is an instance of.  By default, this slot	works by appending.    |

       forward name cmdName ?arg ...?
	      This creates or updates a	forwarded object method	 called	 name.
	      The  method  is  defined be forwarded to the command called cmd-
	      Name, with additional arguments, arg etc.,  added	 before	 those
	      arguments	specified by the caller	of the method. Forwarded meth-
	      ods should be deleted using the method  subcommand.  The	method
	      will  be	exported  if name starts with a	lower-case letter, and
	      non-exported otherwise.

       method name argList bodyScript
	      This creates, updates or deletes an object method. The  name  of
	      the  method is name, the formal arguments	to the method (defined
	      using the	same format as for the Tcl proc	command) will  be  ar-
	      gList,  and  the body of the method will be bodyScript. When the
	      body of the method is evaluated, the current  namespace  of  the
	      method  will  be	a  namespace that is unique to the object. The
	      method will be exported if name starts with a lower-case letter,
	      and non-exported otherwise.

       mixin ?-slotOperation? ?className ...?
	      This slot	(see SLOTTED DEFINITIONS below)	sets or	updates	a per- |
	      object list of additional	classes	that are to be mixed into  the
	      object.  Each  argument, className, names	a single class that is
	      to be mixed in.  By default, this	slot works by replacement.     |

       renamemethod fromName toName
	      This renames the method called fromName in an object to  toName.
	      The  method  must	 have  previously  existed  in the object, and
	      toName must not previously refer to a  method  in	 that  object.
	      Does  not	 affect	 the classes that the object is	an instance of
	      and cannot rename	in an instance object the methods provided  by
	      those  classes (though a oo::objdefine forwarded method may pro-
	      vide an equivalent capability). Does not change the export  sta-
	      tus  of the method; if it	was exported before, it	will be	after-
	      wards.

       unexport	name ?name ...?
	      This arranges for	each of	the named methods, name, to be not ex-
	      ported  (i.e. not	usable outside the object through the object's
	      command, but instead just	through	the my command visible in  the
	      object's	context)  by  the  object being	defined. Note that the
	      methods themselves may be	actually defined by a class;  instance
	      unexports	override class visibility.

       variable	?-slotOperation? ?name ...?
	      This  slot  (see SLOTTED DEFINITIONS below) arranges for each of |
	      the named	variables to be	automatically made  available  in  the |
	      methods  declared	 by  the  object being defined.	 Each variable |
	      name must	not have any namespace separators and  must  not  look |
	      like  an array access. All variables will	be actually present in |
	      the object on which the method is	executed. Note that the	 vari- |
	      able  lists  declared by the classes and mixins of which the ob- |
	      ject is an instance are completely disjoint; the list  of	 vari- |
	      able  names  is just for methods declared	by this	object.	By de- |
	      fault, this slot works by	appending.			       |

SLOTTED	DEFINITIONS							       |
       Some of the configurable	definitions of a class or object  are  slotted |
       definitions. This means that the	configuration is implemented by	a slot |
       object, that is an instance of the class	oo::Slot, which	manages	a list |
       of  values  (class names, variable names, etc.) that comprises the con- |
       tents of	the slot. The class defines three operations (as methods) that |
       may be done on the slot:

       slot -append ?member ...?
	      This appends the given member elements to	the slot definition.   |

       slot -clear
	      This sets	the slot definition to the empty list.		       |

       slot -set ?member ...?
	      This  replaces  the  slot	 definition with the given member ele- |
	      ments.							       |

       A consequence of	this is	that any use of	 a  slot's  default  operation |
       where  the first	member argument	begins with a hyphen will be an	error. |
       One of the above	operations should be used explicitly in	those  circum- |
       stances.								       |

   SLOT	IMPLEMENTATION							       |
       Internally, slot	objects	also define a method --default-operation which |
       is forwarded to the default operation of	the slot (thus,	for the	 class |
       "variable"  slot, this is forwarded to "my -append"), and these methods |
       which provide the implementation	interface:

       slot Get
	      Returns a	list that is the current contents of  the  slot.  This |
	      method  must  always  be	called from a stack frame created by a |
	      call to oo::define or oo::objdefine.

       slot Set	elementList
	      Sets the contents	of the slot to the list	 elementList  and  re- |
	      turns the	empty string. This method must always be called	from a |
	      stack frame created by a call to oo::define or oo::objdefine.    |

       The implementation of these methods is slot-dependent (and  responsible |
       for  accessing  the  correct  part  of the class	or object definition). |
       Slots also have an unknown method handler to tie	all these  pieces  to- |
       gether,	and  they  hide	their destroy method so	that it	is not invoked |
       inadvertently. It is recommended	that any  user	changes	 to  the  slot |
       mechanism  be  restricted  to defining new operations whose names start |
       with a hyphen.

EXAMPLES
       This example demonstrates how to	use both forms of the  oo::define  and
       oo::objdefine  commands	(they work in the same way), as	well as	illus-
       trating four of the subcommands of them.

	      oo::class	create c
	      c	create o
	      oo::define c method foo {} {
		  puts "world"
	      }
	      oo::objdefine o {
		  method bar {}	{
		      my Foo "hello "
		      my foo
		  }
		  forward Foo ::puts -nonewline
		  unexport foo
	      }
	      o	bar		   -_ prints "hello world"
	      o	foo		   -_ error "unknown method foo"
	      o	Foo Bar		   -_ error "unknown method Foo"
	      oo::objdefine o renamemethod bar lollipop
	      o	lollipop	   -_ prints "hello world"

       This example shows how additional classes can be	mixed into an  object.
       It also shows how mixin is a slot that supports appending:

	      oo::object create	inst
	      inst m1		   -_ error "unknown method m1"
	      inst m2		   -_ error "unknown method m2"

	      oo::class	create A {
		  method m1 {} {
		      puts "red	brick"
		  }
	      }
	      oo::objdefine inst {
		  mixin	A
	      }
	      inst m1		   -_ prints "red brick"
	      inst m2		   -_ error "unknown method m2"

	      oo::class	create B {
		  method m2 {} {
		      puts "blue brick"
		  }
	      }
	      oo::objdefine inst {
		  mixin	-append	B
	      }
	      inst m1		   -_ prints "red brick"
	      inst m2		   -_ prints "blue brick"

SEE ALSO
       next(n),	oo::class(n), oo::object(n)

KEYWORDS
       class, definition, method, object, slot

TclOO				      0.3			     define(n)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | KEYWORDS

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

home | help