PageRenderTime 47ms CodeModel.GetById 20ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 0ms

/interpreter/tags/at2-build190607/src/edu/vub/at/objects/ATObject.java

http://ambienttalk.googlecode.com/
Java | 831 lines | 55 code | 45 blank | 731 comment | 0 complexity | d60e5759b3c102b70a8087504f27e21c MD5 | raw file
  1/**
  2 * AmbientTalk/2 Project
  3 * ATObject.java created on 13-jul-2006 at 15:33:42
  4 * (c) Programming Technology Lab, 2006 - 2007
  5 * Authors: Tom Van Cutsem & Stijn Mostinckx
  6 * 
  7 * Permission is hereby granted, free of charge, to any person
  8 * obtaining a copy of this software and associated documentation
  9 * files (the "Software"), to deal in the Software without
 10 * restriction, including without limitation the rights to use,
 11 * copy, modify, merge, publish, distribute, sublicense, and/or
 12 * sell copies of the Software, and to permit persons to whom the
 13 * Software is furnished to do so, subject to the following
 14 * conditions:
 15 *
 16 * The above copyright notice and this permission notice shall be
 17 * included in all copies or substantial portions of the Software.
 18 *
 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 21 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 23 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 24 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 25 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 26 * OTHER DEALINGS IN THE SOFTWARE.
 27 */
 28package edu.vub.at.objects;
 29
 30import edu.vub.at.actors.ATAsyncMessage;
 31import edu.vub.at.exceptions.InterpreterException;
 32import edu.vub.at.exceptions.XDuplicateSlot;
 33import edu.vub.at.exceptions.XIllegalQuote;
 34import edu.vub.at.exceptions.XIllegalUnquote;
 35import edu.vub.at.exceptions.XObjectOffline;
 36import edu.vub.at.exceptions.XSelectorNotFound;
 37import edu.vub.at.exceptions.XUnassignableField;
 38import edu.vub.at.exceptions.XUndefinedSlot;
 39import edu.vub.at.objects.coercion.ATConversions;
 40import edu.vub.at.objects.grammar.ATSymbol;
 41import edu.vub.at.objects.mirrors.NATMirage;
 42import edu.vub.at.objects.mirrors.OBJMirrorRoot;
 43import edu.vub.at.objects.natives.NATCallframe;
 44import edu.vub.at.objects.natives.NATNil;
 45import edu.vub.at.objects.natives.NATObject;
 46import edu.vub.at.objects.natives.NATText;
 47import edu.vub.at.objects.symbiosis.JavaClass;
 48import edu.vub.at.objects.symbiosis.JavaObject;
 49
 50/**
 51 * ATObject represents the public interface common to any AmbientTalk/2 object.
 52 * Any value representing an ambienttalk object should implement this interface.
 53 * 
 54 * More specifically, this interface actually defines two interfaces all at once:
 55 * <ul>
 56 *  <li>A <b>base-level</b> interface to AmbientTalk objects, describing all
 57 *      methods and fields that a regular AmbientTalk object understands.
 58 *  <li>A <b>meta-level</b> interface to AmbientTalk objects, describing all
 59 *      methods and fields that the <b>mirror</b> on any AmbientTalk object
 60 *      understands.
 61 * </ul>
 62 * 
 63 * In the AmbientTalk/2 Interpreter implementation, there are only a few classes
 64 * that (almost) fully implement this interface. The principal implementors are:
 65 * 
 66 * <ul>
 67 *   <li>{@link NATNil}: provides a default implementation for all <i>native</i> data types.
 68 *   For example, native methods, closures, abstract grammar nodes, booleans, numbers, etc.
 69 *   are all represented as AmbientTalk objects with 'native' behaviour.
 70 *   <li>{@link NATCallframe}: overrides most of the default behaviour of {@link NATNil} to
 71 *   implement the behaviour of call frames, also known as <i>activation records</i>. In
 72 *   AmbientTalk, call frames are the objects that together define the runtime stack.
 73 *   They are objects with support for fields but without support for actual methods.
 74 *   <li>{@link NATObject}: extends the behaviour of call frames to include support for
 75 *   full-fledged, programmer-defined objects with support for methods and delegation.
 76 *   <li>{@link JavaClass} and {@link JavaObject}: adapt the behaviour of native AmbientTalk
 77 *   objects to engage in symbiosis with either a Java class or a Java object.
 78 *   This implementation makes use of the Java Reflection API to regard Java objects
 79 *   as though it were AmbientTalk objects.
 80 *   <li>{@link NATMirage} and {@link OBJMirrorRoot}: these two classes work in tandem to
 81 *   enable reflection on AmbientTalk objects. That is, because of these two classes, an
 82 *   AmbientTalk programmer can himself invoke the methods provided in this interface.
 83 *   {@link NATMirage} implements each operation in this interface by forwarding a
 84 *   downed invocation to a custom so-called <i>mirror</i> object. This mirror object
 85 *   can delegate to {@link OBJMirrorRoot}, which is a special object that implements
 86 *   each meta-level operation of this interface as a base-level operation. Hence, in
 87 *   a sense, {@link OBJMirrorRoot} also 'implements' this interface, but at the
 88 *   AmbientTalk level, rather than at the Java level.
 89 * </ul>
 90 * 
 91 * @author tvcutsem
 92 */
 93public interface ATObject extends ATConversions {
 94
 95    /* ------------------------------
 96      * -- Message Sending Protocol --
 97      * ------------------------------ */
 98
 99    /**
100     * This behavioural meta-level operation reifies the act of sending
101     * an asynchronous message.
102     * 
103     * When the base-level AmbientTalk code <code>rcv<-m()</code> is
104     * evaluated in the context of an object <tt>o</tt>, an asynchronous message
105     * <code><-m()</code> is first created by the current actor mirror.
106     * Subsequently, this message needs to be sent to the receiver. This
107     * meta-level operation is reified by this method, as if by invoking:
108     * <pre>(reflect: o).send(message)</pre>
109     * The default behaviour is to access the current actor's mirror and to
110     * ask the actor to send the message in this object's stead by invoking
111     * <pre>actor.send(message)</pre>
112     * 
113     * @param message the asynchronous message to be sent by this object
114     * @return the result of message sending, which will be the value of an
115     * asynchronous message send expression.
116     */
117    public ATObject meta_send(ATAsyncMessage message) throws InterpreterException;
118    
119    /**
120     * This behavioural meta-level operation reifies the act of receiving
121     * an asynchronous message.
122     * 
123     * When an AmbientTalk object receives a message that was sent to it
124     * asynchronously, the message is delivered to the object's mirror by
125     * means of this meta-level operation.
126     * <p>
127     * The default behaviour of a mirror in response to the reception of a
128     * message <tt>msg</tt> is to invoke:
129     * <pre>msg.process(self)</pre>
130     * In turn, the default message processing behaviour is to invoke
131     * the method corresponding to the message's selector on this object.
132     * Hence, usually a <tt>receive</tt> operation is simply translated into
133     * a <tt>invoke</tt> operation. The reason for having a separate <tt>receive</tt>
134     * operation is that this enables the AmbientTalk meta-level programmer to
135     * distinguish between synchronously and asynchronously received messages.
136     * @param message the message that was asynchronously sent to this object
137     * @return by default, the value of invoking the method corresponding to the message
138     */
139    public ATObject meta_receive(ATAsyncMessage message) throws InterpreterException;
140   
141    /**
142     * This meta-level operation reifies the act of synchronous message sending
143     * (better known as "method invocation").
144     * Hence, the meta-level equivalent
145     * of the base-level code <code>o.m()</code> is:
146     * <pre>(reflect: o).invoke(o,`m,[])</pre>.
147     * 
148     * Method invocation comprises selector lookup and the application of the value
149     * bound to the selector. Selector lookup first queries an object's local
150     * fields, then the method dictionary. If the selector is not found, the
151     * search continues in the objects <i>dynamic parent</i>.
152     * <p>
153     * Note also that the first argument to <tt>invoke</tt> denotes the
154     * so-called "receiver" of the invocation. It is this object to which
155     * the <tt>self</tt> pseudo-variable should be bound during method execution.
156     * 
157     * @see #meta_doesNotUnderstand(ATSymbol) for what happens if the selector
158     * is not found.
159     *
160     * @param receiver the object to which <tt>self</tt> is bound during execution
161     * of the method
162     * @param selector a symbol denoting the name of the method to be invoked
163     * @param arguments the table of actual arguments to be passed to the method
164     * @return by default, the object returned from the invoked method
165     */
166    public ATObject meta_invoke(ATObject receiver, ATSymbol selector, ATTable arguments) throws InterpreterException;
167
168    /**
169     * This meta-level method is used to determine whether an object has a
170     * field or method corresponding to the given selector, without actually invoking
171     * or selecting any value associated with that selector.
172     * <p>
173     * The lookup process is the same as that for the <tt>invoke</tt> operation (i.e.
174     * not only the object's own fields and methods are searched, but also those of
175     * its dynamic parents).
176     * 
177     * @param selector a symbol denoting the name of a field or method
178     * @return a boolean denoting whether the object responds to <tt>o.selector</tt>
179     */
180    public ATBoolean meta_respondsTo(ATSymbol selector) throws InterpreterException;
181
182    /**
183     * This behavioural meta-level operation reifies a failed dynamic method or field lookup.
184     * 
185     * When method invocation or field selection fails to find the selector in
186     * the dynamic parent chain of an object, rather than immediately raising an
187     * {@link XSelectorNotFound} exception, the mirror of the original receiver
188     * of the method invocation or field selection is asked to handle failed lookup.
189     * <p>
190     * The default behaviour of <tt>doesNotUnderstand</tt> is to raise an
191     * {@link XSelectorNotFound} exception.
192     * <p>
193     * This method is very reminiscent of Smalltalk's well-known
194     * <tt>doesNotUnderstand:</tt> and of Ruby's <tt>method_missing</tt> methods.
195     * There are, however, two important differences:
196     * <ul>
197     *  <li> <tt>doesNotUnderstand</tt> is a <b>meta</b>-level operation in AmbientTalk.
198     *  It is an operation defined on mirrors, not on regular objects.
199     *  <li> <tt>doesNotUnderstand</tt> in AmbientTalk relates to <i>attribute
200     *  selection</i>, not to <i>method invocation</i>. Hence, this operation is
201     *  more general in AmbientTalk than in Smalltalk: it intercepts both failed
202     *  method invocations as well as failed field selections. Hence, it can be used
203     *  to model "virtual" fields. This shows in the interface: this operation
204     *  does not consume the actual arguments of a failed method invocation. These
205     *  should be consumed by means of currying, e.g. by making <tt>doesNotUnderstand</tt>
206     *  return a block which can then take the arguments table as its sole parameter.
207     * </ul>
208     *
209     * @param selector a symbol denoting the name of a method or field that could not be found
210     * @return by default, this operation does not return a value, but raises an exception instead.
211     * @throws edu.vub.at.exceptions.XSelectorNotFound the default reaction to a failed selection
212     */
213    public ATObject meta_doesNotUnderstand(ATSymbol selector) throws InterpreterException;
214
215    /* -----------------------------
216     * -- Object Passing protocol --
217     * ----------------------------- */
218
219    /**
220     * This behavioural meta-level operation reifies object serialization.
221     * 
222     * When an AmbientTalk object crosses actor boundaries, e.g. by means of
223     * parameter passing, as a return value or because it was explicitly
224     * exported, this meta-level operation is invoked on the object's mirror.
225     * <p>
226     * This operation allows objects to specify themselves how they should
227     * be parameter-passed during inter-actor communication. The interpreter
228     * will never pass an object to another actor directly, but instead always
229     * parameter-passes the <i>return value</i> of invoing <tt>pass()</tt> on
230     * the object's mirror.
231     * <p>
232     * Mirrors on by-copy objects implement <tt>pass</tt> as follows:
233     * <pre>def pass() { base }</pre>
234     * Mirrors on by-reference objects implement <tt>pass</tt> by returning
235     * a far reference to their base-level object.
236     * 
237     * @return the object to be parameter-passed instead of this object. For objects,
238     * the default is a far reference to themselves. For isolates, the default is
239     * to return themselves.
240     */
241    public ATObject meta_pass() throws InterpreterException;
242
243    /**
244     * This behavioural meta-level operation reifies object deserialization.
245     * 
246     * When an AmbientTalk object has just crossed an actor boundary (e.g.
247     * because of inter-actor message sending) this meta-level operation
248     * is invoked on the object's mirror.
249     * <p>
250     * This meta-level operation gives objects a chance to tell the interpreter
251     * which object they actually represent, because the object retained
252     * after parameter passing is the return value of the <tt>resolve</tt>
253     * operation.
254     * <p>
255     * Mirrors on by-copy objects, like isolates, implement <tt>resolve</tt> as follows:
256     * <pre>def resolve() { base }</pre>
257     * In other words, by-copy objects represent themselves. By-reference objects
258     * are paremeter passed as far references. Mirrors on far references implement
259     * <tt>resolve</tt> by trying to resolve the far reference into a local, regular
260     * object reference (which is possible if the object they point to is located
261     * in the actor in which they just arrived). If it is not possible to resolve
262     * a far reference into a local object, the far reference remains a far reference.
263     * <p>
264     * Note that for isolates, this operation also ensures that the isolate's
265     * lexical scope is rebound to the lexical root of the recipient actor.
266     *  
267     * @return the object represented by this object
268     * @throws XObjectOffline if a far reference to a local object can no longer be resolved
269     * because the object has been taken offline 
270     */
271    public ATObject meta_resolve() throws InterpreterException;
272    
273    /* ------------------------------------------
274     * -- Slot accessing and mutating protocol --
275     * ------------------------------------------ */
276    
277    /**
278     * This meta-level operation reifies field or method selection. Hence, the
279     * base-level evaluation of <code>o.x</code> is interpreted at the meta-level as:
280     * <pre>(reflect: o).select(o, `x)</pre>
281     * 
282     * The selector lookup follows the same search rules as those for <tt>invoke</tt>.
283     * That is: first an object's local fields are searched, then the local method dictionary,
284     * and then the object's <i>dynamic parent</i>.
285     * <p>
286     * The <tt>select</tt> operation can be used to both select fields or methods from
287     * an object. When the selector is bound to a method, the return value of
288     * <tt>select</tt> is a closure that wraps the found method in the object in which
289     * the method was found. This ensures that the method retains its context information,
290     * such as the lexical scope in which it was defined and the value of <tt>self</tt>, which
291     * will be bound to the original receiver, i.e. the first argument of <tt>select</tt>.
292     *
293     * @see #meta_doesNotUnderstand(ATSymbol) for what happens if the selector is not found.
294     *
295     * @param receiver the dynamic receiver of the selection. If the result of the selection is
296     * a method, the closure wrapping the method will bind <tt>self</tt> to this object.
297     * @param selector a symbol denoting the name of the field or method to select.
298     * @return if selector is bound to a field, the value of the field; otherwise if
299     * the selector is bound to a method, a closure wrapping the method.
300     */
301    public ATObject meta_select(ATObject receiver, ATSymbol selector) throws InterpreterException;
302
303    /**
304     * This meta-level operation reifies variable lookup. Hence, the base-level code
305     * <code>x</code> evaluated in the lexical scope <tt>lex</tt> is interpreted at
306     * the meta-evel as:
307     * <pre>(reflect: lex).lookup(`x)</pre>
308     * 
309     * Variable lookup first queries the local fields of this object, then the local
310     * method dictionary. If the selector is not found, the search continues in
311     * this object's <i>lexical parent</i>. Hence, variable lookup follows
312     * <b>lexical scoping rules</b>.
313     * <p>
314     * Similar to the behaviour of <tt>select</tt>, if the selector is bound to a
315     * method rather than a field, <tt>lookup</tt> returns a closure wrapping the method
316     * to preserve proper lexical scoping and the value of <tt>self</tt> for the found
317     * method.
318     * <p>
319     * Note that, unlike <tt>invoke</tt> and <tt>select</tt>, <tt>lookup</tt> does
320     * not give rise to the invocation of <tt>doesNotUnderstand</tt> if the selector
321     * was not found. The reason for this is that lexical lookup is a static process
322     * for which it makes less sense to provide dynamic interception facilities.
323     *
324     * @param selector a symbol denoting the name of the field or method to look up lexically.
325     * @return if selector is bound to a field, the value of the field; otherwise if selector
326     * is bound to a method, a closure wrapping the method.
327     * @throws XUndefinedSlot if the selector could not be found in the lexical scope of this object
328     */
329    public ATObject meta_lookup(ATSymbol selector) throws InterpreterException;
330
331    /**
332     * This meta-level operation reifies field definition. Hence, the base-level
333     * code <code>def x := v</code> evaluated in a lexical scope <tt>lex</tt>
334     * is interpreted at the meta-level as:
335     * <pre>(reflect: lex).defineField(`x, v)</pre>
336     * 
337     * Invoking this meta-level operation on an object's mirror adds a new field
338     * to that object. An object cannot contain two or more fields with the
339     * same name.
340     *
341     * @param name a symbol denoting the name of the new field
342     * @param value the value of the new field
343     * @return nil
344     * @throws edu.vub.at.exceptions.XDuplicateSlot if the object already has a
345     * local field with the given name
346     */
347    public ATNil meta_defineField(ATSymbol name, ATObject value) throws InterpreterException;
348
349    /**
350     * This meta-level operation reifies variable assignment. Hence, the base-level
351     * code <code>x := v</code> evaluated in a lexical scope <tt>lex</tt>
352     * is interpreted at the meta-level as:
353     * <pre>(reflect: lex).assignVariable(`x, v)</pre>
354     * 
355     * When <tt>assignVariable</tt> is invoked on an object's mirror, the variable
356     * to assign is looked up according to rules similar to those defined by <tt>lookup</tt>.
357     * First, the object's local fields are checked. If the selector is not found there,
358     * the fields of the <i>lexical parent</i> of the object are searched recursively.
359     * Hence, variable assignment follows <b>lexical scoping rules</b>.
360     * Note that local methods are always disregarded: methods are not assignable.
361     * <p>
362     * When the lookup is successful, the value bound to the found field is assigned
363     * to the given value.
364     *
365     * @param name a symbol representing the name of the variable to assign.
366     * @param value the value to assign to the variable.
367     * @return nil
368     * @throws XUnassignableField if the variable to assign to cannot be found.
369     */
370    public ATNil meta_assignVariable(ATSymbol name, ATObject value) throws InterpreterException;
371
372    /**
373     * This meta-level operation reifies field assignment. Hence, the base-level
374     * code <code>o.x := v</code> is interpreted at the meta-level as:
375     * <pre>(reflect: o).assignField(`x, v)</pre>
376     * 
377     * When <tt>assignField</tt> is invoked on an object's mirror, the field
378     * to assign is looked up according to rules similar to those defined by
379     * <tt>invoke</tt> and <tt>select</tt>. First, the object's local fields
380     * are checked. If the selector is not found there, the fields of its
381     * <i>dynamic parent</i> are searched recursively. Note that local methods
382     * are always disregarded: methods are not assignable.
383     * <p>
384     * When the lookup is successful, the value bound to the found field is assigned
385     * to the given value.
386     *
387     * @param name a symbol representing the name of the field to assign.
388     * @param value the value to assign to the field.
389     * @return nil
390     * @throws XUnassignableField if the field to assign to cannot be found.
391     */
392    public ATNil meta_assignField(ATObject receiver, ATSymbol name, ATObject value) throws InterpreterException;
393
394    /* -----------------------------------------
395      * -- Cloning and instantiation protocol --
396      * ---------------------------------------- */
397
398    /**
399     * This meta-level operation reifies the act of cloning the base-level object.
400     * Hence, the code <code>clone: o</code> is interpreted at the meta-level as
401     * <pre>(reflect: o).clone()</pre>
402     * 
403     * AmbientTalk's default cloning semantics are based on shallow copying.
404     * A cloned object has copies of the original object's fields, but the values
405     * of the fields are shared between the clones. A clone has the same methods
406     * as the original object. Methods added at a later stage to the original
407     * will not affect the clone's methods and vice versa. This means that each
408     * objects has its own independent fields and methods.
409     * <p>
410     * If the cloned AmbientTalk object contains programmer-defined field objects,
411     * each of these fields is re-instantiated with the clone as a parameter. The
412     * clone is intialized with the re-instantiated fields rather than with the
413     * fields of the original object. This property helps to ensure that each
414     * object has its own independent fields.
415     * <p>
416     * If the object has a <i>shares-a</i> relationship with its parent, the object
417     * and its clone will <b>share</b> the same parent object. Shares-a relationships
418     * are the default in AmbientTalk, and they match with the semantics of
419     * shallow copying: the dynamic parent of an object is a regular field, hence
420     * its contents is shallow-copied.
421     * <p>
422     * If the object has an <i>is-a</i> relationship with its parent object, a
423     * clone of the object will receive a clone of the parent object as its parent.
424     * Hence, is-a relationships "override" the default shallow copying semantics
425     * and recursively clone the parent of an object up to a shares-a relationship.
426     * <p>
427     * If a mirage is cloned, its mirror is automatically re-instantiated with
428     * the new mirage, to ensure that each mirage has its independent mirror.
429     * @return a clone of the mirror's <tt>base</tt> object
430     */
431    public ATObject meta_clone() throws InterpreterException;
432
433    /**
434     * This meta-level operation reifies instance creation. The default
435     * implementation of an AmbientTalk object's <tt>new</tt> method is:
436     * <pre>def new(@initargs) { (reflect: self).newInstance(initargs) }</pre>
437     * 
438     * Creating a new instance of an object is a combination of:
439     * <ul>
440     *  <li>creating a clone of the object
441     *  <li>initializing the clone by invoking its <tt>init</tt> method
442     * </ul>
443     * 
444     * The default implementation is:
445     * <pre>def newInstance(initargs) {
446     *  def instance := self.clone();
447     *  instance.init(@initargs);
448     *  instance;
449     *}
450     * </pre>
451     * 
452     * Instance creation in AmbientTalk is designed to mimick class instantiation
453     * in a class-based language. Instantiating a class <tt>c</tt> requires <i>allocating</i>
454     * a new instance <tt>i</tt> and then invoking the <i>constructor</i> on that
455     * new instance. In AmbientTalk, class allocation is replaced by object
456     * <i>cloning</i>. The benefit is that an instantiated object its variables are
457     * already initialized to useful values, being those of the object from which
458     * it is instantiated. The <tt>init</tt> method plays the role of "constructor"
459     * in AmbientTalk.
460     *
461     * @param initargs a table denoting the actual arguments to be passed to
462     * the <tt>init</tt> method
463     * @return the new instance
464     */
465    public ATObject meta_newInstance(ATTable initargs) throws InterpreterException;
466
467    /* ---------------------------------
468      * -- Structural Access Protocol  --
469      * --------------------------------- */
470
471    /**
472     * This structural meta-level operation adds a field object to the receiver mirror's
473     * base object. An object cannot contain two or more fields with the same name.
474     * 
475     * Note that the field object passed as an argument serves as a <i>prototype</i>
476     * object: the actual field object added is an <i>instance</i> of the passed field object.
477     * A field object should always have an <tt>init</tt> method that takes as an argument
478     * the new host object to which it is added. This is often useful, as the behaviour
479     * of a field may depend on the object in which it resides. Because <tt>addField</tt>
480     * creates a new instance of the field, this gives the field object a chance to
481     * properly refer to its new host. 
482     * <p>
483     * As an example, here is how to add a read-only field <tt>foo</tt> initialized
484     * to <tt>5</tt> to an object <tt>obj</tt>:
485     * <pre>def makeConstantField(nam, val) {
486     *   object: {
487     *     def new(newHost) { self }; // singleton pattern
488     *     def name := nam;
489     *     def readField() { val };
490     *     def writeField(newVal) { nil };
491     *   }
492     * };
493     * (reflect: obj).addField(makeConstantField(`foo, 5));
494     * </pre>
495     * 
496     * @param field the prototype field object whose instance should be added
497     * to the receiver's base object
498     * @return nil
499     * @throws XDuplicateSlot if the base object already has a field with the
500     * same name as the new field
501     */
502    public ATNil meta_addField(ATField field) throws InterpreterException;
503
504    /**
505     * This structural meta-level operation adds a method to the receiver
506     * mirror's base object. An object cannot contain two or more methods
507     * with the same name.
508     * 
509     * @param method a method object to add to the receiver's base object's
510     * method dictionary.
511     * @return nil
512     * @throws XDuplicateSlot if a method with the new method's selector already
513     * exists in the base object.
514     */
515    public ATNil meta_addMethod(ATMethod method) throws InterpreterException;
516
517    /**
518     * This structural meta-level operation allows the metaprogrammer to reify a
519     * field of the receiver mirror's base object. Hence, unlike <tt>select</tt>
520     * and <tt>lookup</tt>, <tt>grabField</tt> returns a <i>field object</i> rather
521     * than the <i>value</i> bound to the field. For example: one could express
522     * <code>obj.super := val</code> at the meta-level as:
523     * 
524     * <pre>
525     * def superField := (reflect: obj).grabField(`super);
526     * superField.writeField(val);
527     * </pre>
528     *
529     * Another important difference between <tt>select</tt>, <tt>lookup</tt> and
530     * <tt>grabField</tt> is that <tt>grabField</tt> only considers the fields
531     * <i>local</i> to the receiver's base object. Fields of lexical or dynamic
532     * parent objects are <i>not</i> considered.
533     *
534     * @param selector a symbol representing the name of the field to select.
535     * @return a mirror on this object's field slot.
536     * @throws XUndefinedSlot if the field cannot be found within the receiver's
537     * base object.
538     */
539    public ATField meta_grabField(ATSymbol selector) throws InterpreterException;
540
541    /**
542     * This structural meta-level operation allows the metaprogrammer to
543     * reify a method defined on the receiver mirror's base object. Note that,
544     * unlike the <tt>select</tt> or <tt>lookup</tt> operations, <tt>grabMethod</tt>
545     * returns the bare method object, i.e. <i>not</i> a closure wrapping the method.
546     * <p>
547     * Also, unlike <tt>select</tt> and <tt>lookup</tt>, <tt>grabField</tt> only
548     * considers the locally defined methods of an object, methods of lexical or
549     * dynamic parent objects are <i>not</i> considered.
550     *
551     * @param selector a symbol representing the name of the method to grab from
552     * the receiver's base object.
553     * @return the bare method object bound to the given selector.
554     * @throws XSelectorNotFound if the method object cannot be found within the
555     * receiver's base object.
556     */
557    public ATMethod meta_grabMethod(ATSymbol selector) throws InterpreterException;
558
559    /**
560     * This structural meta-level operation allows access to all of the
561     * fields defined on the receiver mirror's base object. Note that
562     * this method only returns the base object's <i>locally</i> defined
563     * fields. Fields from parent objects are not returned.
564     * 
565     * @see ATObject#meta_grabField(ATSymbol) for details about the returned
566     * field objects. 
567     * @return a table of field objects (of type {@link ATField}).
568     */
569    public ATTable meta_listFields() throws InterpreterException;
570
571    /**
572     * This structural meta-level operation allows access to all of the
573     * methods defined on the receiver mirror's base object. Note that
574     * this method only returns the base object's <i>locally</i> defined
575     * methods. Methods from parent objects are not returned.
576     * 
577     * @see ATObject#meta_grabMethod(ATSymbol) for details about the returned
578     * method objects.
579     * @return a table of method objects (of type {@link ATMethod}).
580     */
581    public ATTable meta_listMethods() throws InterpreterException;
582
583    /**
584     * This structural meta-level operation returns whether or not
585     * the receiver mirror's base object is an <i>extension</i> of its
586     * parent object.
587     * <p>
588     * In AmbientTalk, all objects are part of a dynamic parent delegation chain:
589     * each object has a <tt>super</tt> field that denotes the object to which to
590     * delegate messages the object cannot understand itself. There are, however,
591     * two kinds of delegation links:
592     * <ul>
593     *  <li><b>IS-A</b> links: this kind of link denotes that the child object is
594     *  a true extension of its parent, and cannot meaningfully exist without the
595     *  parent's state. When the child is cloned, its parent will be cloned as well.
596     *  <li><b>SHARES-A</b> links: this kind of link denotes that the child object
597     *  simply delegates to its parent for purposes of sharing or code reuse. The
598     *  child can meaningfully exist without the parent's state. When the child is
599     *  cloned, the clone will delegate to the same parent.
600     * </ul>
601     *
602     * Examples:
603     * <pre>(reflect: (extend: parent with: code)).isExtensionOfParent() => true
604     *(reflect: (share: parent with: code)).isExtensionOfParent() => false
605     * </pre>
606     * 
607     * Note that accessing the dynamic parent itself is not a meta-level operation,
608     * the dynamic parent can simply be accessed from the base level by performing
609     * <code>obj.super</code>.
610     * 
611     * @return whether the base object extends its parent object via an
612     * <b>IS-A</b> link or not.
613     */
614    public ATBoolean meta_isExtensionOfParent() throws InterpreterException;
615
616    /* ---------------------
617     * -- Mirror Fields   --
618     * --------------------- */
619    
620    /**
621     * The <tt>lexicalParent</tt> field of a mirror denotes the lexical parent
622     * pointer of the mirror's base object. The lexical parent is the enclosing
623     * <i>lexical scope</i> in which the object was defined.
624     * 
625     * @return the object denoting this mirror's base object's lexically
626     * enclosing scope.
627     */
628    public ATObject meta_getLexicalParent() throws InterpreterException;
629
630    /* ------------------------------------------
631      * -- Abstract Grammar evaluation protocol --
632      * ------------------------------------------ */
633
634    /**
635     * This behavioural meta-level operation reifies the evaluation of
636     * abstract grammar objects into values. For objects, this operation
637     * returns the base object itself, signifying that the evaluation
638     * function defined on objects is the identity function. In other words,
639     * objects are <i>self-evaluating</i>. Parse tree objects (first-class
640     * abstract grammar elements), however, have dedicated evaluation
641     * functions. For example, evaluating <code>x</code> is equivalent to
642     * evaluating <code>(reflect: `x).eval(ctx)</code> where <tt>ctx</tt>
643     * is a reification of the current evaluation context.
644     * 
645     * @param ctx a context object that stores the current lexical scope and
646     * the current value of <tt>self</tt>
647     * @return the value of the abstract grammar element denoted by this mirror's
648     * base object.
649     * @throws XIllegalUnquote if an unquote abstract grammar element is evaluated. Such
650     * abstract grammar elements should only be encountered in a quoted parse tree.
651     */
652    public ATObject meta_eval(ATContext ctx) throws InterpreterException;
653
654    /**
655     * This behavioural meta-level operation reifies the quotation of
656     * abstract grammar elements. Regular objects simply return themselves
657     * upon quotation. When an abstract grammar element is quoted, rather
658     * than tree-recursively invoking <tt>eval</tt> on the parse trees,
659     * <tt>quote</tt> is tree-recursively invoked. When encountering
660     * an unquote, <tt>eval</tt> is again invoked on the unquoted subtree,
661     * with the context passed as an argument to <tt>quote</tt>.
662     * 
663     * @param ctx a context object passed on to be used in subsequent evaluations.
664     * @throws XIllegalQuote exception whenever an unquote-splice unquotation is discovered
665     * in an Abstract Grammar node where the resulting table cannot be spliced.
666     */
667    public ATObject meta_quote(ATContext ctx) throws InterpreterException;
668
669    /**
670     * This behavioural meta-level operation reifies the act of printing
671     * the base object in the read-eval-print loop. This operation may be
672     * overridden by mirrors to customise the printed representation of
673     * their base object.
674     * 
675     * @return a text value denoting a human-readable representation of the object.
676     */
677    public NATText meta_print() throws InterpreterException;
678
679    /* ----------------------------------
680     * -- Object Relational Comparison --
681     * ---------------------------------- */
682    
683    /**
684     * This meta-level operation determines whether this mirror's base object
685     * is related to the parameter object by a combination of cloning and
686     * extension operators. The default implementation is:
687     * 
688     * <pre>def isRelatedTo(object) {
689     *  self.isCloneOf(object).or: { (reflect: base.super).isRelatedTo(object) }
690     *}</pre>
691     * 
692     * @param object the object to compare this mirror's base object to
693     * @return true if the given object is a clone of the base object or a clone
694     * of the base object's parents.
695     */
696    public ATBoolean meta_isRelatedTo(ATObject object) throws InterpreterException;
697    
698    /**
699     * This meta-level operation determines whether this mirror's base object
700     * is a clone of the parameter object. The <i>is-clone-of</i> relation is transitive,
701     * so if <tt>martin</tt> is a clone of <tt>sally</tt> and <tt>sally</tt> is a clone of
702     * <tt>dolly</tt>, then <tt>martin</tt> is a clone of <tt>dolly</tt> as well.
703     * The relation is reflexive: <tt>dolly</tt> is a clone of itself.
704     * The relation is symmetric: <tt>dolly</tt> is also a clone of <tt>sally</tt>.
705     * 
706     * @param other the object to check the is-clone-of relationship with.
707     * @return true if the base object and the parameter object are clones (i.e. one
708     * was created by cloning the other), false otherwise.
709     */
710    public ATBoolean meta_isCloneOf(ATObject other) throws InterpreterException;
711
712    /* ---------------------------------
713     * -- Type Testing and Querying --
714     * --------------------------------- */
715    
716    /**
717     * Tests whether the receiver mirror's base object is tagged as a particular type.
718     * 
719     * The default implementation first compares the object's local type tags to the given type
720     * by means of the {@link ATTypeTag#base_isSubtypeOf(ATTypeTag)} method. If no local type
721     * is found, the test is applied recursively on this object's dynamic parent. In code:
722     * <pre>def isTaggedAs(type) {
723     *  (nil != (self.tagsOf: object).find: { |localType|
724	 *    localType.isSubtypeOf(type)
725	 *  }).or: { (reflect: base.super).isTaggedAs(type) }
726	 * };
727     * </pre>
728     * 
729     * The primitive method <tt>is: obj taggedAs: type</tt> is defined in terms of this
730     * method:
731     * <pre>
732     * def is: obj taggedAs: type {
733     *  (reflect: obj).isTaggedAs(type)
734     *};
735     * </pre>
736     * 
737     * @param type the type tag object to check for
738     * @return true if this mirror's base object or one of its parent objects is tagged
739     * with a subtype of the given type, false otherwise.
740     */
741    public ATBoolean meta_isTaggedAs(ATTypeTag type) throws InterpreterException;
742    
743    /**
744     * Returns all of the local type tags of this object. The primitive method
745     * <tt>tagsOf: obj</tt> is defined in terms of this method:
746     * 
747     * <pre>
748     * def tagsOf: obj {
749     *  (reflect: obj).typeTags
750     *};
751     * </pre>
752     * 
753     * @return a table of the type tags that were attached directly to this mirror's base
754     * object. The type tags of its parent objects are not returned.
755     */
756    public ATTable meta_getTypeTags() throws InterpreterException;
757    
758     /* -------------------------------
759      * - Base Level Object interface -
760      * ------------------------------- */
761
762    /**
763     * Bound to the dynamic parent of this object.
764     * 
765     * The dynamic parent of an object is the object to which failed
766     * selection or invocation requests or type tests are delegated to.
767     * 
768     * @return the current dynamic parent of this object.
769     */
770    public ATObject base_getSuper() throws InterpreterException;
771    
772    /**
773     * The identity operator. In AmbientTalk, equality of objects
774     * is by default pointer-equality (i.e. objects are equal only
775     * if they are identical).
776     * 
777     * This is a primitive method, present by default in every AmbientTalk
778     * object but redefinable by the programmer.
779     * 
780     * @return by default, true if the parameter object and this object are identical,
781     * false otherwise.
782     */
783    public ATBoolean base__opeql__opeql_(ATObject other) throws InterpreterException;
784
785    /**
786     * The object instantiation method. Note that in class-based OO languages,
787     * this method is usually at the level of the <i>class</i>. In AmbientTalk,
788     * this method is situated at the object-level directly. It can be overridden
789     * to e.g. enforce the singleton pattern or to return instances of other
790     * objects.
791     * 
792     * The default implementation of this method is:
793     * <pre>def new(@args) {
794     *  (reflect: self).newInstance(@args)
795     *};
796     * </pre>
797     * 
798     * This is a primitive method, present by default in every AmbientTalk
799     * object but redefinable by the programmer.
800     * 
801     * @see ATObject#meta_newInstance(ATTable) for a description of object instantiation.
802     * @param initargs the variable argument list to pass to the <tt>init</tt> method.
803     * @return by default, the new instance of this mirror's base object.
804     */
805    public ATObject base_new(ATObject[] initargs) throws InterpreterException;
806
807    /**
808     * The object initialisation method. In class-based languages, this method
809     * is often called the constructor. AmbientTalk only supports one constructor
810     * per object, but thanks to variable argument lists and optional parameters,
811     * the same flexibility as defining multiple constructors can often be achieved.
812     * Also, by overriding <tt>new</tt>, the developer may invoke additional methods
813     * on newly created objects if this is desirable.
814     * 
815     * The default implementation of this method is:
816     * <pre>def init(@args) {
817     *  super^init(@args)
818     *};
819     * </pre>
820     * 
821     * This is a primitive method, present by default in every AmbientTalk
822     * object but redefinable by the programmer.
823     * 
824     * @see ATObject#meta_newInstance(ATTable) for a description of object initialisation.
825     * @param initargs the arguments to the <tt>init</tt> constructor method.
826     * @return the return value of invoking the <tt>init</tt> method. Note that
827     * this value is <i>discarded</i> when <tt>init</tt> is invoked from the
828     * <tt>newInstance</tt> meta-level operation.
829     */
830    public ATObject base_init(ATObject[] initargs) throws InterpreterException;
831}