more doc

Author: jll63

doc/modules/ROOT/examples/ast.cpp

@@ -18,8 +18,8 @@ struct Node {
     virtual ~Node() {}
 };
 
-struct Literal : Node {
-    explicit Literal(int value) : value(value) {}
+struct Variable : Node {
+    explicit Variable(int value) : value(value) {}
 
     int value;
 };
@@ -39,7 +39,7 @@ struct Negate : Node {
 
 BOOST_OPENMETHOD(value, (virtual_ptr<Node>), int);
 
-BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Literal> node), int) {
+BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Variable> node), int) {
     return node->value;
 }
 
@@ -51,12 +51,12 @@ BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Negate> node), int) {
     return -value(node->child);
 }
 
-BOOST_OPENMETHOD_CLASSES(Node, Literal, Plus, Negate);
+BOOST_OPENMETHOD_CLASSES(Node, Variable, Plus, Negate);
 
 auto main() -> int {
     boost::openmethod::initialize();
 
-    Literal one(1), two(2);
+    Variable one(1), two(2);
     Plus sum(one, two);
     Negate neg(sum);
 
@@ -74,7 +74,7 @@ auto negate(virtual_ptr<Node> node) -> int {
 
 auto main() -> int {
 // tag::final[]
-    Literal one(1);
+    Variable one(1);
     Negate neg(boost::openmethod::final_virtual_ptr(one));
 // end::final[]
 

doc/modules/ROOT/examples/ast_unique_ptr.cpp

@@ -20,8 +20,8 @@ struct Node {
     virtual ~Node() {}
 };
 
-struct Literal : Node {
-    Literal(int value) : value(value) {}
+struct Variable : Node {
+    Variable(int value) : value(value) {}
 
     int value;
 };
@@ -41,7 +41,7 @@ struct Negate : Node {
 
 BOOST_OPENMETHOD(value, (virtual_ptr<Node>), int);
 
-BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Literal> node), int) {
+BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Variable> node), int) {
     return node->value;
 }
 
@@ -53,15 +53,15 @@ BOOST_OPENMETHOD_OVERRIDE(value, (virtual_ptr<Negate> node), int) {
     return -value(node->child);
 }
 
-BOOST_OPENMETHOD_CLASSES(Node, Literal, Plus, Negate);
+BOOST_OPENMETHOD_CLASSES(Node, Variable, Plus, Negate);
 
 auto main() -> int {
     boost::openmethod::initialize();
 
     auto expr = make_unique_virtual<Negate>(
         make_unique_virtual<Plus>(
-            make_unique_virtual<Literal>(1),
-            make_unique_virtual<Literal>(2)));
+            make_unique_virtual<Variable>(1),
+            make_unique_virtual<Variable>(2)));
 
     std::cout << value(expr) << "\n"; // -3
 

doc/modules/ROOT/nav.adoc

@@ -1,3 +1,4 @@
+* xref:motivation.adoc[Motivation]
 * Tutorials
 ** xref:hello_world.adoc[Hello World]
 ** xref:multiple_dispatch.adoc[Multiple Dispatch]

doc/modules/ROOT/pages/index.adoc

@@ -1,76 +1,35 @@
-//
-// Copyright (c) 2025 Jean-Louis Leroy (jean-louis.leroy@gmail.com)
-//
-// Distributed under the Boost Software License, Version 1.0. (See accompanying
-// file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
-//
-// Official repository: https://github.com/boostorg/openmethod
-//
+= Boost.OpenMethod
 
+Boost.OpenMethod is a C++17 library that implements open-methods.
 
-# Introduction
+== Features
 
-Open-methods are similar to virtual functions, but they are not required to be
-members of a class. By being both free and virtual, tdoc/hello_world.adochey provide a solution to
-the Expression Problem:
+* Headers-only.
 
-> Given a set of types, and a set of operations on these types, is it possible
-to add new operations on the existing types, and new types to the existing
-operations, without modifying existing code?
+* Exception agnostic by default.
 
-Open-methods also address the banana-gorilla-jungle problem:
+* Customization points for alternative RTTI systems, error handling, vptr
+placement.
 
-> The problem with object-oriented languages is they’ve got all this implicit
-environment that they carry around with them. You wanted a banana but what you
-got was a gorilla holding the banana and the entire jungle.  — Joe Armstrong,
-creator of Erlang progamming language
+== Requirements
 
-As a bonus, open-methods can take more than one argument into account when
-selecting the appropriate function to call - aka multiple dispatch. For that
-reason, open-methods are often called multi-methods, but that term is
-misleading, as it suggests that the feature is useful only when multiple
-dispatch is needed. In reality,
-https://openaccess.wgtn.ac.nz/articles/thesis/Multiple_Dispatch_in_Practice/16959112/1[it
-has been observed] that, in large systems written in languages that support
-multi-methods, most methods use single-dispatch. The real benefit is in the
-solution to the Expression Problem.
+The library requires a compiler supporting at least C++17.
 
-Open-methods were introduced by the Common Lisp Object System, and they are
-native to many languages: Clojure, Julia, Dylan, TADS, Cecil, Diesel, Nice, etc.
-Bjarne Stroustrup wanted open-methods in C++ almost from the beginning. In D&E
-he writes:
+== Tested Compilers
 
