QoreProgram Class Reference

supports parsing and executing Qore-language code, reference counted, dynamically-allocated only More...

#include <QoreProgram.h>

Inheritance diagram for QoreProgram:
AbstractPrivateData QoreReferenceCounter

List of all members.

Public Member Functions

DLLEXPORT QoreProgram ()
 creates the object
DLLEXPORT QoreProgram (int64 parse_options)
 creates the object and sets the parse options
DLLEXPORT AbstractQoreNodecallFunction (const char *name, const QoreListNode *args, ExceptionSink *xsink)
 calls a function from the function name and returns the return value
DLLEXPORT AbstractQoreNoderun (ExceptionSink *xsink)
 runs the program (instantiates the program class if a program class has been set) and returns the return value (if any)
DLLEXPORT AbstractQoreNoderunTopLevel (ExceptionSink *xsink)
 tuns the top level code and returns any return value
DLLEXPORT void parseFileAndRun (const char *filename)
 parses the given filename and runs the file
DLLEXPORT void parseAndRun (FILE *fp, const char *name)
 parses the given file and runs the file
DLLEXPORT void parseAndRun (const char *str, const char *name)
 parses the given string and runs the code
DLLEXPORT void runClass (const char *classname, ExceptionSink *xsink)
 instantiates the class given and runs its constructor
DLLEXPORT void parseFileAndRunClass (const char *filename, const char *classname)
 parses the given filename and runs the program by instantiating the class given
DLLEXPORT void parseAndRunClass (FILE *fp, const char *name, const char *classname)
 parses the given file and runs the code by instantiating the class given
DLLEXPORT void parseAndRunClass (const char *str, const char *name, const char *classname)
 parses the given string and runs the code by instantiating the class given
DLLEXPORT void parse (FILE *fp, const char *name, ExceptionSink *xsink, ExceptionSink *warn_sink=0, int warn_mask=QP_WARN_ALL)
 parses code from the file given and commits changes to the QoreProgram
DLLEXPORT void parse (const QoreString *str, const QoreString *lstr, ExceptionSink *xsink, ExceptionSink *warn_sink=0, int warn_mask=QP_WARN_ALL)
 parses code from the given string and commits changes to the QoreProgram
DLLEXPORT void parse (const char *str, const char *lstr, ExceptionSink *xsink, ExceptionSink *warn_sink=0, int warn_mask=QP_WARN_ALL)
 parses code from the given string and commits changes to the QoreProgram
DLLEXPORT void parseFile (const char *filename, ExceptionSink *xsink, ExceptionSink *warn_sink=0, int warn_mask=QP_WARN_ALL, bool only_first_except=false)
 parses code from the file given and commits changes to the QoreProgram
DLLEXPORT void parsePending (const char *code, const char *label, ExceptionSink *xsink, ExceptionSink *warn_sink=0, int warn_mask=QP_WARN_ALL)
 parses code from the given string but does not commit changes to the QoreProgram
DLLEXPORT void parsePending (const QoreString *str, const QoreString *lstr, ExceptionSink *xsink, ExceptionSink *warn_sink=0, int warn_mask=QP_WARN_ALL)
 parses code from the given string but does not commit changes to the QoreProgram
DLLEXPORT void parseCommit (ExceptionSink *xsink, ExceptionSink *warn_sink=0, int warn_mask=QP_WARN_ALL)
 commits pending changes to the program
DLLEXPORT void parseRollback ()
 rolls back changes to the program object that were added with QoreProgram::parsePending()
DLLEXPORT bool existsFunction (const char *name)
 returns true if the given function exists as a user function, false if not
virtual DLLEXPORT void deref (ExceptionSink *xsink)
 decrements the reference count of the object
DLLEXPORT void lockOptions ()
 locks parse options so they may not be changed
DLLEXPORT void setExecClass (const char *ecn=0)
 sets the name of the application class to be executed (instantiated) instead of top-level code
DLLEXPORT void parseSetParseOptions (int po)
 adds the parse options given to the parse option mask; DEPRECATED: use parseSetParseOptions(int64) instead
