1.110.2 Get methods

object <-_arg: int -> unchecked

The nth argument (1-based) of the term description. Unless overruled at the object level, this is equivalent to:

get(Obj, ?(Obj?class?term_names, element, N), Arg).

This behaviour is intended to remain reserved for system usage. Do not rely on its definition.

See also

- chain<-_arg
- object<-functor
- object<-_arity
- class-term_names
- class ?
- topic Object -> Term

object <-_arity: -> int

Number or arguments to the term description. Unless overruled, this is the size of the term_names vector of the associated class.

See also

- chain<-_arity
- object<-functor
- object<-_arg
- class ?
- topic Object -> Term

object <-_class_name: -> name

object <-_flags: -> name

object <-_inspect: -> bool

object <-_man_id: -> name

object <-_references: -> int

object <-_slot: name|int -> unchecked

object <-_class: -> class

These methods starting with an’_’(underscore) are defined both on class function and class object. Their behaviour is equivalent to the counterpart with the leading underscore deleted for normal objects. As these methods are explicitly defined on class function however, invoking one of these methods to a function will cause the function itself to handle the message instead of the evaluation. Example:

?- new(O, @display?size),
   get(O, '_class_name', C1),
   get(O, class_name, C2).

C1 = ?
C2 = size

Bugs: It is probably more elegant to introduce a separate send- and get- operation that does not evaluate the receiver.

See also

- object<-class
- class ?

object <-all_constraints: create=[bool] -> chain

object <-all_get_methods: create=[bool] -> chain

object <-all_hypers: create=[bool] -> chain

object <-all_send_methods: create=[bool] -> chain

object <-all_attributes: create=[bool] -> chain

Return a chain holding all the object-level extensions to the object of the given type. If create equals @on, this call will always succeed, possibly returning an empty chain. Otherwise the call might fail.

The following extensions are defined:

object->attribute	Object-level instance variable
constraint	Binary constraint between two objects
hyper	Binary relation (two-way attribute)
object->recogniser	Handler for event objects (class graphical)
object->send_method	Object-level method (send)
object->get_method	Object-level method (get)

See also class constraint and class hyper.

See also

- object->attribute
- object-interceptor

object <-attribute: name -> unchecked

Get the value of an attribute associated to the object using object->attribute. The attribute may also me requested using a plain get operation:

?- new(@o, object),
   send(@o, attribute, gnus, 4).

?- get(@o, attribute, gnus, G).
?- get(@o, gnus, G).

The two are equivalent, except that the latter gives an error if no such attribute is defined.

object <-class: -> class

Instance of class class to which this object belongs. The normal way to test that an object is of some particular class is either object->instance_of or object<-class_name. In most situations the first is to be preferred.

See also

- object<-class_name
- object<-_class
- object->same_class

object <-class_name: -> name

Name of the class the object belongs to. Shorthand for:

get(Object?class, name, ClassName).

See also

- object<-class
- object<-_class_name

object <-class_variable_value: name -> any

Get value of associated class_variable object. See also class_variable/4. Note that, in the absence of a method or variable with the name name, object<-Name is equivalent.

object <-clone: -> object

Object object<-clone creates a clone of an object. The semantics of cloning objects in general are difficult to define. Which related objects are to be cloned and which are to be shared between the clone and the original object?

The approach taken by PCE is not particularly neat. We do not recommend heavy use of this facility.

Object are cloned recursively. This implies all objects that can be reached from this object are cloned as well. The algorithm deals correctly with cyclic structures.

While executing a recursive clone, two flags may influence the result:

variable<-clone_style	Defines the type of relation
class<-clone_style	Defines the type of object

Please consult the documentation of these for details.

Bugs: The semantics are ill defined. Be very carefull with plain cloning and study this description carefully before going ahead. When in doubt, use the inspector tool from the main menu to find out about the result.

See also

- class-clone_style
- object->save_in_file

object <-convert: int|char_array -> object

The method object<-convert is called by type<-translate, part of the generic type-checking and type conversion system. It is not a normal method not the receiver, but the result is an instance of the class on which the method is defined. The receiver is normally the class.

