qt/api/qscriptengine.cpp

   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     Runs the garbage collector.
 100
 101     The garbage collector will attempt to reclaim memory by locating and disposing of objects that are
 102     no longer reachable in the script environment.
 103
 104     Normally you don't need to call this function; the garbage collector will automatically be invoked
 105     when the QScriptEngine decides that it's wise to do so (i.e. when a certain number of new objects
 106     have been created). However, you can call this function to explicitly request that garbage
 107     collection should be performed as soon as possible.
 108
 109     \sa reportAdditionalMemoryCost()
 110 */
 111 void QScriptEngine::collectGarbage()
 112 {
 113     d_ptr->collectGarbage();
 114 }
 115
 116 /*!
 117   Reports an additional memory cost of the given \a size, measured in
 118   bytes, to the garbage collector.
 119
 120   This function can be called to indicate that a JavaScript object has
 121   memory associated with it that isn't managed by Qt Script itself.
 122   Reporting the additional cost makes it more likely that the garbage
 123   collector will be triggered.
 124
 125   Note that if the additional memory is shared with objects outside
 126   the scripting environment, the cost should not be reported, since
 127   collecting the JavaScript object would not cause the memory to be
 128   freed anyway.
 129
 130   Negative \a size values are ignored, i.e. this function can't be
 131   used to report that the additional memory has been deallocated.
 132
 133   \sa collectGarbage()
 134 */
 135 void QScriptEngine::reportAdditionalMemoryCost(int cost)
 136 {
 137     d_ptr->reportAdditionalMemoryCost(cost);
 138 }
 139
 140 /*!
 141   Returns a handle that represents the given string, \a str.
 142
 143   QScriptString can be used to quickly look up properties, and
 144   compare property names, of script objects.
 145
 146   \sa QScriptValue::property()
 147 */
 148 QScriptString QScriptEngine::toStringHandle(const QString& str)
 149 {
 150     return QScriptStringPrivate::get(d_ptr->toStringHandle(str));
 151 }
 152
 153 /*!
 154   Returns a QScriptValue of the primitive type Null.
 155
 156   \sa undefinedValue()
 157 */
 158 QScriptValue QScriptEngine::nullValue()
 159 {
 160     return QScriptValue(this, QScriptValue::NullValue);
 161 }
 162
 163 /*!
 164   Returns a QScriptValue of the primitive type Undefined.
 165
 166   \sa nullValue()
 167 */
 168 QScriptValue QScriptEngine::undefinedValue()
 169 {
 170     return QScriptValue(this, QScriptValue::UndefinedValue);
 171 }
 172
 173 /*!
 174   Returns this engine's Global Object.
 175
 176   By default, the Global Object contains the built-in objects that are
 177   part of \l{ECMA-262}, such as Math, Date and String. Additionally,
 178   you can set properties of the Global Object to make your own
 179   extensions available to all script code. Non-local variables in
 180   script code will be created as properties of the Global Object, as
 181   well as local variables in global code.
 182 */
 183 QScriptValue QScriptEngine::globalObject() const
 184 {
 185     return QScriptValuePrivate::get(d_ptr->globalObject());
 186 }