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

   1 [section boost/python/return_arg.hpp]
   2 [section Introduction]
   3 `return_arg` and `return_self` instantiations are models of [link concepts.callpolicies `CallPolicies`] which return the specified argument parameter (usually `*this`) of a wrapped (member) function.
   4 [endsect]
   5 [section Class `return_arg`]
   6 [table
   7 [[Parameter][Requirements][Description][Default]]
   8  [[arg_pos][A positive compile-time constant of type `std::size_t`.][the position of the argument to be returned.][1]]
   9 [[Base][A model of [link concepts.callpolicies `CallPolicies`]][Used for policy composition. Any `result_converter` it supplies will be overridden by `return_arg`, but its `precall` and `postcall` policies are composed as described here [link concepts.callpolicies `CallPolicies`].][default_call_policies]]
  10  ]
  11 ``
  12 namespace boost { namespace python
  13 {
  14    template <size_t arg_pos=1, class Base = default_call_policies>
  15    struct return_arg : Base
  16    {
  17       static PyObject* postcall(PyObject*, PyObject* result);
  18       struct result_converter{ template <class T> struct apply; };
  19       template <class Sig> struct extract_return_type : mpl::at_c<Sig, arg_pos>{};
  20
  21    };
  22 }}
  23 ``
  24 [endsect]
  25 [section Class `return_arg` static functions]
  26 ``PyObject* postcall(PyObject* args, PyObject* result);``
  27 [variablelist
  28 [[Requires][`PyTuple_Check(args) != 0` and `PyTuple_Size(args) != 0`]]
  29 [[Returns][PyTuple_GetItem(args,arg_pos-1)]]
  30 ]
  31 [endsect]
  32 [section Class template `return_self`]
  33 ``
  34 namespace boost { namespace python
  35 {
  36    template <class Base = default_call_policies>
  37    struct return_self
  38      : return_arg<1,Base>
  39    {};
  40 }}
  41 ``
  42 [endsect]
  43 [section Example]
  44 C++ module definition:
  45 ``
  46 #include <boost/python/module.hpp>
  47 #include <boost/python/class.hpp>
  48 #include <boost/python/return_arg.hpp>
  49
  50 struct Widget
  51 {
  52    Widget() :sensitive_(true){}
  53    bool get_sensitive() const { return sensitive_; }
  54    void set_sensitive(bool s) { this->sensitive_ = s; }
  55  private:
  56    bool sensitive_;
  57 };
  58
  59 struct Label : Widget
  60 {
  61    Label() {}
  62
  63    std::string  get_label() const { return label_; }
  64    void set_label(const std::string &l){ label_ = l; }
  65
  66  private:
  67    std::string label_;
  68 };
  69
  70 using namespace boost::python;
  71 BOOST_PYTHON_MODULE(return_self_ext)
  72 {
  73    class_<widget>("Widget")
  74       .def("sensitive", &Widget::get_sensitive)
  75       .def("sensitive", &Widget::set_sensitive, return_self<>())
  76       ;
  77
  78    class_<Label, bases<Widget> >("Label")
  79       .def("label", &Label::get_label)
  80       .def("label", &Label::set_label, return_self<>())
  81       ;
  82 }
  83 ``
  84 Python code:
  85 ``
  86 >>> from return_self_ext import *
  87 >>> l1 = Label().label("foo").sensitive(false)
  88 >>> l2 = Label().sensitive(false).label("foo")
  89 ``
  90 [endsect]
  91 [endsect]