2 /// Expose C++ objects to Nasal as ghosts
4 // Copyright (C) 2012 Thomas Geymayer <tomgey@gmail.com>
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.
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.
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
20 #ifndef SG_NASAL_GHOST_HXX_
21 #define SG_NASAL_GHOST_HXX_
23 #include "from_nasal.hxx"
24 #include "to_nasal.hxx"
26 #include <simgear/debug/logstream.hxx>
28 #include <boost/bind.hpp>
29 #include <boost/call_traits.hpp>
30 #include <boost/function.hpp>
31 #include <boost/lambda/lambda.hpp>
32 #include <boost/utility/enable_if.hpp>
37 * Bindings between C++ and the Nasal scripting language
43 * Traits for C++ classes exposed as Ghost. This is the basic template for
47 struct GhostTypeTraits
49 /** Whether the class is passed by shared pointer or raw pointer */
50 typedef boost::false_type::type is_shared;
52 /** The raw class type (Without any shared pointer) */
57 struct GhostTypeTraits<boost::shared_ptr<T> >
59 typedef boost::true_type::type is_shared;
65 struct GhostTypeTraits<osg::ref_ptr<T> >
67 typedef boost::true_type::type is_shared;
72 #ifdef SGSharedPtr_HXX
74 struct GhostTypeTraits<SGSharedPtr<T> >
76 typedef boost::true_type::type is_shared;
82 * Policy for creating ghost instances from shared pointer objects.
85 struct SharedPointerPolicy
87 typedef typename GhostTypeTraits<T>::raw_type raw_type;
89 typedef boost::false_type returns_dynamic_type;
92 * Create a shared pointer on the heap to handle the reference counting for
93 * the passed shared pointer while it is used in Nasal space.
95 static T* createInstance(const T& ptr)
100 static pointer getPtr(void* ptr)
103 return *static_cast<T*>(ptr);
108 static raw_type* getRawPtr(void* ptr)
111 return static_cast<T*>(ptr)->get();
116 static raw_type* getRawPtr(const T& ptr)
123 * Policy for creating ghost instances as raw objects on the heap.
126 struct RawPointerPolicy
128 typedef typename GhostTypeTraits<T>::raw_type raw_type;
129 typedef raw_type* pointer;
130 typedef boost::true_type returns_dynamic_type;
133 * Create a new object instance on the heap
135 static T* createInstance()
140 static pointer getPtr(void* ptr)
142 BOOST_STATIC_ASSERT((boost::is_same<pointer, T*>::value));
143 return static_cast<T*>(ptr);
146 static raw_type* getRawPtr(void* ptr)
148 BOOST_STATIC_ASSERT((boost::is_same<raw_type, T>::value));
149 return static_cast<T*>(ptr);
156 * Metadata for Ghost object types
162 * Add a nasal base class to the ghost. Will be available in the ghosts
165 void addNasalBase(const naRef& parent)
167 assert( naIsHash(parent) );
168 _parents.push_back(parent);
171 bool isBaseOf(naGhostType* ghost_type) const
173 if( ghost_type == &_ghost_type )
176 for( DerivedList::const_iterator derived = _derived_classes.begin();
177 derived != _derived_classes.end();
180 if( (*derived)->isBaseOf(ghost_type) )
189 typedef std::vector<const GhostMetadata*> DerivedList;
191 const std::string _name;
192 naGhostType _ghost_type;
193 DerivedList _derived_classes;
194 std::vector<naRef> _parents;
196 explicit GhostMetadata(const std::string& name):
202 void addDerived(const GhostMetadata* derived)
205 _derived_classes.push_back(derived);
211 "Ghost::addDerived: " <<_ghost_type.name << " -> " << derived->_name
215 naRef getParents(naContext c)
217 return nasal::to_nasal(c, _parents);
223 * Context passed to a function/method being called from Nasal
227 CallContext(naContext c, size_t argc, naRef* args):
234 * Get the argument with given index if it exists. Otherwise returns the
235 * passed default value.
237 * @tparam T Type of argument (converted using ::from_nasal)
238 * @param index Index of requested argument
239 * @param def Default value returned if too few arguments available
242 T getArg(size_t index, const T& def = T()) const
247 return from_nasal<T>(c, args[index]);
251 * Get the argument with given index. Raises a Nasal runtime error if there
252 * are to few arguments available.
255 T requireArg(size_t index) const
258 naRuntimeError(c, "Missing required arg #%d", index);
260 return from_nasal<T>(c, args[index]);
269 * Class for exposing C++ objects to Nasal
272 * // Example class to be exposed to Nasal
279 * naRef myMember(naContext c, int argc, naRef* args);
282 * void exposeClasses()
284 * // Register a nasal ghost type for MyClass. This needs to be done only
285 * // once before creating the first ghost instance.
286 * Ghost<MyClass>::init("MyClass")
287 * // Members can be exposed by getters and setters
288 * .member("x", &MyClass::getX, &MyClass::setX)
289 * // For readonly variables only pass a getter
290 * .member("x_readonly", &MyClass::getX)
291 * // It is also possible to expose writeonly members
292 * .member("x_writeonly", &MyClass::setX)
293 * // Methods use a slightly different syntax - The pointer to the member
294 * // function has to be passed as template argument
295 * .method<&MyClass::myMember>("myMember");
301 public internal::GhostMetadata,
302 protected boost::mpl::if_< typename GhostTypeTraits<T>::is_shared,
303 SharedPointerPolicy<T>,
304 RawPointerPolicy<T> >::type
307 typedef T value_type;
308 typedef typename GhostTypeTraits<T>::raw_type raw_type;
309 typedef typename Ghost::pointer pointer;
310 typedef naRef (raw_type::*member_func_t)(const CallContext&);
311 typedef naRef (*free_func_t)(raw_type&, const CallContext&);
312 typedef boost::function<naRef(naContext, raw_type&)> getter_t;
313 typedef boost::function<void(naContext, raw_type&, naRef)> setter_t;
316 * A ghost member. Can consist either of getter and/or setter functions
317 * for exposing a data variable or a single callable function.
325 member_t( const getter_t& getter,
326 const setter_t& setter,
327 naCFunction func = 0 ):
333 member_t(naCFunction func):
342 typedef std::map<std::string, member_t> MemberMap;
345 * Register a new ghost type.
347 * @note Only intialize each ghost type once!
349 * @param name Descriptive name of the ghost type.
351 static Ghost& init(const std::string& name)
353 assert( !getSingletonPtr() );
355 getSingletonHolder().reset( new Ghost(name) );
356 return *getSingletonPtr();
360 * Register a base class for this ghost. The base class needs to be
361 * registers on its own before it can be used as base class.
363 * @tparam BaseGhost Type of base class already wrapped into Ghost class
367 * Ghost<MyBase>::init("MyBase");
368 * Ghost<MyClass>::init("MyClass")
369 * .bases<Ghost<MyBase> >();
372 template<class BaseGhost>
373 typename boost::enable_if_c
374 < boost::is_base_of<GhostMetadata, BaseGhost>::value
375 && boost::is_base_of<typename BaseGhost::raw_type, raw_type>::value,
380 BaseGhost* base = BaseGhost::getSingletonPtr();
384 // Both ways of retrieving the address of a static member function
385 // should be legal but not all compilers know this.
386 // g++-4.4.7+ has been tested to work with both versions
387 #if defined(GCC_VERSION) && GCC_VERSION < 40407
388 // The old version of g++ used on Jenkins (16.11.2012) only compiles
390 &getTypeFor<BaseGhost>
392 // VS (2008, 2010, ... ?) only allow this version.
393 &Ghost::getTypeFor<BaseGhost>
397 // Replace any getter that is not available in the current class.
398 // TODO check if this is the correct behavior of function overriding
399 for( typename BaseGhost::MemberMap::const_iterator member =
400 base->_members.begin();
401 member != base->_members.end();
404 if( _members.find(member->first) == _members.end() )
405 _members[member->first] = member_t
407 member->second.getter,
408 member->second.setter,
417 * Register a base class for this ghost. The base class needs to be
418 * registers on its own before it can be used as base class.
420 * @tparam Base Type of base class (Base as used in Ghost<Base>)
423 * Ghost<MyBase>::init("MyBase");
424 * Ghost<MyClass>::init("MyClass")
429 typename boost::enable_if_c
430 < !boost::is_base_of<GhostMetadata, Base>::value
431 && boost::is_base_of<typename Ghost<Base>::raw_type, raw_type>::value,
436 return bases< Ghost<Base> >();
440 * Register an existing Nasal class/hash as base class for this ghost.
442 * @param parent Nasal hash/class
444 Ghost& bases(const naRef& parent)
446 addNasalBase(parent);
451 * Register a member variable by passing a getter and/or setter method.
453 * @param field Name of member
454 * @param getter Getter for variable
455 * @param setter Setter for variable (Pass 0 to prevent write access)
459 Ghost& member( const std::string& field,
460 Var (raw_type::*getter)() const,
461 void (raw_type::*setter)(typename boost::call_traits<Var>::param_type) = 0 )
466 typedef typename boost::call_traits<Var>::param_type param_type;
467 naRef (*to_nasal_)(naContext, param_type) = &nasal::to_nasal;
469 // Getter signature: naRef(naContext, raw_type&)
470 m.getter = boost::bind(to_nasal_, _1, boost::bind(getter, _2));
475 Var (*from_nasal_)(naContext, naRef) = &nasal::from_nasal;
477 // Setter signature: void(naContext, raw_type&, naRef)
478 m.setter = boost::bind(setter, _2, boost::bind(from_nasal_, _1, _3));
481 return member(field, m.getter, m.setter);
485 * Register a write only member variable.
487 * @param field Name of member
488 * @param setter Setter for variable
491 Ghost& member( const std::string& field,
492 void (raw_type::*setter)(Var) )
494 return member<Var>(field, 0, setter);
498 * Register a member variable by passing a getter and/or setter method.
500 * @param field Name of member
501 * @param getter Getter for variable
502 * @param setter Setter for variable (Pass empty to prevent write access)
505 Ghost& member( const std::string& field,
506 const getter_t& getter,
507 const setter_t& setter = setter_t() )
509 if( !getter.empty() || !setter.empty() )
510 _members[field] = member_t(getter, setter);
516 "Member '" << field << "' requires a getter or setter"
522 * Register a member function.
524 * @note Because only function pointers can be registered as Nasal
525 * functions it is needed to pass the function pointer as template
526 * argument. This allows us to create a separate instance of the
527 * MemberFunctionWrapper for each registered function and therefore
528 * provides us with the needed static functions to be passed on to
531 * @tparam func Pointer to member function being registered.
537 * naRef myMethod(naContext c, int argc, naRef* args);
540 * Ghost<MyClass>::init("Test")
541 * .method<&MyClass::myMethod>("myMethod");
544 template<member_func_t func>
545 Ghost& method(const std::string& name)
547 _members[name].func = &MemberFunctionWrapper<func>::call;
552 * Register a free function as member function. The object instance is
553 * passed as additional first argument.
555 * @tparam func Pointer to free function being registered.
557 * @note Due to a severe bug in Visual Studio it is not possible to create
558 * a specialization of #method for free function pointers and
559 * member function pointers at the same time. Do overcome this
560 * limitation we had to use a different name for this function.
564 * naRef myMethod(MyClass& obj, naContext c, int argc, naRef* args);
566 * Ghost<MyClass>::init("Test")
567 * .method_func<&myMethod>("myMethod");
570 template<free_func_t func>
571 Ghost& method_func(const std::string& name)
573 _members[name].func = &FreeFunctionWrapper<func>::call;
577 // TODO use variadic template when supporting C++11
579 * Create a Nasal instance of this ghost.
581 * @param c Active Nasal context
583 static naRef create( naContext c )
585 return makeGhost(c, Ghost::createInstance());
589 * Create a Nasal instance of this ghost.
591 * @param c Active Nasal context
592 * @param a1 Parameter used for creating new instance
595 static naRef create( naContext c, const A1& a1 )
597 return makeGhost(c, Ghost::createInstance(a1));
601 * Nasal callback for creating a new instance of this ghost.
603 static naRef f_create(naContext c, naRef me, int argc, naRef* args)
608 static bool isBaseOf(naGhostType* ghost_type)
613 return getSingletonPtr()->GhostMetadata::isBaseOf(ghost_type);
616 static bool isBaseOf(naRef obj)
618 return isBaseOf( naGhost_type(obj) );
622 * Convert Nasal object to C++ object. To get a valid object the passed
623 * Nasal objects has to be derived class of the target class (Either
624 * derived in C++ or in Nasal using a 'parents' vector)
626 static pointer fromNasal(naContext c, naRef me)
628 // Check if it's a ghost and if it can be converted
629 if( isBaseOf( naGhost_type(me) ) )
630 return Ghost::getPtr( naGhost_ptr(me) );
632 // Now if it is derived from a ghost (hash with ghost in parent vector)
633 else if( naIsHash(me) )
635 naRef na_parents = naHash_cget(me, const_cast<char*>("parents"));
636 if( !naIsVector(na_parents) )
638 SG_LOG(SG_NASAL, SG_DEBUG, "Missing 'parents' vector for ghost");
642 typedef std::vector<naRef> naRefs;
643 naRefs parents = from_nasal<naRefs>(c, na_parents);
644 for( naRefs::const_iterator parent = parents.begin();
645 parent != parents.end();
648 pointer ptr = fromNasal(c, *parent);
662 typedef naGhostType* (*type_checker_t)(const raw_type*);
663 typedef std::vector<type_checker_t> DerivedList;
664 DerivedList _derived_types;
666 void addDerived( const internal::GhostMetadata* derived_meta,
667 const type_checker_t& derived_info )
669 GhostMetadata::addDerived(derived_meta);
670 _derived_types.push_back(derived_info);
673 template<class BaseGhost>
675 typename boost::enable_if
676 < boost::is_polymorphic<typename BaseGhost::raw_type>,
679 getTypeFor(const typename BaseGhost::raw_type* base)
681 // Check first if passed pointer can by converted to instance of class
684 < typename BaseGhost::raw_type,
685 typename Ghost::raw_type
687 && dynamic_cast<const typename Ghost::raw_type*>(base) != base )
690 // Now check if we can further downcast to one of our derived classes.
691 for( typename DerivedList::reverse_iterator
692 derived = getSingletonPtr()->_derived_types.rbegin();
693 derived != getSingletonPtr()->_derived_types.rend();
696 naGhostType* ghost_type =
697 (*derived)( static_cast<const typename Ghost::raw_type*>(base) );
702 // If base is not an instance of any derived class, this class has to
703 // be the dynamic type.
704 return &getSingletonPtr()->_ghost_type;
707 template<class BaseGhost>
709 typename boost::disable_if
710 < boost::is_polymorphic<typename BaseGhost::raw_type>,
713 getTypeFor(const typename BaseGhost::raw_type* base)
715 // For non polymorphic classes there is no possibility to get the actual
716 // dynamic type, therefore we can only use its static type.
717 return &BaseGhost::getSingletonPtr()->_ghost_type;
720 static Ghost* getSingletonPtr()
722 return getSingletonHolder().get();
725 static raw_type& requireObject(naContext c, naRef me)
727 raw_type* obj = Ghost::getRawPtr( fromNasal(c, me) );
728 naGhostType* ghost_type = naGhost_type(me);
734 "method called on object of wrong type: is '%s' expected '%s'",
735 ghost_type ? ghost_type->name : "unknown",
736 getSingletonPtr()->_ghost_type.name
743 * Wrapper class to enable registering pointers to member functions as
744 * Nasal function callbacks. We need to use the function pointer as
745 * template parameter to ensure every registered function gets a static
746 * function which can be passed to Nasal.
748 template<member_func_t func>
749 struct MemberFunctionWrapper
752 * Called from Nasal upon invocation of the according registered
753 * function. Forwards the call to the passed object instance.
755 static naRef call(naContext c, naRef me, int argc, naRef* args)
757 return (requireObject(c, me).*func)(CallContext(c, argc, args));
762 * Wrapper class to enable registering pointers to free functions (only
763 * external linkage). We need to use the function pointer as template
764 * parameter to ensure every registered function gets a static function
765 * which can be passed to Nasal. Even though we just wrap another simple
766 * function pointer this intermediate step is need to be able to retrieve
767 * the object the function call belongs to and pass it along as argument.
769 template<free_func_t func>
770 struct FreeFunctionWrapper
773 * Called from Nasal upon invocation of the according registered
774 * function. Forwards the call to the passed function pointer and passes
775 * the required parameters.
777 static naRef call(naContext c, naRef me, int argc, naRef* args)
779 return func(requireObject(c, me), CallContext(c, argc, args));
783 typedef std::auto_ptr<Ghost> GhostPtr;
786 explicit Ghost(const std::string& name):
787 GhostMetadata( name )
789 _ghost_type.destroy = &destroyGhost;
790 _ghost_type.name = _name.c_str();
791 _ghost_type.get_member = &getMember;
792 _ghost_type.set_member = &setMember;
795 static GhostPtr& getSingletonHolder()
797 static GhostPtr instance;
801 static naRef makeGhost(naContext c, void *ptr)
803 if( !Ghost::getRawPtr(ptr) )
806 naGhostType* ghost_type = 0;
807 if( Ghost::returns_dynamic_type::value )
808 // For pointer policies already returning instances of an object with
809 // the dynamic type of this Ghost's raw_type the type is always the
811 ghost_type = &getSingletonPtr()->_ghost_type;
813 // If wrapping eg. shared pointers the users passes an already
814 // existing instance of an object which will then be hold be a new
815 // shared pointer. We therefore have to check for the dynamic type
816 // of the object as it might differ from the passed static type.
817 ghost_type = getTypeFor<Ghost>( Ghost::getRawPtr(ptr) );
822 return naNewGhost2(c, ghost_type, ptr);
825 static void destroyGhost(void *ptr)
831 * Callback for retrieving a ghost member.
833 static const char* getMember(naContext c, void* g, naRef key, naRef* out)
835 const std::string key_str = nasal::from_nasal<std::string>(c, key);
836 if( key_str == "parents" )
838 if( getSingletonPtr()->_parents.empty() )
841 *out = getSingletonPtr()->getParents(c);
845 typename MemberMap::iterator member =
846 getSingletonPtr()->_members.find(key_str);
848 if( member == getSingletonPtr()->_members.end() )
851 if( member->second.func )
852 *out = nasal::to_nasal(c, member->second.func);
853 else if( !member->second.getter.empty() )
854 *out = member->second.getter(c, *Ghost::getRawPtr(g));
856 return "Read-protected member";
862 * Callback for writing to a ghost member.
864 static void setMember(naContext c, void* g, naRef field, naRef val)
866 const std::string key = nasal::from_nasal<std::string>(c, field);
867 typename MemberMap::iterator member =
868 getSingletonPtr()->_members.find(key);
870 if( member == getSingletonPtr()->_members.end() )
871 naRuntimeError(c, "ghost: No such member: %s", key.c_str());
872 if( member->second.setter.empty() )
873 naRuntimeError(c, "ghost: Write protected member: %s", key.c_str());
875 member->second.setter(c, *Ghost::getRawPtr(g), val);
881 #endif /* SG_NASAL_GHOST_HXX_ */