The task of the object<-convert method is to translate the argument into an instance of the requested type.

For class object itself no translation is necessary as anything in PCE already is an instance of class object. This method will therefore never be called directly by the PCE type conversion system. This method translates a text (char_array object) of the form @<name> into an object if <name> is a valid object reference. This method is useful for defining other conversion functions.

object <-create_context: condition=[code] -> object

If the receiver is executing object->initialise, scan the goal stack searching for a receiver higher in the goal stack for which condition succeeds. Condition is executed with the following arguments:

@receiver	receiving object
@arg1	receiver of message of parent goal
@arg2	implementation of message of parent goal

This method is intended to find the context in which an object (often a graphical) is created, allowing it to query the context for additional information. See also visual<-contained_in.

object <-find_all_send_methods: condition=[code] -> chain

Compute a chain with all behaviour objects that may be used to invoke send behaviour on this object. It will analyse:

• Attributes
• Class’variables and send methods
• Delegation Overruled behaviour is automatically deleted from the chain. The additional conditions is executed binding @arg1 to the implementation object.

object <-find_hyper: hyper_name=[name], test=[code] -> hyper

Find hyper-object from specifications. hyper_name is the name of the hyper, seen from the receiver of this message. If hyper_name is @default, all hypers are considered. test is a code object. If it is not @default, it is executed using the following arguments:

@arg1	Receiver of this message
@arg2	Hyper object
@arg3	Object at other end of the hyper.

See also object<-hypered.

object <-functor: -> name

Functor of the term description of the object. Unless overruled, this is equivalent to object<-class_name.

See also

- topic Object -> Term
- class-term_functor
- object<-_arity
- object<-_arg

object <-get_class: selector=name, argument=unchecked ... -> unchecked

Invoke get_method on object, bypassing possible object-level get_methods associated with object->get_method. This method serves a similar purpose as object->get_super when using class-level programming.

See also

object->get_method

object <-get_hyper: hyper_name=[name], selector=name, argument=unchecked ... -> unchecked

Perform a broadcast get operation on objects object<-hypered to this object. If a hyper_name is given only hypers with this name are considered. Otherwise all hypers are considered. As soon as one of the hypered objects returns a value, this method returns with this value. Otherwise the method fails. Example:

?- new(@o, object),
   new(_, hyper(@o, bitmap('pce.bm'), bitmap)),
   new(_, hyper(@o, text(hello), text)).

