simgear/nasal/cppbind/Ghost.hxx

   1 ///@file Expose C++ objects to Nasal as ghosts
   2 //
   3 // Copyright (C) 2012  Thomas Geymayer <tomgey@gmail.com>
   4 //
   5 // This library is free software; you can redistribute it and/or
   6 // modify it under the terms of the GNU Library General Public
   7 // License as published by the Free Software Foundation; either
   8 // version 2 of the License, or (at your option) any later version.
   9 //
  10 // This library is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 // Library General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU Library General Public
  16 // License along with this library; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
  18
  19 #ifndef SG_NASAL_GHOST_HXX_
  20 #define SG_NASAL_GHOST_HXX_
  21
  22 #include "from_nasal.hxx"
  23 #include "to_nasal.hxx"
  24
  25 #include <simgear/debug/logstream.hxx>
  26
  27 #include <boost/bind.hpp>
  28 #include <boost/function.hpp>
  29 #include <boost/lambda/lambda.hpp>
  30 #include <boost/utility/enable_if.hpp>
  31
  32 namespace nasal
  33 {
  34
  35   /**
  36    * Traits for C++ classes exposed as Ghost. This is the basic template for
  37    * raw types.
  38    */
  39   template<class T>
  40   struct GhostTypeTraits
  41   {
  42     /** Whether the class is passed by shared pointer or raw pointer */
  43     typedef boost::false_type::type is_shared;
  44
  45     /** The raw class type (Without any shared pointer) */
  46     typedef T raw_type;
  47   };
  48
  49   template<class T>
  50   struct GhostTypeTraits<boost::shared_ptr<T> >
  51   {
  52     typedef boost::true_type::type is_shared;
  53     typedef T raw_type;
  54   };
  55
  56 #ifdef OSG_REF_PTR
  57   template<class T>
  58   struct GhostTypeTraits<osg::ref_ptr<T> >
  59   {
  60     typedef boost::true_type::type is_shared;
  61     typedef T raw_type;
  62   };
  63 #endif
  64
  65 #ifdef SGSharedPtr_HXX
  66   template<class T>
  67   struct GhostTypeTraits<SGSharedPtr<T> >
  68   {
  69     typedef boost::true_type::type is_shared;
  70     typedef T raw_type;
  71   };
  72 #endif
  73
  74   /**
  75    * Policy for creating ghost instances from shared pointer objects.
  76    */
  77   template<class T>
  78   struct SharedPointerPolicy
  79   {
  80     typedef typename GhostTypeTraits<T>::raw_type raw_type;
  81
  82     /**
  83      * Create a shared pointer on the heap to handle the reference counting for
  84      * the passed shared pointer while it is used in Nasal space.
  85      */
  86     static T* createInstance(const T& ptr)
  87     {
  88       return new T(ptr);
  89     }
  90
  91     static raw_type* getRawPtr(void* ptr)
  92     {
  93       return static_cast<T*>(ptr)->get();
  94     }
  95   };
  96
  97   /**
  98    * Policy for creating ghost instances as raw objects on the heap.
  99    */
 100   template<class T>
 101   struct RawPointerPolicy
 102   {
 103     typedef typename GhostTypeTraits<T>::raw_type raw_type;
 104
 105     /**
 106      * Create a new object instance on the heap
 107      */
 108     static T* createInstance()
 109     {
 110       return new T();
 111     }
 112
 113     static raw_type* getRawPtr(void* ptr)
 114     {
 115       BOOST_STATIC_ASSERT((boost::is_same<raw_type, T>::value));
 116       return static_cast<T*>(ptr);
 117     }
 118   };
 119
 120   namespace internal
 121   {
 122     /**
 123      * Metadata for Ghost object types
 124      */
 125     class GhostMetadata
 126     {
 127       public:
 128         /**
 129          * Add a nasal base class to the ghost. Will be available in the ghosts
 130          * parents array.
 131          */
 132         void addNasalBase(const naRef& parent)
 133         {
 134           assert( naIsHash(parent) );
 135           _parents.push_back(parent);
 136         }
 137
 138       protected:
 139         const std::string             _name;
 140         naGhostType                   _ghost_type;
 141   //      std::vector<GhostMetadata*>   _base_classes;
 142         std::vector<naRef>            _parents;
 143
 144         explicit GhostMetadata(const std::string& name):
 145           _name(name)
 146         {
 147
 148         }
 149
 150   //      void addBaseClass(GhostMetadata* base)
 151   //      {
 152   //        assert(base);
 153   //        _base_classes.push_back(base);
 154   //      }
 155
 156         naRef getParents(naContext c)
 157         {
 158           return nasal::to_nasal(c, _parents);
 159         }
 160     };
 161   }
 162
 163   /**
 164    * Class for exposing C++ objects to Nasal
 165    *
 166    * @code{cpp}
 167    * // Example class to be exposed to Nasal
 168    * class MyClass
 169    * {
 170    *   public:
 171    *     void setX(int x);
 172    *     int getX() const;
 173    *
 174    *     naRef myMember(int argc, naRef* args);
 175    * }
 176    *
 177    * void exposeClasses()
 178    * {
 179    *   // Register a nasal ghost type for MyClass. This needs to be done only
 180    *   // once before creating the first ghost instance.
 181    *   Ghost<MyClass>::init("MyClass")
 182    *     // Members can be exposed by getters and setters
 183    *     .member("x", &MyClass::getX, &MyClass::setX)
 184    *     // For readonly variables only pass a getter
 185    *     .member("x_readonly", &MyClass::getX)
 186    *     // It is also possible to expose writeonly members
 187    *     .member("x_writeonly", &MyClass::setX)
 188    *     // Methods use a slightly different syntax - The pointer to the member
 189    *     // function has to be passed as template argument
 190    *     .method<&MyClass::myMember>("myMember");
 191    * }
 192    * @endcode
 193    */
 194   template<class T>
 195   class Ghost:
 196     public internal::GhostMetadata,
 197     protected boost::mpl::if_< typename GhostTypeTraits<T>::is_shared,
 198                                SharedPointerPolicy<T>,
 199                                RawPointerPolicy<T> >::type
 200   {
 201     public:
 202       typedef typename GhostTypeTraits<T>::raw_type                 raw_type;
 203       typedef naRef (T::*member_func_t)(int, naRef*);
 204       typedef boost::function<naRef(naContext c, raw_type*)>        getter_t;
 205       typedef boost::function<void(naContext c, raw_type*, naRef)>  setter_t;
 206
 207       /**
 208        * A ghost member. Can consist either of getter and/or setter functions
 209        * for exposing a data variable or a single callable function.
 210        */
 211       struct member_t
 212       {
 213         member_t():
 214           func(0)
 215         {}
 216
 217         member_t( const getter_t& getter,
 218                   const setter_t& setter,
 219                   naCFunction func = 0 ):
 220           getter( getter ),
 221           setter( setter ),
 222           func( func )
 223         {}
 224
 225         member_t(naCFunction func):
 226           func( func )
 227         {}
 228
 229         getter_t    getter;
 230         setter_t    setter;
 231         naCFunction func;
 232       };
 233
 234       typedef std::map<std::string, member_t> MemberMap;
 235
 236       /**
 237        * Register a new ghost type.
 238        *
 239        * @param name    Descriptive name of the ghost type.
 240        */
 241       static Ghost& init(const std::string& name)
 242       {
 243         getSingletonHolder().reset( new Ghost(name) );
 244         return *getSingletonPtr();
 245       }
 246
 247       /**
 248        * Register a base class for this ghost. The base class needs to be
 249        * registers on its own before it can be used as base class.
 250        *
 251        * @tparam BaseGhost  Type of base class already wrapped into Ghost class
 252        *                    (Ghost<Base>)
 253        *
 254        * @code{cpp}
 255        * Ghost<MyBase>::init("MyBase");
 256        * Ghost<MyClass>::init("MyClass")
 257        *   .bases<Ghost<MyBase> >();
 258        * @endcode
 259        */
 260       template<class BaseGhost>
 261       typename boost::enable_if_c
 262         <    boost::is_base_of<GhostMetadata, BaseGhost>::value
 263           && boost::is_base_of<typename BaseGhost::raw_type, raw_type>::value,
 264           Ghost
 265         >::type&
 266       bases()
 267       {
 268         BaseGhost* base = BaseGhost::getSingletonPtr();
 269         //addBaseClass( base );
 270
 271         // Replace any getter that is not available in the current class.
 272         // TODO check if this is the correct behavior of function overriding
 273         for( typename BaseGhost::MemberMap::const_iterator member =
 274                base->_members.begin();
 275                member != base->_members.end();
 276              ++member )
 277         {
 278           if( _members.find(member->first) == _members.end() )
 279             _members[member->first] = member_t
 280             (
 281               member->second.getter,
 282               member->second.setter,
 283               member->second.func
 284             );
 285         }
 286
 287         return *this;
 288       }
 289
 290       /**
 291        * Register a base class for this ghost. The base class needs to be
 292        * registers on its own before it can be used as base class.
 293        *
 294        * @tparam Base   Type of base class (Base as used in Ghost<Base>)
 295        *
 296        * @code{cpp}
 297        * Ghost<MyBase>::init("MyBase");
 298        * Ghost<MyClass>::init("MyClass")
 299        *   .bases<MyBase>();
 300        * @endcode
 301        */
 302       template<class Base>
 303       typename boost::enable_if_c
 304         <   !boost::is_base_of<GhostMetadata, Base>::value
 305           && boost::is_base_of<typename Ghost<Base>::raw_type, raw_type>::value,
 306           Ghost
 307         >::type&
 308       bases()
 309       {
 310         return bases< Ghost<Base> >();
 311       }
 312
 313       /**
 314        * Register an existing Nasal class/hash as base class for this ghost.
 315        *
 316        * @param parent  Nasal hash/class
 317        */
 318       Ghost& bases(const naRef& parent)
 319       {
 320         addNasalBase(parent);
 321         return *this;
 322       }
 323
 324       /**
 325        * Register a member variable by passing a getter and/or setter method.
 326        *
 327        * @param field   Name of member
 328        * @param getter  Getter for variable
 329        * @param setter  Setter for variable (Pass 0 to prevent write access)
 330        *
 331        */
 332       template<class Var>
 333       Ghost& member( const std::string& field,
 334                      Var (raw_type::*getter)() const,
 335                      void (raw_type::*setter)(Var) = 0 )
 336       {
 337         member_t m;
 338         if( getter )
 339         {
 340           naRef (*to_nasal_)(naContext, Var) = &nasal::to_nasal;
 341
 342           // Getter signature: naRef(naContext, raw_type*)
 343           m.getter = boost::bind(to_nasal_, _1, boost::bind(getter, _2));
 344         }
 345
 346         if( setter )
 347         {
 348           Var (*from_nasal_)(naContext, naRef) = &nasal::from_nasal;
 349
 350           // Setter signature: void(naContext, raw_type*, naRef)
 351           m.setter = boost::bind(setter, _2, boost::bind(from_nasal_, _1, _3));
 352         }
 353
 354         return member(field, m.getter, m.setter);
 355       }
 356
 357       /**
 358        * Register a write only member variable.
 359        *
 360        * @param field   Name of member
 361        * @param setter  Setter for variable
 362        */
 363       template<class Var>
 364       Ghost& member( const std::string& field,
 365                      void (raw_type::*setter)(Var) )
 366       {
 367         return member<Var>(field, 0, setter);
 368       }
 369
 370       /**
 371        * Register a member variable by passing a getter and/or setter method.
 372        *
 373        * @param field   Name of member
 374        * @param getter  Getter for variable
 375        * @param setter  Setter for variable (Pass empty to prevent write access)
 376        *
 377        */
 378       Ghost& member( const std::string& field,
 379                      const getter_t& getter,
 380                      const setter_t& setter = setter_t() )
 381       {
 382         if( !getter.empty() || !setter.empty() )
 383           _members[field] = member_t(getter, setter);
 384         else
 385           SG_LOG
 386           (
 387             SG_NASAL,
 388             SG_WARN,
 389             "Member '" << field << "' requires a getter or setter"
 390           );
 391         return *this;
 392       }
 393
 394       /**
 395        * Register a member function.
 396        *
 397        * @note Because only function pointers can be registered as Nasal
 398        *       functions it is needed to pass the function pointer as template
 399        *       argument. This allows us to create a separate instance of the
 400        *       MemberFunctionWrapper for each registered function and therefore
 401        *       provides us with the needed static functions to be passed on to
 402        *       Nasal.
 403        *
 404        * @tparam func   Pointer to member function being registered.
 405        *
 406        * @code{cpp}
 407        * class MyClass
 408        * {
 409        *   public:
 410        *     naRef myMethod(int argc, naRef* args);
 411        * }
 412        *
 413        * Ghost<MyClass>::init("Test")
 414        *   .method<&MyClass::myMethod>("myMethod");
 415        * @endcode
 416        */
 417       template<member_func_t func>
 418       Ghost& method(const std::string& name)
 419       {
 420         _members[name].func = &MemberFunctionWrapper<func>::call;
 421         return *this;
 422       }
 423
 424       // TODO use variadic template when supporting C++11
 425       /**
 426        * Create a Nasal instance of this ghost.
 427        *
 428        * @param c   Active Nasal context
 429        */
 430       static naRef create( naContext c )
 431       {
 432         return makeGhost(c, Ghost::createInstance());
 433       }
 434
 435       /**
 436        * Create a Nasal instance of this ghost.
 437        *
 438        * @param c   Active Nasal context
 439        * @param a1  Parameter used for creating new instance
 440        */
 441       template<class A1>
 442       static naRef create( naContext c, const A1& a1 )
 443       {
 444         return makeGhost(c, Ghost::createInstance(a1));
 445       }
 446
 447       /**
 448        * Nasal callback for creating a new instance of this ghost.
 449        */
 450       static naRef f_create(naContext c, naRef me, int argc, naRef* args)
 451       {
 452         return create(c);
 453       }
 454
 455     private:
 456
 457       template<class>
 458       friend class Ghost;
 459
 460       static Ghost* getSingletonPtr()
 461       {
 462         return getSingletonHolder().get();
 463       }
 464
 465       /**
 466        * Wrapper class to enable registering pointers to member functions as
 467        * Nasal function callbacks. We need to use the function pointer as
 468        * template parameter to ensure every registered function gets a static
 469        * function which can be passed to Nasal.
 470        */
 471       template<member_func_t func>
 472       struct MemberFunctionWrapper
 473       {
 474         /**
 475          * Called from Nasal upon invocation of the according registered
 476          * function. Forwards the call to the passed object instance.
 477          */
 478         static naRef call(naContext c, naRef me, int argc, naRef* args)
 479         {
 480           if( naGhost_type(me) != &getSingletonPtr()->_ghost_type )
 481             naRuntimeError
 482             (
 483               c,
 484               "method called on object of wrong type: '%s' expected",
 485               getSingletonPtr()->_ghost_type.name
 486             );
 487
 488           raw_type* obj = Ghost::getRawPtr( static_cast<T*>(naGhost_ptr(me)) );
 489           assert(obj);
 490
 491           return (obj->*func)(argc, args);
 492         }
 493       };
 494
 495       typedef std::auto_ptr<Ghost> GhostPtr;
 496       MemberMap _members;
 497
 498       explicit Ghost(const std::string& name):
 499         GhostMetadata( name )
 500       {
 501         _ghost_type.destroy = &destroyGhost;
 502         _ghost_type.name = _name.c_str();
 503         _ghost_type.get_member = &getMember;
 504         _ghost_type.set_member = &setMember;
 505       }
 506
 507       static GhostPtr& getSingletonHolder()
 508       {
 509         static GhostPtr instance;
 510         return instance;
 511       }
 512
 513       static naRef makeGhost(naContext c, void *ptr)
 514       {
 515         return naNewGhost2(c, &getSingletonPtr()->_ghost_type, ptr);
 516       }
 517
 518       static void destroyGhost(void *ptr)
 519       {
 520         delete (T*)ptr;
 521       }
 522
 523       /**
 524        * Callback for retrieving a ghost member.
 525        */
 526       static const char* getMember(naContext c, void* g, naRef key, naRef* out)
 527       {
 528         const std::string key_str = nasal::from_nasal<std::string>(c, key);
 529         if( key_str == "parents" )
 530         {
 531           if( getSingletonPtr()->_parents.empty() )
 532             return 0;
 533
 534           *out = getSingletonPtr()->getParents(c);
 535           return "";
 536         }
 537
 538         typename MemberMap::iterator member =
 539           getSingletonPtr()->_members.find(key_str);
 540
 541         if( member == getSingletonPtr()->_members.end() )
 542           return 0;
 543
 544         if( member->second.func )
 545           *out = nasal::to_nasal(c, member->second.func);
 546         else if( !member->second.getter.empty() )
 547           *out = member->second.getter(c, Ghost::getRawPtr(g));
 548         else
 549           return "Read-protected member";
 550
 551         return "";
 552       }
 553
 554       /**
 555        * Callback for writing to a ghost member.
 556        */
 557       static void setMember(naContext c, void* g, naRef field, naRef val)
 558       {
 559         const std::string key = nasal::from_nasal<std::string>(c, field);
 560         typename MemberMap::iterator member =
 561           getSingletonPtr()->_members.find(key);
 562
 563         if( member == getSingletonPtr()->_members.end() )
 564           naRuntimeError(c, "ghost: No such member: %s", key.c_str());
 565         if( member->second.setter.empty() )
 566           naRuntimeError(c, "ghost: Write protected member: %s", key.c_str());
 567
 568         member->second.setter(c, Ghost::getRawPtr(g), val);
 569       }
 570   };
 571
 572 } // namespace nasal
 573
 574 #endif /* SG_NASAL_GHOST_HXX_ */