Rename examples files, as per #288

This renames example files from `exampleN` to `example-description`.

Specifically, the following renaming is applied:

example1 -> example-methods-and-attributes
example2 -> example-python-types
example3 -> example-operator-overloading
example4 -> example-constants-and-functions
example5 -> example-callbacks (*)
example6 -> example-sequence-and-iterators
example7 -> example-buffers
example8 -> example-custom-ref-counting
example9 -> example-modules
example10 -> example-numpy-vectorize
example11 -> example-arg-keywords-and-defaults
example12 -> example-virtual-functions
example13 -> example-keep-alive
example14 -> example-opaque-types
example15 -> example-pickling
example16 -> example-inheritance
example17 -> example-stl-binders
example18 -> example-eval
example19 -> example-custom-exceptions

* the inheritance parts of example5 are moved into example-inheritance
(previously example16), and the remainder is left as example-callbacks.

This commit also renames the internal variables ("Example1",
"Example2", "Example4", etc.) into non-numeric names ("ExampleMandA",
"ExamplePythonTypes", "ExampleWithEnum", etc.) to correspond to the
file renaming.

The order of tests is preserved, but this can easily be changed if
there is some more natural ordering by updating the list in
examples/CMakeLists.txt.

example/CMakeLists.txt

@@ -7,25 +7,25 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
 endif()
 
 set(PYBIND11_EXAMPLES
-  example1.cpp
-  example2.cpp
-  example3.cpp
-  example4.cpp
-  example5.cpp
-  example6.cpp
-  example7.cpp
-  example8.cpp
-  example9.cpp
-  example10.cpp
-  example11.cpp
-  example12.cpp
-  example13.cpp
-  example14.cpp
-  example15.cpp
-  example16.cpp
-  example17.cpp
-  example18.cpp
-  example19.cpp
+  example-methods-and-attributes.cpp
+  example-python-types.cpp
+  example-operator-overloading.cpp
+  example-constants-and-functions.cpp
+  example-callbacks.cpp
+  example-sequences-and-iterators.cpp
+  example-buffers.cpp
+  example-smart-ptr.cpp
+  example-modules.cpp
+  example-numpy-vectorize.cpp
+  example-arg-keywords-and-defaults.cpp
+  example-virtual-functions.cpp
+  example-keep-alive.cpp
+  example-opaque-types.cpp
+  example-pickling.cpp
+  example-inheritance.cpp
+  example-stl-binder-vector.cpp
+  example-eval.cpp
+  example-custom-exceptions.cpp
   issues.cpp
 )
 