DLLEXPORT void parseSetParseOptions (int64 po)
 adds the parse options given to the parse option mask
DLLEXPORT void waitForTermination ()
 this call blocks until the program's last thread terminates
DLLEXPORT void waitForTerminationAndDeref (ExceptionSink *xsink)
 this call blocks until the program's last thread terminates, and then calls QoreProgram::deref()
DLLEXPORT QoreNamespacegetQoreNS () const
 returns a pointer to the "Qore" namespace
DLLEXPORT RootQoreNamespacegetRootNS () const
 returns a pointer to the root namespace
DLLEXPORT int setWarningMask (int wm)
 sets the warning mask
DLLEXPORT int enableWarning (int code)
 enables a warning by its code
DLLEXPORT int disableWarning (int code)
 disables a warning by its code
DLLEXPORT int getParseOptions () const
 returns the parse options currently set for this program; DEPRECATED; use getParseOptions64() instead
DLLEXPORT int64 getParseOptions64 () const
 returns the parse options currently set for this program
DLLEXPORT void setParseOptions (int po, ExceptionSink *xsink)
 sets the parse options and adds Qore-language exception information if an error occurs
DLLEXPORT void setParseOptions (int64 po, ExceptionSink *xsink)
 sets the parse options and adds Qore-language exception information if an error occurs
DLLEXPORT void disableParseOptions (int po, ExceptionSink *xsink)
 turns off the parse options given in the passed mask and adds Qore-language exception information if an error occurs
DLLEXPORT void disableParseOptions (int64 po, ExceptionSink *xsink)
 turns off the parse options given in the passed mask and adds Qore-language exception information if an error occurs
DLLEXPORT QoreListNodegetUserFunctionList ()
 returns a list of all user functions in this program
DLLEXPORT bool checkWarning (int code) const
 returns true if the warning code is set
DLLEXPORT int getWarningMask () const
 returns the warning mask
DLLEXPORT bool checkFeature (const char *f) const
 returns true if the given feature is present in the program object
DLLEXPORT QoreListNodegetFeatureList () const
 returns a list of features in the program object
DLLEXPORT QoreStringNodegetScriptName () const
 returns the script file name, if known (0 if not)
DLLEXPORT QoreStringNodegetScriptPath () const
 returns the script path (directory and name), if known (0 if not)
DLLEXPORT QoreStringNodegetScriptDir () const
 returns the script directory, if known (0 if not)
DLLEXPORT void setScriptPath (const char *path)
 sets the script path
DLLEXPORT AbstractQoreNodegetGlobalVariableValue (const char *var, bool &found) const
 returns the value of the global variable given (do not include the "$" symbol), the caller owns the reference count returned
DLLLOCAL UserFunction * findUserFunction (const char *name)
 returns a pointed to the given user function if it exists (otherwise returns 0)
DLLLOCAL const char * parseGetScriptDir () const
 returns the script directory, if known (0 if not), does not grab the parse lock, only to be called while parsing

Protected Member Functions

virtual DLLLOCAL ~QoreProgram ()
 the destructor is private in order to prohibit the object from being allocated on the stack

Detailed Description

supports parsing and executing Qore-language code, reference counted, dynamically-allocated only

This class implements a transaction and thread-safe container for qore-language code This class implements two-layered reference counting to address problems with circular references. When a program has a global variable that contains an object that references the program... objects now reference the dependency counter, so when the object's counter reaches zero and the global variable list is deleted, then the variables will in turn dereference the program so it can be deleted.


Constructor & Destructor Documentation

virtual DLLLOCAL QoreProgram::~QoreProgram (  )  [protected, virtual]

the destructor is private in order to prohibit the object from being allocated on the stack

the destructor is run when the reference count reaches 0

DLLEXPORT QoreProgram::QoreProgram ( int64  parse_options  ) 

creates the object and sets the parse options

Parameters:
parse_options the parse options mask for the QoreProgram object

Member Function Documentation

DLLEXPORT AbstractQoreNode* QoreProgram::callFunction ( const char *  name,
const QoreListNode args,
ExceptionSink xsink 
)

