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     typedef boost::false_type returns_dynamic_type;
  88
  89     /**
  90      * Create a shared pointer on the heap to handle the reference counting for
  91      * the passed shared pointer while it is used in Nasal space.
  92      */
  93     static T* createInstance(const T& ptr)
  94     {
  95       return new T(ptr);
  96     }
  97
  98     static raw_type* getRawPtr(void* ptr)
  99     {
 100       return static_cast<T*>(ptr)->get();
 101     }
 102   };
 103
 104   /**
 105    * Policy for creating ghost instances as raw objects on the heap.
 106    */
 107   template<class T>
 108   struct RawPointerPolicy
 109   {
 110     typedef typename GhostTypeTraits<T>::raw_type raw_type;
 111     typedef boost::true_type returns_dynamic_type;
 112
 113     /**
 114      * Create a new object instance on the heap
 115      */
 116     static T* createInstance()
 117     {
 118       return new T();
 119     }
 120
 121     static raw_type* getRawPtr(void* ptr)
 122     {
 123       BOOST_STATIC_ASSERT((boost::is_same<raw_type, T>::value));
 124       return static_cast<T*>(ptr);
 125     }
 126   };
 127
 128   namespace internal
 129   {
 130     /**
 131      * Metadata for Ghost object types
 132      */
 133     class GhostMetadata
 134     {
 135       public:
 136         /**
 137          * Add a nasal base class to the ghost. Will be available in the ghosts
 138          * parents array.
 139          */
 140         void addNasalBase(const naRef& parent)
 141         {
 142           assert( naIsHash(parent) );
 143           _parents.push_back(parent);
 144         }
 145
 146       protected:
 147         const std::string             _name;
 148         naGhostType                   _ghost_type;
 149   //      std::vector<GhostMetadata*>   _base_classes;
 150         std::vector<naRef>            _parents;
 151
 152         explicit GhostMetadata(const std::string& name):
 153           _name(name)
 154         {
 155
 156         }
 157
 158   //      void addBaseClass(GhostMetadata* base)
 159   //      {
 160   //        assert(base);
 161   //        _base_classes.push_back(base);
 162   //      }
 163
 164         naRef getParents(naContext c)
 165         {
 166           return nasal::to_nasal(c, _parents);
 167         }
 168     };
 169   }
 170
 171   /**
 172    * Class for exposing C++ objects to Nasal
 173    *
 174    * @code{cpp}
 175    * // Example class to be exposed to Nasal
 176    * class MyClass
 177    * {
 178    *   public:
 179    *     void setX(int x);
 180    *     int getX() const;
 181    *
 182    *     naRef myMember(naContext c, int argc, naRef* args);
 183    * }
 184    *
 185    * void exposeClasses()
 186    * {
 187    *   // Register a nasal ghost type for MyClass. This needs to be done only
 188    *   // once before creating the first ghost instance.
 189    *   Ghost<MyClass>::init("MyClass")
 190    *     // Members can be exposed by getters and setters
 191    *     .member("x", &MyClass::getX, &MyClass::setX)
 192    *     // For readonly variables only pass a getter
 193    *     .member("x_readonly", &MyClass::getX)
 194    *     // It is also possible to expose writeonly members
 195    *     .member("x_writeonly", &MyClass::setX)
 196    *     // Methods use a slightly different syntax - The pointer to the member
 197    *     // function has to be passed as template argument
 198    *     .method<&MyClass::myMember>("myMember");
 199    * }
 200    * @endcode
 201    */
 202   template<class T>
 203   class Ghost:
 204     public internal::GhostMetadata,
 205     protected boost::mpl::if_< typename GhostTypeTraits<T>::is_shared,
 206                                SharedPointerPolicy<T>,
 207                                RawPointerPolicy<T> >::type
 208   {
 209     public:
 210       typedef typename GhostTypeTraits<T>::raw_type                 raw_type;
 211       typedef naRef (raw_type::*member_func_t)(naContext, int, naRef*);
 212       typedef naRef (*free_func_t)(raw_type&, naContext, int, naRef*);
 213       typedef boost::function<naRef(naContext, raw_type*)>        getter_t;
 214       typedef boost::function<void(naContext, raw_type*, naRef)>  setter_t;
 215
 216       /**
 217        * A ghost member. Can consist either of getter and/or setter functions
 218        * for exposing a data variable or a single callable function.
 219        */
 220       struct member_t
 221       {
 222         member_t():
 223           func(0)
 224         {}
 225
 226         member_t( const getter_t& getter,
 227                   const setter_t& setter,
 228                   naCFunction func = 0 ):
 229           getter( getter ),
 230           setter( setter ),
 231           func( func )
 232         {}
 233
 234         member_t(naCFunction func):
 235           func( func )
 236         {}
 237
 238         getter_t    getter;
 239         setter_t    setter;
 240         naCFunction func;
 241       };
 242
 243       typedef std::map<std::string, member_t> MemberMap;
 244
 245       /**
 246        * Register a new ghost type.
 247        *
 248        * @note Only intialize each ghost type once!
 249        *
 250        * @param name    Descriptive name of the ghost type.
 251        */
 252       static Ghost& init(const std::string& name)
 253       {
 254         assert( !getSingletonPtr() );
 255
 256         getSingletonHolder().reset( new Ghost(name) );
 257         return *getSingletonPtr();
 258       }
 259
 260       /**
 261        * Register a base class for this ghost. The base class needs to be
 262        * registers on its own before it can be used as base class.
 263        *
 264        * @tparam BaseGhost  Type of base class already wrapped into Ghost class
 265        *                    (Ghost<Base>)
 266        *
 267        * @code{cpp}
 268        * Ghost<MyBase>::init("MyBase");
 269        * Ghost<MyClass>::init("MyClass")
 270        *   .bases<Ghost<MyBase> >();
 271        * @endcode
 272        */
 273       template<class BaseGhost>
 274       typename boost::enable_if_c
 275         <    boost::is_base_of<GhostMetadata, BaseGhost>::value
 276           && boost::is_base_of<typename BaseGhost::raw_type, raw_type>::value,
 277           Ghost
 278         >::type&
 279       bases()
 280       {
 281         BaseGhost* base = BaseGhost::getSingletonPtr();
 282         base->addDerived( &getTypeFor<BaseGhost> );
 283
 284         // Replace any getter that is not available in the current class.
 285         // TODO check if this is the correct behavior of function overriding
 286         for( typename BaseGhost::MemberMap::const_iterator member =
 287                base->_members.begin();
 288                member != base->_members.end();
 289              ++member )
 290         {
 291           if( _members.find(member->first) == _members.end() )
 292             _members[member->first] = member_t
 293             (
 294               member->second.getter,
 295               member->second.setter,
 296               member->second.func
 297             );
 298         }
 299
 300         return *this;
 301       }
 302
 303       /**
 304        * Register a base class for this ghost. The base class needs to be
 305        * registers on its own before it can be used as base class.
 306        *
 307        * @tparam Base   Type of base class (Base as used in Ghost<Base>)
 308        *
 309        * @code{cpp}
 310        * Ghost<MyBase>::init("MyBase");
 311        * Ghost<MyClass>::init("MyClass")
 312        *   .bases<MyBase>();
 313        * @endcode
 314        */
 315       template<class Base>
 316       typename boost::enable_if_c
 317         <   !boost::is_base_of<GhostMetadata, Base>::value
 318           && boost::is_base_of<typename Ghost<Base>::raw_type, raw_type>::value,
 319           Ghost
 320         >::type&
 321       bases()
 322       {
 323         return bases< Ghost<Base> >();
 324       }
 325
 326       /**
 327        * Register an existing Nasal class/hash as base class for this ghost.
 328        *
 329        * @param parent  Nasal hash/class
 330        */
 331       Ghost& bases(const naRef& parent)
 332       {
 333         addNasalBase(parent);
 334         return *this;
 335       }
 336
 337       /**
 338        * Register a member variable by passing a getter and/or setter method.
 339        *
 340        * @param field   Name of member
 341        * @param getter  Getter for variable
 342        * @param setter  Setter for variable (Pass 0 to prevent write access)
 343        *
 344        */
 345       template<class Var>
 346       Ghost& member( const std::string& field,
 347                      Var (raw_type::*getter)() const,
 348                      void (raw_type::*setter)(Var) = 0 )
 349       {
 350         member_t m;
 351         if( getter )
 352         {
 353           naRef (*to_nasal_)(naContext, Var) = &nasal::to_nasal;
 354
 355           // Getter signature: naRef(naContext, raw_type*)
 356           m.getter = boost::bind(to_nasal_, _1, boost::bind(getter, _2));
 357         }
 358
 359         if( setter )
 360         {
 361           Var (*from_nasal_)(naContext, naRef) = &nasal::from_nasal;
 362
 363           // Setter signature: void(naContext, raw_type*, naRef)
 364           m.setter = boost::bind(setter, _2, boost::bind(from_nasal_, _1, _3));
 365         }
 366
 367         return member(field, m.getter, m.setter);
 368       }
 369
 370       /**
 371        * Register a write only member variable.
 372        *
 373        * @param field   Name of member
 374        * @param setter  Setter for variable
 375        */
 376       template<class Var>
 377       Ghost& member( const std::string& field,
 378                      void (raw_type::*setter)(Var) )
 379       {
 380         return member<Var>(field, 0, setter);
 381       }
 382
 383       /**
 384        * Register a member variable by passing a getter and/or setter method.
 385        *
 386        * @param field   Name of member
 387        * @param getter  Getter for variable
 388        * @param setter  Setter for variable (Pass empty to prevent write access)
 389        *
 390        */
 391       Ghost& member( const std::string& field,
 392                      const getter_t& getter,
 393                      const setter_t& setter = setter_t() )
 394       {
 395         if( !getter.empty() || !setter.empty() )
 396           _members[field] = member_t(getter, setter);
 397         else
 398           SG_LOG
 399           (
 400             SG_NASAL,
 401             SG_WARN,
 402             "Member '" << field << "' requires a getter or setter"
 403           );
 404         return *this;
 405       }
 406
 407       /**
 408        * Register a member function.
 409        *
 410        * @note Because only function pointers can be registered as Nasal
 411        *       functions it is needed to pass the function pointer as template
 412        *       argument. This allows us to create a separate instance of the
 413        *       MemberFunctionWrapper for each registered function and therefore
 414        *       provides us with the needed static functions to be passed on to
 415        *       Nasal.
 416        *
 417        * @tparam func   Pointer to member function being registered.
 418        *
 419        * @code{cpp}
 420        * class MyClass
 421        * {
 422        *   public:
 423        *     naRef myMethod(naContext c, int argc, naRef* args);
 424        * }
 425        *
 426        * Ghost<MyClass>::init("Test")
 427        *   .method<&MyClass::myMethod>("myMethod");
 428        * @endcode
 429        */
 430       template<member_func_t func>
 431       Ghost& method(const std::string& name)
 432       {
 433         _members[name].func = &MemberFunctionWrapper<func>::call;
 434         return *this;
 435       }
 436
 437       /**
 438        * Register a free function as member function. The object instance is
 439        * passed as additional first argument.
 440        *
 441        * @tparam func   Pointer to free function being registered.
 442        *
 443        * @note Due to a severe bug in Visual Studio it is not possible to create
 444        *       a specialization of #method for free function pointers and
 445        *       member function pointers at the same time. Do overcome this
 446        *       limitation we had to use a different name for this function.
 447        *
 448        * @code{cpp}
 449        * class MyClass;
 450        * naRef myMethod(MyClass& obj, naContext c, int argc, naRef* args);
 451        *
 452        * Ghost<MyClass>::init("Test")
 453        *   .method_func<&myMethod>("myMethod");
 454        * @endcode
 455        */
 456       template<free_func_t func>
 457       Ghost& method_func(const std::string& name)
 458       {
 459         _members[name].func = &FreeFunctionWrapper<func>::call;
 460         return *this;
 461       }
 462
 463       // TODO use variadic template when supporting C++11
 464       /**
 465        * Create a Nasal instance of this ghost.
 466        *
 467        * @param c   Active Nasal context
 468        */
 469       static naRef create( naContext c )
 470       {
 471         return makeGhost(c, Ghost::createInstance());
 472       }
 473
 474       /**
 475        * Create a Nasal instance of this ghost.
 476        *
 477        * @param c   Active Nasal context
 478        * @param a1  Parameter used for creating new instance
 479        */
 480       template<class A1>
 481       static naRef create( naContext c, const A1& a1 )
 482       {
 483         return makeGhost(c, Ghost::createInstance(a1));
 484       }
 485
 486       /**
 487        * Nasal callback for creating a new instance of this ghost.
 488        */
 489       static naRef f_create(naContext c, naRef me, int argc, naRef* args)
 490       {
 491         return create(c);
 492       }
 493
 494     private:
 495
 496       template<class>
 497       friend class Ghost;
 498
 499       typedef naGhostType* (*type_checker_t)(const raw_type*);
 500       typedef std::vector<type_checker_t> DerivedList;
 501       DerivedList _derived_classes;
 502
 503       void addDerived(const type_checker_t& derived_info)
 504       {
 505         _derived_classes.push_back(derived_info);
 506       }
 507
 508       template<class BaseGhost>
 509       static
 510       typename boost::enable_if
 511         < boost::is_polymorphic<typename BaseGhost::raw_type>,
 512           naGhostType*
 513         >::type
 514       getTypeFor(const typename BaseGhost::raw_type* base)
 515       {
 516         // Check first if passed pointer can by converted to instance of class
 517         // this ghost wraps.
 518         if(   !boost::is_same
 519                  < typename BaseGhost::raw_type,
 520                    typename Ghost::raw_type
 521                  >::value
 522             && dynamic_cast<const Ghost::raw_type*>(base) != base )
 523           return 0;
 524
 525         // Now check if we can further downcast to one of our derived classes.
 526         for( typename DerivedList::reverse_iterator
 527                derived = getSingletonPtr()->_derived_classes.rbegin();
 528                derived != getSingletonPtr()->_derived_classes.rend();
 529              ++derived )
 530         {
 531           naGhostType* ghost_type =
 532             (*derived)( static_cast<const typename Ghost::raw_type*>(base) );
 533           if( ghost_type )
 534             return ghost_type;
 535         }
 536
 537         // If base is not an instance of any derived class, this class has to
 538         // be the dynamic type.
 539         return &getSingletonPtr()->_ghost_type;
 540       }
 541
 542       template<class BaseGhost>
 543       static
 544       typename boost::disable_if
 545         < boost::is_polymorphic<typename BaseGhost::raw_type>,
 546           naGhostType*
 547         >::type
 548       getTypeFor(const typename BaseGhost::raw_type* base)
 549       {
 550         // For non polymorphic classes there is no possibility to get the actual
 551         // dynamic type, therefore we can only use its static type.
 552         return &BaseGhost::getSingletonPtr()->_ghost_type;
 553       }
 554
 555       static Ghost* getSingletonPtr()
 556       {
 557         return getSingletonHolder().get();
 558       }
 559
 560       // TODO integrate with from_nasal template to be able to cast objects
 561       //      passed as function argument.
 562       static raw_type* from_nasal(naRef me)
 563       {
 564         if( naGhost_type(me) != &getSingletonPtr()->_ghost_type )
 565           return 0;
 566
 567         return Ghost::getRawPtr( static_cast<T*>(naGhost_ptr(me)) );
 568       }
 569
 570       static raw_type* requireObject(naContext c, naRef me)
 571       {
 572         raw_type* obj = Ghost::from_nasal(me);
 573         if( !obj )
 574           naRuntimeError
 575           (
 576             c,
 577             "method called on object of wrong type: '%s' expected",
 578             getSingletonPtr()->_ghost_type.name
 579           );
 580
 581         return obj;
 582       }
 583
 584       /**
 585        * Wrapper class to enable registering pointers to member functions as
 586        * Nasal function callbacks. We need to use the function pointer as
 587        * template parameter to ensure every registered function gets a static
 588        * function which can be passed to Nasal.
 589        */
 590       template<member_func_t func>
 591       struct MemberFunctionWrapper
 592       {
 593         /**
 594          * Called from Nasal upon invocation of the according registered
 595          * function. Forwards the call to the passed object instance.
 596          */
 597         static naRef call(naContext c, naRef me, int argc, naRef* args)
 598         {
 599           return (requireObject(c, me)->*func)(c, argc, args);
 600         }
 601       };
 602
 603       /**
 604        * Wrapper class to enable registering pointers to free functions (only
 605        * external linkage). We need to use the function pointer as template
 606        * parameter to ensure every registered function gets a static function
 607        * which can be passed to Nasal. Even though we just wrap another simple
 608        * function pointer this intermediate step is need to be able to retrieve
 609        * the object the function call belongs to and pass it along as argument.
 610        */
 611       template<free_func_t func>
 612       struct FreeFunctionWrapper
 613       {
 614         /**
 615          * Called from Nasal upon invocation of the according registered
 616          * function. Forwards the call to the passed function pointer and passes
 617          * the required parameters.
 618          */
 619         static naRef call(naContext c, naRef me, int argc, naRef* args)
 620         {
 621           return func(*requireObject(c, me), c, argc, args);
 622         }
 623       };
 624
 625       typedef std::auto_ptr<Ghost> GhostPtr;
 626       MemberMap _members;
 627
 628       explicit Ghost(const std::string& name):
 629         GhostMetadata( name )
 630       {
 631         _ghost_type.destroy = &destroyGhost;
 632         _ghost_type.name = _name.c_str();
 633         _ghost_type.get_member = &getMember;
 634         _ghost_type.set_member = &setMember;
 635       }
 636
 637       static GhostPtr& getSingletonHolder()
 638       {
 639         static GhostPtr instance;
 640         return instance;
 641       }
 642
 643       static naRef makeGhost(naContext c, void *ptr)
 644       {
 645         naGhostType* ghost_type = 0;
 646         if( Ghost::returns_dynamic_type::value )
 647           // For pointer policies already returning instances of an object with
 648           // the dynamic type of this Ghost's raw_type the type is always the
 649           // same.
 650           ghost_type = &getSingletonPtr()->_ghost_type;
 651         else
 652           // If wrapping eg. shared pointers the users passes an already
 653           // existing instance of an object which will then be hold be a new
 654           // shared pointer. We therefore have to check for the dynamic type
 655           // of the object as it might differ from the passed static type.
 656           ghost_type = getTypeFor<Ghost>( Ghost::getRawPtr(ptr) );
 657
 658         if( !ghost_type )
 659           return naNil();
 660
 661         return naNewGhost2(c, ghost_type, ptr);
 662       }
 663
 664       static void destroyGhost(void *ptr)
 665       {
 666         delete (T*)ptr;
 667       }
 668
 669       /**
 670        * Callback for retrieving a ghost member.
 671        */
 672       static const char* getMember(naContext c, void* g, naRef key, naRef* out)
 673       {
 674         const std::string key_str = nasal::from_nasal<std::string>(c, key);
 675         if( key_str == "parents" )
 676         {
 677           if( getSingletonPtr()->_parents.empty() )
 678             return 0;
 679
 680           *out = getSingletonPtr()->getParents(c);
 681           return "";
 682         }
 683
 684         typename MemberMap::iterator member =
 685           getSingletonPtr()->_members.find(key_str);
 686
 687         if( member == getSingletonPtr()->_members.end() )
 688           return 0;
 689
 690         if( member->second.func )
 691           *out = nasal::to_nasal(c, member->second.func);
 692         else if( !member->second.getter.empty() )
 693           *out = member->second.getter(c, Ghost::getRawPtr(g));
 694         else
 695           return "Read-protected member";
 696
 697         return "";
 698       }
 699
 700       /**
 701        * Callback for writing to a ghost member.
 702        */
 703       static void setMember(naContext c, void* g, naRef field, naRef val)
 704       {
 705         const std::string key = nasal::from_nasal<std::string>(c, field);
 706         typename MemberMap::iterator member =
 707           getSingletonPtr()->_members.find(key);
 708
 709         if( member == getSingletonPtr()->_members.end() )
 710           naRuntimeError(c, "ghost: No such member: %s", key.c_str());
 711         if( member->second.setter.empty() )
 712           naRuntimeError(c, "ghost: Write protected member: %s", key.c_str());
 713
 714         member->second.setter(c, Ghost::getRawPtr(g), val);
 715       }
 716   };
 717
 718 } // namespace nasal
 719
 720 #endif /* SG_NASAL_GHOST_HXX_ */