OLD | NEW |
1 // Copyright 2012 the V8 project authors. All rights reserved. | 1 // Copyright 2012 the V8 project authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 /** \mainpage V8 API Reference Guide | 5 /** \mainpage V8 API Reference Guide |
6 * | 6 * |
7 * V8 is Google's open source JavaScript engine. | 7 * V8 is Google's open source JavaScript engine. |
8 * | 8 * |
9 * This set of documents provides reference material generated from the | 9 * This set of documents provides reference material generated from the |
10 * V8 header file, include/v8.h. | 10 * V8 header file, include/v8.h. |
(...skipping 421 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
432 V8_INLINE MaybeLocal(Local<S> that) | 432 V8_INLINE MaybeLocal(Local<S> that) |
433 : val_(reinterpret_cast<T*>(*that)) { | 433 : val_(reinterpret_cast<T*>(*that)) { |
434 TYPE_CHECK(T, S); | 434 TYPE_CHECK(T, S); |
435 } | 435 } |
436 | 436 |
437 V8_INLINE bool IsEmpty() const { return val_ == nullptr; } | 437 V8_INLINE bool IsEmpty() const { return val_ == nullptr; } |
438 | 438 |
439 template <class S> | 439 template <class S> |
440 V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const { | 440 V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const { |
441 out->val_ = IsEmpty() ? nullptr : this->val_; | 441 out->val_ = IsEmpty() ? nullptr : this->val_; |
442 return IsEmpty(); | 442 return !IsEmpty(); |
443 } | 443 } |
444 | 444 |
445 V8_INLINE Local<T> ToLocalChecked() { | 445 V8_INLINE Local<T> ToLocalChecked() { |
446 // TODO(dcarney): add DCHECK. | 446 // TODO(dcarney): add DCHECK. |
447 return Local<T>(val_); | 447 return Local<T>(val_); |
448 } | 448 } |
449 | 449 |
450 template <class S> | 450 template <class S> |
451 V8_INLINE Local<S> FromMaybe(Local<S> default_value) const { | 451 V8_INLINE Local<S> FromMaybe(Local<S> default_value) const { |
452 return IsEmpty() ? default_value : Local<S>(val_); | 452 return IsEmpty() ? default_value : Local<S>(val_); |
(...skipping 606 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1059 | 1059 |
1060 /** | 1060 /** |
1061 * A compiled JavaScript script, tied to a Context which was active when the | 1061 * A compiled JavaScript script, tied to a Context which was active when the |
1062 * script was compiled. | 1062 * script was compiled. |
1063 */ | 1063 */ |
1064 class V8_EXPORT Script { | 1064 class V8_EXPORT Script { |
1065 public: | 1065 public: |
1066 /** | 1066 /** |
1067 * A shorthand for ScriptCompiler::Compile(). | 1067 * A shorthand for ScriptCompiler::Compile(). |
1068 */ | 1068 */ |
| 1069 // TODO(dcarney): deprecate. |
1069 static Local<Script> Compile(Handle<String> source, | 1070 static Local<Script> Compile(Handle<String> source, |
1070 ScriptOrigin* origin = NULL); | 1071 ScriptOrigin* origin = nullptr); |
| 1072 static MaybeLocal<Script> Compile(Local<Context> context, |
| 1073 Handle<String> source, |
| 1074 ScriptOrigin* origin = nullptr); |
1071 | 1075 |
1072 // To be decprecated, use the Compile above. | 1076 // TODO(dcarney): deprecate. |
1073 static Local<Script> Compile(Handle<String> source, | 1077 static Local<Script> Compile(Handle<String> source, |
1074 Handle<String> file_name); | 1078 Handle<String> file_name); |
1075 | 1079 |
1076 /** | 1080 /** |
1077 * Runs the script returning the resulting value. It will be run in the | 1081 * Runs the script returning the resulting value. It will be run in the |
1078 * context in which it was created (ScriptCompiler::CompileBound or | 1082 * context in which it was created (ScriptCompiler::CompileBound or |
1079 * UnboundScript::BindToCurrentContext()). | 1083 * UnboundScript::BindToCurrentContext()). |
1080 */ | 1084 */ |
1081 Local<Value> Run(); | 1085 Local<Value> Run(); |
1082 | 1086 |
(...skipping 175 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1258 * consumed later to speed up compilation of identical source scripts. | 1262 * consumed later to speed up compilation of identical source scripts. |
1259 * | 1263 * |
1260 * Note that when producing cached data, the source must point to NULL for | 1264 * Note that when producing cached data, the source must point to NULL for |
1261 * cached data. When consuming cached data, the cached data must have been | 1265 * cached data. When consuming cached data, the cached data must have been |
1262 * produced by the same version of V8. | 1266 * produced by the same version of V8. |
1263 * | 1267 * |
1264 * \param source Script source code. | 1268 * \param source Script source code. |
1265 * \return Compiled script object (context independent; for running it must be | 1269 * \return Compiled script object (context independent; for running it must be |
1266 * bound to a context). | 1270 * bound to a context). |
1267 */ | 1271 */ |
| 1272 // TODO(dcarney): deprecate |
1268 static Local<UnboundScript> CompileUnbound( | 1273 static Local<UnboundScript> CompileUnbound( |
1269 Isolate* isolate, Source* source, | 1274 Isolate* isolate, Source* source, |
1270 CompileOptions options = kNoCompileOptions); | 1275 CompileOptions options = kNoCompileOptions); |
| 1276 static MaybeLocal<UnboundScript> CompileUnboundScript( |
| 1277 Isolate* isolate, Source* source, |
| 1278 CompileOptions options = kNoCompileOptions); |
1271 | 1279 |
1272 /** | 1280 /** |
1273 * Compiles the specified script (bound to current context). | 1281 * Compiles the specified script (bound to current context). |
1274 * | 1282 * |
1275 * \param source Script source code. | 1283 * \param source Script source code. |
1276 * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile() | 1284 * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile() |
1277 * using pre_data speeds compilation if it's done multiple times. | 1285 * using pre_data speeds compilation if it's done multiple times. |
1278 * Owned by caller, no references are kept when this function returns. | 1286 * Owned by caller, no references are kept when this function returns. |
1279 * \return Compiled script object, bound to the context that was active | 1287 * \return Compiled script object, bound to the context that was active |
1280 * when this function was called. When run it will always use this | 1288 * when this function was called. When run it will always use this |
1281 * context. | 1289 * context. |
1282 */ | 1290 */ |
| 1291 // TODO(dcarney): deprecate |
1283 static Local<Script> Compile( | 1292 static Local<Script> Compile( |
1284 Isolate* isolate, Source* source, | 1293 Isolate* isolate, Source* source, |
1285 CompileOptions options = kNoCompileOptions); | 1294 CompileOptions options = kNoCompileOptions); |
| 1295 static MaybeLocal<Script> Compile(Local<Context> context, Source* source, |
| 1296 CompileOptions options = kNoCompileOptions); |
1286 | 1297 |
1287 /** | 1298 /** |
1288 * Returns a task which streams script data into V8, or NULL if the script | 1299 * Returns a task which streams script data into V8, or NULL if the script |
1289 * cannot be streamed. The user is responsible for running the task on a | 1300 * cannot be streamed. The user is responsible for running the task on a |
1290 * background thread and deleting it. When ran, the task starts parsing the | 1301 * background thread and deleting it. When ran, the task starts parsing the |
1291 * script, and it will request data from the StreamedSource as needed. When | 1302 * script, and it will request data from the StreamedSource as needed. When |
1292 * ScriptStreamingTask::Run exits, all data has been streamed and the script | 1303 * ScriptStreamingTask::Run exits, all data has been streamed and the script |
1293 * can be compiled (see Compile below). | 1304 * can be compiled (see Compile below). |
1294 * | 1305 * |
1295 * This API allows to start the streaming with as little data as possible, and | 1306 * This API allows to start the streaming with as little data as possible, and |
1296 * the remaining data (for example, the ScriptOrigin) is passed to Compile. | 1307 * the remaining data (for example, the ScriptOrigin) is passed to Compile. |
1297 */ | 1308 */ |
1298 static ScriptStreamingTask* StartStreamingScript( | 1309 static ScriptStreamingTask* StartStreamingScript( |
1299 Isolate* isolate, StreamedSource* source, | 1310 Isolate* isolate, StreamedSource* source, |
1300 CompileOptions options = kNoCompileOptions); | 1311 CompileOptions options = kNoCompileOptions); |
1301 | 1312 |
1302 /** | 1313 /** |
1303 * Compiles a streamed script (bound to current context). | 1314 * Compiles a streamed script (bound to current context). |
1304 * | 1315 * |
1305 * This can only be called after the streaming has finished | 1316 * This can only be called after the streaming has finished |
1306 * (ScriptStreamingTask has been run). V8 doesn't construct the source string | 1317 * (ScriptStreamingTask has been run). V8 doesn't construct the source string |
1307 * during streaming, so the embedder needs to pass the full source here. | 1318 * during streaming, so the embedder needs to pass the full source here. |
1308 */ | 1319 */ |
| 1320 // TODO(dcarney): deprecate |
1309 static Local<Script> Compile(Isolate* isolate, StreamedSource* source, | 1321 static Local<Script> Compile(Isolate* isolate, StreamedSource* source, |
1310 Handle<String> full_source_string, | 1322 Handle<String> full_source_string, |
1311 const ScriptOrigin& origin); | 1323 const ScriptOrigin& origin); |
| 1324 static MaybeLocal<Script> Compile(Local<Context> context, |
| 1325 StreamedSource* source, |
| 1326 Handle<String> full_source_string, |
| 1327 const ScriptOrigin& origin); |
1312 | 1328 |
1313 /** | 1329 /** |
1314 * Return a version tag for CachedData for the current V8 version & flags. | 1330 * Return a version tag for CachedData for the current V8 version & flags. |
1315 * | 1331 * |
1316 * This value is meant only for determining whether a previously generated | 1332 * This value is meant only for determining whether a previously generated |
1317 * CachedData instance is still valid; the tag has no other meaing. | 1333 * CachedData instance is still valid; the tag has no other meaing. |
1318 * | 1334 * |
1319 * Background: The data carried by CachedData may depend on the exact | 1335 * Background: The data carried by CachedData may depend on the exact |
1320 * V8 version number or currently compiler flags. This means when | 1336 * V8 version number or currently compiler flags. This means when |
1321 * persisting CachedData, the embedder must take care to not pass in | 1337 * persisting CachedData, the embedder must take care to not pass in |
1322 * data from another V8 version, or the same version with different | 1338 * data from another V8 version, or the same version with different |
1323 * features enabled. | 1339 * features enabled. |
1324 * | 1340 * |
1325 * The easiest way to do so is to clear the embedder's cache on any | 1341 * The easiest way to do so is to clear the embedder's cache on any |
1326 * such change. | 1342 * such change. |
1327 * | 1343 * |
1328 * Alternatively, this tag can be stored alongside the cached data and | 1344 * Alternatively, this tag can be stored alongside the cached data and |
1329 * compared when it is being used. | 1345 * compared when it is being used. |
1330 */ | 1346 */ |
1331 static uint32_t CachedDataVersionTag(); | 1347 static uint32_t CachedDataVersionTag(); |
1332 | 1348 |
1333 /** | 1349 /** |
1334 * Compile an ES6 module. | 1350 * Compile an ES6 module. |
1335 * | 1351 * |
1336 * This is an experimental feature. | 1352 * This is an experimental feature. |
1337 * | 1353 * |
1338 * TODO(adamk): Script is likely the wrong return value for this; | 1354 * TODO(adamk): Script is likely the wrong return value for this; |
1339 * should return some new Module type. | 1355 * should return some new Module type. |
1340 */ | 1356 */ |
| 1357 // TODO(dcarney): deprecate. |
1341 static Local<Script> CompileModule( | 1358 static Local<Script> CompileModule( |
1342 Isolate* isolate, Source* source, | 1359 Isolate* isolate, Source* source, |
1343 CompileOptions options = kNoCompileOptions); | 1360 CompileOptions options = kNoCompileOptions); |
| 1361 static MaybeLocal<Script> CompileModule( |
| 1362 Local<Context> context, Source* source, |
| 1363 CompileOptions options = kNoCompileOptions); |
1344 | 1364 |
1345 /** | 1365 /** |
1346 * Compile a function for a given context. This is equivalent to running | 1366 * Compile a function for a given context. This is equivalent to running |
1347 * | 1367 * |
1348 * with (obj) { | 1368 * with (obj) { |
1349 * return function(args) { ... } | 1369 * return function(args) { ... } |
1350 * } | 1370 * } |
1351 * | 1371 * |
1352 * It is possible to specify multiple context extensions (obj in the above | 1372 * It is possible to specify multiple context extensions (obj in the above |
1353 * example). | 1373 * example). |
1354 */ | 1374 */ |
| 1375 // TODO(dcarney): deprecate. |
1355 static Local<Function> CompileFunctionInContext( | 1376 static Local<Function> CompileFunctionInContext( |
1356 Isolate* isolate, Source* source, Local<Context> context, | 1377 Isolate* isolate, Source* source, Local<Context> context, |
1357 size_t arguments_count, Local<String> arguments[], | 1378 size_t arguments_count, Local<String> arguments[], |
1358 size_t context_extension_count, Local<Object> context_extensions[]); | 1379 size_t context_extension_count, Local<Object> context_extensions[]); |
| 1380 static MaybeLocal<Function> CompileFunctionInContext( |
| 1381 Local<Context> context, Source* source, size_t arguments_count, |
| 1382 Local<String> arguments[], size_t context_extension_count, |
| 1383 Local<Object> context_extensions[]); |
1359 | 1384 |
1360 private: | 1385 private: |
1361 static Local<UnboundScript> CompileUnboundInternal(Isolate* isolate, | 1386 static MaybeLocal<UnboundScript> CompileUnboundInternal( |
1362 Source* source, | 1387 Isolate* isolate, Source* source, CompileOptions options, bool is_module); |
1363 CompileOptions options, | |
1364 bool is_module); | |
1365 }; | 1388 }; |
1366 | 1389 |
1367 | 1390 |
1368 /** | 1391 /** |
1369 * An error message. | 1392 * An error message. |
1370 */ | 1393 */ |
1371 class V8_EXPORT Message { | 1394 class V8_EXPORT Message { |
1372 public: | 1395 public: |
1373 Local<String> Get() const; | 1396 Local<String> Get() const; |
1374 Local<String> GetSourceLine() const; | 1397 Local<String> GetSourceLine() const; |
(...skipping 6347 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7722 */ | 7745 */ |
7723 | 7746 |
7724 | 7747 |
7725 } // namespace v8 | 7748 } // namespace v8 |
7726 | 7749 |
7727 | 7750 |
7728 #undef TYPE_CHECK | 7751 #undef TYPE_CHECK |
7729 | 7752 |
7730 | 7753 |
7731 #endif // V8_H_ | 7754 #endif // V8_H_ |
OLD | NEW |