ceph/src/boost/libs/python/doc/reference/def_visitor.qbk

   1 [section boost/python/def_visitor.hpp]
   2 [section Introduction]
   3 <boost/python/def_visitor.hpp> provides a generic visitation interface through which the [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] def member functionality can be extended non-intrusively to avoid cluttering the [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] interface. It declares the `def_visitor<T>` class template, which is parameterized on the derived type `DerivedVisitor`, which provides the actual `def` functionality through its `visit` member functions.
   4 [endsect]
   5 [section Class `def_visitor`]
   6 The class `def_visitor` is a base class paramaterized by its derived class. The `def_visitor` class is a protocol class. Its derived class, DerivedVisitor, is expected to have a member function `visit`. The `def_visitor` class is never instantiated directly. Instead, an instance of its subclass, DerivedVisitor,  is passed on as an argument to the [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] `def` member function.
   7
   8 ``
   9 namespace boost { namespace python {
  10
  11     template <class DerivedVisitor>
  12     class def_visitor {};
  13 }
  14 ``
  15
  16 [variablelist
  17  [[Requires][The client supplied class DerivedVisitor template parameter is expected to:
  18  * be privately derived from def_visitor
  19  * grant friend access to class def_visitor_access
  20  * define either or both visit member functions listed in the table below:
  21    [table
  22    [[Expression][Return Type][Requirements][Effects]]
  23    [[`visitor.visit(cls)`][`void`]
  24     [`cls` is an instance of a [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_]  being wrapped to Python. `visitor` is a `def_visitor` derived class.]
  25     [A call to `cls.def(visitor)` forwards to this member function.]]
  26    [[`visitor.visit(cls, name, options)`][`void`]
  27     [`cls` is a [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] instance, name is a C string. `visitor` is a `def_visitor` derived class. options is a context specific optional argument.]
  28     [A call to `cls.def(name, visitor)` or `cls.def(name, visitor, options)` forwards to this member function. ]]]
  29     ]]
  30     ]
  31 [endsect]
  32 [section Example]
  33 ``
  34 class X {/*...*/};
  35
  36 class my_def_visitor : boost::python::def_visitor<my_def_visitor>
  37 {
  38   friend class def_visitor_access;
  39
  40   template <class classT>
  41   void visit(classT& c) const
  42   {
  43     c.def("foo", &my_def_visitor::foo);
  44     c.def("bar", &my_def_visitor::bar);
  45   }
  46
  47   static void foo(X& self);
  48   static void bar(X& self);
  49 };
  50
  51 BOOST_PYTHON_MODULE(my_ext)
  52 {
  53   class_<X>("X")
  54     .def(my_def_visitor());
  55 }
  56 ``
  57 [endsect]
  58 [endsect]