001: /***** BEGIN LICENSE BLOCK *****
002: * Version: CPL 1.0/GPL 2.0/LGPL 2.1
003: *
004: * The contents of this file are subject to the Common Public
005: * License Version 1.0 (the "License"); you may not use this file
006: * except in compliance with the License. You may obtain a copy of
007: * the License at http://www.eclipse.org/legal/cpl-v10.html
008: *
009: * Software distributed under the License is distributed on an "AS
010: * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
011: * implied. See the License for the specific language governing
012: * rights and limitations under the License.
013: *
014: * Copyright (C) 2002-2004 Anders Bengtsson <ndrsbngtssn@yahoo.se>
015: * Copyright (C) 2002-2004 Jan Arne Petersen <jpetersen@uni-bonn.de>
016: * Copyright (C) 2004 Thomas E Enebo <enebo@acm.org>
017: * Copyright (C) 2004 Charles O Nutter <headius@headius.com>
018: * Copyright (C) 2004 Stefan Matthias Aust <sma@3plus4.de>
019: * Copyright (C) 2006 Ola Bini <ola.bini@ki.se>
020: *
021: * Alternatively, the contents of this file may be used under the terms of
022: * either of the GNU General Public License Version 2 or later (the "GPL"),
023: * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
024: * in which case the provisions of the GPL or the LGPL are applicable instead
025: * of those above. If you wish to allow use of your version of this file only
026: * under the terms of either the GPL or the LGPL, and not to allow others to
027: * use your version of this file under the terms of the CPL, indicate your
028: * decision by deleting the provisions above and replace them with the notice
029: * and other provisions required by the GPL or the LGPL. If you do not delete
030: * the provisions above, a recipient may use your version of this file under
031: * the terms of any one of the CPL, the GPL or the LGPL.
032: ***** END LICENSE BLOCK *****/package org.jruby.runtime.builtin;
033:
034: import java.util.Iterator;
035: import java.util.Map;
036:
037: import org.jruby.Ruby;
038: import org.jruby.RubyArray;
039: import org.jruby.RubyClass;
040: import org.jruby.RubyFloat;
041: import org.jruby.RubyHash;
042: import org.jruby.RubyInteger;
043: import org.jruby.RubyModule;
044: import org.jruby.RubyFixnum;
045: import org.jruby.RubyProc;
046: import org.jruby.RubyString;
047: import org.jruby.runtime.Block;
048: import org.jruby.runtime.CallType;
049: import org.jruby.runtime.ThreadContext;
050:
051: /** Object is the parent class of all classes in Ruby. Its methods are
052: * therefore available to all objects unless explicitly overridden.
053: *
054: * @author jpetersen
055: */
056: public interface IRubyObject {
057: /**
058: *
059: */
060: public static final IRubyObject[] NULL_ARRAY = new IRubyObject[0];
061:
062: /**
063: * Return the ClassIndex value for the native type this object was
064: * constructed from. Particularly useful for determining marshalling
065: * format. All instances of subclasses of Hash, for example
066: * are of Java type RubyHash, and so should utilize RubyHash marshalling
067: * logic in addition to user-defined class marshalling logic.
068: *
069: * @return the ClassIndex of the native type this object was constructed from
070: */
071: int getNativeTypeIndex();
072:
073: /**
074: * Gets a copy of the instance variables for this object, if any exist.
075: * Returns null if this object has no instance variables.
076: * "safe" in that it doesn't cause the instance var map to be created.
077: *
078: * @return A snapshot of the instance vars, or null if none.
079: */
080: Map safeGetInstanceVariables();
081:
082: /**
083: * Returns true if the object has any instance variables, false otherwise.
084: * "safe" in that it doesn't cause the instance var map to be created.
085: *
086: * @return true if the object has instance variables, false otherwise.
087: */
088: boolean safeHasInstanceVariables();
089:
090: /**
091: * RubyMethod getInstanceVar.
092: * @param string
093: * @return RubyObject
094: */
095: IRubyObject getInstanceVariable(String string);
096:
097: /**
098: * RubyMethod setInstanceVar.
099: * @param string
100: * @param rubyObject
101: * @return RubyObject
102: */
103: IRubyObject setInstanceVariable(String string,
104: IRubyObject rubyObject);
105:
106: /**
107: *
108: * @return
109: */
110: Map getInstanceVariables();
111:
112: /**
113: *
114: *
115: * @param instanceVariables
116: */
117: void setInstanceVariables(Map instanceVariables);
118:
119: /**
120: *
121: * @return
122: */
123: Map getInstanceVariablesSnapshot();
124:
125: /**
126: *
127: * @param context
128: * @param rubyclass
129: * @param name
130: * @param args
131: * @param callType
132: * @param block
133: * @return
134: */
135: IRubyObject callMethod(ThreadContext context, RubyModule rubyclass,
136: String name, IRubyObject[] args, CallType callType,
137: Block block);
138:
139: /**
140: *
141: * @param context
142: * @param rubyclass
143: * @param methodIndex
144: * @param name
145: * @param args
146: * @param callType
147: * @param block
148: * @return
149: */
150: IRubyObject callMethod(ThreadContext context, RubyModule rubyclass,
151: int methodIndex, String name, IRubyObject[] args,
152: CallType callType, Block block);
153:
154: /**
155: *
156: * @param context
157: * @param methodIndex
158: * @param name
159: * @param arg
160: * @return
161: */
162: IRubyObject callMethod(ThreadContext context, int methodIndex,
163: String name, IRubyObject arg);
164:
165: /**
166: *
167: * @param context
168: * @param methodIndex
169: * @param name
170: * @param args
171: * @return
172: */
173: IRubyObject callMethod(ThreadContext context, int methodIndex,
174: String name, IRubyObject[] args);
175:
176: /**
177: *
178: * @param context
179: * @param methodIndex
180: * @param name
181: * @param args
182: * @param callType
183: * @return
184: */
185: IRubyObject callMethod(ThreadContext context, int methodIndex,
186: String name, IRubyObject[] args, CallType callType);
187:
188: /**
189: *
190: * @param context
191: * @param name
192: * @param args
193: * @param callType
194: * @return
195: */
196: IRubyObject callMethod(ThreadContext context, String name,
197: IRubyObject[] args, CallType callType);
198:
199: /**
200: *
201: * @param context
202: * @param name
203: * @param args
204: * @param callType
205: * @param block
206: * @return
207: */
208: IRubyObject callMethod(ThreadContext context, String name,
209: IRubyObject[] args, CallType callType, Block block);
210:
211: // Used by the compiler, to allow visibility checks
212: /**
213: *
214: * @param context
215: * @param name
216: * @param args
217: * @param caller
218: * @param callType
219: * @param block
220: * @return
221: */
222: IRubyObject compilerCallMethod(ThreadContext context, String name,
223: IRubyObject[] args, IRubyObject caller, CallType callType,
224: Block block);
225:
226: /**
227: *
228: * @param context
229: * @param methodIndex
230: * @param name
231: * @param args
232: * @param caller
233: * @param callType
234: * @param block
235: * @return
236: */
237: IRubyObject compilerCallMethodWithIndex(ThreadContext context,
238: int methodIndex, String name, IRubyObject[] args,
239: IRubyObject caller, CallType callType, Block block);
240:
241: /**
242: *
243: * @param context
244: * @param args
245: * @param block
246: * @return
247: */
248: IRubyObject callSuper(ThreadContext context, IRubyObject[] args,
249: Block block);
250:
251: /**
252: *
253: * @param context
254: * @param string
255: * @return
256: */
257: IRubyObject callMethod(ThreadContext context, String string);
258:
259: /**
260: *
261: * @param context
262: * @param string
263: * @return
264: */
265: IRubyObject callMethod(ThreadContext context, int methodIndex,
266: String string);
267:
268: /**
269: *
270: * @param context
271: * @param string
272: * @param aBlock
273: * @return
274: */
275: IRubyObject callMethod(ThreadContext context, String string,
276: Block aBlock);
277:
278: /**
279: *
280: * @param context
281: * @param string
282: * @param arg
283: * @return
284: */
285: IRubyObject callMethod(ThreadContext context, String string,
286: IRubyObject arg);
287:
288: /**
289: *
290: * @param context
291: * @param method
292: * @param rubyArgs
293: * @return
294: */
295: IRubyObject callMethod(ThreadContext context, String method,
296: IRubyObject[] rubyArgs);
297:
298: /**
299: *
300: * @param context
301: * @param method
302: * @param rubyArgs
303: * @param block
304: * @return
305: */
306: IRubyObject callMethod(ThreadContext context, String method,
307: IRubyObject[] rubyArgs, Block block);
308:
309: /**
310: * RubyMethod isNil.
311: * @return boolean
312: */
313: boolean isNil();
314:
315: /**
316: *
317: * @return
318: */
319: boolean isTrue();
320:
321: /**
322: * RubyMethod isTaint.
323: * @return boolean
324: */
325: boolean isTaint();
326:
327: /**
328: * RubyMethod setTaint.
329: * @param b
330: */
331: void setTaint(boolean b);
332:
333: /**
334: * RubyMethod isFrozen.
335: * @return boolean
336: */
337: boolean isFrozen();
338:
339: /**
340: * RubyMethod setFrozen.
341: * @param b
342: */
343: void setFrozen(boolean b);
344:
345: /**
346: *
347: * @return
348: */
349: boolean isImmediate();
350:
351: /**
352: * RubyMethod isKindOf.
353: * @param rubyClass
354: * @return boolean
355: */
356: boolean isKindOf(RubyModule rubyClass);
357:
358: /**
359: * Infect this object using the taint of another object
360: * @param obj
361: * @return
362: */
363: IRubyObject infectBy(IRubyObject obj);
364:
365: /**
366: * RubyMethod getRubyClass.
367: * @return
368: */
369: RubyClass getMetaClass();
370:
371: /**
372: *
373: * @param metaClass
374: */
375: void setMetaClass(RubyClass metaClass);
376:
377: /**
378: * RubyMethod getSingletonClass.
379: * @return RubyClass
380: */
381: RubyClass getSingletonClass();
382:
383: /**
384: * RubyMethod getType.
385: * @return RubyClass
386: */
387: RubyClass getType();
388:
389: /**
390: * RubyMethod respondsTo.
391: * @param string
392: * @return boolean
393: */
394: boolean respondsTo(String string);
395:
396: /**
397: * RubyMethod getRuntime.
398: * @return
399: */
400: Ruby getRuntime();
401:
402: /**
403: * RubyMethod getJavaClass.
404: * @return Class
405: */
406: Class getJavaClass();
407:
408: /**
409: * Evaluate the given string under the specified binding object. If the binding is not a Proc or Binding object
410: * (RubyProc or RubyBinding) throw an appropriate type error.
411: * @param context TODO
412: * @param evalString The string containing the text to be evaluated
413: * @param binding The binding object under which to perform the evaluation
414: * @param file The filename to use when reporting errors during the evaluation
415: * @param lineNumber is the line number to pretend we are starting from
416: * @return An IRubyObject result from the evaluation
417: */
418: IRubyObject evalWithBinding(ThreadContext context,
419: IRubyObject evalString, IRubyObject binding, String file,
420: int lineNumber);
421:
422: /**
423: * Evaluate the given string.
424: * @param context TODO
425: * @param evalString The string containing the text to be evaluated
426: * @param file The filename to use when reporting errors during the evaluation
427: * @return An IRubyObject result from the evaluation
428: */
429: IRubyObject evalSimple(ThreadContext context,
430: IRubyObject evalString, String file);
431:
432: /**
433: * Convert the object into a symbol name if possible.
434: *
435: * @return String the symbol name
436: */
437: String asSymbol();
438:
439: /** rb_obj_as_string
440: * @return
441: */
442: RubyString asString();
443:
444: /**
445: * Methods which perform to_xxx if the object has such a method
446: * @return
447: */
448: RubyArray convertToArray();
449:
450: /**
451: *
452: * @return
453: */
454: RubyHash convertToHash();
455:
456: /**
457: *
458: * @return
459: */
460: RubyFloat convertToFloat();
461:
462: /**
463: *
464: * @return
465: */
466: RubyInteger convertToInteger();
467:
468: /**
469: *
470: * @return
471: */
472: RubyString convertToString();
473:
474: /**
475: * Converts this object to type 'targetType' using 'convertMethod' method (MRI: convert_type).
476: *
477: * @param targetType is the type we are trying to convert to
478: * @param convertMethod is the method to be called to try and convert to targeType
479: * @param raiseOnError will throw an Error if conversion does not work
480: * @return the converted value
481: */
482: IRubyObject convertToType(RubyClass targetType,
483: int convertMethodIndex, String convertMethod,
484: boolean raiseOnError);
485:
486: /**
487: * Higher level conversion utility similiar to convertToType but it can throw an
488: * additional TypeError during conversion (MRI: rb_check_convert_type).
489: *
490: * @param targetType is the type we are trying to convert to
491: * @param convertMethod is the method to be called to try and convert to targeType
492: * @return the converted value
493: */
494: IRubyObject convertToTypeWithCheck(RubyClass targetType,
495: int convertMethodIndex, String convertMethod);
496:
497: /**
498: *
499: * @param targetType
500: * @param convertMethod
501: * @param raiseOnMissingMethod
502: * @param raiseOnWrongTypeResult
503: * @param allowNilThrough
504: * @return
505: */
506: public IRubyObject convertToType(RubyClass targetType,
507: int convertMethodIndex, String convertMethod,
508: boolean raiseOnMissingMethod,
509: boolean raiseOnWrongTypeResult, boolean allowNilThrough);
510:
511: /**
512: *
513: * @return
514: */
515: IRubyObject anyToString();
516:
517: /**
518: *
519: * @return
520: */
521: IRubyObject checkStringType();
522:
523: /**
524: *
525: * @return
526: */
527: IRubyObject checkArrayType();
528:
529: /**
530: * RubyMethod dup.
531: * @return
532: */
533: IRubyObject dup();
534:
535: /**
536: * RubyMethod inspect.
537: * @return String
538: */
539: IRubyObject inspect();
540:
541: /**
542: * RubyMethod rbClone.
543: * @return IRubyObject
544: */
545: IRubyObject rbClone(Block unusedBlock);
546:
547: /**
548: *
549: * @return
550: */
551: boolean isSingleton();
552:
553: /**
554: *
555: * @return
556: */
557: Iterator instanceVariableNames();
558:
559: /**
560: * Our version of Data_Wrap_Struct.
561: *
562: * This method will just set a private pointer to the object provided. This pointer is transient
563: * and will not be accessible from Ruby.
564: *
565: * @param obj the object to wrap
566: */
567: void dataWrapStruct(Object obj);
568:
569: /**
570: * Our version of Data_Get_Struct.
571: *
572: * Returns a wrapped data value if there is one, otherwise returns null.
573: *
574: * @return the object wrapped.
575: */
576: Object dataGetStruct();
577:
578: /**
579: *
580: * @return
581: */
582: RubyFixnum id();
583:
584: public IRubyObject equal(IRubyObject other);
585:
586: IRubyObject equalInternal(final ThreadContext context,
587: final IRubyObject other);
588:
589: public boolean eql(IRubyObject other);
590:
591: public boolean eqlInternal(final ThreadContext context,
592: final IRubyObject other);
593:
594: public void addFinalizer(RubyProc finalizer);
595:
596: public void removeFinalizers();
597: }
|