calls a function from the function name and returns the return value

if the function does not exist, an exception is added to "xsink"

Parameters:
name the name of the function to call
args the argument to the function (can be 0)
xsink if an error occurs, the Qore-language exception information will be added here
virtual DLLEXPORT void QoreProgram::deref ( ExceptionSink xsink  )  [virtual]

decrements the reference count of the object

Parameters:
xsink any Qore-language exception information is stored here

Reimplemented from AbstractPrivateData.

DLLEXPORT void QoreProgram::disableParseOptions ( int64  po,
ExceptionSink xsink 
)

turns off the parse options given in the passed mask and adds Qore-language exception information if an error occurs

Parameters:
po the parse options to subtract from the parse option mask
xsink if an error occurs, the Qore-language exception information will be added here
DLLEXPORT void QoreProgram::disableParseOptions ( int  po,
ExceptionSink xsink 
)

turns off the parse options given in the passed mask and adds Qore-language exception information if an error occurs

DEPRECATED: use disableParseOptions(int64, ...) instead

Parameters:
po the parse options to subtract from the parse option mask
xsink if an error occurs, the Qore-language exception information will be added here
DLLEXPORT int QoreProgram::disableWarning ( int  code  ) 

disables a warning by its code

Parameters:
code the warning code to disable
Returns:
0 for success, -1 for error
DLLEXPORT int QoreProgram::enableWarning ( int  code  ) 

enables a warning by its code

Parameters:
code the warning code to enable
Returns:
0 for success, -1 for error
DLLEXPORT AbstractQoreNode* QoreProgram::getGlobalVariableValue ( const char *  var,
bool &  found 
) const

returns the value of the global variable given (do not include the "$" symbol), the caller owns the reference count returned

Parameters:
var the variable name to return (do not include the "$" symbol)
found returns true if the variable exists, false if not
Returns:
the value of the global variable given; if a non-zero pointer is returned, the caller owns the reference count returned
DLLEXPORT QoreStringNode* QoreProgram::getScriptDir (  )  const

returns the script directory, if known (0 if not)

Returns:
the script directory, if known (0 if not)
DLLEXPORT QoreStringNode* QoreProgram::getScriptName (  )  const

returns the script file name, if known (0 if not)

Returns:
the script file name, if known (0 if not)
DLLEXPORT QoreStringNode* QoreProgram::getScriptPath (  )  const

returns the script path (directory and name), if known (0 if not)

Returns:
the script path (directory and name), if known (0 if not)
DLLEXPORT QoreListNode* QoreProgram::getUserFunctionList (  ) 

returns a list of all user functions in this program

Returns:
a list of all user functions in this program
DLLEXPORT void QoreProgram::parse ( const char *  str,
const char *  lstr,
ExceptionSink xsink,
ExceptionSink warn_sink = 0,
int  warn_mask = QP_WARN_ALL 
)

parses code from the given string and commits changes to the QoreProgram

Note:
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
str the code to parse; the encoding of the string is assumed to be QCS_DEFAULT
lstr the label of the code being parsed to be used as a file name
xsink if an error occurs, the Qore-language exception information will be added here
warn_sink if a warning is raised, the warning information will be added here
warn_mask the warning mask to set (-1 sets all possible warnings)
DLLEXPORT void QoreProgram::parse ( const QoreString str,
const QoreString lstr,
ExceptionSink xsink,
ExceptionSink warn_sink = 0,
int  warn_mask = QP_WARN_ALL 
)

parses code from the given string and commits changes to the QoreProgram

Note:
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
str the code to parse
lstr the label of the code being parsed to be used as a file name
xsink if an error occurs, the Qore-language exception information will be added here
warn_sink if a warning is raised, the warning information will be added here
warn_mask the warning mask to set (-1 sets all possible warnings)
DLLEXPORT void QoreProgram::parse ( FILE *  fp,
const char *  name,
ExceptionSink xsink,
ExceptionSink warn_sink = 0,
int  warn_mask = QP_WARN_ALL 
)

parses code from the file given and commits changes to the QoreProgram

