Add callback examples with named parameters

docs/advanced.rst

@@ -139,8 +139,19 @@ its return value upon execution.
         };
     }
 
+This example demonstrates using python named parameters in C++ callbacks which
+requires using ``py::cpp_function`` as a wrapper. Usage is similar to defining
+methods of classes:
+
+.. code-block:: cpp
+
+    py::cpp_function func_cpp() {
+        return py::cpp_function([](int i) { return i+1; },
+           py::arg("number"));
+    }
+
 After including the extra header file :file:`pybind11/functional.h`, it is almost
-trivial to generate binding code for both of these functions.
+trivial to generate binding code for all of these functions.
 
 .. code-block:: cpp
 
@@ -151,6 +162,7 @@ trivial to generate binding code for both of these functions.
 
         m.def("func_arg", &func_arg);
         m.def("func_ret", &func_ret);
+        m.def("func_cpp", &func_cpp);
 
         return m.ptr();
     }
@@ -169,7 +181,9 @@ The following interactive session shows how to call them from Python.
     >>> square_plus_1 = example.func_ret(square)
     >>> square_plus_1(4)
     17L
-    >>>
+    >>> plus_1 = func_cpp()
+    >>> plus_1(number=43)
+    44L
 
 .. note::
 

example/example5.cpp

@@ -60,6 +60,11 @@ std::function<int(int)> test_callback4() {
     return [](int i) { return i+1; };
 }
 
+py::cpp_function test_callback5() {
+    return py::cpp_function([](int i) { return i+1; },
+       py::arg("number"));
+}
+
 void init_ex5(py::module &m) {
     py::class_<Pet> pet_class(m, "Pet");
     pet_class
@@ -82,6 +87,7 @@ void init_ex5(py::module &m) {
     m.def("test_callback2", &test_callback2);
     m.def("test_callback3", &test_callback3);
     m.def("test_callback4", &test_callback4);
+    m.def("test_callback5", &test_callback5);
 
     /* Test cleanup of lambda closure */
 

example/example5.py

@@ -29,6 +29,7 @@ from example import test_callback1
 from example import test_callback2
 from example import test_callback3
 from example import test_callback4
+from example import test_callback5
 from example import test_cleanup
 
 def func1():
@@ -49,5 +50,7 @@ print(test_callback1(partial(func3, "Partial object with one argument")))
 test_callback3(lambda i: i + 1)
 f = test_callback4()
 print("func(43) = %i" % f(43))
+f = test_callback5()
+print("func(number=43) = %i" % f(number=43))
 
 test_cleanup()

example/example5.ref

@@ -24,3 +24,4 @@ False
 Callback function 3 called : Partial object with one argument
 False
 func(43) = 44
+func(number=43) = 44