engineExports.h

Public Functions

DECLARE_SCOPE(ReflectionAPI )

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _ENGINEEXPORTS_H_
 25#define _ENGINEEXPORTS_H_
 26
 27#ifndef _ENGINEOBJECT_H_
 28   #include "console/engineObject.h"
 29#endif
 30
 31
 32/// @file
 33/// Foundation for the engine API export system.
 34///
 35/// The engine DLL exposes a well-defined API that the control layer can
 36/// use to interface with the engine.  The structure of this API is accessible
 37/// through 
 38///
 39/// The system is primarily meant to allow mechanical extraction and processing
 40/// of the API.  It is not meant to be used as a direct means to actually interface
 41/// with the engine.
 42///
 43/// All export classes are themselves EngineObjects so they can be used in the
 44/// API.  They are, however, all declared as non-instantiable classes.
 45
 46
 47class EngineExportScope;
 48
 49
 50DECLARE_SCOPE( ReflectionAPI );
 51
 52
 53/// Kind of entity being exported.
 54enum EngineExportKind
 55{
 56   EngineExportKindScope,     ///< A collection of exports grouped in a separate named scope.
 57   EngineExportKindFunction,  ///< A function call across the interop border going either in or out.
 58   EngineExportKindType       ///< A data type for data exchange between the engine and its control layer.  Note that types are also scopes.
 59};
 60
 61
 62/// Information about an entity exported by the engine API.  This is an abstract base
 63/// class.
 64class EngineExport : public StaticEngineObject
 65{
 66   public:
 67
 68      DECLARE_ABSTRACT_CLASS( EngineExport, StaticEngineObject );
 69      DECLARE_INSCOPE( ReflectionAPI );
 70      friend class EngineExportScope; // Default constructor.
 71   
 72   protected:
 73   
 74      /// Name of the export.  Never NULL but will be an empty string for anonymous
 75      /// exports such as function types.
 76      const char* mExportName;
 77
 78      /// Kind of export.
 79      EngineExportKind mExportKind;
 80   
 81      /// The scope in which this export is defined.
 82      EngineExportScope* mExportScope;
 83      
 84      /// Documentation string.
 85      const char* mDocString;
 86
 87      /// Next export in the link chain of the export's scope.
 88      EngineExport* mNextExport;
 89            
 90      /// Protected constructor as this is an abstract class.
 91      ///
 92      /// @param name Export name.
 93      /// @param kind Export kind.
 94      /// @param scope Scope to export to.
 95      /// @param docString Documentation string.
 96      EngineExport( const char* name, EngineExportKind kind, EngineExportScope* scope, const char* docString );
 97            
 98   public:
 99   
100      /// Return the name of the export.
101      const char* getExportName() const { return mExportName; }
102      
103      /// Return the fully qualified name of this export starting from the global export scope.
104      /// Qualifiers are separated with "::".
105      String getFullyQualifiedExportName() const;
106      
107      /// Return the kind of entity being exported.
108      EngineExportKind getExportKind() const { return mExportKind; }
109      
110      /// Return the scope that contains this export.  All exports except the global scope
111      /// itself are contained in a scope.
112      EngineExportScope* getExportScope() const { return mExportScope; }
113
114      /// Get the next export in the link chain of the export's associated scope.
115      EngineExport* getNextExport() const { return mNextExport; }
116
117      /// Return the documentation string for this type.
118      const char* getDocString() const { return mDocString; }
119
120   private:
121   
122      /// Special constructor for the global scope instance.
123      EngineExport()
124         : mExportName( "" ),
125           mExportKind( EngineExportKindScope ),
126           mExportScope( NULL ),
127           mNextExport( NULL ) {}
128};
129
130
131/// A group of engine exports.
132class EngineExportScope : public EngineExport
133{
134   public:
135   
136      DECLARE_CLASS( EngineExportScope, EngineExport );
137      friend class EngineExport; // mExports
138      friend struct _GLOBALSCOPE; // smGlobalScope
139      template< typename T > friend T* constructInPlace( T* );
140   
141   protected:
142      
143      /// Head of the link chain of exports for this scope.
144      EngineExport* mExports;
145      
146      /// The global export scope singleton.
147      static EngineExportScope smGlobalScope;
148   
149   public:
150   
151      /// Construct a new export scope.
152      ///
153      /// @param name Name of the scope inside its parent scope.
154      /// @param scope Parent scope.
155      /// @param docString Documentation string.
156      EngineExportScope( const char* name, EngineExportScope* scope, const char* docString );
157   
158      /// Return the global export scope singleton.  This is the root of the
159      /// export hierarchy and thus directly or indirectly contains all
160      /// entities exported by the engine.
161      static EngineExportScope* getGlobalScope() { return &smGlobalScope; }
162            
163      /// Return the chain of exports associated with this scope.
164      EngineExport* getExports() const { return mExports; }
165      
166   private:
167   
168      /// Constructor for the global scope.
169      EngineExportScope() {}
170};
171
172
173/// @}
174
175#endif // !_ENGINEEXPORTS_H_
176