more doc

Author: jll63

doc/modules/ROOT/examples/ast.cpp

@@ -5,80 +5,65 @@
 
 // clang-format off
 
-// tag::ast[]
-
-#include <iostream>
-
-#include <boost/openmethod.hpp>
-#include <boost/openmethod/initialize.hpp>
-
-using boost::openmethod::virtual_ptr;
-
+// tag::content[]
 struct Node {
     virtual ~Node() {}
+    virtual int value() const = 0;
 };
 
 struct Variable : Node {
-    explicit Variable(int value) : value(value) {}
-
-    int value;
+    Variable(int value) : v(value) {}
+    int value() const override { return v; }
+    int v;
 };
 
 struct Plus : Node {
-    Plus(virtual_ptr<Node> left, virtual_ptr<Node> right)
-        : left(left), right(right) {}
-
-    virtual_ptr<Node> left, right;
+    Plus(const Node& left, const Node& right) : left(left), right(right) {}
+    int value() const override { return left.value() + right.value(); }
+    const Node& left; const Node& right;
 };
 
-struct Negate : Node {
-    explicit Negate(virtual_ptr<Node> node) : child(node) {}
-
-    virtual_ptr<Node> child;
+struct Times : Node {
+    Times(const Node& left, const Node& right) : left(left), right(right) {}
+    int value() const override { return left.value() * right.value(); }
+    const Node& left; const Node& right;
 };
 
-BOOST_OPENMETHOD(value, (virtual_ptr<Node>), int);
+#include <boost/openmethod.hpp>
+#include <boost/openmethod/initialize.hpp>
+#include <iostream>
 
-BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Variable> node), int) {
-    return node->value;
-}
+using boost::openmethod::virtual_ptr;
 
-BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Plus> node), int) {
-    return value(node->left) + value(node->right);
-}
+BOOST_OPENMETHOD(postfix, (virtual_ptr<const Node> node, std::ostream& os), void);
 
-BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Negate> node), int) {
-    return -value(node->child);
+BOOST_OPENMETHOD_OVERRIDE(
+    postfix, (virtual_ptr<const Variable> var, std::ostream& os), void) {
+    os << var->v;
 }
 
-BOOST_OPENMETHOD_CLASSES(Node, Variable, Plus, Negate);
-
-auto main() -> int {
-    boost::openmethod::initialize();
-
-    Variable one(1), two(2);
-    Plus sum(one, two);
-    Negate neg(sum);
-
-    std::cout << value(neg) << "\n"; // -3
-
-    return 0;
+BOOST_OPENMETHOD_OVERRIDE(
+    postfix, (virtual_ptr<const Plus> plus, std::ostream& os), void) {
+    postfix(plus->left, os);
+    os << ' ';
+    postfix(plus->right, os);
+    os << " +";
 }
-// end::ast[]
 
-auto negate(virtual_ptr<Node> node) -> int {
-    return -value(node);
+BOOST_OPENMETHOD_OVERRIDE(
+    postfix, (virtual_ptr<const Times> times, std::ostream& os), void) {
+    postfix(times->left, os);
+    os << ' ';
+    postfix(times->right, os);
+    os << " *";
 }
 
-#define main alt_main
+BOOST_OPENMETHOD_CLASSES(Node, Variable, Plus, Times);
 
-auto main() -> int {
-// tag::final[]
-    Variable one(1);
-    Negate neg(boost::openmethod::final_virtual_ptr(one));
-// end::final[]
-
-    std::cout << value(boost::openmethod::final_virtual_ptr(neg)) << "\n"; // -3
-
-    return 0;
+int main() {
+    boost::openmethod::initialize();
+    Variable a{2}, b{3}, c{4};
+    Plus d{a, b}; Times e{d, c};
+    postfix(e, std::cout);
+    std::cout << " = " << e.value() << "\n"; // 2 3 + 4 * = 20
 }

doc/modules/ROOT/examples/ast_virtual_function.cpp

@@ -5,10 +5,9 @@
 
 // clang-format off
 
+// tag::content[]
 #include <iostream>
 
-// tag::all[]
-
 struct Node {
     virtual ~Node() {}
     virtual int value() const = 0;
@@ -35,6 +34,6 @@ struct Times : Node {
 int main() {
     Variable a{2}, b{3}, c{4};
     Plus d{a, b}; Times e{d, c};
-    std::cout << e.value() << "\n"; // prints "20"
+    std::cout << e.value() << "\n"; // 20
 }
-// end::all[]
+// end::content[]

doc/modules/ROOT/examples/ast_virtual_function_2.cpp

@@ -5,9 +5,8 @@
 
 // clang-format off
 
-#include <iostream>
-
 // tag::all[]
+#include <iostream>
 
 struct Node {
     virtual ~Node() {}

doc/modules/ROOT/nav.adoc

@@ -1,11 +1,10 @@
-* xref:motivation.adoc[Motivation]
-* Basic Features
-** xref:hello_world.adoc[Hello World]
-** xref:smart_pointers.adoc[Smart Pointers]
-** xref:performance.adoc[Performance]
-** xref:headers_namespaces.adoc[Headers and Namespaces]
-** xref:friendship.adoc[Friendship]
-** xref:multiple_dispatch.adoc[Multiple Dispatch]
+* xref:introduction.adoc[Introduction]
+* xref:basics.adoc[Basics]
+* xref:smart_pointers.adoc[Smart Pointers]
+* xref:performance.adoc[Performance]
+* xref:headers_namespaces.adoc[Headers and Namespaces]
+* xref:friendship.adoc[Friendship]
+* xref:multiple_dispatch.adoc[Multiple Dispatch]
 * Advanced Features
 ** xref:core_api.adoc[Core API]
 ** xref:virtual_ptr_alt.adoc[Virtual Pointer Alternatives]

doc/modules/ROOT/pages/basics.adoc

@@ -0,0 +1,105 @@
+:exampledir: ../example
+
+## Basics
+
+An _open-method_ is a free-standing function that takes one or more _virtual_
+_parameters_. When it is called, it forwards to an _overrider_ selected by
+examining the dynamic type of the virtual parameters.
+
+If this sounds like a virtual function, that's because because an open-method
+with one virtual parameter is equivalent to a virtual function - with a big
+difference: it exists outside of classes.
+
+A virtual parameter is in the form `virtual_ptr<C>`. It is a pointer-like class
+that points to an instance of class `C`.
+
+To create an open-method that implements the `postfix` operation, we use the
+xref:BOOST_OPENMETHOD.adoc[BOOST_OPENMETHOD] macro:
+
+```c++
+BOOST_OPENMETHOD(
+    postfix, (virtual_ptr<const Node> node, std::ostream& os), void);
+```
+
+This method is called `postfix`. It takes one virtual parameter, `node`, and one
+non-virtual parameter, `os`. It returns `void`. The macro generates the
+following function:
+
+```c++
+inline auto postfix(virtual_ptr<const Node> node, std::ostream& os) -> void {
+    // examine the type of *node
+    // select an overrider
+    // call it
+}
+```
+
+Before we can call the method, we need to define overriders. For this we use the
+xref:BOOST_OPENMETHOD_OVERRIDE.adoc[BOOST_OPENMETHOD_OVERRIDE] macro:
+
+```c++
+BOOST_OPENMETHOD_OVERRIDE(
+    postfix, (virtual_ptr<const Variable> var, std::ostream& os), void) {
+    os << var->v;
+}
+```
+
+The overrider must have virtual parameters in the same position as in the
+method, and they must point to an object of the same class as in the method, or
+a class derived from it. The other parameters must have the same types as in the
+method.
+
+Let's look at another overrider:
+
+```c++
+BOOST_OPENMETHOD_OVERRIDE(
+    postfix, (virtual_ptr<const Plus> plus, std::ostream& os), void) {
+    postfix(plus->left, os);
+    os << ' ';
+    postfix(plus->right, os);
+}
+```
+
+This one calls `postfix` recursively to print the left and right
+sub-expressions. Note that we call the method just like an ordinary function.
+
+`postfix` expects a `virtual_ptr<const Node>`, and we are passing it a _plain_
+_reference_ to a `Plus` object. This works because `virtual_ptr` has conversion
+constructors from plain references or pointers to an object, or from other
+`virtual_ptr` to compatible classes.
+
+There are two more things we need to do.
+
+OpenMethod is a library, not a compiler. It needs to be aware of all the classes
+that may be used as virtual parameters, and in method calls, and their
+inheritance relationships. We do this using the
+xref:BOOST_OPENMETHOD_CLASSES.adoc[BOOST_OPENMETHOD_CLASSES] macro:
+
+```c++
+BOOST_OPENMETHOD_CLASSES(Node, Variable, Plus, Times);
+```
+
+Classes can be registered multiple times, in any order, and incrementally. Every
+direct base of a class must appear together with it in at least one call to
+`BOOST_OPENMETHOD_CLASSES`. This enables the library to deduce the complete
+inheritance lattice.
+
+Finally, we need to call `boost::openmethod::initialize()` before the first call
+to an open-method. This builds the dispatch tables used during method calls. It
+is typically done once, at the very beginning of main, and requires the
+inclusion of `<boost/openmethod/initialize.hpp>`.
+
+```c++
+#include <boost/openmethod/initialize.hpp>
+
+int main() {
+    boost::openmethod::initialize();
+    // ...
+}
+```
+
+Putting it all together:
+
+[source,cpp]
+----
+include::{examplesdir}/ast.cpp[tag=content]
+----