/* vim: set ts=4 sw=4 tw=99 et:

  *

  * Copyright (C) 2004-2012 David Anderson

  *

  * This file is part of SourcePawn.

  *

  * SourcePawn is free software: you can redistribute it and/or modify it under

  * the terms of the GNU General Public License as published by the Free

  * Software Foundation, either version 3 of the License, or (at your option)

  * any later version.

  * 

  * SourcePawn is distributed in the hope that it will be useful, but WITHOUT ANY

  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

  * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  *

  * You should have received a copy of the GNU General Public License along with

  * SourcePawn. If not, see http://www.gnu.org/licenses/.

  */

 #ifndef _include_sourcepawn2_api_h_

 #define _include_sourcepawn2_api_h_

 #include <assert.h>

 #include <stddef.h>

 #include "../include/keima_util.h"

 namespace ke {

 class Zone;

 class Object;

 class HandleScope;

 class HeapRoot;

 }

 namespace Ke {

 class Function;

 class Package;

 /*

  * A Handle is a safe pointer that holds an object reference, such that it

  * can be scanned and potentially moved by the garbage collector.

  */

 template <typename T>

 class Handle

 {

     template <typename S> friend class Root;

   protected:

     template <typename S> void typeCheck() {

         while (false) {

             T *v1 = NULL;

             S *v2 = NULL;

             v1 = v2;

             (void)v1;

         }

     }

   public:

     Handle()

       : obj_(NULL)

     {

     }

     template <typename S> Handle(Handle<S> other)

       : obj_(reinterpret_cast<S *>(*other))

     {

         typeCheck<S>();

     }

     explicit Handle(T *obj)

       : obj_(obj)

     {

     }

     T *operator ->() const {

         return obj_;

     }

     T *operator *() const {

         return obj_;

     }

     operator bool () const {

         return !!obj_;

     }

   protected:

     T *obj_;

 };

 /*

  * A local variable that roots an object. Locals are owned by the nearest

  * HandleScope, and as soon as that HandleScope dies, all its Locals are

  * no longer available.

  */

 template <typename T>

 class Local : public Handle<T>

 {

   public:

     Local()

       : Handle<T>()

     {

     }

     template <typename S> Local(Local<S> other)

       : Handle<T>(reinterpret_cast<T *>(*other))

     {

         this->template typeCheck<S>();

     }

     template <typename S> Local(S *other)

       : Handle<T>(other)

     {

     }

 };

 /*

  * A non-local variable that outlives HandleScopes. Unlike Local, a Root

  * actually represents a rooted location. Roots must be allocated and

  * disposed, and assignment to a root changes its contained object, not

  * the location of the object.

  */

 template <typename T>

 class Root

 {

   public:

     Root()

       : root_(NULL)

     {

     }

     Root(Handle<T> other)

       : root_(NULL)

     {

         set(other);

     }

     inline ~Root();

     operator const Handle<T>() const {

         return obj_;

     }

     bool operator ==(Handle<T> other) {

         return Handle<T>(*this) == other;

     }

     Root<T> &operator =(Handle<T> other) {

         set(other);

         return *this;

     }

   private:

     void set(Handle<T> other);

     ke::HeapRoot *root_;

     Handle<T> obj_;

 };

 /*

  * A HandleScope is where Local roots are allcoated. When the HandleScope

  * is destroyed, all Handles created under it are also destroyed. HandleScopes

  * may only be allocated on the stack, in LIFO order.

  */

 class HandleScope

 {

   protected:

     ke::Zone *zone_;

     ke::Object **position_;

     HandleScope *prev_;

     HandleScope(ke::Zone *zone, ke::Object **position, HandleScope *prev)

       : zone_(zone),

         position_(position),

         prev_(prev)

     {

     }

   public:

     HandleScope();

     ~HandleScope();

     static ke::Object **CreateHandle(ke::Object *obj);

   private:

     // Disallow silly stuff.

     HandleScope(const HandleScope &);

     void operator =(const HandleScope &);

     void *operator new (size_t size);

     void operator delete(void *, size_t);

 };

 class Parameter;

 // Error messages are pumped through this interface.

 class IMessageReporter

 {

   public:

     virtual void onOutOfMemory() {

     }

     virtual void onUncaughtException(const char *message) {

     }

     virtual void beginCompilationErrors(const char *file) {

     }

     virtual void reportCompilationError(const char *message, unsigned line, unsigned col) {

     }

     virtual void endCompilationErrors() {

     }

 };

 // For the purposes of error reporting, very basic information can be queried

 // about the stack frame. This structure may be used to retrieve such

 // information. During iteration, it is illegal to re-enter any scripted code

 // or call any Keima functions that may cause garbage collection.

 class IStackFrameIterator

 {

   public:

     virtual ~IStackFrameIterator() {

     }

     // Returns true if there are more frames, false otherwise.

     virtual bool done() = 0;

     // Returns the name of the current function. This may be NULL if the

     // function is anonymous.

     virtual const char *function() = 0;

     // Returns the file of the current function. This will return an invalid

     // path for C++ functions (for example, "<native>").

     virtual const char *source() = 0;

     // Returns the line number currently executing on this frame. For C++

     // functions, this is always 0.

     virtual unsigned lineNumber() = 0;

     // Advance to the previous frame in the call stack.

     virtual void prev() = 0;

 };

 // Listener interface for when public functions are registered or unregisted.

 class IPublicFunctionListener

 {

   public:

     virtual ~IPublicFunctionListener() {

     }

     // Called when a public function becomes available to the runtime.

     virtual void registerPublic(Handle<Function> fun) = 0;

     // Called when a public is no longer available to the runtime.

     virtual void unregisterPublic(Handle<Function> fun) = 0;

 };

 // A string is an immutable UTF8 buffer.

 class KE_EXPORT String

 {

   public:

     static Local<String> NewAscii(const char *str);

     // Returns the length of the string, in bytes.

     unsigned length();

     // Returns the character buffer of the string, or NULL on failure. If the

     // string is interned, chars() is guaranteed to succeed.

     const char *chars();

 };

 // A function is an executable unit of code.

 class KE_EXPORT Function

 {

   public:

     // Returns the name of a function, which may be NULL. If not NULL, the

     // string is guaranteed to be interned.

     Local<String> name();

     // Returns the package the function was created in.

     Local<Package> package();

 };

 // A pubvar is an ISourcePawnEngine-compatible structure that holds information

 // about public variables.

 class KE_EXPORT Pubvar

 {

   public:

     // Returns the name of a pubvar, which is never NULL. The string is

     // guaranteed to be interned.

     Local<String> name();

 };

 // A package is a collection of compiled files and possibly sub-packages.

 // Internally, packages are used to implement the "import" statement. However,

 // the host application can also create packages to organize related files,

 // restrict import visibility, or implement hot swapping of loaded modules.

 class KE_EXPORT Package

 {

   public:

     enum {

         Normal = 0,

         // The package cannot be accessed from any import statement.

         Hidden = (1 << 0),

         // Source files compiled in this package cannot import names in the

         // package.

         Jailed = (1 << 1)

     };

     // Creates a package. The parent package may be NULL. The name can be NULL

     // as well. |path| must be a filesystem path, which will be normalized 

     // according to OS-specific rules.

     static Local<Package> New(Handle<Package> parent,

                               Handle<String> name,

                               const char *path,

                               unsigned flags);

     // Returns the name of the package, which may be NULL. The string is

     // guaranteed to be interned.

     Local<String> name();

     // Returns the full path of the package. The string is guaranteed to be

     // interned.

     Local<String> path();

     // Sets the package's native identity. This is a host-application defined

     // value that is passed to native callbacks.  Packages created under this

     // one will automatically inherit this native identity.

     void setNativeIdentity(void *identity);

     // Returns the package's native identity, or NULL if none was set.

     void *getNativeIdentity();

 };

 class Keima

 {

   public:

     /*

      * Initializes the Keima engine. This must be called exactly once before any

      * other Keima functions are called. After this, it is safe to use Keima

      * on the calling thread only. It is not safe to race on calling this.

      */

     static bool Initialize();

     /*

      * Shuts down the Keima engine and frees data structures on all threads.

      */

     static void Shutdown();

     /*

      * Searches the call stack and returns true if the given package has any

      * active code running. This is an O(n) algorithm.

      */

     static bool IsInCallStack(Handle<Package> package);

     /*

      * Reclaim as much memory as possible. This pauses the calling thread

      * until garbage collection completes.

      */

     static void CollectGarbage();

     /*

      * Clear any pending exception.

      */

     static void ClearPendingException();

     /*

      * Executes a function with the given parameters. This interface is

      * intended for compatibility with SourceMod's ISourcePawnEngine2 and

      * should not be used otherwise, since it is intended to support only

      * a small subset of the core language.

      */

     static bool Invoke(Handle<Function> fun, const Parameter *params, unsigned nparams,

                        bool checkTypes, int *result);

     /*

      * Sets the global message handler through which errors will be reported

      */

     static void InstallMessageReporter(IMessageReporter *reporter);

     /* Returns a new stack frame iterator object. */

     static IStackFrameIterator *NewStackFrameIterator();

     /*

      * Binds a native, by name, to an address. Natives are an ISPE1 concept

      * (originally from Pawn/Small's AMX API). In SourceMod 1, natives were

      * registered globally, but bound to plugins individually. We roughly

      * preserve that functionality here, by allowing host applications to

      * give us the name -> address mappings.

      *

      * Natives can be rebound or unbound any number of times. This function

      * fails if there is not enough memory.

      */

     static bool BindNative(const char *name, void *address);

     /* Sets the object that will listen for public functions. */

     static void SetPublicFunctionListener(IPublicFunctionListener *listener);

     /*

      * Installs a system root folder. When an attempt to import locally fails,

      * the list of system roots are searched in the order they were installed.

      *

      * The given path must be absolute. It may contain a trailing slash.

      *

      * The name is an arbitrary, optional identifier that can be used to

      * build fully-qualified package identifiers.

      */

     static bool InstallSystemRoot(const char *path, const char *name);

     /*

      * Compiles a source file into a package and runs any initializers it has.

      * The file name must be a file name only, rather than a path. It may

      * optionally end in ".sp". If no ".sp" is provided, it is added

      * automatically.

      *

      * Note that if the file name (sans ".sp" extension) does not match the

      * regular expression /^[A-Za-z_][A-Za-z0-9_]+$/ then it will not be

      * importable from other files.

      */

     static bool Compile(Handle<Package> package, const char *name);

 };

 /*

  * Suppresses exceptions. This is useful for calling API functions. When this

  * in scope, errors will be reported, but the exception will be cleared after.

  */

 class AutoClearExceptions

 {

   public:

     ~AutoClearExceptions()

     {

         Keima::ClearPendingException();

     }

 };

 // Argument-passing interface for Invoke().

 class Parameter

 {

   public:

     enum Type {

         Int,

         Float,

         IntRef,

         FloatRef,

         Array,

         CharArray

     };

     Parameter()

     {

     }

     Parameter(int i)

       : type_(Int)

     {

         u.i = i;

     }

     Parameter(int *i, bool writeback)

       : type_(IntRef),

         writeback_(writeback)

     {

         u.ip = i;

     }

     Parameter(float f)

       : type_(Float)

     {

         u.f = f;

     }

     Parameter(float *f, bool writeback)

       : type_(FloatRef),

         writeback_(writeback)

     {

         u.fp = f;

     }

     Parameter(Type type, void *buffer, size_t length, bool writeback)

       : type_(type),

         writeback_(writeback),

         length_(length)

     {

         assert(type == Array || type == CharArray);

         u.buffer = buffer;

     }

     Type type() const {

         return type_;

     }

     int i32() const {

         assert(type() == Int);

         return u.i;

     }

     float f() const {

         assert(type() == Float);

         return u.f;

     }

     int *i32p() const {

         assert(type() == IntRef);

         return u.ip;

     }

     float *fp() const {

         assert(type() == FloatRef);

         return u.fp;

     }

     bool writeback() const {

         assert(type() >= IntRef && type() <= CharArray);

         return writeback_;

     }

     size_t length() const {

         return length_;

     }

     void *buffer() const {

         assert(type() == Array || type() == CharArray);

         return u.buffer;

     }

   private:

     Type type_;

     bool writeback_;

     size_t length_;

     union {

         int i;

         float f;

         int *ip;

         float *fp;

         void *buffer;

     } u;

 };

 class Internals

 {

     template <typename T> friend class Root;

   private:

     static ke::HeapRoot *NewHeapRoot();

     static void Destroy(ke::HeapRoot *root);

 };

 template <typename T> void

 Root<T>::set(Handle<T> other)

 {

     if (!other) {

         obj_ = other;

         return;

     }

     ke::Object **ptr = reinterpret_cast<ke::Object **>(*other);

     if (!root_) {

         root_ = Internals::NewHeapRoot();

         if (!root_)

             return;

     }

     *reinterpret_cast<ke::Object **>(root_) = *ptr;

     obj_.obj_ = reinterpret_cast<T *>(root_);

 }

 template <typename T>

 Root<T>::~Root()

 {

     if (!root_)

         return;

     Internals::Destroy(root_);

 }

 }

 #endif // _include_sourcepawn2_api_h_