Note:
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
fp the filename to parse
name the name of the file being parsed and run
xsink if an error occurs, the Qore-language exception information will be added here
warn_sink if a warning is raised, the warning information will be added here
warn_mask the warning mask to set (-1 sets all possible warnings)
DLLEXPORT void QoreProgram::parseAndRun ( const char *  str,
const char *  name 
)

parses the given string and runs the code

The default exception handler is run on any Qore-language exceptions raised while parsing and executing the code.

Note:
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref()
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
str the Qore-language code to parse and run
name the label of the code being parsed and run (used as the file name)
DLLEXPORT void QoreProgram::parseAndRun ( FILE *  fp,
const char *  name 
)

parses the given file and runs the file

the default exception handler is run on any Qore-language exceptions raised while parsing and executing the file.

Note:
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref()
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
fp the filename to run
name the name of the file being parsed and run
DLLEXPORT void QoreProgram::parseAndRunClass ( const char *  str,
const char *  name,
const char *  classname 
)

parses the given string and runs the code by instantiating the class given

The default exception handler is run on any Qore-language exceptions raised while parsing and executing the code.

Note:
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref()
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
str the Qore-language code to parse and run
name the label of the code being parsed and run (used as the file name)
classname the name of the class to instantiate
DLLEXPORT void QoreProgram::parseAndRunClass ( FILE *  fp,
const char *  name,
const char *  classname 
)

parses the given file and runs the code by instantiating the class given

The default exception handler is run on any Qore-language exceptions raised while parsing and executing the file.

Note:
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref()
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
fp the filename to run
name the name of the file being parsed and run
classname the name of the class to instantiate
DLLEXPORT void QoreProgram::parseCommit ( ExceptionSink xsink,
ExceptionSink warn_sink = 0,
int  warn_mask = QP_WARN_ALL 
)

commits pending changes to the program

See also:
QoreProgram::parsePending()
QoreProgram::parseRollback()
DLLEXPORT void QoreProgram::parseFile ( const char *  filename,
ExceptionSink xsink,
ExceptionSink warn_sink = 0,
int  warn_mask = QP_WARN_ALL,
bool  only_first_except = false 
)

parses code from the file given and commits changes to the QoreProgram

Also sets the script path.

Note:
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
filename the filename to open and parse
xsink if an error occurs, the Qore-language exception information will be added here
warn_sink if a warning is raised, the warning information will be added here
warn_mask the warning mask to set (-1 sets all possible warnings)
only_first_except is flag to stop parsing exceptions printing after 1st exception
DLLEXPORT void QoreProgram::parseFileAndRun ( const char *  filename  ) 

parses the given filename and runs the file

any errors opening the file are added as Qore-language exceptions the default exception handler is run on any Qore-language exceptions raised during opening, parsing, and executing the file.

Note:
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref(). Also sets the script path.
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
filename the filename to run
DLLEXPORT void QoreProgram::parseFileAndRunClass ( const char *  filename,
const char *  classname 
)

parses the given filename and runs the program by instantiating the class given

Any errors opening the file are added as Qore-language exceptions. The default exception handler is run on any Qore-language exceptions raised during opening, parsing, and executing the file.

Note:
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref(). Also sets the script path.
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
filename the filename to run
classname the name of the class to instantiate
DLLLOCAL const char* QoreProgram::parseGetScriptDir (  )  const

returns the script directory, if known (0 if not), does not grab the parse lock, only to be called while parsing

Returns:
the script directory, if known (0 if not)
DLLEXPORT void QoreProgram::parsePending ( const QoreString str,
const QoreString lstr,
ExceptionSink xsink,
ExceptionSink warn_sink = 0,
int  warn_mask = QP_WARN_ALL 
)

parses code from the given string but does not commit changes to the QoreProgram

