1 /*

     2     Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies)

     3 

     4     This library is free software; you can redistribute it and/or

     5     modify it under the terms of the GNU Library General Public

     6     License as published by the Free Software Foundation; either

     7     version 2 of the License, or (at your option) any later version.

     8 

     9     This library is distributed in the hope that it will be useful,

    10     but WITHOUT ANY WARRANTY; without even the implied warranty of

    11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    12     Library General Public License for more details.

    13 

    14     You should have received a copy of the GNU Library General Public License

    15     along with this library; see the file COPYING.LIB.  If not, write to

    16     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,

    17     Boston, MA 02110-1301, USA.

    18 */

    19 

    20 #include "config.h"

    21 

    22 #include "qscriptengine.h"

    23 

    24 #include "qscriptengine_p.h"

    25 #include "qscriptprogram_p.h"

    26 #include "qscriptsyntaxcheckresult_p.h"

    27 #include "qscriptvalue_p.h"

    28 

    29 /*!

    30     Constructs a QScriptEngine object.

    31 

    32     The globalObject() is initialized to have properties as described in ECMA-262, Section 15.1.

    33 */

    34 QScriptEngine::QScriptEngine()

    35     : d_ptr(new QScriptEnginePrivate(this))

    36 {

    37 }

    38 

    39 /*!

    40     Destroys this QScriptEngine.

    41 */

    42 QScriptEngine::~QScriptEngine()

    43 {

    44 }

    45 

    46 /*!

    47   Checks the syntax of the given \a program. Returns a

    48   QScriptSyntaxCheckResult object that contains the result of the check.

    49 */

    50 QScriptSyntaxCheckResult QScriptEngine::checkSyntax(const QString &program)

    51 {

    52     // FIXME This is not optimal.

    53     // The JSC C API needs a context to perform a syntax check, it means that a QScriptEnginePrivate

    54     // had to be created. This function is static so we have to create QScriptEnginePrivate for each

    55     // call. We can't remove the "static" for compatibility reason, at least up to Qt5.

    56     // QScriptSyntaxCheckResultPrivate takes ownership of newly created engine. The engine will be

    57     // kept as long as it is needed for lazy evaluation of properties of

    58     // the QScriptSyntaxCheckResultPrivate.

    59     QScriptEnginePrivate* engine = new QScriptEnginePrivate(/* q_ptr */ 0);

    60     return QScriptSyntaxCheckResultPrivate::get(engine->checkSyntax(program));

    61 }

    62 

    63 /*!

    64     Evaluates \a program, using \a lineNumber as the base line number,

    65     and returns the result of the evaluation.

    66 

    67     The script code will be evaluated in the current context.

    68 

    69     The evaluation of \a program can cause an exception in the

    70     engine; in this case the return value will be the exception

    71     that was thrown (typically an \c{Error} object). You can call

    72     hasUncaughtException() to determine if an exception occurred in

    73     the last call to evaluate().

    74 

    75     \a lineNumber is used to specify a starting line number for \a

    76     program; line number information reported by the engine that pertain

    77     to this evaluation (e.g. uncaughtExceptionLineNumber()) will be

    78     based on this argument. For example, if \a program consists of two

    79     lines of code, and the statement on the second line causes a script

    80     exception, uncaughtExceptionLineNumber() would return the given \a

    81     lineNumber plus one. When no starting line number is specified, line

    82     numbers will be 1-based.

    83 

    84     \a fileName is used for error reporting. For example in error objects

    85     the file name is accessible through the "fileName" property if it's

    86     provided with this function.

    87 */

    88 QScriptValue QScriptEngine::evaluate(const QString& program, const QString& fileName, int lineNumber)

    89 {

    90     return QScriptValuePrivate::get(d_ptr->evaluate(program, fileName, lineNumber));

    91 }

    92 

    93 QScriptValue QScriptEngine::evaluate(const QScriptProgram& program)

    94 {

    95     return QScriptValuePrivate::get(d_ptr->evaluate(QScriptProgramPrivate::get(program)));

    96 }

    97 

    98 /*!

    99     Returns true if the last script evaluation resulted in an uncaught

   100     exception; otherwise returns false.

   101 

   102     The exception state is cleared when evaluate() is called.

   103 

   104     \sa uncaughtException(), uncaughtExceptionLineNumber(),

   105       uncaughtExceptionBacktrace()

   106 */

   107 bool QScriptEngine::hasUncaughtException() const

   108 {

   109     return d_ptr->hasUncaughtException();

   110 }

   111 

   112 /*!

   113     Returns the current uncaught exception, or an invalid QScriptValue

   114     if there is no uncaught exception.

   115 

   116     The exception value is typically an \c{Error} object; in that case,

   117     you can call toString() on the return value to obtain an error

   118     message.

   119 

   120     \sa hasUncaughtException(), uncaughtExceptionLineNumber(),

   121       uncaughtExceptionBacktrace()

   122 */

   123 QScriptValue QScriptEngine::uncaughtException() const

   124 {

   125     return QScriptValuePrivate::get(d_ptr->uncaughtException());

   126 }

   127 

   128 /*!

   129     Clears any uncaught exceptions in this engine.

   130 

   131     \sa hasUncaughtException()

   132 */

   133 void QScriptEngine::clearExceptions()

   134 {

   135     d_ptr->clearExceptions();

   136 }

   137 

   138 /*!

   139     Returns the line number where the last uncaught exception occurred.

   140 

   141     Line numbers are 1-based, unless a different base was specified as

   142     the second argument to evaluate().

   143 

   144     \sa hasUncaughtException(), uncaughtExceptionBacktrace()

   145 */

   146 int QScriptEngine::uncaughtExceptionLineNumber() const

   147 {

   148     return d_ptr->uncaughtExceptionLineNumber();

   149 }

   150 

   151 /*!

   152     Returns a human-readable backtrace of the last uncaught exception.

   153 

   154     Each line is of the form \c{<function-name>(<arguments>)@<file-name>:<line-number>}.

   155 

   156     \sa uncaughtException()

   157 */

   158 QStringList QScriptEngine::uncaughtExceptionBacktrace() const

   159 {

   160     return d_ptr->uncaughtExceptionBacktrace();

   161 }

   162 

   163 /*!

   164     Runs the garbage collector.

   165 

   166     The garbage collector will attempt to reclaim memory by locating and disposing of objects that are

   167     no longer reachable in the script environment.

   168 

   169     Normally you don't need to call this function; the garbage collector will automatically be invoked

   170     when the QScriptEngine decides that it's wise to do so (i.e. when a certain number of new objects

   171     have been created). However, you can call this function to explicitly request that garbage

   172     collection should be performed as soon as possible.

   173 

   174     \sa reportAdditionalMemoryCost()

   175 */

   176 void QScriptEngine::collectGarbage()

   177 {

   178     d_ptr->collectGarbage();

   179 }

   180 

   181 /*!

   182   Reports an additional memory cost of the given \a size, measured in

   183   bytes, to the garbage collector.

   184 

   185   This function can be called to indicate that a JavaScript object has

   186   memory associated with it that isn't managed by Qt Script itself.

   187   Reporting the additional cost makes it more likely that the garbage

   188   collector will be triggered.

   189 

   190   Note that if the additional memory is shared with objects outside

   191   the scripting environment, the cost should not be reported, since

   192   collecting the JavaScript object would not cause the memory to be

   193   freed anyway.

   194 

   195   Negative \a size values are ignored, i.e. this function can't be

   196   used to report that the additional memory has been deallocated.

   197 

   198   \sa collectGarbage()

   199 */

   200 void QScriptEngine::reportAdditionalMemoryCost(int cost)

   201 {

   202     d_ptr->reportAdditionalMemoryCost(cost);

   203 }

   204 

   205 /*!

   206   Returns a handle that represents the given string, \a str.

   207 

   208   QScriptString can be used to quickly look up properties, and

   209   compare property names, of script objects.

   210 

   211   \sa QScriptValue::property()

   212 */

   213 QScriptString QScriptEngine::toStringHandle(const QString& str)

   214 {

   215     return QScriptStringPrivate::get(d_ptr->toStringHandle(str));

   216 }

   217 

   218 /*!

   219   Converts the given \a value to an object, if such a conversion is

   220   possible; otherwise returns an invalid QScriptValue. The conversion

   221   is performed according to the following table:

   222 

   223     \table

   224     \header \o Input Type \o Result

   225     \row    \o Undefined  \o An invalid QScriptValue.

   226     \row    \o Null       \o An invalid QScriptValue.

   227     \row    \o Boolean    \o A new Boolean object whose internal value is set to the value of the boolean.

   228     \row    \o Number     \o A new Number object whose internal value is set to the value of the number.

   229     \row    \o String     \o A new String object whose internal value is set to the value of the string.

   230     \row    \o Object     \o The result is the object itself (no conversion).

   231     \endtable

   232 

   233     \sa newObject()

   234 */

   235 QScriptValue QScriptEngine::toObject(const QScriptValue& value)

   236 {

   237     return QScriptValuePrivate::get(QScriptValuePrivate::get(value)->toObject(d_ptr.data()));

   238 }

   239 

   240 /*!

   241   Returns a QScriptValue of the primitive type Null.

   242 

   243   \sa undefinedValue()

   244 */

   245 QScriptValue QScriptEngine::nullValue()

   246 {

   247     return QScriptValue(this, QScriptValue::NullValue);

   248 }

   249 

   250 /*!

   251   Returns a QScriptValue of the primitive type Undefined.

   252 

   253   \sa nullValue()

   254 */

   255 QScriptValue QScriptEngine::undefinedValue()

   256 {

   257     return QScriptValue(this, QScriptValue::UndefinedValue);

   258 }

   259 

   260 /*!

   261   Creates a QtScript object of class Object.

   262 

   263   The prototype of the created object will be the Object

   264   prototype object.

   265 

   266   \sa newArray(), QScriptValue::setProperty()

   267 */

   268 QScriptValue QScriptEngine::newObject()

   269 {

   270     return QScriptValuePrivate::get(d_ptr->newObject());

   271 }

   272 

   273 /*!

   274   Creates a QtScript object of class Array with the given \a length.

   275 

   276   \sa newObject()

   277 */

   278 QScriptValue QScriptEngine::newArray(uint length)

   279 {

   280     return QScriptValuePrivate::get(d_ptr->newArray(length));

   281 }

   282 

   283 /*!

   284   Returns this engine's Global Object.

   285 

   286   By default, the Global Object contains the built-in objects that are

   287   part of \l{ECMA-262}, such as Math, Date and String. Additionally,

   288   you can set properties of the Global Object to make your own

   289   extensions available to all script code. Non-local variables in

   290   script code will be created as properties of the Global Object, as

   291   well as local variables in global code.

   292 */

   293 QScriptValue QScriptEngine::globalObject() const

   294 {

   295     return QScriptValuePrivate::get(d_ptr->globalObject());

   296 }