js/src/jsiter.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=8 sw=4 et tw=78:
   3  *
   4  * ***** BEGIN LICENSE BLOCK *****
   5  * Version: MPL 1.1/GPL 2.0/LGPL 2.1 *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla Communicator client code, released
  17  * March 31, 1998.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1998
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #ifndef jsiter_h___
  41 #define jsiter_h___
  42
  43 /*
  44  * JavaScript iterators.
  45  */
  46 #include "jsprvtd.h"
  47 #include "jspubtd.h"
  48
  49 JS_BEGIN_EXTERN_C
  50
  51 /*
  52  * NB: these flag bits are encoded into the bytecode stream in the immediate
  53  * operand of JSOP_ITER, so don't change them without advancing jsxdrapi.h's
  54  * JSXDR_BYTECODE_VERSION.
  55  */
  56 #define JSITER_ENUMERATE  0x1   /* for-in compatible hidden default iterator */
  57 #define JSITER_FOREACH    0x2   /* return [key, value] pair rather than key */
  58 #define JSITER_KEYVALUE   0x4   /* destructuring for-in wants [key, value] */
  59
  60 /*
  61  * Native iterator object slots, shared between jsiter.cpp and jstracer.cpp.
  62  */
  63 #define JSSLOT_ITER_STATE       (JSSLOT_PRIVATE)
  64 #define JSSLOT_ITER_FLAGS       (JSSLOT_PRIVATE + 1)
  65
  66 /*
  67  * Convert the value stored in *vp to its iteration object. The flags should
  68  * contain JSITER_ENUMERATE if js_ValueToIterator is called when enumerating
  69  * for-in semantics are required, and when the caller can guarantee that the
  70  * iterator will never be exposed to scripts.
  71  */
  72 extern JS_FRIEND_API(JSBool)
  73 js_ValueToIterator(JSContext *cx, uintN flags, jsval *vp);
  74
  75 extern JS_FRIEND_API(JSBool) JS_FASTCALL
  76 js_CloseIterator(JSContext *cx, jsval v);
  77
  78 /*
  79  * Given iterobj, call iterobj.next().  If the iterator stopped, set *rval to
  80  * JSVAL_HOLE. Otherwise set it to the result of the next call.
  81  */
  82 extern JS_FRIEND_API(JSBool)
  83 js_CallIteratorNext(JSContext *cx, JSObject *iterobj, jsval *rval);
  84
  85 /*
  86  * Close iterobj, whose class must be js_IteratorClass.
  87  */
  88 extern void
  89 js_CloseNativeIterator(JSContext *cx, JSObject *iterobj);
  90
  91 extern JSBool
  92 js_ThrowStopIteration(JSContext *cx);
  93
  94 #if JS_HAS_GENERATORS
  95
  96 /*
  97  * Generator state codes.
  98  */
  99 typedef enum JSGeneratorState {
 100     JSGEN_NEWBORN,  /* not yet started */
 101     JSGEN_OPEN,     /* started by a .next() or .send(undefined) call */
 102     JSGEN_RUNNING,  /* currently executing via .next(), etc., call */
 103     JSGEN_CLOSING,  /* close method is doing asynchronous return */
 104     JSGEN_CLOSED    /* closed, cannot be started or closed again */
 105 } JSGeneratorState;
 106
 107 struct JSGenerator {
 108     JSObject            *obj;
 109     JSGeneratorState    state;
 110     JSStackFrame        frame;
 111     JSFrameRegs         savedRegs;
 112     JSArena             arena;
 113     jsval               slots[1];
 114 };
 115
 116 #define FRAME_TO_GENERATOR(fp) \
 117     ((JSGenerator *) ((uint8 *)(fp) - offsetof(JSGenerator, frame)))
 118
 119 extern JSObject *
 120 js_NewGenerator(JSContext *cx, JSStackFrame *fp);
 121
 122 #endif
 123
 124 extern JSClass          js_GeneratorClass;
 125 extern JSClass          js_IteratorClass;
 126 extern JSClass          js_StopIterationClass;
 127
 128 static inline bool
 129 js_ValueIsStopIteration(jsval v)
 130 {
 131     return !JSVAL_IS_PRIMITIVE(v) &&
 132            STOBJ_GET_CLASS(JSVAL_TO_OBJECT(v)) == &js_StopIterationClass;
 133 }
 134
 135 extern JSObject *
 136 js_InitIteratorClasses(JSContext *cx, JSObject *obj);
 137
 138 JS_END_EXTERN_C
 139
 140 #endif /* jsiter_h___ */