example/example11.cpp → example/example-arg-keywords-and-defaults.cpp

 /*
-    example/example11.cpp -- keyword arguments and default values
+    example/example-arg-keywords-and-defaults.cpp -- keyword arguments and default values
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -40,7 +40,7 @@ void args_kwargs_function(py::args args, py::kwargs kwargs) {
     }
 }
 
-void init_ex11(py::module &m) {
+void init_ex_arg_keywords_and_defaults(py::module &m) {
     m.def("kw_func", &kw_func, py::arg("x"), py::arg("y"));
     m.def("kw_func2", &kw_func, py::arg("x") = 100, py::arg("y") = 200);
     m.def("kw_func3", [](const char *) { }, py::arg("data") = std::string("Hello world!"));

example/example7.cpp → example/example-buffers.cpp

 /*
-    example/example7.cpp -- supporting Pythons' buffer protocol
+    example/example-buffers.cpp -- supporting Pythons' buffer protocol
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -73,7 +73,7 @@ private:
     float *m_data;
 };
 
-void init_ex7(py::module &m) {
+void init_ex_buffers(py::module &m) {
     py::class_<Matrix> mtx(m, "Matrix");
 
     mtx.def(py::init<size_t, size_t>())

example/example5.cpp → example/example-callbacks.cpp

 /*
-    example/example5.cpp -- inheritance, callbacks, acquiring and releasing the
-    global interpreter lock
+    example/example-callbacks.cpp -- callbacks
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -12,36 +11,6 @@
 #include <pybind11/functional.h>
 
 
-class Pet {
-public:
-    Pet(const std::string &name, const std::string &species)
-        : m_name(name), m_species(species) {}
-    std::string name() const { return m_name; }
-    std::string species() const { return m_species; }
-private:
-    std::string m_name;
-    std::string m_species;
-};
-
-class Dog : public Pet {
-public:
-    Dog(const std::string &name) : Pet(name, "dog") {}
-    void bark() const { std::cout << "Woof!" << std::endl; }
-};
-
-class Rabbit : public Pet {
-public:
-    Rabbit(const std::string &name) : Pet(name, "parrot") {}
-};
-
-void pet_print(const Pet &pet) {
-    std::cout << pet.name() + " is a " + pet.species() << std::endl;
-}
-
-void dog_bark(const Dog &dog) {
-    dog.bark();
-}
-
 bool test_callback1(py::object func) {
     func();
     return false;
@@ -88,24 +57,7 @@ void test_dummy_function(const std::function<int(int)> &f) {
     }
 }
 
-void init_ex5(py::module &m) {
-    py::class_<Pet> pet_class(m, "Pet");
-    pet_class
-        .def(py::init<std::string, std::string>())
-        .def("name", &Pet::name)
-        .def("species", &Pet::species);
-
-    /* One way of declaring a subclass relationship: reference parent's class_ object */
-    py::class_<Dog>(m, "Dog", pet_class)
-        .def(py::init<std::string>());
-
-    /* Another way of declaring a subclass relationship: reference parent's C++ type */
-    py::class_<Rabbit>(m, "Rabbit", py::base<Pet>())
-        .def(py::init<std::string>());
-
-    m.def("pet_print", pet_print);
-    m.def("dog_bark", dog_bark);
-
+void init_ex_callbacks(py::module &m) {
     m.def("test_callback1", &test_callback1);
     m.def("test_callback2", &test_callback2);
     m.def("test_callback3", &test_callback3);

example/example4.cpp → example/example-constants-and-functions.cpp

 /*
-    example/example4.cpp -- global constants and functions, enumerations, raw byte strings
+    example/example-constants-and-functions.cpp -- global constants and functions, enumerations, raw byte strings
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -14,7 +14,7 @@ enum EMyEnumeration {
     ESecondEntry
 };
 
-class Example4 {
+class ExampleWithEnum {
 public:
     enum EMode {
         EFirstMode = 1,
@@ -22,7 +22,7 @@ public:
     };
 
     static EMode test_function(EMode mode) {
-        std::cout << "Example4::test_function(enum=" << mode << ")" << std::endl;
+        std::cout << "ExampleWithEnum::test_function(enum=" << mode << ")" << std::endl;
         return mode;
     }
 };
@@ -52,7 +52,7 @@ void print_bytes(py::bytes bytes) {
         std::cout << "bytes[" << i << "]=" << (int) value[i] << std::endl;
 }
 
-void init_ex4(py::module &m) {
+void init_ex_constants_and_functions(py::module &m) {
     m.def("test_function", &test_function1);
     m.def("test_function", &test_function2);
     m.def("test_function", &test_function3);
@@ -63,11 +63,11 @@ void init_ex4(py::module &m) {
         .value("ESecondEntry", ESecondEntry)
         .export_values();
 
-    py::class_<Example4> ex4_class(m, "Example4");
-    ex4_class.def_static("test_function", &Example4::test_function);
-    py::enum_<Example4::EMode>(ex4_class, "EMode")
-        .value("EFirstMode", Example4::EFirstMode)
-        .value("ESecondMode", Example4::ESecondMode)
+    py::class_<ExampleWithEnum> exenum_class(m, "ExampleWithEnum");
+    exenum_class.def_static("test_function", &ExampleWithEnum::test_function);
+    py::enum_<ExampleWithEnum::EMode>(exenum_class, "EMode")
+        .value("EFirstMode", ExampleWithEnum::EFirstMode)
+        .value("ESecondMode", ExampleWithEnum::ESecondMode)
         .export_values();
 
     m.def("return_bytes", &return_bytes);

example/example4.py → example/example-constants-and-functions.py

@@ -7,7 +7,7 @@ from example import test_function
 from example import some_constant
 from example import EMyEnumeration
 from example import EFirstEntry
-from example import Example4
+from example import ExampleWithEnum
 from example import return_bytes
 from example import print_bytes
 
@@ -25,34 +25,34 @@ print("integer->enum = %s" % str(EMyEnumeration(2)))
 
 print("A constant = " + str(some_constant))
 
-print(Example4.EMode)
-print(Example4.EMode.EFirstMode)
-print(Example4.EFirstMode)
-Example4.test_function(Example4.EFirstMode)
+print(ExampleWithEnum.EMode)
+print(ExampleWithEnum.EMode.EFirstMode)
+print(ExampleWithEnum.EFirstMode)
+ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode)
 
 print("Equality test 1: " + str(
-    Example4.test_function(Example4.EFirstMode) ==
-    Example4.test_function(Example4.EFirstMode)))
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode) ==
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode)))
 
 print("Inequality test 1: " + str(
-    Example4.test_function(Example4.EFirstMode) !=
-    Example4.test_function(Example4.EFirstMode)))
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode) !=
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode)))
 
 print("Equality test 2: " + str(
-    Example4.test_function(Example4.EFirstMode) ==
-    Example4.test_function(Example4.ESecondMode)))
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode) ==
+    ExampleWithEnum.test_function(ExampleWithEnum.ESecondMode)))
 
 print("Inequality test 2: " + str(
-    Example4.test_function(Example4.EFirstMode) !=
-    Example4.test_function(Example4.ESecondMode)))
+    ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode) !=
+    ExampleWithEnum.test_function(ExampleWithEnum.ESecondMode)))
 
 x = {
-        Example4.test_function(Example4.EFirstMode): 1,
-        Example4.test_function(Example4.ESecondMode): 2
+        ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode): 1,
+        ExampleWithEnum.test_function(ExampleWithEnum.ESecondMode): 2
 }
 
-x[Example4.test_function(Example4.EFirstMode)] = 3
-x[Example4.test_function(Example4.ESecondMode)] = 4
+x[ExampleWithEnum.test_function(ExampleWithEnum.EFirstMode)] = 3
+x[ExampleWithEnum.test_function(ExampleWithEnum.ESecondMode)] = 4
 print("Hashing test = " + str(x))
 
 print_bytes(return_bytes())

example/example4.ref → example/example-constants-and-functions.ref

@@ -16,23 +16,23 @@ A constant = 14
 <class 'example.EMode'>
 EMode.EFirstMode
 EMode.EFirstMode
-Example4::test_function(enum=1)
-Example4::test_function(enum=1)
-Example4::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
 Equality test 1: True
-Example4::test_function(enum=1)
-Example4::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=1)
 Inequality test 1: False
-Example4::test_function(enum=1)
-Example4::test_function(enum=2)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=2)
 Equality test 2: False
-Example4::test_function(enum=1)
-Example4::test_function(enum=2)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=2)
 Inequality test 2: True
-Example4::test_function(enum=1)
-Example4::test_function(enum=2)
-Example4::test_function(enum=1)
-Example4::test_function(enum=2)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=2)
+ExampleWithEnum::test_function(enum=1)
+ExampleWithEnum::test_function(enum=2)
 Hashing test = {EMode.EFirstMode: 3, EMode.ESecondMode: 4}
 bytes[0]=1
 bytes[1]=0

example/example19.cpp → example/example-custom-exceptions.cpp

 /*
-    example/example19.cpp -- exception translation
+    example/example-custom-exceptions.cpp -- exception translation
 
     Copyright (c) 2016 Pim Schellart <P.Schellart@princeton.edu>
 
@@ -66,7 +66,7 @@ void throws_logic_error() {
     throw std::logic_error("this error should fall through to the standard handler");
 }
 
-void init_ex19(py::module &m) {
+void init_ex_custom_exceptions(py::module &m) {
     // make a new custom exception and use it as a translation target
     static py::exception<MyException> ex(m, "MyException");
     py::register_exception_translator([](std::exception_ptr p) {

example/example18.cpp → example/example-eval.cpp

 /*
-    example/example18.cpp -- Usage of eval() and eval_file()
+    example/example-eval.cpp -- Usage of eval() and eval_file()
 
     Copyright (c) 2016 Klemens D. Morgenstern
 
@@ -11,7 +11,7 @@
 #include <pybind11/eval.h>
 #include "example.h"
 
-void example18() {
+void example_eval() {
     py::module main_module = py::module::import("__main__");
     py::object main_namespace = main_module.attr("__dict__");
 
@@ -59,9 +59,9 @@ void example18() {
     main_module.def("call_test2", [&](int value) {val_out = value;});
 
     try {
-        result = py::eval_file("example18_call.py", main_namespace);
+        result = py::eval_file("example-eval_call.py", main_namespace);
     } catch (...) {
-        result = py::eval_file("example/example18_call.py", main_namespace);
+        result = py::eval_file("example/example-eval_call.py", main_namespace);
     }
 
     if (val_out == 42 && result == py::none())
@@ -97,6 +97,6 @@ void example18() {
         cout << "eval_file failure test failed" << endl;
 }
 
-void init_ex18(py::module & m) {
-    m.def("example18", &example18);
+void init_ex_eval(py::module & m) {
+    m.def("example_eval", &example_eval);
 }

example/example-eval.py

+from example import example_eval
+
+example_eval()
+
+