1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qjsengine.h"
5#include "qjsengine_p.h"
6#include "qjsvalue.h"
7#include "qjsvalue_p.h"
8
9#include "private/qv4engine_p.h"
10#include "private/qv4mm_p.h"
11#include "private/qv4errorobject_p.h"
12#include "private/qv4globalobject_p.h"
13#include "private/qv4script_p.h"
14#include "private/qv4runtime_p.h"
15#include <private/qv4dateobject_p.h>
16#include <private/qqmlbuiltinfunctions_p.h>
17#include <private/qqmldebugconnector_p.h>
18#include <private/qv4qobjectwrapper_p.h>
19#include <private/qv4qmetaobjectwrapper_p.h>
20#include <private/qv4stackframe_p.h>
21#include <private/qv4module_p.h>
22#include <private/qv4symbol_p.h>
23
24#include <QtCore/qdatetime.h>
25#include <QtCore/qmetaobject.h>
26#include <QtCore/qstringlist.h>
27#include <QtCore/qvariant.h>
28#include <QtCore/qdatetime.h>
29
30#include <QtCore/qcoreapplication.h>
31#include <QtCore/qdir.h>
32#include <QtCore/qfile.h>
33#include <QtCore/qfileinfo.h>
34#include <QtCore/qpluginloader.h>
35#include <qthread.h>
36#include <qmutex.h>
37#include <qwaitcondition.h>
38#include <private/qqmlglobal_p.h>
39#include <qqmlengine.h>
40
41Q_DECLARE_METATYPE(QList<int>)
42
43/*!
44 \since 5.0
45 \class QJSEngine
46 \reentrant
47
48 \brief The QJSEngine class provides an environment for evaluating JavaScript code.
49
50 \ingroup qtjavascript
51 \inmodule QtQml
52
53 \section1 Evaluating Scripts
54
55 Use evaluate() to evaluate script code.
56
57 \snippet code/src_script_qjsengine.cpp 0
58
59 evaluate() returns a QJSValue that holds the result of the
60 evaluation. The QJSValue class provides functions for converting
61 the result to various C++ types (e.g. QJSValue::toString()
62 and QJSValue::toNumber()).
63
64 The following code snippet shows how a script function can be
65 defined and then invoked from C++ using QJSValue::call():
66
67 \snippet code/src_script_qjsengine.cpp 1
68
69 As can be seen from the above snippets, a script is provided to the
70 engine in the form of a string. One common way of loading scripts is
71 by reading the contents of a file and passing it to evaluate():
72
73 \snippet code/src_script_qjsengine.cpp 2
74
75 Here we pass the name of the file as the second argument to
76 evaluate(). This does not affect evaluation in any way; the second
77 argument is a general-purpose string that is stored in the \c Error
78 object for debugging purposes.
79
80 For larger pieces of functionality, you may want to encapsulate
81 your code and data into modules. A module is a file that contains
82 script code, variables, etc., and uses export statements to describe
83 its interface towards the rest of the application. With the help of
84 import statements, a module can refer to functionality from other modules.
85 This allows building a scripted application from smaller connected building blocks
86 in a safe way. In contrast, the approach of using evaluate() carries the risk
87 that internal variables or functions from one evaluate() call accidentally pollute the
88 global object and affect subsequent evaluations.
89
90 The following example provides a module that can add numbers:
91
92 \code
93 export function sum(left, right)
94 {
95 return left + right
96 }
97 \endcode
98
99 This module can be loaded with QJSEngine::import() if it is saved under
100 the name \c{math.mjs}:
101
102 \code
103 QJSvalue module = myEngine.importModule("./math.mjs");
104 QJSValue sumFunction = module.property("sum");
105 QJSValue result = sumFunction.call(args);
106 \endcode
107
108 Modules can also use functionality from other modules using import
109 statements:
110
111 \code
112 import { sum } from "./math.mjs";
113 export function addTwice(left, right)
114 {
115 return sum(left, right) * 2;
116 }
117 \endcode
118
119 Modules don't have to be files. They can be values registered with
120 QJSEngine::registerModule():
121
122 \code
123 import version from "version";
124
125 export function getVersion()
126 {
127 return version;
128 }
129 \endcode
130
131 \code
132 QJSValue version(610);
133 myEngine.registerModule("version", version);
134 QJSValue module = myEngine.importModule("./myprint.mjs");
135 QJSValue getVersion = module.property("getVersion");
136 QJSValue result = getVersion.call();
137 \endcode
138
139 Named exports are supported, but because they are treated as members of an
140 object, the default export must be an ECMAScript object. Most of the newXYZ
141 functions in QJSValue will return an object.
142
143 \code
144 QJSValue name("Qt6");
145 QJSValue obj = myEngine.newObject();
146 obj.setProperty("name", name);
147 myEngine.registerModule("info", obj);
148 \endcode
149
150 \code
151 import { name } from "info";
152
153 export function getName()
154 {
155 return name;
156 }
157 \endcode
158
159 \section1 Engine Configuration
160
161 The globalObject() function returns the \b {Global Object}
162 associated with the script engine. Properties of the Global Object
163 are accessible from any script code (i.e. they are global
164 variables). Typically, before evaluating "user" scripts, you will
165 want to configure a script engine by adding one or more properties
166 to the Global Object:
167
168 \snippet code/src_script_qjsengine.cpp 3
169
170 Adding custom properties to the scripting environment is one of the
171 standard means of providing a scripting API that is specific to your
172 application. Usually these custom properties are objects created by
173 the newQObject() or newObject() functions.
174
175 \section1 Script Exceptions
176
177 evaluate() can throw a script exception (e.g. due to a syntax
178 error). If it does, then evaluate() returns the value that was thrown
179 (typically an \c{Error} object). Use \l QJSValue::isError() to check
180 for exceptions.
181
182 For detailed information about the error, use \l QJSValue::toString() to
183 obtain an error message, and use \l QJSValue::property() to query the
184 properties of the \c Error object. The following properties are available:
185
186 \list
187 \li \c name
188 \li \c message
189 \li \c fileName
190 \li \c lineNumber
191 \li \c stack
192 \endlist
193
194 \snippet code/src_script_qjsengine.cpp 4
195
196 \section1 Script Object Creation
197
198 Use newObject() to create a JavaScript object; this is the
199 C++ equivalent of the script statement \c{new Object()}. You can use
200 the object-specific functionality in QJSValue to manipulate the
201 script object (e.g. QJSValue::setProperty()). Similarly, use
202 newArray() to create a JavaScript array object.
203
204 \section1 QObject Integration
205
206 Use newQObject() to wrap a QObject (or subclass)
207 pointer. newQObject() returns a proxy script object; properties,
208 children, and signals and slots of the QObject are available as
209 properties of the proxy object. No binding code is needed because it
210 is done dynamically using the Qt meta object system.
211
212 \snippet code/src_script_qjsengine.cpp 5
213
214 Use newQMetaObject() to wrap a QMetaObject; this gives you a
215 "script representation" of a QObject-based class. newQMetaObject()
216 returns a proxy script object; enum values of the class are available
217 as properties of the proxy object.
218
219 Constructors exposed to the meta-object system (using Q_INVOKABLE) can be
220 called from the script to create a new QObject instance with
221 JavaScriptOwnership. For example, given the following class definition:
222
223 \snippet code/src_script_qjsengine.cpp 7
224
225 The \c staticMetaObject for the class can be exposed to JavaScript like so:
226
227 \snippet code/src_script_qjsengine.cpp 8
228
229 Instances of the class can then be created in JavaScript:
230
231 \snippet code/src_script_qjsengine.cpp 9
232
233 \note Currently only classes using the Q_OBJECT macro are supported; it is
234 not possible to expose the \c staticMetaObject of a Q_GADGET class to
235 JavaScript.
236
237 \section2 Dynamic QObject Properties
238
239 Dynamic QObject properties are not supported. For example, the following code
240 will not work:
241
242 \snippet code/src_script_qjsengine.cpp 6
243
244 \section1 Extensions
245
246 QJSEngine provides a compliant ECMAScript implementation. By default,
247 familiar utilities like logging are not available, but they can be
248 installed via the \l installExtensions() function.
249
250 \sa QJSValue, {Making Applications Scriptable},
251 {List of JavaScript Objects and Functions}
252
253*/
254
255/*!
256 \enum QJSEngine::Extension
257
258 This enum is used to specify extensions to be installed via
259 \l installExtensions().
260
261 \value TranslationExtension Indicates that translation functions (\c qsTr(),
262 for example) should be installed. This also installs the Qt.uiLanguage property.
263
264 \value ConsoleExtension Indicates that console functions (\c console.log(),
265 for example) should be installed.
266
267 \value GarbageCollectionExtension Indicates that garbage collection
268 functions (\c gc(), for example) should be installed.
269
270 \value AllExtensions Indicates that all extension should be installed.
271
272 \b TranslationExtension
273
274 The relation between script translation functions and C++ translation
275 functions is described in the following table:
276
277 \table
278 \header \li Script Function \li Corresponding C++ Function
279 \row \li qsTr() \li QObject::tr()
280 \row \li QT_TR_NOOP() \li QT_TR_NOOP()
281 \row \li qsTranslate() \li QCoreApplication::translate()
282 \row \li QT_TRANSLATE_NOOP() \li QT_TRANSLATE_NOOP()
283 \row \li qsTrId() \li qtTrId()
284 \row \li QT_TRID_NOOP() \li QT_TRID_NOOP()
285 \endtable
286
287 This flag also adds an \c arg() function to the string prototype.
288
289 For more information, see the \l {Internationalization with Qt}
290 documentation.
291
292 \b ConsoleExtension
293
294 The \l {Console API}{console} object implements a subset of the
295 \l {https://developer.mozilla.org/en-US/docs/Web/API/Console}{Console API},
296 which provides familiar logging functions, such as \c console.log().
297
298 The list of functions added is as follows:
299
300 \list
301 \li \c console.assert()
302 \li \c console.debug()
303 \li \c console.exception()
304 \li \c console.info()
305 \li \c console.log() (equivalent to \c console.debug())
306 \li \c console.error()
307 \li \c console.time()
308 \li \c console.timeEnd()
309 \li \c console.trace()
310 \li \c console.count()
311 \li \c console.warn()
312 \li \c {print()} (equivalent to \c console.debug())
313 \endlist
314
315 For more information, see the \l {Console API} documentation.
316
317 \b GarbageCollectionExtension
318
319 The \c gc() function is equivalent to calling \l collectGarbage().
320*/
321
322QT_BEGIN_NAMESPACE
323
324static void checkForApplicationInstance()
325{
326 if (!QCoreApplication::instance())
327 qFatal(msg: "QJSEngine: Must construct a QCoreApplication before a QJSEngine");
328}
329
330/*!
331 Constructs a QJSEngine object.
332
333 The globalObject() is initialized to have properties as described in
334 \l{ECMA-262}, Section 15.1.
335*/
336QJSEngine::QJSEngine()
337 : QJSEngine(nullptr)
338{
339}
340
341/*!
342 Constructs a QJSEngine object with the given \a parent.
343
344 The globalObject() is initialized to have properties as described in
345 \l{ECMA-262}, Section 15.1.
346*/
347
348QJSEngine::QJSEngine(QObject *parent)
349 : QJSEngine(*new QJSEnginePrivate, parent)
350{
351 QJSEnginePrivate::addToDebugServer(q: this);
352}
353
354/*!
355 \internal
356*/
357QJSEngine::QJSEngine(QJSEnginePrivate &dd, QObject *parent)
358 : QObject(dd, parent)
359 , m_v4Engine(new QV4::ExecutionEngine(this))
360{
361 checkForApplicationInstance();
362}
363
364/*!
365 Destroys this QJSEngine.
366
367 Garbage is not collected from the persistent JS heap during QJSEngine
368 destruction. If you need all memory freed, call collectGarbage() manually
369 right before destroying the QJSEngine.
370*/
371QJSEngine::~QJSEngine()
372{
373 m_v4Engine->inShutdown = true;
374 QJSEnginePrivate::removeFromDebugServer(q: this);
375 delete m_v4Engine;
376}
377
378/*!
379 \fn QV4::ExecutionEngine *QJSEngine::handle() const
380 \internal
381*/
382
383/*!
384 Runs the garbage collector.
385
386 The garbage collector will attempt to reclaim memory by locating and disposing of objects that are
387 no longer reachable in the script environment.
388
389 Normally you don't need to call this function; the garbage collector will automatically be invoked
390 when the QJSEngine decides that it's wise to do so (i.e. when a certain number of new objects
391 have been created). However, you can call this function to explicitly request that garbage
392 collection should be performed as soon as possible.
393
394
395 \sa {Garbage Collection}
396 \sa {Qt::}{gc()}
397 */
398void QJSEngine::collectGarbage()
399{
400 m_v4Engine->memoryManager->runFullGC();
401}
402
403/*!
404 \since 5.6
405
406 Installs JavaScript \a extensions to add functionality that is not
407 available in a standard ECMAScript implementation.
408
409 The extensions are installed on the given \a object, or on the
410 \l {globalObject()}{Global Object} if no object is specified.
411
412 Several extensions can be installed at once by \c {OR}-ing the enum values:
413
414 \code
415 installExtensions(QJSEngine::TranslationExtension | QJSEngine::ConsoleExtension);
416 \endcode
417
418 \sa Extension
419*/
420void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object)
421{
422 QV4::ExecutionEngine *otherEngine = QJSValuePrivate::engine(jsval: &object);
423 if (otherEngine && otherEngine != m_v4Engine) {
424 qWarning(msg: "QJSEngine: Trying to install extensions from a different engine");
425 return;
426 }
427
428 QV4::Scope scope(m_v4Engine);
429 QV4::ScopedObject obj(scope, QJSValuePrivate::asReturnedValue(jsval: &object));
430 if (!obj)
431 obj = scope.engine->globalObject;
432
433 QV4::GlobalExtensions::init(globalObject: obj, extensions);
434}
435
436/*!
437 \since 5.14
438 Interrupts or re-enables JavaScript execution.
439
440 If \a interrupted is \c true, any JavaScript executed by this engine
441 immediately aborts and returns an error object until this function is
442 called again with a value of \c false for \a interrupted.
443
444 This function is thread safe. You may call it from a different thread
445 in order to interrupt, for example, an infinite loop in JavaScript.
446*/
447void QJSEngine::setInterrupted(bool interrupted)
448{
449 m_v4Engine->isInterrupted.storeRelaxed(newValue: interrupted);
450}
451
452/*!
453 \since 5.14
454 Returns whether JavaScript execution is currently interrupted.
455
456 \sa setInterrupted()
457*/
458bool QJSEngine::isInterrupted() const
459{
460 return m_v4Engine->isInterrupted.loadRelaxed();
461}
462
463static QUrl urlForFileName(const QString &fileName)
464{
465 if (!fileName.startsWith(c: QLatin1Char(':')))
466 return QUrl::fromLocalFile(localfile: fileName);
467
468 QUrl url;
469 url.setPath(path: fileName.mid(position: 1));
470 url.setScheme(QLatin1String("qrc"));
471 return url;
472}
473
474/*!
475 Evaluates \a program, using \a lineNumber as the base line number,
476 and returns the result of the evaluation.
477
478 The script code will be evaluated in the context of the global object.
479
480 \note If you need to evaluate inside a QML context, use \l QQmlExpression
481 instead.
482
483 The evaluation of \a program can cause an \l{Script Exceptions}{exception} in the
484 engine; in this case the return value will be the exception
485 that was thrown (typically an \c{Error} object; see
486 QJSValue::isError()).
487
488 \a lineNumber is used to specify a starting line number for \a
489 program; line number information reported by the engine that pertains
490 to this evaluation will be based on this argument. For example, if
491 \a program consists of two lines of code, and the statement on the
492 second line causes a script exception, the exception line number
493 would be \a lineNumber plus one. When no starting line number is
494 specified, line numbers will be 1-based.
495
496 \a fileName is used for error reporting. For example, in error objects
497 the file name is accessible through the "fileName" property if it is
498 provided with this function.
499
500 \a exceptionStackTrace is used to report whether an uncaught exception was
501 thrown. If you pass a non-null pointer to a QStringList to it, it will set
502 it to list of "stackframe messages" if the script threw an unhandled
503 exception, or an empty list otherwise. A stackframe message has the format
504 function name:line number:column:file name
505 \note In some cases, e.g. for native functions, function name and file name
506 can be empty and line number and column can be -1.
507
508 \note If an exception was thrown and the exception value is not an
509 Error instance (i.e., QJSValue::isError() returns \c false), the
510 exception value will still be returned. Use \c exceptionStackTrace->isEmpty()
511 to distinguish whether the value was a normal or an exceptional return
512 value.
513
514 \sa QQmlExpression::evaluate
515*/
516QJSValue QJSEngine::evaluate(const QString& program, const QString& fileName, int lineNumber, QStringList *exceptionStackTrace)
517{
518 QV4::ExecutionEngine *v4 = m_v4Engine;
519 QV4::Scope scope(v4);
520 QV4::ScopedValue result(scope);
521
522 QV4::Script script(v4->rootContext(), QV4::Compiler::ContextType::Global, program, urlForFileName(fileName).toString(), lineNumber);
523 script.strictMode = false;
524 if (v4->currentStackFrame)
525 script.strictMode = v4->currentStackFrame->v4Function->isStrict();
526 else if (v4->globalCode)
527 script.strictMode = v4->globalCode->isStrict();
528 script.inheritContext = true;
529 script.parse();
530 if (!scope.hasException())
531 result = script.run();
532 if (exceptionStackTrace)
533 exceptionStackTrace->clear();
534 if (scope.hasException()) {
535 QV4::StackTrace trace;
536 result = v4->catchException(trace: &trace);
537 if (exceptionStackTrace) {
538 for (auto &&frame: trace)
539 exceptionStackTrace->push_back(t: QLatin1StringView("%1:%2:%3:%4").arg(
540 args&: frame.function,
541 args: QString::number(qAbs(t: frame.line)),
542 args: QString::number(frame.column),
543 args&: frame.source)
544 );
545 }
546 }
547 if (v4->isInterrupted.loadRelaxed())
548 result = v4->newErrorObject(QStringLiteral("Interrupted"));
549
550 return QJSValuePrivate::fromReturnedValue(d: result->asReturnedValue());
551}
552
553/*!
554 Imports the module located at \a fileName and returns a module namespace object that
555 contains all exported variables, constants and functions as properties.
556
557 If this is the first time the module is imported in the engine, the file is loaded
558 from the specified location in either the local file system or the Qt resource system
559 and evaluated as an ECMAScript module. The file is expected to be encoded in UTF-8 text.
560
561 Subsequent imports of the same module will return the previously imported instance. Modules
562 are singletons and remain around until the engine is destroyed.
563
564 The specified \a fileName will internally be normalized using \l QFileInfo::canonicalFilePath().
565 That means that multiple imports of the same file on disk using different relative paths will
566 load the file only once.
567
568 \note If an exception is thrown during the loading of the module, the return value
569 will be the exception (typically an \c{Error} object; see QJSValue::isError()).
570
571 \sa registerModule()
572
573 \since 5.12
574 */
575QJSValue QJSEngine::importModule(const QString &fileName)
576{
577 const QUrl url = urlForFileName(fileName: QFileInfo(fileName).canonicalFilePath());
578 const auto module = m_v4Engine->loadModule(url: url);
579 if (m_v4Engine->hasException)
580 return QJSValuePrivate::fromReturnedValue(d: m_v4Engine->catchException());
581
582 // If there is neither a native nor a compiled module, we should have seen an exception
583 Q_ASSERT(module);
584
585 QV4::Scope scope(m_v4Engine);
586 QV4::ScopedValue value(scope, module->value());
587 if (!value->isEmpty())
588 return QJSValuePrivate::fromReturnedValue(d: value->asReturnedValue());
589
590 QV4::Scoped<QV4::Module> moduleNamespace(scope, module->instantiate());
591 if (m_v4Engine->hasException)
592 return QJSValuePrivate::fromReturnedValue(d: m_v4Engine->catchException());
593
594 module->evaluate();
595 if (m_v4Engine->isInterrupted.loadRelaxed()) {
596 return QJSValuePrivate::fromReturnedValue(
597 d: m_v4Engine->newErrorObject(QStringLiteral("Interrupted"))->asReturnedValue());
598 }
599
600 return QJSValuePrivate::fromReturnedValue(d: moduleNamespace->asReturnedValue());
601}
602
603/*!
604 Registers a QJSValue to serve as a module. After this function is called,
605 all modules that import \a moduleName will import the value of \a value
606 instead of loading \a moduleName from the filesystem.
607
608 Any valid QJSValue can be registered, but named exports (i.e.
609 \c {import { name } from "info"} are treated as members of an object, so
610 the default export must be created with one of the newXYZ methods of
611 QJSEngine.
612
613 Because this allows modules that do not exist on the filesystem to be imported,
614 scripting applications can use this to provide built-in modules, similar to
615 Node.js.
616
617 Returns \c true on success, \c false otherwise.
618
619 \note The QJSValue \a value is not called or read until it is used by another module.
620 This means that there is no code to evaluate, so no errors will be seen until
621 another module throws an exception while trying to load this module.
622
623 \warning Attempting to access a named export from a QJSValue that is not an
624 object will trigger a \l{Script Exceptions}{exception}.
625
626 \sa importModule()
627 */
628bool QJSEngine::registerModule(const QString &moduleName, const QJSValue &value)
629{
630 QV4::Scope scope(m_v4Engine);
631 QV4::ScopedValue v4Value(scope, QJSValuePrivate::asReturnedValue(jsval: &value));
632 m_v4Engine->registerNativeModule(url: QUrl(moduleName), value: v4Value);
633 if (m_v4Engine->hasException)
634 return false;
635 return true;
636}
637
638/*!
639 Creates a JavaScript object of class Object.
640
641 The prototype of the created object will be the Object
642 prototype object.
643
644 \sa newArray(), QJSValue::setProperty()
645*/
646QJSValue QJSEngine::newObject()
647{
648 QV4::Scope scope(m_v4Engine);
649 QV4::ScopedValue v(scope, m_v4Engine->newObject());
650 return QJSValuePrivate::fromReturnedValue(d: v->asReturnedValue());
651}
652
653/*!
654 \since 6.2
655
656 Creates a JavaScript object of class Symbol, with value \a name.
657
658 The prototype of the created object will be the Symbol prototype object.
659
660 \sa newObject()
661*/
662QJSValue QJSEngine::newSymbol(const QString &name)
663{
664 QV4::Scope scope(m_v4Engine);
665 QV4::ScopedValue v(scope, QV4::Symbol::create(e: m_v4Engine, s: u'@' + name));
666 return QJSValuePrivate::fromReturnedValue(d: v->asReturnedValue());
667}
668
669/*!
670 \since 5.12
671
672 Creates a JavaScript object of class Error, with \a message as the error
673 message.
674
675 The prototype of the created object will be \a errorType.
676
677 \sa newObject(), throwError(), QJSValue::isError()
678*/
679QJSValue QJSEngine::newErrorObject(QJSValue::ErrorType errorType, const QString &message)
680{
681 QV4::Scope scope(m_v4Engine);
682 QV4::ScopedObject error(scope);
683 switch (errorType) {
684 case QJSValue::RangeError:
685 error = m_v4Engine->newRangeErrorObject(message);
686 break;
687 case QJSValue::SyntaxError:
688 error = m_v4Engine->newSyntaxErrorObject(message);
689 break;
690 case QJSValue::TypeError:
691 error = m_v4Engine->newTypeErrorObject(message);
692 break;
693 case QJSValue::URIError:
694 error = m_v4Engine->newURIErrorObject(message);
695 break;
696 case QJSValue::ReferenceError:
697 error = m_v4Engine->newReferenceErrorObject(message);
698 break;
699 case QJSValue::EvalError:
700 error = m_v4Engine->newEvalErrorObject(message);
701 break;
702 case QJSValue::GenericError:
703 error = m_v4Engine->newErrorObject(message);
704 break;
705 case QJSValue::NoError:
706 return QJSValue::UndefinedValue;
707 }
708 return QJSValuePrivate::fromReturnedValue(d: error->asReturnedValue());
709}
710
711/*!
712 Creates a JavaScript object of class Array with the given \a length.
713
714 \sa newObject()
715*/
716QJSValue QJSEngine::newArray(uint length)
717{
718 QV4::Scope scope(m_v4Engine);
719 QV4::ScopedArrayObject array(scope, m_v4Engine->newArrayObject());
720 if (length < 0x1000)
721 array->arrayReserve(n: length);
722 array->setArrayLengthUnchecked(length);
723 return QJSValuePrivate::fromReturnedValue(d: array.asReturnedValue());
724}
725
726/*!
727 Creates a JavaScript object that wraps the given QObject \a
728 object, using JavaScriptOwnership.
729
730 Signals and slots, properties and children of \a object are
731 available as properties of the created QJSValue.
732
733 If \a object is a null pointer, this function returns a null value.
734
735 If a default prototype has been registered for the \a object's class
736 (or its superclass, recursively), the prototype of the new script
737 object will be set to be that default prototype.
738
739 If the given \a object is deleted outside of the engine's control, any
740 attempt to access the deleted QObject's members through the JavaScript
741 wrapper object (either by script code or C++) will result in a
742 \l{Script Exceptions}{script exception}.
743
744 \sa QJSValue::toQObject()
745*/
746QJSValue QJSEngine::newQObject(QObject *object)
747{
748 QV4::ExecutionEngine *v4 = m_v4Engine;
749 QV4::Scope scope(v4);
750 if (object) {
751 QQmlData *ddata = QQmlData::get(object, create: true);
752 if (!ddata || !ddata->explicitIndestructibleSet)
753 QQmlEngine::setObjectOwnership(object, QQmlEngine::JavaScriptOwnership);
754 }
755 QV4::ScopedValue v(scope, QV4::QObjectWrapper::wrap(engine: v4, object));
756 return QJSValuePrivate::fromReturnedValue(d: v->asReturnedValue());
757}
758
759/*!
760 \since 5.8
761
762 Creates a JavaScript object that wraps the given QMetaObject
763 The \a metaObject must outlive the script engine. It is recommended to only
764 use this method with static metaobjects.
765
766
767 When called as a constructor, a new instance of the class will be created.
768 Only constructors exposed by Q_INVOKABLE will be visible from the script engine.
769
770 \sa newQObject(), {QObject Integration}
771*/
772
773QJSValue QJSEngine::newQMetaObject(const QMetaObject* metaObject) {
774 QV4::ExecutionEngine *v4 = m_v4Engine;
775 QV4::Scope scope(v4);
776 QV4::ScopedValue v(scope, QV4::QMetaObjectWrapper::create(engine: v4, metaObject));
777 return QJSValuePrivate::fromReturnedValue(d: v->asReturnedValue());
778}
779
780/*! \fn template <typename T> QJSValue QJSEngine::newQMetaObject()
781
782 \since 5.8
783 Creates a JavaScript object that wraps the static QMetaObject associated
784 with class \c{T}.
785
786 \sa newQObject(), {QObject Integration}
787*/
788
789
790/*!
791 Returns this engine's Global Object.
792
793 By default, the Global Object contains the built-in objects that are
794 part of \l{ECMA-262}, such as Math, Date and String. Additionally,
795 you can set properties of the Global Object to make your own
796 extensions available to all script code. Non-local variables in
797 script code will be created as properties of the Global Object, as
798 well as local variables in global code.
799*/
800QJSValue QJSEngine::globalObject() const
801{
802 QV4::Scope scope(m_v4Engine);
803 QV4::ScopedValue v(scope, m_v4Engine->globalObject);
804 return QJSValuePrivate::fromReturnedValue(d: v->asReturnedValue());
805}
806
807QJSPrimitiveValue QJSEngine::createPrimitive(QMetaType type, const void *ptr)
808{
809 QV4::Scope scope(m_v4Engine);
810 QV4::ScopedValue v(scope, m_v4Engine->metaTypeToJS(type, data: ptr));
811 return QV4::ExecutionEngine::createPrimitive(v);
812}
813
814QJSManagedValue QJSEngine::createManaged(QMetaType type, const void *ptr)
815{
816 QJSManagedValue result(m_v4Engine);
817 *result.d = m_v4Engine->metaTypeToJS(type, data: ptr);
818 return result;
819}
820
821/*!
822 * \internal
823 * used by QJSEngine::toScriptValue
824 */
825QJSValue QJSEngine::create(QMetaType type, const void *ptr)
826{
827 QV4::Scope scope(m_v4Engine);
828 QV4::ScopedValue v(scope, scope.engine->metaTypeToJS(type, data: ptr));
829 return QJSValuePrivate::fromReturnedValue(d: v->asReturnedValue());
830}
831
832bool QJSEngine::convertPrimitive(const QJSPrimitiveValue &value, QMetaType type, void *ptr)
833{
834 switch (value.type()) {
835 case QJSPrimitiveValue::Undefined:
836 return QV4::ExecutionEngine::metaTypeFromJS(value: QV4::Value::undefinedValue(), type, data: ptr);
837 case QJSPrimitiveValue::Null:
838 return QV4::ExecutionEngine::metaTypeFromJS(value: QV4::Value::nullValue(), type, data: ptr);
839 case QJSPrimitiveValue::Boolean:
840 return QV4::ExecutionEngine::metaTypeFromJS(value: QV4::Value::fromBoolean(b: value.toBoolean()), type, data: ptr);
841 case QJSPrimitiveValue::Integer:
842 return QV4::ExecutionEngine::metaTypeFromJS(value: QV4::Value::fromInt32(i: value.toInteger()), type, data: ptr);
843 case QJSPrimitiveValue::Double:
844 return QV4::ExecutionEngine::metaTypeFromJS(value: QV4::Value::fromDouble(d: value.toDouble()), type, data: ptr);
845 case QJSPrimitiveValue::String:
846 return convertString(string: value.toString(), metaType: type, ptr);
847 }
848
849 Q_UNREACHABLE_RETURN(false);
850}
851
852bool QJSEngine::convertManaged(const QJSManagedValue &value, int type, void *ptr)
853{
854 return convertManaged(value, type: QMetaType(type), ptr);
855}
856
857bool QJSEngine::convertManaged(const QJSManagedValue &value, QMetaType type, void *ptr)
858{
859 return QV4::ExecutionEngine::metaTypeFromJS(value: *value.d, type, data: ptr);
860}
861
862bool QJSEngine::convertString(const QString &string, QMetaType metaType, void *ptr)
863{
864 // have a string based value without engine. Do conversion manually
865 if (metaType == QMetaType::fromType<bool>()) {
866 *reinterpret_cast<bool*>(ptr) = string.size() != 0;
867 return true;
868 }
869 if (metaType == QMetaType::fromType<QString>()) {
870 *reinterpret_cast<QString*>(ptr) = string;
871 return true;
872 }
873 if (metaType == QMetaType::fromType<QUrl>()) {
874 *reinterpret_cast<QUrl *>(ptr) = QUrl(string);
875 return true;
876 }
877
878 double d = QV4::RuntimeHelpers::stringToNumber(s: string);
879 switch (metaType.id()) {
880 case QMetaType::Int:
881 *reinterpret_cast<int*>(ptr) = QV4::Value::toInt32(d);
882 return true;
883 case QMetaType::UInt:
884 *reinterpret_cast<uint*>(ptr) = QV4::Value::toUInt32(d);
885 return true;
886 case QMetaType::Long:
887 *reinterpret_cast<long*>(ptr) = QV4::Value::toInteger(d);
888 return true;
889 case QMetaType::ULong:
890 *reinterpret_cast<ulong*>(ptr) = QV4::Value::toInteger(d);
891 return true;
892 case QMetaType::LongLong:
893 *reinterpret_cast<qlonglong*>(ptr) = QV4::Value::toInteger(d);
894 return true;
895 case QMetaType::ULongLong:
896 *reinterpret_cast<qulonglong*>(ptr) = QV4::Value::toInteger(d);
897 return true;
898 case QMetaType::Double:
899 *reinterpret_cast<double*>(ptr) = d;
900 return true;
901 case QMetaType::Float:
902 *reinterpret_cast<float*>(ptr) = d;
903 return true;
904 case QMetaType::Short:
905 *reinterpret_cast<short*>(ptr) = QV4::Value::toInt32(d);
906 return true;
907 case QMetaType::UShort:
908 *reinterpret_cast<unsigned short*>(ptr) = QV4::Value::toUInt32(d);
909 return true;
910 case QMetaType::Char:
911 *reinterpret_cast<char*>(ptr) = QV4::Value::toInt32(d);
912 return true;
913 case QMetaType::UChar:
914 *reinterpret_cast<unsigned char*>(ptr) = QV4::Value::toUInt32(d);
915 return true;
916 case QMetaType::QChar:
917 *reinterpret_cast<QChar*>(ptr) = QChar(QV4::Value::toUInt32(d));
918 return true;
919 case QMetaType::Char16:
920 *reinterpret_cast<char16_t *>(ptr) = QV4::Value::toUInt32(d);
921 return true;
922 default:
923 return false;
924 }
925}
926
927/*!
928 \internal
929 convert \a value to \a type, store the result in \a ptr
930*/
931bool QJSEngine::convertV2(const QJSValue &value, QMetaType metaType, void *ptr)
932{
933 if (const QString *string = QJSValuePrivate::asQString(jsval: &value))
934 return convertString(string: *string, metaType, ptr);
935
936 // Does not need scoping since QJSValue still holds on to the value.
937 return QV4::ExecutionEngine::metaTypeFromJS(value: QV4::Value::fromReturnedValue(val: QJSValuePrivate::asReturnedValue(jsval: &value)),
938 type: metaType, data: ptr);
939}
940
941bool QJSEngine::convertVariant(const QVariant &value, QMetaType metaType, void *ptr)
942{
943 // TODO: We could probably avoid creating a QV4::Value in many cases, but we'd have to
944 // duplicate much of metaTypeFromJS and some methods of QV4::Value itself here.
945 QV4::Scope scope(handle());
946 QV4::ScopedValue scoped(scope, scope.engine->fromVariant(value));
947 return QV4::ExecutionEngine::metaTypeFromJS(value: scoped, type: metaType, data: ptr);
948}
949
950bool QJSEngine::convertMetaType(QMetaType fromType, const void *from, QMetaType toType, void *to)
951{
952 // TODO: We could probably avoid creating a QV4::Value in many cases, but we'd have to
953 // duplicate much of metaTypeFromJS and some methods of QV4::Value itself here.
954 QV4::Scope scope(handle());
955 QV4::ScopedValue scoped(scope, scope.engine->fromData(type: fromType, ptr: from));
956 return QV4::ExecutionEngine::metaTypeFromJS(value: scoped, type: toType, data: to);
957}
958
959QString QJSEngine::convertQObjectToString(QObject *object)
960{
961 return QV4::QObjectWrapper::objectToString(
962 engine: handle(), metaObject: object ? object->metaObject() : nullptr, object);
963}
964
965QString QJSEngine::convertDateTimeToString(const QDateTime &dateTime)
966{
967 return QV4::DateObject::dateTimeToString(dateTime, engine: handle());
968}
969
970double QJSEngine::convertDateTimeToNumber(const QDateTime &dateTime)
971{
972 return QV4::DateObject::dateTimeToNumber(dateTime);
973}
974
975QDate QJSEngine::convertDateTimeToDate(const QDateTime &dateTime)
976{
977 return QV4::DateObject::dateTimeToDate(dateTime);
978}
979
980/*! \fn template <typename T> QJSValue QJSEngine::toScriptValue(const T &value)
981
982 Creates a QJSValue with the given \a value.
983
984 \sa fromScriptValue(), coerceValue()
985*/
986
987/*! \fn template <typename T> QJSManagedValue QJSEngine::toManagedValue(const T &value)
988
989 Creates a QJSManagedValue with the given \a value.
990
991 \sa fromManagedValue(), coerceValue()
992*/
993
994/*! \fn template <typename T> QJSPrimitiveValue QJSEngine::toPrimitiveValue(const T &value)
995
996 Creates a QJSPrimitiveValue with the given \a value.
997
998 Since QJSPrimitiveValue can only hold int, bool, double, QString, and the
999 equivalents of JavaScript \c null and \c undefined, the value will be
1000 coerced aggressively if you pass any other type.
1001
1002 \sa fromPrimitiveValue(), coerceValue()
1003*/
1004
1005/*! \fn template <typename T> T QJSEngine::fromScriptValue(const QJSValue &value)
1006
1007 Returns the given \a value converted to the template type \c{T}.
1008
1009 \sa toScriptValue(), coerceValue()
1010*/
1011
1012/*! \fn template <typename T> T QJSEngine::fromManagedValue(const QJSManagedValue &value)
1013
1014 Returns the given \a value converted to the template type \c{T}.
1015
1016 \sa toManagedValue(), coerceValue()
1017*/
1018
1019/*! \fn template <typename T> T QJSEngine::fromPrimitiveValue(const QJSPrimitiveValue &value)
1020
1021 Returns the given \a value converted to the template type \c{T}.
1022
1023 Since QJSPrimitiveValue can only hold int, bool, double, QString, and the
1024 equivalents of JavaScript \c null and \c undefined, the value will be
1025 coerced aggressively if you request any other type.
1026
1027 \sa toPrimitiveValue(), coerceValue()
1028*/
1029
1030/*! \fn template <typename T> T QJSEngine::fromVariant(const QVariant &value)
1031
1032 Returns the given \a value converted to the template type \c{T}.
1033 The conversion is done in JavaScript semantics. Those differ from
1034 qvariant_cast's semantics. There are a number of implicit
1035 conversions between JavaScript-equivalent types that are not
1036 performed by qvariant_cast by default.
1037
1038 \sa coerceValue(), fromScriptValue(), {QVariant::}{qvariant_cast()}
1039*/
1040
1041/*! \fn template <typename From, typename To> T QJSEngine::coerceValue(const From &from)
1042
1043 Returns the given \a from converted to the template type \c{To}.
1044 The conversion is done in JavaScript semantics. Those differ from
1045 qvariant_cast's semantics. There are a number of implicit
1046 conversions between JavaScript-equivalent types that are not
1047 performed by qvariant_cast by default. This method is a generalization of
1048 all the other conversion methods in this class.
1049
1050 \sa fromVariant(), {QVariant::}{qvariant_cast()}, fromScriptValue(), toScriptValue()
1051*/
1052
1053/*!
1054 Throws a run-time error (exception) with the given \a message.
1055
1056 This method is the C++ counterpart of a \c throw() expression in
1057 JavaScript. It enables C++ code to report run-time errors to QJSEngine.
1058 Therefore it should only be called from C++ code that was invoked by a
1059 JavaScript function through QJSEngine.
1060
1061 When returning from C++, the engine will interrupt the normal flow of
1062 execution and call the next pre-registered exception handler with
1063 an error object that contains the given \a message. The error object
1064 will point to the location of the top-most context on the JavaScript
1065 caller stack; specifically, it will have properties \c lineNumber,
1066 \c fileName and \c stack. These properties are described in
1067 \l{Script Exceptions}.
1068
1069 In the following example a C++ method in \e FileAccess.cpp throws an error
1070 in \e qmlFile.qml at the position where \c readFileAsText() is called:
1071
1072 \code
1073 // qmlFile.qml
1074 function someFunction() {
1075 ...
1076 var text = FileAccess.readFileAsText("/path/to/file.txt");
1077 }
1078 \endcode
1079
1080 \code
1081 // FileAccess.cpp
1082 // Assuming that FileAccess is a QObject-derived class that has been
1083 // registered as a singleton type and provides an invokable method
1084 // readFileAsText()
1085
1086 QJSValue FileAccess::readFileAsText(const QString & filePath) {
1087 QFile file(filePath);
1088
1089 if (!file.open(QIODevice::ReadOnly)) {
1090 jsEngine->throwError(file.errorString());
1091 return QString();
1092 }
1093
1094 ...
1095 return content;
1096 }
1097 \endcode
1098
1099 It is also possible to catch the thrown error in JavaScript:
1100 \code
1101 // qmlFile.qml
1102 function someFunction() {
1103 ...
1104 var text;
1105 try {
1106 text = FileAccess.readFileAsText("/path/to/file.txt");
1107 } catch (error) {
1108 console.warn("In " + error.fileName + ":" + "error.lineNumber" +
1109 ": " + error.message);
1110 }
1111 }
1112 \endcode
1113
1114 If you need a more specific run-time error to describe an exception, you can use the
1115 \l {QJSEngine::}{throwError(QJSValue::ErrorType errorType, const QString &message)}
1116 overload.
1117
1118 \since Qt 5.12
1119 \sa {Script Exceptions}
1120*/
1121void QJSEngine::throwError(const QString &message)
1122{
1123 m_v4Engine->throwError(message);
1124}
1125
1126/*!
1127 \overload throwError()
1128
1129 Throws a run-time error (exception) with the given \a errorType and
1130 \a message.
1131
1132 \code
1133 // Assuming that DataEntry is a QObject-derived class that has been
1134 // registered as a singleton type and provides an invokable method
1135 // setAge().
1136
1137 void DataEntry::setAge(int age) {
1138 if (age < 0 || age > 200) {
1139 jsEngine->throwError(QJSValue::RangeError,
1140 "Age must be between 0 and 200");
1141 }
1142 ...
1143 }
1144 \endcode
1145
1146 \since Qt 5.12
1147 \sa {Script Exceptions}, newErrorObject()
1148*/
1149void QJSEngine::throwError(QJSValue::ErrorType errorType, const QString &message)
1150{
1151 QV4::Scope scope(m_v4Engine);
1152 QJSValue error = newErrorObject(errorType, message);
1153 QV4::ScopedObject e(scope, QJSValuePrivate::asReturnedValue(jsval: &error));
1154 if (!e)
1155 return;
1156 m_v4Engine->throwError(value: e);
1157}
1158
1159/*!
1160 \overload throwError()
1161
1162 Throws a pre-constructed run-time \a error (exception). This way you can
1163 use \l newErrorObject() to create the error and customize it as necessary.
1164
1165 \since 6.1
1166 \sa {Script Exceptions}, newErrorObject()
1167*/
1168void QJSEngine::throwError(const QJSValue &error)
1169{
1170 // safe, QJSValue holds a persistent reference
1171 m_v4Engine->throwError(value: QV4::Value::fromReturnedValue(val: QJSValuePrivate::asReturnedValue(jsval: &error)));
1172}
1173
1174/*!
1175 * Returns \c true if the last JavaScript execution resulted in an exception or
1176 * if throwError() was called. Otherwise returns \c false. Mind that evaluate()
1177 * catches any exceptions thrown in the evaluated code.
1178 *
1179 * \since Qt 6.1
1180 */
1181bool QJSEngine::hasError() const
1182{
1183 return m_v4Engine->hasException;
1184}
1185
1186/*!
1187 * If an exception is currently pending, catches it and returns it as a
1188 * QJSValue. Otherwise returns undefined as QJSValue. After calling this method
1189 * hasError() returns \c false.
1190 *
1191 * \since Qt 6.1
1192 */
1193QJSValue QJSEngine::catchError()
1194{
1195 if (m_v4Engine->hasException)
1196 return QJSValuePrivate::fromReturnedValue(d: m_v4Engine->catchException());
1197 else
1198 return QJSValue();
1199}
1200
1201/*!
1202 \property QJSEngine::uiLanguage
1203 \brief the language to be used for translating user interface strings
1204 \since 5.15
1205
1206 This property holds the name of the language to be used for user interface
1207 string translations. It is exposed for reading and writing as \c{Qt.uiLanguage} when
1208 the QJSEngine::TranslationExtension is installed on the engine. It is always exposed
1209 in instances of QQmlEngine.
1210
1211 You can set the value freely and use it in bindings. It is recommended to set it
1212 after installing translators in your application. By convention, an empty string
1213 means no translation from the language used in the source code is intended to occur.
1214*/
1215void QJSEngine::setUiLanguage(const QString &language) {
1216 Q_D(QJSEngine);
1217 d->uiLanguage = language; // property takes care of signal emission if necessary
1218}
1219
1220QString QJSEngine::uiLanguage() const
1221{
1222 Q_D(const QJSEngine);
1223 return d->uiLanguage;
1224}
1225
1226QJSEnginePrivate *QJSEnginePrivate::get(QV4::ExecutionEngine *e)
1227{
1228 return e->jsEngine()->d_func();
1229}
1230
1231QJSEnginePrivate::~QJSEnginePrivate()
1232{
1233 QQmlMetaType::freeUnusedTypesAndCaches();
1234}
1235
1236void QJSEnginePrivate::addToDebugServer(QJSEngine *q)
1237{
1238 if (QCoreApplication::instance()->thread() != q->thread())
1239 return;
1240
1241 QQmlDebugConnector *server = QQmlDebugConnector::instance();
1242 if (!server || server->hasEngine(engine: q))
1243 return;
1244
1245 server->open();
1246 server->addEngine(engine: q);
1247}
1248
1249void QJSEnginePrivate::removeFromDebugServer(QJSEngine *q)
1250{
1251 QQmlDebugConnector *server = QQmlDebugConnector::instance();
1252 if (server && server->hasEngine(engine: q))
1253 server->removeEngine(engine: q);
1254}
1255
1256/*!
1257 \since 5.5
1258 \relates QJSEngine
1259
1260 Returns the QJSEngine associated with \a object, if any.
1261
1262 This function is useful if you have exposed a QObject to the JavaScript environment
1263 and later in your program would like to regain access. It does not require you to
1264 keep the wrapper around that was returned from QJSEngine::newQObject().
1265 */
1266QJSEngine *qjsEngine(const QObject *object)
1267{
1268 QQmlData *data = QQmlData::get(object);
1269 if (!data || data->jsWrapper.isNullOrUndefined())
1270 return nullptr;
1271 return data->jsWrapper.engine()->jsEngine();
1272}
1273
1274
1275/*!
1276 \enum QJSEngine::ObjectOwnership
1277
1278 ObjectOwnership controls whether or not the JavaScript memory manager automatically destroys the
1279 QObject when the corresponding JavaScript object is garbage collected by the
1280 engine. The two ownership options are:
1281
1282 \value CppOwnership The object is owned by C++ code and the JavaScript memory manager will never
1283 delete it. The JavaScript destroy() method cannot be used on these objects. This
1284 option is similar to QScriptEngine::QtOwnership.
1285
1286 \value JavaScriptOwnership The object is owned by JavaScript. When the object
1287 is returned to the JavaScript memory manager as the return value of a method call, the JavaScript
1288 memory manager will track it and delete it if there are no remaining JavaScript references to it
1289 and it has no QObject::parent(). An object tracked by one QJSEngine will be deleted during that
1290 QJSEngine's destructor. Thus, JavaScript references between objects with JavaScriptOwnership from
1291 two different engines will not be valid if one of these engines is deleted. This option is similar
1292 to QScriptEngine::ScriptOwnership.
1293
1294 Generally an application doesn't need to set an object's ownership explicitly. The JavaScript
1295 memory manager uses a heuristic to set the default ownership. By default, an object that is
1296 created by the JavaScript memory manager has JavaScriptOwnership. The exception to this are the
1297 root objects created by calling QQmlComponent::create() or QQmlComponent::beginCreate(), which
1298 have CppOwnership by default. The ownership of these root-level objects is considered to have been
1299 transferred to the C++ caller.
1300
1301 Objects not-created by the JavaScript memory manager have CppOwnership by default. The exception
1302 to this are objects returned from C++ method calls; their ownership will be set to
1303 JavaScriptOwnership. This applies only to explicit invocations of Q_INVOKABLE methods or slots,
1304 but not to property getter invocations.
1305
1306 Calling setObjectOwnership() overrides the default ownership.
1307
1308 \sa {Data Ownership}
1309*/
1310
1311/*!
1312 Sets the \a ownership of \a object.
1313
1314 An object with \c JavaScriptOwnership is not garbage collected as long
1315 as it still has a parent, even if there are no references to it.
1316
1317 \sa QJSEngine::ObjectOwnership
1318*/
1319void QJSEngine::setObjectOwnership(QObject *object, ObjectOwnership ownership)
1320{
1321 if (!object)
1322 return;
1323
1324 QQmlData *ddata = QQmlData::get(object, create: true);
1325 if (!ddata)
1326 return;
1327
1328 ddata->indestructible = (ownership == CppOwnership)?true:false;
1329 ddata->explicitIndestructibleSet = true;
1330}
1331
1332/*!
1333 Returns the ownership of \a object.
1334
1335 \sa QJSEngine::ObjectOwnership
1336*/
1337QJSEngine::ObjectOwnership QJSEngine::objectOwnership(QObject *object)
1338{
1339 if (!object)
1340 return CppOwnership;
1341
1342 QQmlData *ddata = QQmlData::get(object, create: false);
1343 if (!ddata)
1344 return CppOwnership;
1345 else
1346 return ddata->indestructible?CppOwnership:JavaScriptOwnership;
1347}
1348
1349QT_END_NAMESPACE
1350
1351#include "moc_qjsengine.cpp"
1352

source code of qtdeclarative/src/qml/jsapi/qjsengine.cpp