Parameters:
str the code to parse
lstr the label of the code being parsed to be used as a file name
xsink if an error occurs, the Qore-language exception information will be added here
warn_sink if a warning is raised, the warning information will be added here
warn_mask the warning mask to set (-1 sets all possible warnings)
See also:
QoreProgram::parseCommit()
QoreProgram::parseRollback()
DLLEXPORT void QoreProgram::parsePending ( const char *  code,
const char *  label,
ExceptionSink xsink,
ExceptionSink warn_sink = 0,
int  warn_mask = QP_WARN_ALL 
)

parses code from the given string but does not commit changes to the QoreProgram

Parameters:
code the code to parse; the encoding of the string is assumed to be QCS_DEFAULT
label the label of the code being parsed to be used as a file name
xsink if an error occurs, the Qore-language exception information will be added here
warn_sink if a warning is raised, the warning information will be added here
warn_mask the warning mask to set (-1 sets all possible warnings)
See also:
QoreProgram::parseCommit()
QoreProgram::parseRollback()
DLLEXPORT void QoreProgram::parseRollback (  ) 

rolls back changes to the program object that were added with QoreProgram::parsePending()

See also:
QoreProgram::parsePending()
QoreProgram::parseCommit()
DLLEXPORT AbstractQoreNode* QoreProgram::run ( ExceptionSink xsink  ) 

runs the program (instantiates the program class if a program class has been set) and returns the return value (if any)

Note:
if the program is run as a class it's not possible to return a value
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref()
See also:
QoreProgram::setExecClass()
Parameters:
xsink if an error occurs, the Qore-language exception information will be added here
Returns:
the value returned by the final return statement (if any, can be 0)
DLLEXPORT void QoreProgram::runClass ( const char *  classname,
ExceptionSink xsink 
)

instantiates the class given and runs its constructor

Note:
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref()
will also commit any pending changes added with QoreProgram::parsePending()
Parameters:
classname the name of the class to instantiate
xsink if an error occurs, the Qore-language exception information will be added here
DLLEXPORT AbstractQoreNode* QoreProgram::runTopLevel ( ExceptionSink xsink  ) 

tuns the top level code and returns any return value

Note:
any threads started by this call will continue running in the background, to wait for them to terminate, call QoreProgram::waitForTermination() or QoreProgram::waitForTerminationAndDeref()
Parameters:
xsink if an error occurs, the Qore-language exception information will be added here
Returns:
the value returned by the final return statement (if any, can be 0)
DLLEXPORT void QoreProgram::setExecClass ( const char *  ecn = 0  ) 

sets the name of the application class to be executed (instantiated) instead of top-level code

normally parse option PO_NO_TOP_LEVEL_STATEMENTS should be set as well

Note:
the string passed here will copied
Parameters:
ecn the name of the class to be executed as the program class
See also:
QoreProgram::parseSetParseOptions()
DLLEXPORT void QoreProgram::setParseOptions ( int64  po,
ExceptionSink xsink 
)

sets the parse options and adds Qore-language exception information if an error occurs

Parameters:
po the parse options to add to the parse option mask
xsink if an error occurs, the Qore-language exception information will be added here
DLLEXPORT void QoreProgram::setParseOptions ( int  po,
ExceptionSink xsink 
)

sets the parse options and adds Qore-language exception information if an error occurs

DEPRECATED: use setParseOptions(int64, ...)

Parameters:
po the parse options to add to the parse option mask
xsink if an error occurs, the Qore-language exception information will be added here
DLLEXPORT void QoreProgram::setScriptPath ( const char *  path  ) 

sets the script path

Parameters:
path the directory and filename of the script (set to 0 to clear)
DLLEXPORT int QoreProgram::setWarningMask ( int  wm  ) 

sets the warning mask

Parameters:
wm the new warning mask
Returns:
0 for success, -1 for error
DLLEXPORT void QoreProgram::waitForTerminationAndDeref ( ExceptionSink xsink  ) 

this call blocks until the program's last thread terminates, and then calls QoreProgram::deref()

Parameters:
xsink if an error occurs, the Qore-language exception information will be added here

Referenced by QoreProgramHelper::~QoreProgramHelper().


The documentation for this class was generated from the following file:

Generated on 14 Jun 2010 for Qore Programming Language by  doxygen 1.6.1