simgear/nasal/cppbind/Ghost.hxx

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