?- pce_catch_error(no_behaviour,
                                   get(@o, get_hyper,
                                           @default, string, S).
S = hello

?- pce_catch_error(no_behaviour,
                                   get(@o, get_hyper,
                                           @default, pixel, 3, 5, P).
P = @off

The first query is answered by the text object, while the latter is answered by the bitmap object (delegated to the bitmap<-image). Note the use of pce_catch_error/2 to avoid an error while broadcasting to objects that do not understand the method.

object <-send_method: name -> tuple

object <-get_method: name -> tuple

This method locates the implementation for the specified selector for the specified (send/get) type of operation. It will try (in this order):

• attribute objects (see object->attribute).
• class<-send_method
• Delegation. See class<-delegate The tuple<-first contains the receiver, which is either the object itself or the object the message will be delegated to. The tuple<-second contains the behaviour object that implements the method.

  Examples:

  ?- new(@p, point),
     get(@p, send_method, mirror, tuple(Object, Impl)).
  
  Object = @p/point
  Impl = @632241/send_method
  
  ?- new(@v, view),
     get(@v, send_method, append, tuple(Object, Impl)).
  
  Object = @833889/editor
  Impl = @749374/send_method

  The second example indicates that, when a message object->append is sent to @v it will be delegated to the editor @833889.

  See also object->has_get_method, object->has_send_method and object<-all_send_methods.

object <-get_sub: selector=name, argument=unchecked ... -> unchecked

Invoke message on @receiver, using the definition from the object's own class instead of the current class. See class->get_method for further details.

Bugs: Actually, a normal get operation executed in a method already performs a object<-get_sub. Reserved fro future extension.

object <-get_super: selector=name, argument=unchecked ... -> unchecked

Invoke behaviour of the super-class. This behaviour is intended to be used only for using behaviour of the superclass when defining new classes. This method is only valid in the context of class-defined methods. The receiver should be the same object as the receiver of the executing method (i.e. object<-get_super is always to it self).

See also object<-slot.

See also

- topic Methods
- topic Class-level Programming
- object->send_super

object <-get_vector: unchecked ... -> unchecked

Invokes a get-method on the object itself. The first element of the vector is used as a selector, the subsequent ones are used as arguments to the behaviour. E.g.

get(@prolog, get_vector, vector(plus, 1, 1), X).

Is a very complicated way to add 1 and 1.

This behaviour is intended to deal with delegating messages trapped via the object->get_catch_all behaviour.

See also

object->send_vector

object <-hypered: hyper_name=[name], test=[code] -> object

Find a hyper-related object. Name is the name of the hyper (seen from the side of the receiver). Test is an optionally additional test. If present, this test is executed using the following arguments:

@arg1	This object
@arg2	The hyper object
@arg3	The object at the other end of the hyper

The first matching object is returned. See also object<-all_hypers.

object <-inspect: -> bool

Inherits description from: object->inspect

See also

- object->inspect
- object<-_inspect

object <-lock_object: -> bool

When @on, PCE's garbage collector will not remove this object, even if it has no references. Globally named objects are by default locked, as are most reusable objects for which the class maintains a table: types, names, modifiers, etc.

A locked object is destroyed by object->free. To protect an object against object->free, use object->protect.

When @off, the lock is removed from the object. If the object has no references, it will be object->free’d. If this is not desirable, use object<-unlock.

See also

- object->protect
- object->done
- object->lock_object

object <-object_reference: -> name|int

Reference name of the object (see object->name_reference) or integer reference for objects that have no named reference. See also pce<-object_from_reference.

See also

pce<-object_from_reference

object <-print_name: -> text=char_array

The method object<-print_name is intended to convert an object into a textual representation. It serves two purposes:

• Implement the %N special sequence in string->format
• Realise text_item<-print_name_of_value. This method is redefined by various subclasses. object<-print_name itself performs the following steps:
• If the object accepts object<-name and the return value can be converted into a char_array object, return this converted value.
• Otherwise return a new string holding the internal debugger representation of objects.

object <-protect: -> bool

Inherits description from: object->protect

See also

object->protect

object <-references: -> int

PCE uses reference counts for the incremental garbage collector. The number of references is the number of slot relations towards this object.

Note that PCE does not know which objects have references to an object; slot-relations are uni-directional.

See also

- tool Inspector
- topic Garbage collection
- object<-_references

object <-report_to: -> object

Object for object->report. The default for non-visual objects is the receiver of the current event (@event). See also visual<-report_to.

object <-self: -> object

Returns the object itself. Hardly ever necessary within the architecture of PCE.

object <-slot: name|int -> unchecked

Get the value of the named slot, bypassing protection. When given an integer, get the value of the nth-slot (counting from 1).

This method is used in the implementation of get_method objects if the get method wants to access a slot with the same name without interaction from the method. See also class->get_method.

See also

- class variable
- class->get_method
- object->get_method
- object->slot
- object<-_slot

object <-storage_reference: -> any

This method is used by object->save_in_file to handle shared object resources (colours, fonts, etc.). If this method is executed successfully, object->save_in_file stores the classname of the the object and the returned object.

source_sink<-object loads the classname, converts the classname to a type object, loads the returned reference object and attempts type<-check to produce an object of the requested type.

See colour<-storage_reference for an example.

object <-unlock: -> unchecked

Unlock object and return object<-self. If, after unlocking, the object has no references, it will be pushed on the‘anser stack’, making it visible to the incremental garbage collector.

In combination with object->lock_object, this method may be used to disconnect an object from its environment, handing it back to the incremental garbage collector. An example can be found in emacs_window<-prompt, a part of PceEmacs.

Assume we have a chain object holding a point and we want to delete the object from the chain without deleting the point. Direct usage of chain->delete may destroy the point. The following code avoids this:

send(Point, lock_object, @on),
send(Chain, delete, Point),
get(Point, unlock, _).