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/mpl/has_xxx.hpp>
33 #include <boost/utility/enable_if.hpp>
38 * Bindings between C++ and the Nasal scripting language
46 * Metadata for Ghost object types
52 * Add a nasal base class to the ghost. Will be available in the ghosts
55 void addNasalBase(const naRef& parent)
57 assert( naIsHash(parent) );
58 _parents.push_back(parent);
61 bool isBaseOf(naGhostType* ghost_type) const
63 if( ghost_type == &_ghost_type )
66 for( DerivedList::const_iterator derived = _derived_classes.begin();
67 derived != _derived_classes.end();
70 if( (*derived)->isBaseOf(ghost_type) )
79 typedef std::vector<const GhostMetadata*> DerivedList;
81 const std::string _name;
82 naGhostType _ghost_type;
83 DerivedList _derived_classes;
84 std::vector<naRef> _parents;
86 explicit GhostMetadata(const std::string& name):
92 void addDerived(const GhostMetadata* derived)
95 _derived_classes.push_back(derived);
101 "Ghost::addDerived: " <<_ghost_type.name << " -> " << derived->_name
105 naRef getParents(naContext c)
107 return nasal::to_nasal(c, _parents);
111 BOOST_MPL_HAS_XXX_TRAIT_DEF(element_type)
115 * Context passed to a function/method being called from Nasal
119 CallContext(naContext c, size_t argc, naRef* args):
126 * Get the argument with given index if it exists. Otherwise returns the
127 * passed default value.
129 * @tparam T Type of argument (converted using ::from_nasal)
130 * @param index Index of requested argument
131 * @param def Default value returned if too few arguments available
134 T getArg(size_t index, const T& def = T()) const
139 return from_nasal<T>(c, args[index]);
143 * Get the argument with given index. Raises a Nasal runtime error if there
144 * are to few arguments available.
147 T requireArg(size_t index) const
150 naRuntimeError(c, "Missing required arg #%d", index);
152 return from_nasal<T>(c, args[index]);
161 * Class for exposing C++ objects to Nasal
164 * // Example class to be exposed to Nasal
171 * naRef myMember(naContext c, int argc, naRef* args);
173 * typedef boost::shared_ptr<MyClass> MyClassPtr;
175 * void exposeClasses()
177 * // Register a nasal ghost type for MyClass. This needs to be done only
178 * // once before creating the first ghost instance. The exposed class needs
179 * // to be wrapped inside a shared pointer, eg. boost::shared_ptr.
180 * Ghost<MyClassPtr>::init("MyClass")
181 * // Members can be exposed by getters and setters
182 * .member("x", &MyClass::getX, &MyClass::setX)
183 * // For readonly variables only pass a getter
184 * .member("x_readonly", &MyClass::getX)
185 * // It is also possible to expose writeonly members
186 * .member("x_writeonly", &MyClass::setX)
187 * // Methods use a slightly different syntax - The pointer to the member
188 * // function has to be passed as template argument
189 * .method<&MyClass::myMember>("myMember");
195 public internal::GhostMetadata
197 BOOST_STATIC_ASSERT( internal::has_element_type<T>::value );
200 typedef typename T::element_type raw_type;
202 typedef naRef (raw_type::*member_func_t)(const CallContext&);
203 typedef naRef (*free_func_t)(raw_type&, const CallContext&);
204 typedef boost::function<naRef(naContext, raw_type&)> getter_t;
205 typedef boost::function<void(naContext, raw_type&, naRef)> setter_t;
208 * A ghost member. Can consist either of getter and/or setter functions
209 * for exposing a data variable or a single callable function.
217 member_t( const getter_t& getter,
218 const setter_t& setter,
219 naCFunction func = 0 ):
225 member_t(naCFunction func):
234 typedef std::map<std::string, member_t> MemberMap;
237 * Register a new ghost type.
239 * @note Only intialize each ghost type once!
241 * @param name Descriptive name of the ghost type.
243 static Ghost& init(const std::string& name)
245 assert( !getSingletonPtr() );
247 getSingletonHolder().reset( new Ghost(name) );
248 return *getSingletonPtr();
252 * Register a base class for this ghost. The base class needs to be
253 * registers on its own before it can be used as base class.
255 * @tparam BaseGhost Type of base class already wrapped into Ghost class
259 * Ghost<MyBasePtr>::init("MyBase");
260 * Ghost<MyClassPtr>::init("MyClass")
261 * .bases<Ghost<MyBasePtr> >();
264 template<class BaseGhost>
265 typename boost::enable_if
267 boost::is_base_of<GhostMetadata, BaseGhost>,
274 boost::is_base_of<typename BaseGhost::raw_type, raw_type>::value
277 BaseGhost* base = BaseGhost::getSingletonPtr();
281 // Both ways of retrieving the address of a static member function
282 // should be legal but not all compilers know this.
283 // g++-4.4.7+ has been tested to work with both versions
284 #if defined(GCC_VERSION) && GCC_VERSION < 40407
285 // The old version of g++ used on Jenkins (16.11.2012) only compiles
287 &getTypeFor<BaseGhost>
289 // VS (2008, 2010, ... ?) only allow this version.
290 &Ghost::getTypeFor<BaseGhost>
294 // Replace any getter that is not available in the current class.
295 // TODO check if this is the correct behavior of function overriding
296 for( typename BaseGhost::MemberMap::const_iterator member =
297 base->_members.begin();
298 member != base->_members.end();
301 if( _members.find(member->first) == _members.end() )
302 _members[member->first] = member_t
304 member->second.getter,
305 member->second.setter,
314 * Register a base class for this ghost. The base class needs to be
315 * registers on its own before it can be used as base class.
317 * @tparam Base Type of base class (Base as used in Ghost<BasePtr>)
320 * Ghost<MyBasePtr>::init("MyBase");
321 * Ghost<MyClassPtr>::init("MyClass")
322 * .bases<MyBasePtr>();
326 typename boost::disable_if
328 boost::is_base_of<GhostMetadata, Base>,
335 boost::is_base_of<typename Ghost<Base>::raw_type, raw_type>::value
338 return bases< Ghost<Base> >();
342 * Register an existing Nasal class/hash as base class for this ghost.
344 * @param parent Nasal hash/class
346 Ghost& bases(const naRef& parent)
348 addNasalBase(parent);
353 * Register a member variable by passing a getter and/or setter method.
355 * @param field Name of member
356 * @param getter Getter for variable
357 * @param setter Setter for variable (Pass 0 to prevent write access)
360 template<class Ret, class Param>
361 Ghost& member( const std::string& field,
362 Ret (raw_type::*getter)() const,
363 void (raw_type::*setter)(Param) )
368 typedef typename boost::call_traits<Ret>::param_type param_type;
369 naRef (*to_nasal_)(naContext, param_type) = &nasal::to_nasal;
371 // Getter signature: naRef(naContext, raw_type&)
372 m.getter = boost::bind(to_nasal_, _1, boost::bind(getter, _2));
377 typename boost::remove_reference<Param>::type
378 (*from_nasal_)(naContext, naRef) = &nasal::from_nasal;
380 // Setter signature: void(naContext, raw_type&, naRef)
381 m.setter = boost::bind(setter, _2, boost::bind(from_nasal_, _1, _3));
384 return member(field, m.getter, m.setter);
388 * Register a read only member variable.
390 * @param field Name of member
391 * @param getter Getter for variable
394 Ghost& member( const std::string& field,
395 Ret (raw_type::*getter)() const )
397 return member<Ret, Ret>(field, getter, 0);
401 * Register a write only member variable.
403 * @param field Name of member
404 * @param setter Setter for variable
407 Ghost& member( const std::string& field,
408 void (raw_type::*setter)(Var) )
410 return member<Var, Var>(field, 0, setter);
414 * Register a member variable by passing a getter and/or setter method.
416 * @param field Name of member
417 * @param getter Getter for variable
418 * @param setter Setter for variable (Pass empty to prevent write access)
421 Ghost& member( const std::string& field,
422 const getter_t& getter,
423 const setter_t& setter = setter_t() )
425 if( !getter.empty() || !setter.empty() )
426 _members[field] = member_t(getter, setter);
432 "Member '" << field << "' requires a getter or setter"
438 * Register a member function.
440 * @note Because only function pointers can be registered as Nasal
441 * functions it is needed to pass the function pointer as template
442 * argument. This allows us to create a separate instance of the
443 * MemberFunctionWrapper for each registered function and therefore
444 * provides us with the needed static functions to be passed on to
447 * @tparam func Pointer to member function being registered.
453 * naRef myMethod(naContext c, int argc, naRef* args);
456 * Ghost<MyClassPtr>::init("Test")
457 * .method<&MyClass::myMethod>("myMethod");
460 template<member_func_t func>
461 Ghost& method(const std::string& name)
463 _members[name].func = &MemberFunctionWrapper<func>::call;
468 * Register a free function as member function. The object instance is
469 * passed as additional first argument.
471 * @tparam func Pointer to free function being registered.
473 * @note Due to a severe bug in Visual Studio it is not possible to create
474 * a specialization of #method for free function pointers and
475 * member function pointers at the same time. Do overcome this
476 * limitation we had to use a different name for this function.
480 * naRef myMethod(MyClass& obj, naContext c, int argc, naRef* args);
482 * Ghost<MyClassPtr>::init("Test")
483 * .method_func<&myMethod>("myMethod");
486 template<free_func_t func>
487 Ghost& method_func(const std::string& name)
489 _members[name].func = &FreeFunctionWrapper<func>::call;
493 // TODO use variadic template when supporting C++11
495 * Create a Nasal instance of this ghost.
497 * @param c Active Nasal context
499 // TODO check if default constructor exists
500 // static naRef create( naContext c )
502 // return makeGhost(c, createInstance());
506 * Create a Nasal instance of this ghost.
508 * @param c Active Nasal context
509 * @param a1 Parameter used for creating new instance
512 static naRef create( naContext c, const A1& a1 )
514 return makeGhost(c, createInstance(a1));
518 * Nasal callback for creating a new instance of this ghost.
520 static naRef f_create(naContext c, naRef me, int argc, naRef* args)
525 static bool isBaseOf(naGhostType* ghost_type)
530 return getSingletonPtr()->GhostMetadata::isBaseOf(ghost_type);
533 static bool isBaseOf(naRef obj)
535 return isBaseOf( naGhost_type(obj) );
539 * Convert Nasal object to C++ object. To get a valid object the passed
540 * Nasal objects has to be derived class of the target class (Either
541 * derived in C++ or in Nasal using a 'parents' vector)
543 static pointer fromNasal(naContext c, naRef me)
545 // Check if it's a ghost and if it can be converted
546 if( isBaseOf( naGhost_type(me) ) )
547 return getPtr( naGhost_ptr(me) );
549 // Now if it is derived from a ghost (hash with ghost in parent vector)
550 else if( naIsHash(me) )
552 naRef na_parents = naHash_cget(me, const_cast<char*>("parents"));
553 if( !naIsVector(na_parents) )
555 SG_LOG(SG_NASAL, SG_DEBUG, "Missing 'parents' vector for ghost");
559 typedef std::vector<naRef> naRefs;
560 naRefs parents = from_nasal<naRefs>(c, na_parents);
561 for( naRefs::const_iterator parent = parents.begin();
562 parent != parents.end();
565 pointer ptr = fromNasal(c, *parent);
579 typedef naGhostType* (*type_checker_t)(const raw_type*);
580 typedef std::vector<type_checker_t> DerivedList;
581 DerivedList _derived_types;
584 * Create a shared pointer on the heap to handle the reference counting
585 * for the passed shared pointer while it is used in Nasal space.
587 static pointer* createInstance(const pointer& ptr)
589 return ptr ? new pointer(ptr) : 0;
592 static pointer getPtr(void* ptr)
595 return *static_cast<pointer*>(ptr);
600 static raw_type* getRawPtr(void* ptr)
603 return static_cast<pointer*>(ptr)->get();
608 static raw_type* getRawPtr(const pointer& ptr)
613 void addDerived( const internal::GhostMetadata* derived_meta,
614 const type_checker_t& derived_info )
616 GhostMetadata::addDerived(derived_meta);
617 _derived_types.push_back(derived_info);
620 template<class BaseGhost>
622 typename boost::enable_if
623 < boost::is_polymorphic<typename BaseGhost::raw_type>,
626 getTypeFor(const typename BaseGhost::raw_type* base)
628 // Check first if passed pointer can by converted to instance of class
631 < typename BaseGhost::raw_type,
632 typename Ghost::raw_type
634 && dynamic_cast<const typename Ghost::raw_type*>(base) != base )
637 // Now check if we can further downcast to one of our derived classes.
638 for( typename DerivedList::reverse_iterator
639 derived = getSingletonPtr()->_derived_types.rbegin();
640 derived != getSingletonPtr()->_derived_types.rend();
643 naGhostType* ghost_type =
644 (*derived)( static_cast<const typename Ghost::raw_type*>(base) );
649 // If base is not an instance of any derived class, this class has to
650 // be the dynamic type.
651 return &getSingletonPtr()->_ghost_type;
654 template<class BaseGhost>
656 typename boost::disable_if
657 < boost::is_polymorphic<typename BaseGhost::raw_type>,
660 getTypeFor(const typename BaseGhost::raw_type* base)
662 // For non polymorphic classes there is no possibility to get the actual
663 // dynamic type, therefore we can only use its static type.
664 return &BaseGhost::getSingletonPtr()->_ghost_type;
667 static Ghost* getSingletonPtr()
669 return getSingletonHolder().get();
672 static raw_type& requireObject(naContext c, naRef me)
674 raw_type* obj = getRawPtr( fromNasal(c, me) );
675 naGhostType* ghost_type = naGhost_type(me);
681 "method called on object of wrong type: is '%s' expected '%s'",
682 ghost_type ? ghost_type->name : "unknown",
683 getSingletonPtr()->_ghost_type.name
690 * Wrapper class to enable registering pointers to member functions as
691 * Nasal function callbacks. We need to use the function pointer as
692 * template parameter to ensure every registered function gets a static
693 * function which can be passed to Nasal.
695 template<member_func_t func>
696 struct MemberFunctionWrapper
699 * Called from Nasal upon invocation of the according registered
700 * function. Forwards the call to the passed object instance.
702 static naRef call(naContext c, naRef me, int argc, naRef* args)
704 return (requireObject(c, me).*func)(CallContext(c, argc, args));
709 * Wrapper class to enable registering pointers to free functions (only
710 * external linkage). We need to use the function pointer as template
711 * parameter to ensure every registered function gets a static function
712 * which can be passed to Nasal. Even though we just wrap another simple
713 * function pointer this intermediate step is need to be able to retrieve
714 * the object the function call belongs to and pass it along as argument.
716 template<free_func_t func>
717 struct FreeFunctionWrapper
720 * Called from Nasal upon invocation of the according registered
721 * function. Forwards the call to the passed function pointer and passes
722 * the required parameters.
724 static naRef call(naContext c, naRef me, int argc, naRef* args)
726 return func(requireObject(c, me), CallContext(c, argc, args));
730 typedef std::auto_ptr<Ghost> GhostPtr;
733 explicit Ghost(const std::string& name):
734 GhostMetadata( name )
736 _ghost_type.destroy = &destroyGhost;
737 _ghost_type.name = _name.c_str();
738 _ghost_type.get_member = &getMember;
739 _ghost_type.set_member = &setMember;
742 static GhostPtr& getSingletonHolder()
744 static GhostPtr instance;
748 static naRef makeGhost(naContext c, void *ptr)
752 // We are wrapping shared pointers to already existing objects which
753 // will then be hold be a new shared pointer. We therefore have to
754 // check for the dynamic type of the object as it might differ from
755 // the passed static type.
756 naGhostType* ghost_type = getTypeFor<Ghost>( getRawPtr(ptr) );
759 return naNewGhost2(c, ghost_type, ptr);
766 static void destroyGhost(void *ptr)
768 delete static_cast<pointer*>(ptr);
772 * Callback for retrieving a ghost member.
774 static const char* getMember(naContext c, void* g, naRef key, naRef* out)
776 const std::string key_str = nasal::from_nasal<std::string>(c, key);
777 if( key_str == "parents" )
779 if( getSingletonPtr()->_parents.empty() )
782 *out = getSingletonPtr()->getParents(c);
786 typename MemberMap::iterator member =
787 getSingletonPtr()->_members.find(key_str);
789 if( member == getSingletonPtr()->_members.end() )
792 if( member->second.func )
793 *out = nasal::to_nasal(c, member->second.func);
794 else if( !member->second.getter.empty() )
795 *out = member->second.getter(c, *getRawPtr(g));
797 return "Read-protected member";
803 * Callback for writing to a ghost member.
805 static void setMember(naContext c, void* g, naRef field, naRef val)
807 const std::string key = nasal::from_nasal<std::string>(c, field);
808 typename MemberMap::iterator member =
809 getSingletonPtr()->_members.find(key);
811 if( member == getSingletonPtr()->_members.end() )
812 naRuntimeError(c, "ghost: No such member: %s", key.c_str());
813 if( member->second.setter.empty() )
814 naRuntimeError(c, "ghost: Write protected member: %s", key.c_str());
816 member->second.setter(c, *getRawPtr(g), val);
822 #endif /* SG_NASAL_GHOST_HXX_ */