-> I repeatedly considered a mechanism for a virtual function call based on more
-than one object, often called multi-methods. I rejected multi-methods with
-regret because I liked the idea, but couldn’t find an acceptable form under
-which to accept it. [...] Multi-methods is one of the interesting what-ifs of
-C++. Could I have designed and implemented them well enough at the time? Would
-their applications have been important enough to warrant the effort? What other
-work might have been left undone to provide the time to design and implement
-multi-methods? Since about 1985, I have always felt some twinge of regret for
-not providing multi-methods (Stroustrup, 1994, The Design and Evolution of
-C{plus}{plus}, 13.8).
+Boost.OpenMethod has been tested with the following compilers:
 
-Circa 2007, he and his PhD students Peter Pirkelbauer and Yuriy Solodkyy wrote a
-series of papers and a prototype implementation based on the EDG compiler.
-Unfortunately, open-methods never made it into the standard. Stroustrup bemoans,
-in a more recent paper:
+* clang: 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20
+* gcc: 8, 9, 10, 11, 12, 13, 14, 15
+* msvc: 14.3
 
-> In retrospect, I don’t think that the object-oriented notation (e.g., x.f(y))
-should ever have been introduced. The traditional mathematical notation f(x,y)
-is sufficient. As a side benefit, the mathematical notation would naturally have
-given us multi-methods, thereby saving us from the visitor pattern workaround
-(Stroustrup, 2020, Thriving in a Crowded and ChangingWorld: C++ 2006–2020).
+== Quality Assurance
 
-This library implements the features described in the
-http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2216.pdf[N2216 paper],
-with some extensions:
+The development infrastructure for the library includes these per-commit
+analyses:
 
-* a mechanism for calling the next most specialized overrider
+* Coverage reports
+* Clang sanitizers
+* Compilation and tests on Drone.io and GitHub Actions
 
-* support for smart pointers
-
-* customization points for RTTI, error handling, tracing, smart pointers...
-
-Multiple and virtual inheritance are supported, with the exception of repeated
-inheritance.
+== Acknowledgments

doc/modules/ROOT/pages/motivation.adoc

@@ -0,0 +1,88 @@
+
+## Motivation
+
+Consider a class hierarchy that represents and evaluates arithmetic expressions:
+
+[source,cpp]
+----
+include::{examplesdir}/ast_virtual_function.cpp[tag=all]
+----
+
+We want to add a new operation that prints the expression in postfix notation.
+
+
+How do we do it?
+
+There is a simple way: add a new virtual function:
+
+[source,cpp]
+----
+struct Node {
+    // as before
+    virtual void postfix(std::ostream& os) const = 0;
+};
+
+struct Variable : Node {
+    // as before
+    virtual void postfix(std::ostream& os) const override { os << v; }
+};
+
+struct Plus : Node {
+    // as before
+    void postfix(std::ostream& os) const override {
+        left.postfix(os); os << ' '; right.postfix(os); os << " +";
+    }
+};
+
+struct Times : Node {
+    // as before
+    void postfix(std::ostream& os) const override {
+        left.postfix(os); os << ' '; right.postfix(os); os << " *";
+    }
+};
+
+int main() {
+    Variable a{2}, b{3}, c{4};
+    Plus d{a, b}; Times e{d, c};
+    e.postfix(std::cout);
+    std::cout << " = " << e.value() << "\n"; // prints "20"
+}
+----
+
+If the classes are part of a small, self-contained program, this may be the
+reasonable solution. Otherwise, there are serious problems with this approach.
+
+* We need to modify all the classes in the hierarchy, which may be
+  numerous and spread across multiple files, in a real program. This assumes that we have access to their source code.
+
+* We need to recompile all the files that use the Node classes, because the
+layout of their virtual function tables (v-tables) has changed.
+
+* If the Node classes put in a library, and used in several programs, they all
+pull all the overriders of the `postfix` function, even if they don't use
+`postfix` at all.
+
+* They also pull `postfix`{empty}'s transitive dependencies, in this case `std::ostream`, locales, facets, exceptions, etc.
+
+In C++, this problem is often handled via the Visitor design pattern. We may
+still need to modify Node to equip it with Visitor support, but once that is
+done, we can add all the operations we want, albeit in a clumsy fashion. Sadly,
+it is now difficult to add new _Node_ classes, because we have to modify the
+Visitor's interface, and all its implementations, and recompile all the files
+that use the Visitor.
+
+Paul Graham said that design patterns are essentially workarounds for features
+that are missing in less expressive languages. Indeed, in some languages, our
+problem does not even exist. C# has extension classes. Lisp, Clojure, Dylan,
+Julia, Cecil, TADS, and others, have multi-methods.
+
+But wait! What do multi-methods have to do with this problem? There is no
+multiple dispatch going on here! The thing is, "multi-methods" is not a very
+good name. In this document, we will use the term "open-methods" instead (or
+just "methods").
+
+An open-method is like a virtual function, but it exists outside of a class, as
+a free-standing function. We can create all the open-methods we need, without
+ever needing to modify existing classes.
+
+This library implements open-methods for C++17 and above.

doc/openmethod.adoc

@@ -12,7 +12,7 @@ Jean-Louis Leroy
 
 :leveloffset: +1
 
-include::introduction.adoc[]
+include::motivation.adoc[]
 include::tutorial.adoc[]
 include::reference.adoc[]