PageRenderTime 58ms CodeModel.GetById 11ms app.highlight 28ms RepoModel.GetById 1ms app.codeStats 1ms

/interpreter/tags/at2dist091109/src/edu/vub/at/objects/ATMirrorRoot.java

http://ambienttalk.googlecode.com/
Java | 784 lines | 45 code | 42 blank | 697 comment | 0 complexity | 2ffceb89072cbcbc7810c92aadb85bef MD5 | raw file
  1/**
  2 * AmbientTalk/2 Project
  3 * JavaInterfaceAdaptor.java created on Jul 13, 2006 at 10:25:01 PM
  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.XUndefinedSlot;
 38import edu.vub.at.objects.grammar.ATSymbol;
 39import edu.vub.at.objects.mirrors.NATMirage;
 40import edu.vub.at.objects.natives.NATText;
 41
 42/**
 43 * This is the interface of the root node of the intercessive mirrors delegation hierarchy.
 44 * <p>
 45 * Intercessive mirrors are always tied to a particular 'base' object.
 46 * The default intercessive mirror is named 'defaultMirror' and is an object
 47 * that understands all meta-level operations applicable on objects, implementing them using default semantics.
 48 * It can be thought of as being defined as follows:
 49 * 
 50 * <pre>
 51 * def mirrorroot := object: {
 52 *   def base := object: { nil } mirroredBy: self // base of the mirror root is an empty mirage
 53 *   def init(b) {
 54 *     base := b
 55 *   }
 56 *   def invoke(@args) { <default native invocation behaviour on base> }
 57 *   def select(@args) { <default native selection behaviour on base> }
 58 *   ...
 59 * } taggedAs: [ Mirror ]
 60 * </pre>
 61 * <p>
 62 * This object can then simply be extended / composed by other objects to deviate from the default semantics.
 63 * Note that the default semantics is applied to 'base' and *not* 'self.base', in other words:
 64 * although child mirrors can define their own 'base' field, it is not taken into consideration
 65 * by the mirror root. This also ensures that the mirror root is not abused to enact upon a mirage
 66 * for which it was not assigned to be the mirror.
 67 * <p>
 68 * Hence, 'mirrors' are simply objects with the same interface as this mirrorroot object: they should be
 69 * able to respond to all meta-level messages and have a 'base' field.
 70 * 
 71 * @author tvcutsem, smostinc
 72 */
 73public interface ATMirrorRoot extends ATObject {
 74
 75	/**
 76	 * The read-only field containing the mirror's base-level mirage.
 77	 */
 78	public NATMirage base_base() throws InterpreterException;
 79	
 80	/* ------------------------------
 81     * -- Message Sending Protocol --
 82     * ------------------------------ */
 83
 84   /**
 85    * This behavioural meta-level operation reifies the act of sending
 86    * an asynchronous message.
 87    * 
 88    * When the base-level AmbientTalk code <code>rcv<-m()</code> is
 89    * evaluated in the context of an object <tt>o</tt>, an asynchronous message
 90    * <code><-m()</code> is first created by the current actor mirror.
 91    * Subsequently, this message needs to be sent to the receiver. This
 92    * meta-level operation is reified by this method, as if by invoking:
 93    * <pre>(reflect: o).send(message)</pre>
 94    * The default behaviour is to access the current actor's mirror and to
 95    * ask the actor to send the message in this object's stead by invoking
 96    * <pre>actor.send(message)</pre>
 97    * @param receiver the object designated to receive the asynchronous message
 98    * @param message the asynchronous message to be sent by this object
 99    * 
100    * @return the result of message sending, which will be the value of an
101    * asynchronous message send expression.
102    */
103   public ATObject base_send(ATObject receiver, ATAsyncMessage message) throws InterpreterException;
104   
105   /**
106    * This behavioural meta-level operation reifies the act of receiving
107    * an asynchronous message.
108    * 
109    * When an asynchronous message is sent to an AmbientTalk object, its mirror
110    * is notified of this event by the invocation of this method. The method
111    * is invoked in the same execution turn as the turn in which the message
112    * is sent. This allows the receiver (e.g. a custom eventual reference proxy)
113    * to intervene in the message sending process and return a value different
114    * than the default <tt>nil</tt> value.
115    * <p>
116    * The default behaviour of a mirror on a local reference in response to
117    * the reception of an async
118    * message is to schedule this message for execution in a later turn
119    * in its owner's message queue. The actor will then later process
120    * the message by invoking
121    * <pre>msg.process(self)</pre>
122    * In turn, the default message processing behaviour is to invoke
123    * the method corresponding to the message's selector on this object.
124    * Hence, usually a <tt>receive</tt> operation is translated into
125    * a <tt>invoke</tt> operation in a later turn. The reason for having a
126    * separate <tt>receive</tt>
127    * operation is that this enables the AmbientTalk meta-level programmer to
128    * distinguish between synchronously and asynchronously received messages.
129    * 
130    * Far references react to <tt>receive</tt> by transmitting their message
131    * to their remote target.
132    * 
133    * @param message the message that was asynchronously sent to this object
134    * @return <tt>nil</tt>, by default
135    */
136   public ATObject base_receive(ATAsyncMessage message) throws InterpreterException;
137  
138   /**
139    * This meta-level operation reifies synchronous message sending ("method invocation").
140    * Hence, the meta-level equivalent
141    * of the base-level code <code>o.m()</code> is:
142    * <pre>(reflect: o).invoke(o,`m,[])</pre>.
143    * 
144    * Method invocation comprises selector lookup and the application of the value
145    * bound to the selector. Selector lookup first queries an object's local
146    * fields, then the method dictionary:
147    * <ul>
148    *  <li>If the selector ends with <tt>:=</tt> and matches a field, the field
149    *  is assigned if a unary argument list is specified (i.e. the field is treated
150    *  as a mutator method).
151    *  <li>Otherwise, if the selector is bound to a field containing
152    * a closure, that closure is applied to the given arguments.
153    *  <li>If the field is not bound to a closure, the field value is returned provided no arguments were
154    * specified (i.e. the field is treated like an accessor method).
155    *  <li>If the selector is bound to a method, the method is applied.
156    *  <li>If the selector is not found, the search continues in the objects <i>dynamic parent</i>.
157    * </ul>
158    * <p>
159    * Note also that the first argument to <tt>invoke</tt> denotes the
160    * so-called "receiver" of the invocation. It is this object to which
161    * the <tt>self</tt> pseudo-variable should be bound during method execution.
162    * 
163    * @see #base_doesNotUnderstand(ATSymbol) for what happens if the selector
164    * is not found.
165    *
166    * @param delegate the object to which <tt>self</tt> is bound during execution
167    * of the method
168    * @param invocation an object encapsulating at least the invocation's
169    *        <tt>selector</tt> (a {@link ATSymbol}) and <tt>arguments</tt> (a {@link ATTable}).
170    * @return by default, the object returned from the invoked method
171    */
172   public ATObject base_invoke(ATObject delegate, ATMethodInvocation invocation) throws InterpreterException;
173
174   /**
175    * This meta-level operation reifies "field selection".
176    * In other words, the base-level code
177    * <code>o.m</code>
178    * is interpreted at the meta-level as:
179    * <code>(reflect: o).invokeField(o, `m)</code>
180    * 
181    * This meta-level operation is nearly identical to {@link #base_invoke(ATObject, ATMethodInvocation)} with one
182    * important difference. When the selector is bound to a field storing a closure, this meta-level operation
183    * does <b>not</b> auto-apply the closure, but returns the closure instead.
184    * 
185    * For all other cases, the following equality holds:
186    * <code>o.m == o.m()</code>
187    * or, at the meta-level:
188    * <code>(reflect: o).invokeField(o, `m) == (reflect: o).invoke(o, MethodInvocation.new(`m, []))</code>
189    * 
190    * This effectively means that for client objects, it should not matter whether
191    * a property is implemented as a field or as a pair of accessor/mutator methods.
192    * 
193    * @param receiver the base-level object from which the 'field' should be selected.
194    * @param selector a symbol denoting the name of the method, accessor or mutator to be invoked
195    * @return the value of a field, or the return value of a nullary method.
196    */
197   public ATObject base_invokeField(ATObject receiver, ATSymbol selector) throws InterpreterException;
198   
199   /**
200    * This meta-level method is used to determine whether an object has a
201    * field or method corresponding to the given selector, without actually invoking
202    * or selecting any value associated with that selector.
203    * <p>
204    * The lookup process is the same as that for the <tt>invoke</tt> operation (i.e.
205    * not only the object's own fields and methods are searched, but also those of
206    * its dynamic parents).
207    * 
208    * @param selector a symbol denoting the name of a field (accessor or mutator) or method
209    * @return a boolean denoting whether the object responds to <tt>o.selector</tt>
210    */
211   public ATBoolean base_respondsTo(ATSymbol selector) throws InterpreterException;
212
213   /**
214    * This behavioural meta-level operation reifies a failed dynamic method or field lookup.
215    * 
216    * When method invocation or field selection fails to find the selector in
217    * the dynamic parent chain of an object, rather than immediately raising an
218    * {@link XSelectorNotFound} exception, the mirror of the original receiver
219    * of the method invocation or field selection is asked to handle failed lookup.
220    * <p>
221    * The default behaviour of <tt>doesNotUnderstand</tt> is to raise an
222    * {@link XSelectorNotFound} exception.
223    * <p>
224    * This method is very reminiscent of Smalltalk's well-known
225    * <tt>doesNotUnderstand:</tt> and of Ruby's <tt>method_missing</tt> methods.
226    * There are, however, two important differences:
227    * <ul>
228    *  <li> <tt>doesNotUnderstand</tt> is a <b>meta</b>-level operation in AmbientTalk.
229    *  It is an operation defined on mirrors, not on regular objects.
230    *  <li> <tt>doesNotUnderstand</tt> in AmbientTalk relates to <i>attribute
231    *  selection</i>, not to <i>method invocation</i>. Hence, this operation is
232    *  more general in AmbientTalk than in Smalltalk: it intercepts both failed
233    *  method invocations as well as failed field selections. Hence, it can be used
234    *  to model "virtual" fields. This shows in the interface: this operation
235    *  does not consume the actual arguments of a failed method invocation. Moreover,
236    *  a closure should be returned which can subsequently be applied for failed invocations.
237    *  Failed selections can simply return this closure without application. Hence, arguments
238    *  should be consumed by means of currying, e.g. by making <tt>doesNotUnderstand</tt>
239    *  return a block which can then take the arguments table as its sole parameter.
240    * </ul>
241    *
242    * @param selector a symbol denoting the name of a method or field that could not be found
243    * @return by default, this operation does not return a value, but raises an exception instead.
244    * @throws edu.vub.at.exceptions.XSelectorNotFound the default reaction to a failed selection
245    */
246   public ATClosure base_doesNotUnderstand(ATSymbol selector) throws InterpreterException;
247
248   /* -----------------------------
249    * -- Object Passing protocol --
250    * ----------------------------- */
251
252   /**
253    * This behavioural meta-level operation reifies object serialization.
254    * 
255    * When an AmbientTalk object crosses actor boundaries, e.g. by means of
256    * parameter passing, as a return value or because it was explicitly
257    * exported, this meta-level operation is invoked on the object's mirror.
258    * <p>
259    * This operation allows objects to specify themselves how they should
260    * be parameter-passed during inter-actor communication. The interpreter
261    * will never pass an object to another actor directly, but instead always
262    * parameter-passes the <i>return value</i> of invoing <tt>pass()</tt> on
263    * the object's mirror.
264    * <p>
265    * Mirrors on by-copy objects implement <tt>pass</tt> as follows:
266    * <pre>def pass() { base }</pre>
267    * Mirrors on by-reference objects implement <tt>pass</tt> by returning
268    * a far reference to their base-level object.
269    * 
270    * @return the object to be parameter-passed instead of this object. For objects,
271    * the default is a far reference to themselves. For isolates, the default is
272    * to return themselves.
273    */
274	public ATObject base_pass() throws InterpreterException;
275
276   /**
277    * This behavioural meta-level operation reifies object deserialization.
278    * 
279    * When an AmbientTalk object has just crossed an actor boundary (e.g.
280    * because of inter-actor message sending) this meta-level operation
281    * is invoked on the object's mirror.
282    * <p>
283    * This meta-level operation gives objects a chance to tell the interpreter
284    * which object they actually represent, because the object retained
285    * after parameter passing is the return value of the <tt>resolve</tt>
286    * operation.
287    * <p>
288    * Mirrors on by-copy objects, like isolates, implement <tt>resolve</tt> as follows:
289    * <pre>def resolve() { base }</pre>
290    * In other words, by-copy objects represent themselves. By-reference objects
291    * are paremeter passed as far references. Mirrors on far references implement
292    * <tt>resolve</tt> by trying to resolve the far reference into a local, regular
293    * object reference (which is possible if the object they point to is located
294    * in the actor in which they just arrived). If it is not possible to resolve
295    * a far reference into a local object, the far reference remains a far reference.
296    * <p>
297    * Note that for isolates, this operation also ensures that the isolate's
298    * lexical scope is rebound to the lexical root of the recipient actor.
299    *  
300    * @return the object represented by this object
301    * @throws XObjectOffline if a far reference to a local object can no longer be resolved
302    * because the object has been taken offline 
303    */
304	public ATObject base_resolve() throws InterpreterException;
305   
306   /* ------------------------------------------
307    * -- Slot accessing and mutating protocol --
308    * ------------------------------------------ */
309   
310   /**
311    * This meta-level operation reifies first-class field or method selection. Hence, the
312    * base-level evaluation of <code>o.&x</code> is interpreted at the meta-level as:
313    * <pre>(reflect: o).select(o, `x)</pre>
314    * 
315    * The selector lookup follows the same search rules as those for <tt>invoke</tt>.
316    * That is: first an object's local fields and method dictionary are searched,
317    * and only then the object's <i>dynamic parent</i>.
318    * <p>
319    * The <tt>select</tt> operation can be used to both select fields or methods from
320    * an object. When the selector is bound to a method, the return value of
321    * <tt>select</tt> is a closure that wraps the found method in the object in which
322    * the method was found. This ensures that the method retains its context information,
323    * such as the lexical scope in which it was defined and the value of <tt>self</tt>, which
324    * will be bound to the original receiver, i.e. the first argument of <tt>select</tt>.
325    * <p>
326    * If the selector matches a field, an accessor is returned. If the selector ends with
327    * <tt>:=</tt>, a mutator is returned instead. An accessor is a nullary closure which upon
328    * application yields the field's value. A mutator is a unary closure which upon
329    * application assigns the field to the specified value.
330	 * Even for fields already bound to a closure, selecting the field returns an accessor
331	 * closure, not the bound closure itself.
332    *
333    * @see #base_doesNotUnderstand(ATSymbol) for what happens if the selector is not found.
334    *
335    * @param receiver the dynamic receiver of the selection. If the result of the selection is
336    * a method, the closure wrapping the method will bind <tt>self</tt> to this object.
337    * @param selector a symbol denoting the name of the field or method to select.
338    * @return if selector is bound to a field, an accessor or mutator for the field; otherwise if
339    * the selector is bound to a method, a closure wrapping the method.
340    */
341   public ATClosure base_select(ATObject receiver, ATSymbol selector) throws InterpreterException;
342
343   /**
344    * This meta-level operation reifies field definition. Hence, the base-level
345    * code <code>def x := v</code> evaluated in a lexical scope <tt>lex</tt>
346    * is interpreted at the meta-level as:
347    * <pre>(reflect: lex).defineField(`x, v)</pre>
348    * 
349    * Invoking this meta-level operation on an object's mirror adds a new field
350    * to that object. An object cannot contain two or more fields with the
351    * same name.
352    *
353    * @param name a symbol denoting the name of the new field
354    * @param value the value of the new field
355    * @return nil
356    * @throws edu.vub.at.exceptions.XDuplicateSlot if the object already has a
357    * local field with the given name
358    */
359   public ATNil base_defineField(ATSymbol name, ATObject value) throws InterpreterException;
360
361   /* -----------------------------------------
362     * -- Cloning and instantiation protocol --
363     * ---------------------------------------- */
364
365   /**
366    * This meta-level operation reifies the act of cloning the base-level object.
367    * Hence, the code <code>clone: o</code> is interpreted at the meta-level as
368    * <pre>(reflect: o).clone()</pre>
369    * 
370    * AmbientTalk's default cloning semantics are based on shallow copying.
371    * A cloned object has copies of the original object's fields, but the values
372    * of the fields are shared between the clones. A clone has the same methods
373    * as the original object. Methods added at a later stage to the original
374    * will not affect the clone's methods and vice versa. This means that each
375    * objects has its own independent fields and methods.
376    * <p>
377    * If the cloned AmbientTalk object contains programmer-defined field objects,
378    * each of these fields is re-instantiated with the clone as a parameter. The
379    * clone is intialized with the re-instantiated fields rather than with the
380    * fields of the original object. This property helps to ensure that each
381    * object has its own independent fields.
382    * <p>
383    * If the object has a <i>shares-a</i> relationship with its parent, the object
384    * and its clone will <b>share</b> the same parent object. Shares-a relationships
385    * are the default in AmbientTalk, and they match with the semantics of
386    * shallow copying: the dynamic parent of an object is a regular field, hence
387    * its contents is shallow-copied.
388    * <p>
389    * If the object has an <i>is-a</i> relationship with its parent object, a
390    * clone of the object will receive a clone of the parent object as its parent.
391    * Hence, is-a relationships "override" the default shallow copying semantics
392    * and recursively clone the parent of an object up to a shares-a relationship.
393    * <p>
394    * If a mirage is cloned, its mirror is automatically re-instantiated with
395    * the new mirage, to ensure that each mirage has its independent mirror.
396    * @return a clone of the mirror's <tt>base</tt> object
397    */
398	public ATObject base_clone() throws InterpreterException;
399
400   /**
401    * This meta-level operation reifies instance creation. The default
402    * implementation of an AmbientTalk object's <tt>new</tt> method is:
403    * <pre>def new(@initargs) { (reflect: self).newInstance(initargs) }</pre>
404    * 
405    * Creating a new instance of an object is a combination of:
406    * <ul>
407    *  <li>creating a clone of the object
408    *  <li>initializing the clone by invoking its <tt>init</tt> method
409    * </ul>
410    * 
411    * The default implementation is:
412    * <pre>def newInstance(initargs) {
413    *  def instance := self.clone();
414    *  instance.init(@initargs);
415    *  instance;
416    *}
417    * </pre>
418    * 
419    * Instance creation in AmbientTalk is designed to mimick class instantiation
420    * in a class-based language. Instantiating a class <tt>c</tt> requires <i>allocating</i>
421    * a new instance <tt>i</tt> and then invoking the <i>constructor</i> on that
422    * new instance. In AmbientTalk, class allocation is replaced by object
423    * <i>cloning</i>. The benefit is that an instantiated object its variables are
424    * already initialized to useful values, being those of the object from which
425    * it is instantiated. The <tt>init</tt> method plays the role of "constructor"
426    * in AmbientTalk.
427    *
428    * @param initargs a table denoting the actual arguments to be passed to
429    * the <tt>init</tt> method
430    * @return the new instance
431    */
432   public ATObject base_newInstance(ATTable initargs) throws InterpreterException;
433
434   /* ---------------------------------
435     * -- Structural Access Protocol  --
436     * --------------------------------- */
437
438   /**
439    * This structural meta-level operation adds a field object to the receiver mirror's
440    * base object. An object cannot contain two or more fields with the same name.
441    * 
442    * Note that the field object passed as an argument serves as a <i>prototype</i>
443    * object: the actual field object added is an <i>instance</i> of the passed field object.
444    * A field object should always have an <tt>init</tt> method that takes as an argument
445    * the new host object to which it is added. This is often useful, as the behaviour
446    * of a field may depend on the object in which it resides. Because <tt>addField</tt>
447    * creates a new instance of the field, this gives the field object a chance to
448    * properly refer to its new host. 
449    * <p>
450    * As an example, here is how to add a read-only field <tt>foo</tt> initialized
451    * to <tt>5</tt> to an object <tt>obj</tt>:
452    * <pre>def makeConstantField(nam, val) {
453    *   object: {
454    *     def new(newHost) { self }; // singleton pattern
455    *     def name := nam;
456    *     def readField() { val };
457    *     def writeField(newVal) { nil };
458    *   }
459    * };
460    * (reflect: obj).addField(makeConstantField(`foo, 5));
461    * </pre>
462    * 
463    * @param field the prototype field object whose instance should be added
464    * to the receiver's base object
465    * @return nil
466    * @throws XDuplicateSlot if the base object already has a field with the
467    * same name as the new field
468    */
469   public ATNil base_addField(ATField field) throws InterpreterException;
470
471   /**
472    * This structural meta-level operation adds a method to the receiver
473    * mirror's base object. An object cannot contain two or more methods
474    * with the same name.
475    * 
476    * @param method a method object to add to the receiver's base object's
477    * method dictionary.
478    * @return nil
479    * @throws XDuplicateSlot if a method with the new method's selector already
480    * exists in the base object.
481    */
482   public ATNil base_addMethod(ATMethod method) throws InterpreterException;
483
484   /**
485    * This structural meta-level operation allows the metaprogrammer to reify a
486    * field of the receiver mirror's base object. Hence, unlike <tt>select</tt>
487    * and <tt>lookup</tt>, <tt>grabField</tt> returns a <i>field object</i> rather
488    * than the <i>value</i> bound to the field. For example: one could express
489    * <code>obj.super := val</code> at the meta-level as:
490    * 
491    * <pre>
492    * def superField := (reflect: obj).grabField(`super);
493    * superField.writeField(val);
494    * </pre>
495    *
496    * Another important difference between <tt>select</tt>, <tt>lookup</tt> and
497    * <tt>grabField</tt> is that <tt>grabField</tt> only considers the fields
498    * <i>local</i> to the receiver's base object. Fields of lexical or dynamic
499    * parent objects are <i>not</i> considered.
500    *
501    * @param selector a symbol representing the name of the field to select.
502    * @return a mirror on this object's field slot.
503    * @throws XUndefinedSlot if the field cannot be found within the receiver's
504    * base object.
505    */
506   public ATField base_grabField(ATSymbol selector) throws InterpreterException;
507
508   /**
509    * This structural meta-level operation allows the metaprogrammer to
510    * reify a method defined on the receiver mirror's base object. Note that,
511    * unlike the <tt>select</tt> or <tt>lookup</tt> operations, <tt>grabMethod</tt>
512    * returns the bare method object, i.e. <i>not</i> a closure wrapping the method.
513    * <p>
514    * Also, unlike <tt>select</tt> and <tt>lookup</tt>, <tt>grabField</tt> only
515    * considers the locally defined methods of an object, methods of lexical or
516    * dynamic parent objects are <i>not</i> considered.
517    *
518    * @param selector a symbol representing the name of the method to grab from
519    * the receiver's base object.
520    * @return the bare method object bound to the given selector.
521    * @throws XSelectorNotFound if the method object cannot be found within the
522    * receiver's base object.
523    */
524   public ATMethod base_grabMethod(ATSymbol selector) throws InterpreterException;
525
526   /**
527    * This structural meta-level operation allows access to all of the
528    * fields defined on the receiver mirror's base object. Note that
529    * this method only returns the base object's <i>locally</i> defined
530    * fields. Fields from parent objects are not returned.
531    * 
532    * @see ATMirrorRoot#base_grabField(ATSymbol) for details about the returned
533    * field objects. 
534    * @return a table of field objects (of type {@link ATField}).
535    */
536   public ATTable base_listFields() throws InterpreterException;
537
538   /**
539    * This structural meta-level operation allows access to all of the
540    * methods defined on the receiver mirror's base object. Note that
541    * this method only returns the base object's <i>locally</i> defined
542    * methods. Methods from parent objects are not returned.
543    * 
544    * @see ATMirrorRoot#base_grabMethod(ATSymbol) for details about the returned
545    * method objects.
546    * @return a table of method objects (of type {@link ATMethod}).
547    */
548   public ATTable base_listMethods() throws InterpreterException;
549
550   /**
551    * This structural meta-level operation adds a slot object to the receiver mirror's
552    * base object. An object cannot contain two or more slots with the same name.
553    * 
554    * A slot is either a method or a closure. A closure serves to encapsulate access to
555    * or mutation of a field.
556    * 
557    * Care must be taken with closures when the object to which they are added is
558    * cloned or instantiated: the closure will be shared between clones!
559    * <p>
560    * As an example, here is how to add a read-only field <tt>foo</tt> initialized
561    * to <tt>5</tt> to an object <tt>obj</tt>:
562    * <pre>
563    * def [accessor,mutator] := /.at.lang.values.createFieldSlot(`foo, 5);
564    * (reflect: obj).addSlot(accessor);
565    * </pre>
566    * 
567    * @param slot the method representing the slot to be added
568    * to the receiver's base object
569    * @return nil
570    * @throws XDuplicateSlot if the base object already has a slot with the
571    * same name as the new slot
572    */
573   public ATNil base_addSlot(ATMethod slot) throws InterpreterException;
574
575   /**
576    * This structural meta-level operation allows the metaprogrammer to reify a
577    * slot of the receiver mirror's base object. Hence, unlike <tt>select</tt>
578    * and <tt>lookup</tt>, <tt>grabSlot</tt> returns a <i>slot object</i> rather
579    * than the <i>value</i> bound to the slot. For example: one could express
580    * <code>obj.super := val</code> at the meta-level as:
581    * 
582    * <pre>
583    * def superMutator := (reflect: obj).grabSlot(`super:=);
584    * superMutator(val);
585    * </pre>
586    *
587    * Another important difference between <tt>select</tt>, <tt>lookup</tt> and
588    * <tt>grabSlot</tt> is that <tt>grabSlot</tt> only considers the slots
589    * <i>local</i> to the receiver's base object. Slots of lexical or dynamic
590    * parent objects are <i>not</i> considered.
591    *
592    * @param selector a symbol representing the name of the slot to select.
593    * @return a method representing the selected slot.
594    * @throws XUndefinedSlot if the field cannot be found within the receiver's
595    * base object.
596    */
597   public ATMethod base_grabSlot(ATSymbol selector) throws InterpreterException;
598
599   /**
600    * This structural meta-level operation allows access to all of the
601    * slots defined on the receiver mirror's base object. Note that
602    * this method only returns the base object's <i>locally</i> defined
603    * slots. Slots from parent objects are not returned.
604    * 
605    * @see ATMirrorRoot#base_grabSlot(ATSymbol) for details about the returned
606    * slot objects. 
607    * @return a table of slot objects (of type {@link ATMethod}).
608    */
609   public ATTable base_listSlots() throws InterpreterException;
610   
611   /**
612    * This structural meta-level operation removes a slot from the
613    * object. Note that this method only removes slots that are
614    * <i>locally</i> defined in the object.
615    * 
616    * @param selector the name of the slot to remove
617    * @return the value to which the slot was previously bound
618    * (e.g. a value or a method object)
619    * @throws XSelectorNotFound if no slot with the given name is found in the object
620    */
621   public ATObject base_removeSlot(ATSymbol selector) throws InterpreterException;
622   
623   /**
624    * This structural meta-level operation returns whether or not
625    * the receiver mirror's base object is an <i>extension</i> of its
626    * parent object.
627    * <p>
628    * In AmbientTalk, all objects are part of a dynamic parent delegation chain:
629    * each object has a <tt>super</tt> field that denotes the object to which to
630    * delegate messages the object cannot understand itself. There are, however,
631    * two kinds of delegation links:
632    * <ul>
633    *  <li><b>IS-A</b> links: this kind of link denotes that the child object is
634    *  a true extension of its parent, and cannot meaningfully exist without the
635    *  parent's state. When the child is cloned, its parent will be cloned as well.
636    *  <li><b>SHARES-A</b> links: this kind of link denotes that the child object
637    *  simply delegates to its parent for purposes of sharing or code reuse. The
638    *  child can meaningfully exist without the parent's state. When the child is
639    *  cloned, the clone will delegate to the same parent.
640    * </ul>
641    *
642    * Examples:
643    * <pre>(reflect: (extend: parent with: code)).isExtensionOfParent() => true
644    *(reflect: (share: parent with: code)).isExtensionOfParent() => false
645    * </pre>
646    * 
647    * Note that accessing the dynamic parent itself is not a meta-level operation,
648    * the dynamic parent can simply be accessed from the base level by performing
649    * <code>obj.super</code>.
650    * 
651    * @return whether the base object extends its parent object via an
652    * <b>IS-A</b> link or not.
653    */
654   public ATBoolean base_isExtensionOfParent() throws InterpreterException;
655   
656   /* ------------------------------------------
657     * -- Abstract Grammar evaluation protocol --
658     * ------------------------------------------ */
659
660   /**
661    * This behavioural meta-level operation reifies the evaluation of
662    * abstract grammar objects into values. For objects, this operation
663    * returns the base object itself, signifying that the evaluation
664    * function defined on objects is the identity function. In other words,
665    * objects are <i>self-evaluating</i>. Parse tree objects (first-class
666    * abstract grammar elements), however, have dedicated evaluation
667    * functions. For example, evaluating <code>x</code> is equivalent to
668    * evaluating <code>(reflect: `x).eval(ctx)</code> where <tt>ctx</tt>
669    * is a reification of the current evaluation context.
670    * 
671    * @param ctx a context object that stores the current lexical scope and
672    * the current value of <tt>self</tt>
673    * @return the value of the abstract grammar element denoted by this mirror's
674    * base object.
675    * @throws XIllegalUnquote if an unquote abstract grammar element is evaluated. Such
676    * abstract grammar elements should only be encountered in a quoted parse tree.
677    */
678   public ATObject base_eval(ATContext ctx) throws InterpreterException;
679
680   /**
681    * This behavioural meta-level operation reifies the quotation of
682    * abstract grammar elements. Regular objects simply return themselves
683    * upon quotation. When an abstract grammar element is quoted, rather
684    * than tree-recursively invoking <tt>eval</tt> on the parse trees,
685    * <tt>quote</tt> is tree-recursively invoked. When encountering
686    * an unquote, <tt>eval</tt> is again invoked on the unquoted subtree,
687    * with the context passed as an argument to <tt>quote</tt>.
688    * 
689    * @param ctx a context object passed on to be used in subsequent evaluations.
690    * @throws XIllegalQuote exception whenever an unquote-splice unquotation is discovered
691    * in an Abstract Grammar node where the resulting table cannot be spliced.
692    */
693   public ATObject base_quote(ATContext ctx) throws InterpreterException;
694
695   /**
696    * This behavioural meta-level operation reifies the act of printing
697    * the base object in the read-eval-print loop. This operation may be
698    * overridden by mirrors to customise the printed representation of
699    * their base object.
700    * 
701    * @return a text value denoting a human-readable representation of the object.
702    */
703   public NATText base_print() throws InterpreterException;
704
705   /* ----------------------------------
706    * -- Object Relational Comparison --
707    * ---------------------------------- */
708   
709   /**
710    * This meta-level operation determines whether this mirror's base object
711    * is related to the parameter object by a combination of cloning and
712    * extension operators. The default implementation is:
713    * 
714    * <pre>def isRelatedTo(object) {
715    *  self.isCloneOf(object).or: { (reflect: base.super).isRelatedTo(object) }
716    *}</pre>
717    * 
718    * @param object the object to compare this mirror's base object to
719    * @return true if the given object is a clone of the base object or a clone
720    * of the base object's parents.
721    */
722   public ATBoolean base_isRelatedTo(ATObject object) throws InterpreterException;
723   
724   /**
725    * This meta-level operation determines whether this mirror's base object
726    * is a clone of the parameter object. The <i>is-clone-of</i> relation is transitive,
727    * so if <tt>martin</tt> is a clone of <tt>sally</tt> and <tt>sally</tt> is a clone of
728    * <tt>dolly</tt>, then <tt>martin</tt> is a clone of <tt>dolly</tt> as well.
729    * The relation is reflexive: <tt>dolly</tt> is a clone of itself.
730    * The relation is symmetric: <tt>dolly</tt> is also a clone of <tt>sally</tt>.
731    * 
732    * @param other the object to check the is-clone-of relationship with.
733    * @return true if the base object and the parameter object are clones (i.e. one
734    * was created by cloning the other), false otherwise.
735    */
736   public ATBoolean base_isCloneOf(ATObject other) throws InterpreterException;
737
738   /* ---------------------------------
739    * -- Type Testing and Querying --
740    * --------------------------------- */
741   
742   /**
743    * Tests whether the receiver mirror's base object is tagged as a particular type.
744    * 
745    * The default implementation first compares the object's local type tags to the given type
746    * by means of the {@link ATTypeTag#base_isSubtypeOf(ATTypeTag)} method. If no local type
747    * is found, the test is applied recursively on this object's dynamic parent. In code:
748    * <pre>def isTaggedAs(type) {
749    *  (nil != (self.tagsOf: object).find: { |localType|
750	 *    localType.isSubtypeOf(type)
751	 *  }).or: { (reflect: base.super).isTaggedAs(type) }
752	 * };
753    * </pre>
754    * 
755    * The primitive method <tt>is: obj taggedAs: type</tt> is defined in terms of this
756    * method:
757    * <pre>
758    * def is: obj taggedAs: type {
759    *  (reflect: obj).isTaggedAs(type)
760    *};
761    * </pre>
762    * 
763    * @param type the type tag object to check for
764    * @return true if this mirror's base object or one of its parent objects is tagged
765    * with a subtype of the given type, false otherwise.
766    */
767   public ATBoolean base_isTaggedAs(ATTypeTag type) throws InterpreterException;
768   
769   /**
770    * Returns all of the local type tags of this object. The primitive method
771    * <tt>tagsOf: obj</tt> is defined in terms of this method:
772    * 
773    * <pre>
774    * def tagsOf: obj {
775    *  (reflect: obj).typeTags
776    *};
777    * </pre>
778    * 
779    * @return a table of the type tags that were attached directly to this mirror's base
780    * object. The type tags of its parent objects are not returned.
781    */
782	public ATTable base_typeTags() throws InterpreterException;
783
784}