1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtScript module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL-ONLY$

    10 ** GNU Lesser General Public License Usage

    11 ** This file may be used under the terms of the GNU Lesser

    12 ** General Public License version 2.1 as published by the Free Software

    13 ** Foundation and appearing in the file LICENSE.LGPL included in the

    14 ** packaging of this file.  Please review the following information to

    15 ** ensure the GNU Lesser General Public License version 2.1 requirements

    16 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    17 **

    18 ** If you have questions regarding the use of this file, please contact

    19 ** Nokia at qt-info@nokia.com.

    20 ** $QT_END_LICENSE$

    21 **

    22 ****************************************************************************/

    23 

    24 #ifndef QSCRIPTENGINE_H

    25 #define QSCRIPTENGINE_H

    26 

    27 #include <QtCore/qmetatype.h>

    28 

    29 #include <QtCore/qvariant.h>

    30 #include <QtCore/qsharedpointer.h>

    31 

    32 #ifndef QT_NO_QOBJECT

    33 #include <QtCore/qobject.h>

    34 #else

    35 #include <QtCore/qobjectdefs.h>

    36 #endif

    37 

    38 #include <QtScript/qscriptvalue.h>

    39 #include <QtScript/qscriptcontext.h>

    40 #include <QtScript/qscriptstring.h>

    41 #include <QtScript/qscriptprogram.h>

    42 

    43 QT_BEGIN_HEADER

    44 

    45 QT_BEGIN_NAMESPACE

    46 

    47 QT_MODULE(Script)

    48 

    49 class QDateTime;

    50 class QScriptClass;

    51 class QScriptEngineAgent;

    52 class QScriptEnginePrivate;

    53 

    54 #ifndef QT_NO_QOBJECT

    55 

    56 template <class T>

    57 inline QScriptValue qscriptQMetaObjectConstructor(QScriptContext *, QScriptEngine *, T *)

    58 {

    59     return QScriptValue();

    60 }

    61 

    62 #endif // QT_NO_QOBJECT

    63 

    64 #ifndef QT_NO_REGEXP

    65 class QRegExp;

    66 #endif

    67 

    68 #ifndef QT_NO_MEMBER_TEMPLATES

    69 template <typename T>

    70 inline QScriptValue qScriptValueFromValue(QScriptEngine *, const T &);

    71 

    72 template <typename T>

    73 inline T qScriptValueToValue(const QScriptValue &);

    74 #endif

    75 

    76 class QScriptSyntaxCheckResultPrivate;

    77 class Q_SCRIPT_EXPORT QScriptSyntaxCheckResult

    78 {

    79 public:

    80     enum State {

    81         Error,

    82         Intermediate,

    83         Valid

    84     };

    85 

    86     QScriptSyntaxCheckResult(const QScriptSyntaxCheckResult &other);

    87     ~QScriptSyntaxCheckResult();

    88 

    89     State state() const;

    90     int errorLineNumber() const;

    91     int errorColumnNumber() const;

    92     QString errorMessage() const;

    93 

    94     QScriptSyntaxCheckResult &operator=(const QScriptSyntaxCheckResult &other);

    95 

    96 private:

    97     QScriptSyntaxCheckResult();

    98     QScriptSyntaxCheckResult(QScriptSyntaxCheckResultPrivate *d);

    99     QExplicitlySharedDataPointer<QScriptSyntaxCheckResultPrivate> d_ptr;

   100 

   101     Q_DECLARE_PRIVATE(QScriptSyntaxCheckResult)

   102     friend class QScriptEngine;

   103     friend class QScriptEnginePrivate;

   104 };

   105 

   106 class Q_SCRIPT_EXPORT QScriptEngine

   107 #ifndef QT_NO_QOBJECT

   108     : public QObject

   109 #endif

   110 {

   111 #ifndef QT_NO_QOBJECT

   112     Q_OBJECT

   113 #endif

   114 public:

   115     enum ValueOwnership {

   116         QtOwnership,

   117         ScriptOwnership,

   118         AutoOwnership

   119     };

   120 

   121     enum QObjectWrapOption {

   122         ExcludeChildObjects = 0x0001,

   123         ExcludeSuperClassMethods = 0x0002,

   124         ExcludeSuperClassProperties = 0x0004,

   125         ExcludeSuperClassContents = 0x0006,

   126         SkipMethodsInEnumeration = 0x0008,

   127         ExcludeDeleteLater = 0x0010,

   128 

   129         AutoCreateDynamicProperties = 0x0100,

   130         PreferExistingWrapperObject = 0x0200

   131     };

   132     Q_DECLARE_FLAGS(QObjectWrapOptions, QObjectWrapOption)

   133 

   134     QScriptEngine();

   135 #ifndef QT_NO_QOBJECT

   136     explicit QScriptEngine(QObject *parent);

   137 #endif

   138     virtual ~QScriptEngine();

   139 

   140     QScriptValue globalObject() const;

   141     void setGlobalObject(const QScriptValue &object);

   142 

   143     QScriptContext *currentContext() const;

   144     QScriptContext *pushContext();

   145     void popContext();

   146 

   147     bool canEvaluate(const QString &program) const;

   148     static QScriptSyntaxCheckResult checkSyntax(const QString &program);

   149 

   150     QScriptValue evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1);

   151 

   152     QScriptValue evaluate(const QScriptProgram &program);

   153 

   154     bool isEvaluating() const;

   155     void abortEvaluation(const QScriptValue &result = QScriptValue());

   156 

   157     bool hasUncaughtException() const;

   158     QScriptValue uncaughtException() const;

   159     int uncaughtExceptionLineNumber() const;

   160     QStringList uncaughtExceptionBacktrace() const;

   161     void clearExceptions();

   162 

   163     QScriptValue nullValue();

   164     QScriptValue undefinedValue();

   165 

   166     typedef QScriptValue (*FunctionSignature)(QScriptContext *, QScriptEngine *);

   167     typedef QScriptValue (*FunctionWithArgSignature)(QScriptContext *, QScriptEngine *, void *);

   168 

   169     QScriptValue newFunction(FunctionSignature signature, int length = 0);

   170     QScriptValue newFunction(FunctionSignature signature, const QScriptValue &prototype, int length = 0);

   171 

   172     QScriptValue newFunction(FunctionWithArgSignature signature, void *arg);

   173 

   174     QScriptValue newVariant(const QVariant &value);

   175     QScriptValue newVariant(const QScriptValue &object, const QVariant &value);

   176 

   177 #ifndef QT_NO_REGEXP

   178     QScriptValue newRegExp(const QRegExp &regexp);

   179 #endif

   180 

   181     QScriptValue newObject();

   182     QScriptValue newObject(QScriptClass *scriptClass, const QScriptValue &data = QScriptValue());

   183     QScriptValue newArray(uint length = 0);

   184     QScriptValue newRegExp(const QString &pattern, const QString &flags);

   185     QScriptValue newDate(qsreal value);

   186     QScriptValue newDate(const QDateTime &value);

   187     QScriptValue newActivationObject();

   188 

   189 #ifndef QT_NO_QOBJECT

   190     QScriptValue newQObject(QObject *object, ValueOwnership ownership = QtOwnership,

   191                             const QObjectWrapOptions &options = 0);

   192     QScriptValue newQObject(const QScriptValue &scriptObject, QObject *qtObject,

   193                             ValueOwnership ownership = QtOwnership,

   194                             const QObjectWrapOptions &options = 0);

   195 

   196     QScriptValue newQMetaObject(const QMetaObject *metaObject, const QScriptValue &ctor = QScriptValue());

   197 

   198 #  ifndef QT_NO_MEMBER_TEMPLATES

   199     template <class T> QScriptValue scriptValueFromQMetaObject();

   200 #  endif // QT_NO_MEMBER_TEMPLATES

   201 

   202 #endif // QT_NO_QOBJECT

   203 

   204 

   205 

   206     QScriptValue defaultPrototype(int metaTypeId) const;

   207     void setDefaultPrototype(int metaTypeId, const QScriptValue &prototype);

   208 

   209 

   210     typedef QScriptValue (*MarshalFunction)(QScriptEngine *, const void *);

   211     typedef void (*DemarshalFunction)(const QScriptValue &, void *);

   212 

   213 

   214 

   215 #ifndef QT_NO_MEMBER_TEMPLATES

   216     template <typename T>

   217     inline QScriptValue toScriptValue(const T &value)

   218     {

   219         return qScriptValueFromValue(this, value);

   220     }

   221     template <typename T>

   222     inline T fromScriptValue(const QScriptValue &value)

   223     {

   224         return qScriptValueToValue<T>(value);

   225     }

   226 #endif // QT_NO_MEMBER_TEMPLATES

   227 

   228     void installTranslatorFunctions(const QScriptValue &object = QScriptValue());

   229 

   230     QScriptValue importExtension(const QString &extension);

   231     QStringList availableExtensions() const;

   232     QStringList importedExtensions() const;

   233 

   234     void collectGarbage();

   235 

   236     void setProcessEventsInterval(int interval);

   237     int processEventsInterval() const;

   238 

   239     void setAgent(QScriptEngineAgent *agent);

   240     QScriptEngineAgent *agent() const;

   241 

   242     QScriptString toStringHandle(const QString &str);

   243     QScriptValue toObject(const QScriptValue &value);

   244 

   245     QScriptValue objectById(qint64 id) const;

   246 

   247 #ifndef QT_NO_QOBJECT

   248 Q_SIGNALS:

   249     void signalHandlerException(const QScriptValue &exception);

   250 #endif

   251 

   252 private:

   253     QScriptValue create(int type, const void *ptr);

   254 

   255     bool convert(const QScriptValue &value, int type, void *ptr);

   256     static bool convertV2(const QScriptValue &value, int type, void *ptr);

   257 

   258     void registerCustomType(int type, MarshalFunction mf, DemarshalFunction df,

   259                             const QScriptValue &prototype);

   260 

   261     friend inline void qScriptRegisterMetaType_helper(QScriptEngine *,

   262         int, MarshalFunction, DemarshalFunction, const QScriptValue &);

   263 

   264     friend inline QScriptValue qScriptValueFromValue_helper(QScriptEngine *, int, const void *);

   265 

   266     friend inline bool qscriptvalue_cast_helper(const QScriptValue &, int, void *);

   267 

   268 protected:

   269 #ifdef QT_NO_QOBJECT

   270     QScopedPointer<QScriptEnginePrivate> d_ptr;

   271 

   272     QScriptEngine(QScriptEnginePrivate &dd);

   273 #else

   274     QScriptEngine(QScriptEnginePrivate &dd, QObject *parent = 0);

   275 #endif

   276 

   277 private:

   278     Q_DECLARE_PRIVATE(QScriptEngine)

   279     Q_DISABLE_COPY(QScriptEngine)

   280 #ifndef QT_NO_QOBJECT

   281     Q_PRIVATE_SLOT(d_func(), void _q_objectDestroyed(QObject *))

   282 #endif

   283 };

   284 

   285 #ifndef QT_NO_QOBJECT

   286 template <class T>

   287 inline QScriptValue qScriptValueFromQMetaObject(

   288     QScriptEngine *engine

   289 #ifndef qdoc

   290     , T * /* dummy */ = 0

   291 #endif

   292     )

   293 {

   294     typedef QScriptValue(*ConstructPtr)(QScriptContext *, QScriptEngine *, T *);

   295     ConstructPtr cptr = qscriptQMetaObjectConstructor<T>;

   296     return engine->newQMetaObject(&T::staticMetaObject,

   297                                   engine->newFunction(reinterpret_cast<QScriptEngine::FunctionWithArgSignature>(cptr), 0));

   298 }

   299 

   300 #define Q_SCRIPT_DECLARE_QMETAOBJECT(T, _Arg1) \

   301 template<> inline QScriptValue qscriptQMetaObjectConstructor<T>(QScriptContext *ctx, QScriptEngine *eng, T *) \

   302 { \

   303     _Arg1 arg1 = qscriptvalue_cast<_Arg1> (ctx->argument(0)); \

   304     T* t = new T(arg1); \

   305     if (ctx->isCalledAsConstructor()) \

   306         return eng->newQObject(ctx->thisObject(), t, QScriptEngine::AutoOwnership); \

   307     QScriptValue o = eng->newQObject(t, QScriptEngine::AutoOwnership); \

   308     o.setPrototype(ctx->callee().property(QString::fromLatin1("prototype"))); \

   309     return o; \

   310 }

   311 

   312 #  ifndef QT_NO_MEMBER_TEMPLATES

   313     template <class T> QScriptValue QScriptEngine::scriptValueFromQMetaObject()

   314     {

   315         return qScriptValueFromQMetaObject<T>(this);

   316     }

   317 #  endif // QT_NO_MEMBER_TEMPLATES

   318 

   319 #endif // QT_NO_QOBJECT

   320 

   321 inline QScriptValue qScriptValueFromValue_helper(QScriptEngine *engine, int type, const void *ptr)

   322 {

   323     if (!engine)

   324         return QScriptValue();

   325 

   326     return engine->create(type, ptr);

   327 }

   328 

   329 template <typename T>

   330 inline QScriptValue qScriptValueFromValue(QScriptEngine *engine, const T &t)

   331 {

   332     return qScriptValueFromValue_helper(engine, qMetaTypeId<T>(), &t);

   333 }

   334 

   335 template <>

   336 inline QScriptValue qScriptValueFromValue<QVariant>(QScriptEngine *engine, const QVariant &v)

   337 {

   338     QScriptValue result = qScriptValueFromValue_helper(engine, v.userType(), v.data());

   339     if (!result.isValid())

   340         result = engine->newVariant(v);

   341     return result;

   342 }

   343 

   344 inline bool qscriptvalue_cast_helper(const QScriptValue &value, int type, void *ptr)

   345 {

   346     return QScriptEngine::convertV2(value, type, ptr);

   347 }

   348 

   349 template<typename T>

   350 T qscriptvalue_cast(const QScriptValue &value

   351 #if !defined qdoc && defined Q_CC_MSVC && _MSC_VER < 1300

   352 , T * = 0

   353 #endif

   354     )

   355 {

   356     T t;

   357     const int id = qMetaTypeId<T>();

   358 

   359     if (qscriptvalue_cast_helper(value, id, &t))

   360         return t;

   361     else if (value.isVariant())

   362         return qvariant_cast<T>(value.toVariant());

   363 

   364     return T();

   365 }

   366 

   367 #if !defined Q_CC_MSVC || _MSC_VER >= 1300

   368 template <>

   369 inline QVariant qscriptvalue_cast<QVariant>(const QScriptValue &value)

   370 {

   371     return value.toVariant();

   372 }

   373 #endif

   374 

   375 template <typename T>

   376 inline T qScriptValueToValue(const QScriptValue &value)

   377 {

   378     return qscriptvalue_cast<T>(value);

   379 }

   380 

   381 inline void qScriptRegisterMetaType_helper(QScriptEngine *eng, int type,

   382                                            QScriptEngine::MarshalFunction mf,

   383                                            QScriptEngine::DemarshalFunction df,

   384                                            const QScriptValue &prototype)

   385 {

   386     eng->registerCustomType(type, mf, df, prototype);

   387 }

   388 

   389 template<typename T>

   390 int qScriptRegisterMetaType(

   391     QScriptEngine *eng,

   392     QScriptValue (*toScriptValue)(QScriptEngine *, const T &t),

   393     void (*fromScriptValue)(const QScriptValue &, T &t),

   394     const QScriptValue &prototype = QScriptValue()

   395 #ifndef qdoc

   396     , T * /* dummy */ = 0

   397 #endif

   398 )

   399 {

   400     const int id = qRegisterMetaType<T>(); // make sure it's registered

   401 

   402     qScriptRegisterMetaType_helper(

   403         eng, id, reinterpret_cast<QScriptEngine::MarshalFunction>(toScriptValue),

   404         reinterpret_cast<QScriptEngine::DemarshalFunction>(fromScriptValue),

   405         prototype);

   406 

   407     return id;

   408 }

   409 

   410 template <class Container>

   411 QScriptValue qScriptValueFromSequence(QScriptEngine *eng, const Container &cont)

   412 {

   413     QScriptValue a = eng->newArray();

   414     typename Container::const_iterator begin = cont.begin();

   415     typename Container::const_iterator end = cont.end();

   416     typename Container::const_iterator it;

   417     quint32 i;

   418     for (it = begin, i = 0; it != end; ++it, ++i)

   419         a.setProperty(i, qScriptValueFromValue(eng, *it));

   420     return a;

   421 }

   422 

   423 template <class Container>

   424 void qScriptValueToSequence(const QScriptValue &value, Container &cont)

   425 {

   426     quint32 len = value.property(QLatin1String("length")).toUInt32();

   427     for (quint32 i = 0; i < len; ++i) {

   428         QScriptValue item = value.property(i);

   429 #if defined Q_CC_MSVC && !defined Q_CC_MSVC_NET

   430         cont.push_back(qscriptvalue_cast<Container::value_type>(item));

   431 #else

   432         cont.push_back(qscriptvalue_cast<typename Container::value_type>(item));

   433 #endif

   434     }

   435 }

   436 

   437 template<typename T>

   438 int qScriptRegisterSequenceMetaType(

   439     QScriptEngine *engine,

   440     const QScriptValue &prototype = QScriptValue()

   441 #ifndef qdoc

   442     , T * /* dummy */ = 0

   443 #endif

   444 )

   445 {

   446     return qScriptRegisterMetaType<T>(engine, qScriptValueFromSequence,

   447                                       qScriptValueToSequence, prototype);

   448 }

   449 

   450 #ifndef QT_NO_QOBJECT

   451 Q_SCRIPT_EXPORT bool qScriptConnect(QObject *sender, const char *signal,

   452                                     const QScriptValue &receiver,

   453                                     const QScriptValue &function);

   454 Q_SCRIPT_EXPORT bool qScriptDisconnect(QObject *sender, const char *signal,

   455                                        const QScriptValue &receiver,

   456                                        const QScriptValue &function);

   457 #endif // QT_NO_QOBJECT

   458 

   459 Q_DECLARE_OPERATORS_FOR_FLAGS(QScriptEngine::QObjectWrapOptions)

   460 

   461 QT_END_NAMESPACE

   462 

   463 QT_END_HEADER

   464 

   465 #endif // QSCRIPTENGINE_H