/interpreter/tags/at2dist170907/src/edu/vub/at/objects/ATObject.java

http://ambienttalk.googlecode.com/ · Java · 967 lines · 67 code · 57 blank · 843 comment · 0 complexity · 330b16a5f6e137a46e0eeeb390908c2e 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. */
  28. package edu.vub.at.objects;
  29. import edu.vub.at.actors.ATAsyncMessage;
  30. import edu.vub.at.exceptions.InterpreterException;
  31. import edu.vub.at.exceptions.XArityMismatch;
  32. import edu.vub.at.exceptions.XDuplicateSlot;
  33. import edu.vub.at.exceptions.XIllegalQuote;
  34. import edu.vub.at.exceptions.XIllegalUnquote;
  35. import edu.vub.at.exceptions.XObjectOffline;
  36. import edu.vub.at.exceptions.XSelectorNotFound;
  37. import edu.vub.at.exceptions.XUnassignableField;
  38. import edu.vub.at.exceptions.XUndefinedSlot;
  39. import edu.vub.at.objects.coercion.ATConversions;
  40. import edu.vub.at.objects.grammar.ATAssignmentSymbol;
  41. import edu.vub.at.objects.grammar.ATSymbol;
  42. import edu.vub.at.objects.mirrors.NATMirage;
  43. import edu.vub.at.objects.mirrors.OBJMirrorRoot;
  44. import edu.vub.at.objects.natives.NATCallframe;
  45. import edu.vub.at.objects.natives.NATObject;
  46. import edu.vub.at.objects.natives.NATText;
  47. import edu.vub.at.objects.natives.NativeATObject;
  48. import edu.vub.at.objects.symbiosis.JavaClass;
  49. import edu.vub.at.objects.symbiosis.JavaObject;
  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 NativeATObject}: 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 NativeATObject} 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. */
  93. public interface ATObject extends ATConversions {
  94. /* ------------------------------
  95. * -- Message Sending Protocol --
  96. * ------------------------------ */
  97. /**
  98. * This behavioural meta-level operation reifies the act of sending
  99. * an asynchronous message.
  100. *
  101. * When the base-level AmbientTalk code <code>rcv<-m()</code> is
  102. * evaluated in the context of an object <tt>o</tt>, an asynchronous message
  103. * <code><-m()</code> is first created by the current actor mirror.
  104. * Subsequently, this message needs to be sent to the receiver. This
  105. * meta-level operation is reified by this method, as if by invoking:
  106. * <pre>(reflect: o).send(message)</pre>
  107. * The default behaviour is to access the current actor's mirror and to
  108. * ask the actor to send the message in this object's stead by invoking
  109. * <pre>actor.send(message)</pre>
  110. * @param receiver the object designated to receive the asynchronous message
  111. * @param message the asynchronous message to be sent by this object
  112. *
  113. * @return the result of message sending, which will be the value of an
  114. * asynchronous message send expression.
  115. */
  116. public ATObject meta_send(ATObject receiver, ATAsyncMessage message) throws InterpreterException;
  117. /**
  118. * This behavioural meta-level operation reifies the act of receiving
  119. * an asynchronous message.
  120. *
  121. * When an AmbientTalk object receives a message that was sent to it
  122. * asynchronously, the message is delivered to the object's mirror by
  123. * means of this meta-level operation.
  124. * <p>
  125. * The default behaviour of a mirror in response to the reception of a
  126. * message <tt>msg</tt> is to invoke:
  127. * <pre>msg.process(self)</pre>
  128. * In turn, the default message processing behaviour is to invoke
  129. * the method corresponding to the message's selector on this object.
  130. * Hence, usually a <tt>receive</tt> operation is simply translated into
  131. * a <tt>invoke</tt> operation. The reason for having a separate <tt>receive</tt>
  132. * operation is that this enables the AmbientTalk meta-level programmer to
  133. * distinguish between synchronously and asynchronously received messages.
  134. * @param message the message that was asynchronously sent to this object
  135. * @return by default, the value of invoking the method corresponding to the message
  136. */
  137. public ATObject meta_receive(ATAsyncMessage message) throws InterpreterException;
  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 #meta_doesNotUnderstand(ATSymbol) for what happens if the selector
  164. * is not found.
  165. *
  166. * @param receiver the object to which <tt>self</tt> is bound during execution
  167. * of the method
  168. * @param selector a symbol denoting the name of the method, accessor or mutator to be invoked
  169. * @param arguments the table of actual arguments to be passed to the method
  170. * @return by default, the object returned from the invoked method
  171. */
  172. public ATObject meta_invoke(ATObject receiver, ATSymbol selector, ATTable arguments) throws InterpreterException;
  173. /**
  174. * This meta-level operation reifies "field selection".
  175. * In other words, the base-level code
  176. * <code>o.m</code>
  177. * is interpreted at the meta-level as:
  178. * <code>(reflect: o).invokeField(o, `m)</code>
  179. *
  180. * This meta-level operation is nearly identical to {@link #meta_invoke(ATObject, ATSymbol, ATTable)} with one
  181. * important difference. When the selector is bound to a field storing a closure, this meta-level operation
  182. * does <b>not</b> auto-apply the closure, but returns the closure instead.
  183. *
  184. * For all other cases, the following equality holds:
  185. * <code>o.m == o.m()</code>
  186. * or, at the meta-level:
  187. * <code>(reflect: o).invokeField(o, `m) == (reflect: o).invoke(o, `m, [])</code>
  188. *
  189. * This effectively means that for client objects, it should not matter whether
  190. * a property is implemented as a field or as a pair of accessor/mutator methods.
  191. *
  192. * @param receiver the base-level object from which the 'field' should be selected.
  193. * @param selector a symbol denoting the name of the method, accessor or mutator to be invoked
  194. * @return the value of a field, or the return value of a nullary method.
  195. */
  196. public ATObject meta_invokeField(ATObject receiver, ATSymbol selector) throws InterpreterException;
  197. /**
  198. * This meta-level method is used to determine whether an object has a
  199. * field or method corresponding to the given selector, without actually invoking
  200. * or selecting any value associated with that selector.
  201. * <p>
  202. * The lookup process is the same as that for the <tt>invoke</tt> operation (i.e.
  203. * not only the object's own fields and methods are searched, but also those of
  204. * its dynamic parents).
  205. *
  206. * @param selector a symbol denoting the name of a field (accessor or mutator) or method
  207. * @return a boolean denoting whether the object responds to <tt>o.selector</tt>
  208. */
  209. public ATBoolean meta_respondsTo(ATSymbol selector) throws InterpreterException;
  210. /**
  211. * This behavioural meta-level operation reifies a failed dynamic method or field lookup.
  212. *
  213. * When method invocation or field selection fails to find the selector in
  214. * the dynamic parent chain of an object, rather than immediately raising an
  215. * {@link XSelectorNotFound} exception, the mirror of the original receiver
  216. * of the method invocation or field selection is asked to handle failed lookup.
  217. * <p>
  218. * The default behaviour of <tt>doesNotUnderstand</tt> is to raise an
  219. * {@link XSelectorNotFound} exception.
  220. * <p>
  221. * This method is very reminiscent of Smalltalk's well-known
  222. * <tt>doesNotUnderstand:</tt> and of Ruby's <tt>method_missing</tt> methods.
  223. * There are, however, two important differences:
  224. * <ul>
  225. * <li> <tt>doesNotUnderstand</tt> is a <b>meta</b>-level operation in AmbientTalk.
  226. * It is an operation defined on mirrors, not on regular objects.
  227. * <li> <tt>doesNotUnderstand</tt> in AmbientTalk relates to <i>attribute
  228. * selection</i>, not to <i>method invocation</i>. Hence, this operation is
  229. * more general in AmbientTalk than in Smalltalk: it intercepts both failed
  230. * method invocations as well as failed field selections. Hence, it can be used
  231. * to model "virtual" fields. This shows in the interface: this operation
  232. * does not consume the actual arguments of a failed method invocation. Moreover,
  233. * a closure should be returned which can subsequently be applied for failed invocations.
  234. * Failed selections can simply return this closure without application. Hence, arguments
  235. * should be consumed by means of currying, e.g. by making <tt>doesNotUnderstand</tt>
  236. * return a block which can then take the arguments table as its sole parameter.
  237. * </ul>
  238. *
  239. * @param selector a symbol denoting the name of a method or field that could not be found
  240. * @return by default, this operation does not return a value, but raises an exception instead.
  241. * @throws edu.vub.at.exceptions.XSelectorNotFound the default reaction to a failed selection
  242. */
  243. public ATClosure meta_doesNotUnderstand(ATSymbol selector) throws InterpreterException;
  244. /* -----------------------------
  245. * -- Object Passing protocol --
  246. * ----------------------------- */
  247. /**
  248. * This behavioural meta-level operation reifies object serialization.
  249. *
  250. * When an AmbientTalk object crosses actor boundaries, e.g. by means of
  251. * parameter passing, as a return value or because it was explicitly
  252. * exported, this meta-level operation is invoked on the object's mirror.
  253. * <p>
  254. * This operation allows objects to specify themselves how they should
  255. * be parameter-passed during inter-actor communication. The interpreter
  256. * will never pass an object to another actor directly, but instead always
  257. * parameter-passes the <i>return value</i> of invoing <tt>pass()</tt> on
  258. * the object's mirror.
  259. * <p>
  260. * Mirrors on by-copy objects implement <tt>pass</tt> as follows:
  261. * <pre>def pass() { base }</pre>
  262. * Mirrors on by-reference objects implement <tt>pass</tt> by returning
  263. * a far reference to their base-level object.
  264. *
  265. * @return the object to be parameter-passed instead of this object. For objects,
  266. * the default is a far reference to themselves. For isolates, the default is
  267. * to return themselves.
  268. */
  269. public ATObject meta_pass() throws InterpreterException;
  270. /**
  271. * This behavioural meta-level operation reifies object deserialization.
  272. *
  273. * When an AmbientTalk object has just crossed an actor boundary (e.g.
  274. * because of inter-actor message sending) this meta-level operation
  275. * is invoked on the object's mirror.
  276. * <p>
  277. * This meta-level operation gives objects a chance to tell the interpreter
  278. * which object they actually represent, because the object retained
  279. * after parameter passing is the return value of the <tt>resolve</tt>
  280. * operation.
  281. * <p>
  282. * Mirrors on by-copy objects, like isolates, implement <tt>resolve</tt> as follows:
  283. * <pre>def resolve() { base }</pre>
  284. * In other words, by-copy objects represent themselves. By-reference objects
  285. * are paremeter passed as far references. Mirrors on far references implement
  286. * <tt>resolve</tt> by trying to resolve the far reference into a local, regular
  287. * object reference (which is possible if the object they point to is located
  288. * in the actor in which they just arrived). If it is not possible to resolve
  289. * a far reference into a local object, the far reference remains a far reference.
  290. * <p>
  291. * Note that for isolates, this operation also ensures that the isolate's
  292. * lexical scope is rebound to the lexical root of the recipient actor.
  293. *
  294. * @return the object represented by this object
  295. * @throws XObjectOffline if a far reference to a local object can no longer be resolved
  296. * because the object has been taken offline
  297. */
  298. public ATObject meta_resolve() throws InterpreterException;
  299. /* ------------------------------------------
  300. * -- Slot accessing and mutating protocol --
  301. * ------------------------------------------ */
  302. /**
  303. * This meta-level operation reifies first-class field or method selection. Hence, the
  304. * base-level evaluation of <code>o.&x</code> is interpreted at the meta-level as:
  305. * <pre>(reflect: o).select(o, `x)</pre>
  306. *
  307. * The selector lookup follows the same search rules as those for <tt>invoke</tt>.
  308. * That is: first an object's local fields and method dictionary are searched,
  309. * and only then the object's <i>dynamic parent</i>.
  310. * <p>
  311. * The <tt>select</tt> operation can be used to both select fields or methods from
  312. * an object. When the selector is bound to a method, the return value of
  313. * <tt>select</tt> is a closure that wraps the found method in the object in which
  314. * the method was found. This ensures that the method retains its context information,
  315. * such as the lexical scope in which it was defined and the value of <tt>self</tt>, which
  316. * will be bound to the original receiver, i.e. the first argument of <tt>select</tt>.
  317. * <p>
  318. * If the selector matches a field, an accessor is returned. If the selector ends with
  319. * <tt>:=</tt>, a mutator is returned instead. An accessor is a nullary closure which upon
  320. * application yields the field's value. A mutator is a unary closure which upon
  321. * application assigns the field to the specified value.
  322. * Even for fields already bound to a closure, selecting the field returns an accessor
  323. * closure, not the bound closure itself.
  324. *
  325. * @see #meta_doesNotUnderstand(ATSymbol) for what happens if the selector is not found.
  326. *
  327. * @param receiver the dynamic receiver of the selection. If the result of the selection is
  328. * a method, the closure wrapping the method will bind <tt>self</tt> to this object.
  329. * @param selector a symbol denoting the name of the field or method to select.
  330. * @return if selector is bound to a field, an accessor or mutator for the field; otherwise if
  331. * the selector is bound to a method, a closure wrapping the method.
  332. */
  333. public ATClosure meta_select(ATObject receiver, ATSymbol selector) throws InterpreterException;
  334. /**
  335. * This meta-level operation reifies field definition. Hence, the base-level
  336. * code <code>def x := v</code> evaluated in a lexical scope <tt>lex</tt>
  337. * is interpreted at the meta-level as:
  338. * <pre>(reflect: lex).defineField(`x, v)</pre>
  339. *
  340. * Invoking this meta-level operation on an object's mirror adds a new field
  341. * to that object. An object cannot contain two or more fields with the
  342. * same name.
  343. *
  344. * @param name a symbol denoting the name of the new field
  345. * @param value the value of the new field
  346. * @return nil
  347. * @throws edu.vub.at.exceptions.XDuplicateSlot if the object already has a
  348. * local field with the given name
  349. */
  350. public ATNil meta_defineField(ATSymbol name, ATObject value) throws InterpreterException;
  351. /* -----------------------------------------
  352. * -- Cloning and instantiation protocol --
  353. * ---------------------------------------- */
  354. /**
  355. * This meta-level operation reifies the act of cloning the base-level object.
  356. * Hence, the code <code>clone: o</code> is interpreted at the meta-level as
  357. * <pre>(reflect: o).clone()</pre>
  358. *
  359. * AmbientTalk's default cloning semantics are based on shallow copying.
  360. * A cloned object has copies of the original object's fields, but the values
  361. * of the fields are shared between the clones. A clone has the same methods
  362. * as the original object. Methods added at a later stage to the original
  363. * will not affect the clone's methods and vice versa. This means that each
  364. * objects has its own independent fields and methods.
  365. * <p>
  366. * If the cloned AmbientTalk object contains programmer-defined field objects,
  367. * each of these fields is re-instantiated with the clone as a parameter. The
  368. * clone is intialized with the re-instantiated fields rather than with the
  369. * fields of the original object. This property helps to ensure that each
  370. * object has its own independent fields.
  371. * <p>
  372. * If the object has a <i>shares-a</i> relationship with its parent, the object
  373. * and its clone will <b>share</b> the same parent object. Shares-a relationships
  374. * are the default in AmbientTalk, and they match with the semantics of
  375. * shallow copying: the dynamic parent of an object is a regular field, hence
  376. * its contents is shallow-copied.
  377. * <p>
  378. * If the object has an <i>is-a</i> relationship with its parent object, a
  379. * clone of the object will receive a clone of the parent object as its parent.
  380. * Hence, is-a relationships "override" the default shallow copying semantics
  381. * and recursively clone the parent of an object up to a shares-a relationship.
  382. * <p>
  383. * If a mirage is cloned, its mirror is automatically re-instantiated with
  384. * the new mirage, to ensure that each mirage has its independent mirror.
  385. * @return a clone of the mirror's <tt>base</tt> object
  386. */
  387. public ATObject meta_clone() throws InterpreterException;
  388. /**
  389. * This meta-level operation reifies instance creation. The default
  390. * implementation of an AmbientTalk object's <tt>new</tt> method is:
  391. * <pre>def new(@initargs) { (reflect: self).newInstance(initargs) }</pre>
  392. *
  393. * Creating a new instance of an object is a combination of:
  394. * <ul>
  395. * <li>creating a clone of the object
  396. * <li>initializing the clone by invoking its <tt>init</tt> method
  397. * </ul>
  398. *
  399. * The default implementation is:
  400. * <pre>def newInstance(initargs) {
  401. * def instance := self.clone();
  402. * instance.init(@initargs);
  403. * instance;
  404. *}
  405. * </pre>
  406. *
  407. * Instance creation in AmbientTalk is designed to mimick class instantiation
  408. * in a class-based language. Instantiating a class <tt>c</tt> requires <i>allocating</i>
  409. * a new instance <tt>i</tt> and then invoking the <i>constructor</i> on that
  410. * new instance. In AmbientTalk, class allocation is replaced by object
  411. * <i>cloning</i>. The benefit is that an instantiated object its variables are
  412. * already initialized to useful values, being those of the object from which
  413. * it is instantiated. The <tt>init</tt> method plays the role of "constructor"
  414. * in AmbientTalk.
  415. *
  416. * @param initargs a table denoting the actual arguments to be passed to
  417. * the <tt>init</tt> method
  418. * @return the new instance
  419. */
  420. public ATObject meta_newInstance(ATTable initargs) throws InterpreterException;
  421. /* ---------------------------------
  422. * -- Structural Access Protocol --
  423. * --------------------------------- */
  424. /**
  425. * This structural meta-level operation adds a field object to the receiver mirror's
  426. * base object. An object cannot contain two or more fields with the same name.
  427. *
  428. * Note that the field object passed as an argument serves as a <i>prototype</i>
  429. * object: the actual field object added is an <i>instance</i> of the passed field object.
  430. * A field object should always have an <tt>init</tt> method that takes as an argument
  431. * the new host object to which it is added. This is often useful, as the behaviour
  432. * of a field may depend on the object in which it resides. Because <tt>addField</tt>
  433. * creates a new instance of the field, this gives the field object a chance to
  434. * properly refer to its new host.
  435. * <p>
  436. * As an example, here is how to add a read-only field <tt>foo</tt> initialized
  437. * to <tt>5</tt> to an object <tt>obj</tt>:
  438. * <pre>def makeConstantField(nam, val) {
  439. * object: {
  440. * def new(newHost) { self }; // singleton pattern
  441. * def name := nam;
  442. * def readField() { val };
  443. * def writeField(newVal) { nil };
  444. * }
  445. * };
  446. * (reflect: obj).addField(makeConstantField(`foo, 5));
  447. * </pre>
  448. *
  449. * @param field the prototype field object whose instance should be added
  450. * to the receiver's base object
  451. * @return nil
  452. * @throws XDuplicateSlot if the base object already has a field with the
  453. * same name as the new field
  454. */
  455. public ATNil meta_addField(ATField field) throws InterpreterException;
  456. /**
  457. * This structural meta-level operation adds a method to the receiver
  458. * mirror's base object. An object cannot contain two or more methods
  459. * with the same name.
  460. *
  461. * @param method a method object to add to the receiver's base object's
  462. * method dictionary.
  463. * @return nil
  464. * @throws XDuplicateSlot if a method with the new method's selector already
  465. * exists in the base object.
  466. */
  467. public ATNil meta_addMethod(ATMethod method) throws InterpreterException;
  468. /**
  469. * This structural meta-level operation allows the metaprogrammer to reify a
  470. * field of the receiver mirror's base object. Hence, unlike <tt>select</tt>
  471. * and <tt>lookup</tt>, <tt>grabField</tt> returns a <i>field object</i> rather
  472. * than the <i>value</i> bound to the field. For example: one could express
  473. * <code>obj.super := val</code> at the meta-level as:
  474. *
  475. * <pre>
  476. * def superField := (reflect: obj).grabField(`super);
  477. * superField.writeField(val);
  478. * </pre>
  479. *
  480. * Another important difference between <tt>select</tt>, <tt>lookup</tt> and
  481. * <tt>grabField</tt> is that <tt>grabField</tt> only considers the fields
  482. * <i>local</i> to the receiver's base object. Fields of lexical or dynamic
  483. * parent objects are <i>not</i> considered.
  484. *
  485. * @param selector a symbol representing the name of the field to select.
  486. * @return a mirror on this object's field slot.
  487. * @throws XUndefinedSlot if the field cannot be found within the receiver's
  488. * base object.
  489. */
  490. public ATField meta_grabField(ATSymbol selector) throws InterpreterException;
  491. /**
  492. * This structural meta-level operation allows the metaprogrammer to
  493. * reify a method defined on the receiver mirror's base object. Note that,
  494. * unlike the <tt>select</tt> or <tt>lookup</tt> operations, <tt>grabMethod</tt>
  495. * returns the bare method object, i.e. <i>not</i> a closure wrapping the method.
  496. * <p>
  497. * Also, unlike <tt>select</tt> and <tt>lookup</tt>, <tt>grabField</tt> only
  498. * considers the locally defined methods of an object, methods of lexical or
  499. * dynamic parent objects are <i>not</i> considered.
  500. *
  501. * @param selector a symbol representing the name of the method to grab from
  502. * the receiver's base object.
  503. * @return the bare method object bound to the given selector.
  504. * @throws XSelectorNotFound if the method object cannot be found within the
  505. * receiver's base object.
  506. */
  507. public ATMethod meta_grabMethod(ATSymbol selector) throws InterpreterException;
  508. /**
  509. * This structural meta-level operation allows access to all of the
  510. * fields defined on the receiver mirror's base object. Note that
  511. * this method only returns the base object's <i>locally</i> defined
  512. * fields. Fields from parent objects are not returned.
  513. *
  514. * @see ATObject#meta_grabField(ATSymbol) for details about the returned
  515. * field objects.
  516. * @return a table of field objects (of type {@link ATField}).
  517. */
  518. public ATTable meta_listFields() throws InterpreterException;
  519. /**
  520. * This structural meta-level operation allows access to all of the
  521. * methods defined on the receiver mirror's base object. Note that
  522. * this method only returns the base object's <i>locally</i> defined
  523. * methods. Methods from parent objects are not returned.
  524. *
  525. * @see ATObject#meta_grabMethod(ATSymbol) for details about the returned
  526. * method objects.
  527. * @return a table of method objects (of type {@link ATMethod}).
  528. */
  529. public ATTable meta_listMethods() throws InterpreterException;
  530. /**
  531. * This structural meta-level operation returns whether or not
  532. * the receiver mirror's base object is an <i>extension</i> of its
  533. * parent object.
  534. * <p>
  535. * In AmbientTalk, all objects are part of a dynamic parent delegation chain:
  536. * each object has a <tt>super</tt> field that denotes the object to which to
  537. * delegate messages the object cannot understand itself. There are, however,
  538. * two kinds of delegation links:
  539. * <ul>
  540. * <li><b>IS-A</b> links: this kind of link denotes that the child object is
  541. * a true extension of its parent, and cannot meaningfully exist without the
  542. * parent's state. When the child is cloned, its parent will be cloned as well.
  543. * <li><b>SHARES-A</b> links: this kind of link denotes that the child object
  544. * simply delegates to its parent for purposes of sharing or code reuse. The
  545. * child can meaningfully exist without the parent's state. When the child is
  546. * cloned, the clone will delegate to the same parent.
  547. * </ul>
  548. *
  549. * Examples:
  550. * <pre>(reflect: (extend: parent with: code)).isExtensionOfParent() => true
  551. *(reflect: (share: parent with: code)).isExtensionOfParent() => false
  552. * </pre>
  553. *
  554. * Note that accessing the dynamic parent itself is not a meta-level operation,
  555. * the dynamic parent can simply be accessed from the base level by performing
  556. * <code>obj.super</code>.
  557. *
  558. * @return whether the base object extends its parent object via an
  559. * <b>IS-A</b> link or not.
  560. */
  561. public ATBoolean meta_isExtensionOfParent() throws InterpreterException;
  562. /* ------------------------------------------
  563. * -- Abstract Grammar evaluation protocol --
  564. * ------------------------------------------ */
  565. /**
  566. * This behavioural meta-level operation reifies the evaluation of
  567. * abstract grammar objects into values. For objects, this operation
  568. * returns the base object itself, signifying that the evaluation
  569. * function defined on objects is the identity function. In other words,
  570. * objects are <i>self-evaluating</i>. Parse tree objects (first-class
  571. * abstract grammar elements), however, have dedicated evaluation
  572. * functions. For example, evaluating <code>x</code> is equivalent to
  573. * evaluating <code>(reflect: `x).eval(ctx)</code> where <tt>ctx</tt>
  574. * is a reification of the current evaluation context.
  575. *
  576. * @param ctx a context object that stores the current lexical scope and
  577. * the current value of <tt>self</tt>
  578. * @return the value of the abstract grammar element denoted by this mirror's
  579. * base object.
  580. * @throws XIllegalUnquote if an unquote abstract grammar element is evaluated. Such
  581. * abstract grammar elements should only be encountered in a quoted parse tree.
  582. */
  583. public ATObject meta_eval(ATContext ctx) throws InterpreterException;
  584. /**
  585. * This behavioural meta-level operation reifies the quotation of
  586. * abstract grammar elements. Regular objects simply return themselves
  587. * upon quotation. When an abstract grammar element is quoted, rather
  588. * than tree-recursively invoking <tt>eval</tt> on the parse trees,
  589. * <tt>quote</tt> is tree-recursively invoked. When encountering
  590. * an unquote, <tt>eval</tt> is again invoked on the unquoted subtree,
  591. * with the context passed as an argument to <tt>quote</tt>.
  592. *
  593. * @param ctx a context object passed on to be used in subsequent evaluations.
  594. * @throws XIllegalQuote exception whenever an unquote-splice unquotation is discovered
  595. * in an Abstract Grammar node where the resulting table cannot be spliced.
  596. */
  597. public ATObject meta_quote(ATContext ctx) throws InterpreterException;
  598. /**
  599. * This behavioural meta-level operation reifies the act of printing
  600. * the base object in the read-eval-print loop. This operation may be
  601. * overridden by mirrors to customise the printed representation of
  602. * their base object.
  603. *
  604. * @return a text value denoting a human-readable representation of the object.
  605. */
  606. public NATText meta_print() throws InterpreterException;
  607. /* ----------------------------------
  608. * -- Object Relational Comparison --
  609. * ---------------------------------- */
  610. /**
  611. * This meta-level operation determines whether this mirror's base object
  612. * is related to the parameter object by a combination of cloning and
  613. * extension operators. The default implementation is:
  614. *
  615. * <pre>def isRelatedTo(object) {
  616. * self.isCloneOf(object).or: { (reflect: base.super).isRelatedTo(object) }
  617. *}</pre>
  618. *
  619. * @param object the object to compare this mirror's base object to
  620. * @return true if the given object is a clone of the base object or a clone
  621. * of the base object's parents.
  622. */
  623. public ATBoolean meta_isRelatedTo(ATObject object) throws InterpreterException;
  624. /**
  625. * This meta-level operation determines whether this mirror's base object
  626. * is a clone of the parameter object. The <i>is-clone-of</i> relation is transitive,
  627. * so if <tt>martin</tt> is a clone of <tt>sally</tt> and <tt>sally</tt> is a clone of
  628. * <tt>dolly</tt>, then <tt>martin</tt> is a clone of <tt>dolly</tt> as well.
  629. * The relation is reflexive: <tt>dolly</tt> is a clone of itself.
  630. * The relation is symmetric: <tt>dolly</tt> is also a clone of <tt>sally</tt>.
  631. *
  632. * @param other the object to check the is-clone-of relationship with.
  633. * @return true if the base object and the parameter object are clones (i.e. one
  634. * was created by cloning the other), false otherwise.
  635. */
  636. public ATBoolean meta_isCloneOf(ATObject other) throws InterpreterException;
  637. /* ---------------------------------
  638. * -- Type Testing and Querying --
  639. * --------------------------------- */
  640. /**
  641. * Tests whether the receiver mirror's base object is tagged as a particular type.
  642. *
  643. * The default implementation first compares the object's local type tags to the given type
  644. * by means of the {@link ATTypeTag#base_isSubtypeOf(ATTypeTag)} method. If no local type
  645. * is found, the test is applied recursively on this object's dynamic parent. In code:
  646. * <pre>def isTaggedAs(type) {
  647. * (nil != (self.tagsOf: object).find: { |localType|
  648. * localType.isSubtypeOf(type)
  649. * }).or: { (reflect: base.super).isTaggedAs(type) }
  650. * };
  651. * </pre>
  652. *
  653. * The primitive method <tt>is: obj taggedAs: type</tt> is defined in terms of this
  654. * method:
  655. * <pre>
  656. * def is: obj taggedAs: type {
  657. * (reflect: obj).isTaggedAs(type)
  658. *};
  659. * </pre>
  660. *
  661. * @param type the type tag object to check for
  662. * @return true if this mirror's base object or one of its parent objects is tagged
  663. * with a subtype of the given type, false otherwise.
  664. */
  665. public ATBoolean meta_isTaggedAs(ATTypeTag type) throws InterpreterException;
  666. /**
  667. * Returns all of the local type tags of this object. The primitive method
  668. * <tt>tagsOf: obj</tt> is defined in terms of this method:
  669. *
  670. * <pre>
  671. * def tagsOf: obj {
  672. * (reflect: obj).typeTags
  673. *};
  674. * </pre>
  675. *
  676. * @return a table of the type tags that were attached directly to this mirror's base
  677. * object. The type tags of its parent objects are not returned.
  678. */
  679. public ATTable meta_typeTags() throws InterpreterException;
  680. /* -------------------------------
  681. * - Base Level Object interface -
  682. * ------------------------------- */
  683. /**
  684. * Bound to the dynamic parent of this object.
  685. *
  686. * The dynamic parent of an object is the object to which failed
  687. * selection or invocation requests or type tests are delegated to.
  688. *
  689. * @return the current dynamic parent of this object.
  690. */
  691. public ATObject base_super() throws InterpreterException;
  692. /**
  693. * The identity operator. In AmbientTalk, equality of objects
  694. * is by default pointer-equality (i.e. objects are equal only
  695. * if they are identical).
  696. *
  697. * This is a primitive method, present by default in every AmbientTalk
  698. * object but redefinable by the programmer.
  699. *
  700. * @return by default, true if the parameter object and this object are identical,
  701. * false otherwise.
  702. */
  703. public ATBoolean base__opeql__opeql_(ATObject other) throws InterpreterException;
  704. /**
  705. * The object instantiation method. Note that in class-based OO languages,
  706. * this method is usually at the level of the <i>class</i>. In AmbientTalk,
  707. * this method is situated at the object-level directly. It can be overridden
  708. * to e.g. enforce the singleton pattern or to return instances of other
  709. * objects.
  710. *
  711. * The default implementation of this method is:
  712. * <pre>def new(@args) {
  713. * (reflect: self).newInstance(@args)
  714. *};
  715. * </pre>
  716. *
  717. * This is a primitive method, present by default in every AmbientTalk
  718. * object but redefinable by the programmer.
  719. *
  720. * @see ATObject#meta_newInstance(ATTable) for a description of object instantiation.
  721. * @param initargs the variable argument list to pass to the <tt>init</tt> method.
  722. * @return by default, the new instance of this mirror's base object.
  723. */
  724. public ATObject base_new(ATObject[] initargs) throws InterpreterException;
  725. /**
  726. * The object initialisation method. In class-based languages, this method
  727. * is often called the constructor. AmbientTalk only supports one constructor
  728. * per object, but thanks to variable argument lists and optional parameters,
  729. * the same flexibility as defining multiple constructors can often be achieved.
  730. * Also, by overriding <tt>new</tt>, the developer may invoke additional methods
  731. * on newly created objects if this is desirable.
  732. *
  733. * The default implementation of this method is:
  734. * <pre>def init(@args) {
  735. * super^init(@args)
  736. *};
  737. * </pre>
  738. *
  739. * This is a primitive method, present by default in every AmbientTalk
  740. * object but redefinable by the programmer.
  741. *
  742. * @see ATObject#meta_newInstance(ATTable) for a description of object initialisation.
  743. * @param initargs the arguments to the <tt>init</tt> constructor method.
  744. * @return the return value of invoking the <tt>init</tt> method. Note that
  745. * this value is <i>discarded</i> when <tt>init</tt> is invoked from the
  746. * <tt>newInstance</tt> meta-level operation.
  747. */
  748. public ATObject base_init(ATObject[] initargs) throws InterpreterException;
  749. /* -----------------------------------------
  750. * - Implementation-Level Object interface -
  751. * ----------------------------------------- */
  752. /**
  753. * The <tt>lexicalParent</tt> field of a mirror denotes the lexical parent
  754. * pointer of the mirror's base object. The lexical parent is the enclosing
  755. * <i>lexical scope</i> in which the object was defined.
  756. *
  757. * @return the object denoting this mirror's base object's lexically
  758. * enclosing scope.
  759. */
  760. public ATObject impl_lexicalParent() throws InterpreterException;
  761. /**
  762. * Interprets <code>o.x()</code> or <code>o.m(arg)</code>.
  763. * Implements slot access. This method is an implementation-level method (not part of the MOP).
  764. * @param receiver the dynamic receiver of the slot invocation.
  765. * @param selector a regular symbol denoting the slot accessor.
  766. * @param arguments the actual arguments to the slot invocation.
  767. * @return the result of applying the accessor.
  768. * @throws XArityMismatch if a field accessor is not invoked with exactly zero arguments.
  769. */
  770. public ATObject impl_invokeAccessor(ATObject receiver, ATSymbol selector, ATTable arguments) throws InterpreterException;
  771. /**
  772. * Interprets <code>o.x := v</code>.
  773. * Implements slot mutation. This method is an implementation-level method (not part of the MOP).
  774. * @param receiver the dynamic receiver of the slot invocation.
  775. * @param selector an assignment symbol denoting which slot to invoke.
  776. * @param arguments the actual arguments to the slot invocation.
  777. * @return the result of applying the mutator.
  778. * @throws XArityMismatch if a field mutator is not invoked with exactly one argument.
  779. */
  780. public ATObject impl_invokeMutator(ATObject receiver, ATAssignmentSymbol selector, ATTable arguments) throws InterpreterException;
  781. /**
  782. * Interprets <code>o.&m</code>.
  783. * Implements slot accessor selection. This method is an implementation-level method (not part of the MOP).
  784. * @param receiver the dynamic receiver of the slot selection.
  785. * @param selector a regular symbol denoting the accessor to select.
  786. * @return a closure wrapping the selected method or an accessor for a field.
  787. */
  788. public ATClosure impl_selectAccessor(ATObject receiver, ATSymbol selector) throws InterpreterException;
  789. /**
  790. * Interprets <code>o.&m:=</code>.
  791. * Implements slot mutator selection. This method is an implementation-level method (not part of the MOP).
  792. * @param receiver the dynamic receiver of the slot selection.
  793. * @param selector an assignment symbol denoting the mutator to select.
  794. * @return a closure representing the mutator of a given slot.
  795. */
  796. public ATClosure impl_selectMutator(ATObject receiver, ATAssignmentSymbol selector) throws InterpreterException;
  797. /**
  798. * Interprets <code>x := v</code> (equivalent to <code>x:=(v)</code>) or <code>f(v)</code>.
  799. * Implements functions calls and lexical access to variables.
  800. * This method is an implementation-level method (not part of the MOP).
  801. * Variable lookup first queries the local fields of this object, then the local
  802. * method dictionary. If the selector is not found, the search continues in
  803. * this object's <i>lexical parent</i>. Hence, variable lookup follows
  804. * <b>lexical scoping rules</b>.
  805. * <p>
  806. * Similar to the behaviour of <tt>invoke</tt>, if the selector is bound to a
  807. * field rather than a method, <tt>call</tt> treats the field as an accessor
  808. * or mutator method (depending on the selector).
  809. * <p>
  810. * Note that, unlike <tt>invoke</tt> and <tt>select</tt>, <tt>call</tt> does
  811. * not give rise to the invocation of <tt>doesNotUnderstand</tt> if the selector
  812. * was not found. The reason for this is that lexical lookup is a static process
  813. * for which it makes less sense to provide dynamic interception facilities.
  814. *
  815. * @param selector a symbol denoting the name of the field or method to look up lexically.
  816. * @param arguments the arguments to the lexically scoped function call.
  817. * @return if selector is bound to a field, the value of the field; otherwise if selector
  818. * is bound to a method, the return value of the method.
  819. * @throws XUndefinedSlot if the selector could not be found in the lexical scope of this object.
  820. */
  821. public ATObject impl_call(ATSymbol selector, ATTable arguments) throws InterpreterException;
  822. /**
  823. * Interprets <code>f(v)</code>.
  824. * Implements the protocol to access lexical variables and methods. This operation (which is not exposed
  825. * as part of the MOP) locates the lexically visible binding with the given selector and will return
  826. * the value of the slot.
  827. * <p>
  828. * When this object has a local slot corresponding to the selector:
  829. * <ul>
  830. * <li> and the slot contains a method or closure, it will be applied with the given arguments (within a context
  831. * where self is bound to this object)
  832. * <li> and the slot contains a value and the argumentlist is empty, the value is returned
  833. * <li> and the slot contains a value and the argumentlist is not empty, an arity mismatch exception is raised
  834. * </ul>
  835. * <p>
  836. * When no local slot is found, lookup continues along the lexical parent chain. When the lexical chain is
  837. * completely traversed, an undefined slot exception is raised.
  838. */
  839. public ATObject impl_callAccessor(ATSymbol selector, ATTable arguments) throws InterpreterException;
  840. /**
  841. * Interprets <code>x := v</code> (which is equivalent to <code>x:=(v)</code>.
  842. * Implements the protocol to assign lexical variables. This operation (which is not exposed as part of the MOP)
  843. * locates slots to assign corresponding to a specific assignment symbol (selector + ":=") and looks for:
  844. * <ol>
  845. * <li> a mutator method with the specified assignment symbol (i.e. including the ":=") which can then be
  846. * invoked with the provided arguments.
  847. * <li> a field with a corresponding selector (i.e. without the ":=") which is then treated as if it were
  848. * a unary mutator method.
  849. * </ol>
  850. *
  851. * If the slot is a method slot, an {@link XUnassignableField} exception is raised, otherwise the arity of the
  852. * arguments is verified (should be precisely 1) and the first argument is used as the new value of the slot.
  853. * <p>
  854. * When no local slot is found, lookup continues along the lexical parent chain. When the lexical chain is
  855. * completely traversed, a selector not found exception is reported.
  856. */
  857. public ATObject impl_callMutator(ATAssignmentSymbol selector, ATTable arguments) throws InterpreterException;
  858. /**
  859. * Interprets <code>x</code>.
  860. * This method is an implementation-level method (not part of the MOP).
  861. *
  862. * This method is equivalent to {@link #impl_call(ATSymbol, ATTable)} where
  863. * the arguments equal <tt>[]</tt>, except for one case: when the selector
  864. * resolves to a field containing a closure, the closure is not auto-applied
  865. * with zero arguments, but is instead returned. For all other purposes,
  866. * evaluating <tt>m</tt> is equivalent to evaluating <tt>m()</tt> such that
  867. * fields and nullary methods can be uniformly accessed.
  868. *
  869. * @param selector the name of a lexically visible field or method.
  870. * @return the value of a field or the return value of an accessor method.
  871. */
  872. public ATObject impl_callField(ATSymbol selector) throws InterpreterException;
  873. /**
  874. * Interprets <code>&x</code> or <code>&x:=</code>.
  875. * This method is an implementation-level method (not part of the MOP).
  876. *
  877. * This operation is the lexical counterpart of {@link #meta_select(ATObject, ATSymbol)}.
  878. * @param selector the name of a lexically visible field or method.
  879. * @return a closure wrapping a method, or an accessor or mutator linked to a lexically visible field.
  880. */
  881. public ATClosure impl_lookup(ATSymbol selector) throws InterpreterException;
  882. /**
  883. * Interprets <code>&x</code>.
  884. * This method is an implementation-level method (not part of the MOP).
  885. *
  886. * @param selector the name of a lexically visible field or method.
  887. * @return a closure wrapping a method, or an accessor linked to a lexically visible field.
  888. */
  889. public ATClosure impl_lookupAccessor(ATSymbol selector) throws InterpreterException;
  890. /**
  891. * Interprets <code>&x:=</code>.
  892. * This method is an implementation-level method (not part of the MOP).
  893. *
  894. * If the selector minus <tt>:=</tt> is bound to a field, the field is assigned
  895. * i
  896. * @param selector the name of a lexically visible method or of a field (whose name does not have the <tt>:=</tt> prefix).
  897. * @return a closure wrapping a method, or a mutator linked to a lexically visible field.
  898. */
  899. public ATClosure impl_lookupMutator(ATAssignmentSymbol selector) throws InterpreterException;
  900. /**
  901. * This is a callback method used in AmbientTalk's native equality protocol.
  902. * When evaluating <tt>o1 == o2</tt> in AmbientTalk, <tt>o1</tt>'s <tt>==</tt>
  903. * method will invoke <tt>o2.identityEquals(o1)</tt>.
  904. *
  905. * The native implementation can make use of Java's <tt>==</tt> operator where
  906. * appropriate.
  907. */
  908. public ATBoolean impl_identityEquals(ATObject other) throws InterpreterException;
  909. }