Add documentation for names

Also fix instances of SQLPP_ALIAS_PROVIDER.

Author: rbock

docs/connection_pool.md

@@ -2,7 +2,7 @@
 
 # Connection pools
 
-sqlpp11 has support for connection pools which are centralized caches of database connections. When you need a database connection, you can fetch one from the connection pool, use the connection to make SQL
+sqlpp23 has support for connection pools which are centralized caches of database connections. When you need a database connection, you can fetch one from the connection pool, use the connection to make SQL
 queries and when you no longer need the connection object, destroy it, usually by letting it go out of scope. When a connection object is destroyed, the actual connection to the database server is not closed,
 but put in a cache instead and next time when you need a database connection object, you will be handed one that reuses a cached connection. If there are no connections is the cache, then a new connection
 will be created, wrapped in a connection object and handed to you.

docs/functions.md

@@ -171,7 +171,7 @@ select(sqlpp::value(
 The other use of the `value` function is to wrap a [sub select](/docs/sub_select.md) for use as a selected column.
 
 ```c++
-SQLPP_ALIAS_PROVIDER(cheese_cake); // Declared outside of function
+SQLPP_CREATE_NAME_TAG(cheese_cake); // Declared outside of function
 // ...
 for (const auto& row :
      db(select(all_of(foo),

docs/names.md

@@ -0,0 +1,106 @@
+[**\< Index**](/docs/README.md)
+
+# Names
+
+C++ and SQL use names to refer to entities. sqlpp23 automatically translates
+between names in C++ and names in SQL for columns and tables, e.g. when you
+select columns from a table, the resulting SQL expression contains the correct
+names and the members of result rows also refer to the correct names.
+
+```c++
+for (const auto& row : db(select(
+    foo.id, foo.name, foo.language).from(foo))) {
+    // use row.id, row.name, row.language
+```
+
+This works because tables and their columns are specifically created such that
+they "know" their SQL name.
+
+The C++ name of entities does not matter, though.
+
+```c++
+constexpr auto foo = TabFoo{};  // represented as tab_foo in SQL
+constexpr auto bar = foo; // also represented as tab_foo in SQL
+```
+
+Also, other expressions, like function calls or arithmetic operations, for instance, do
+not have a name per se.
+
+If you want to give something an SQL name or if you want to change its SQL name,
+you can either
+
+- use the name of something that already has a name
+- prepare a name tag
+
+and attach that name tag to a table, column, or expression via the `.as()`
+function.
+
+## Name tags
+
+Name tags are created using the `SQLPP_CREATE_NAME_TAG` macro. It has to be used
+outside of functions (typically in an unnamed namespace), e.g.
+
+```
+// Outside of function scope.
+SQLPP_CREATE_NAME_TAG(my_fancy_name);
+SQLPP_CREATE_NAME_TAG(max_id);
+```
+
+sqlpp23 also provides a couple of convenience name tags in the `sqlpp::alias`
+namespace. These are
+
+```
+sqlpp::alias::a;
+// ...
+sqlpp::alias::z;
+sqlpp::alias::left;
+sqlpp::alias::right;
+```
+
+## `.as()`
+
+Tables, columns, and expressions in sqlpp23 expose the `.as()` member function.
+It takes name tag (see above) or an expression that already has a name as an
+argument and renames the in SQL using the `AS` operator.
+
+```c++
+auto foo = TabFoo{};        // a table called tab_foo in SQL
+auto id = foo.id;           // a column called id in SQL
+auto x = (foo.id + 17) * 4; // an sqlpp expression with no SQL name
+auto seven = 7;             // a value with no SQL name
+
+// re-naming a table, e.g. for a self-join
+auto left = foo.as(sqlpp::alias::left);     // tab_foo AS left
+auto right = foo.as(sqlpp::alias::right);   // tab_foo AS right
+
+// re-naming a column
+id.as(sqlpp::alias::a);     // tab_foo.id AS a
+left.id.as(my_fancy_name);  // left.id AS my_fancy_name
+
+// naming an sqlpp expression
+x.as(foo.id);               // ((tab_foo.id + 17) * 4) AS id
+max(foo.id).as(max_id);     // MAX(tab_foo.id) AS max_id
+
+// naming a value
+sqlpp::value(seven).as(sqlpp::alias::s); // 7 AS s
+```
+
+## C++26 reflection (experimental)
+
+C++26 offers [reflection](https://wg21.link/P2996). One aspect of that is an improved
+meta-programming access to names.
+
+When used with C++26 and reflection support, the library offers another overload of the
+`.as` function.
+
+```c++
+// with reflection, you can use a string literal as template argument to name or
+// rename entities.
+foo.as<"left">();             // tab_foo AS left
+max(left.id).as<"max_id">();  // MAX(left.id) AS max_id
+```
+
+**Experimental**
+As of this writing (2026-02), this is known to compile with g++-16.0.1 with `-freflection`.
+
+[**\< Index**](/docs/README.md)

docs/select.md

@@ -101,8 +101,7 @@ would be `foo.id`, `foo.name` and `foo.hasFun`.
 
 Other expressions, like function calls or arithmetic operations, for instance, do
 not have a name per se. But you can give them a name using the
-`as(name_provider)` method. The easiest way is to use a named expression as
-`name_provider`, e.g.
+`as(name_provider)` method, see [names](/docs/names.md).
 
 ```C++
 const auto unnamed_expression = (foo.id + 17) * 4;
@@ -114,22 +113,6 @@ for (const auto& row : db(select(
 }
 ```
 
-Another option is to define an alias like this:
-
-```C++
-// In namespace scope
-SQLPP_ALIAS_PROVIDER(total);
-
-[...]
-
-// In a function
-for (const auto& row : db(select(sum(id).as(total)).as(foo.id).from(tab).where(true))
-{
-   std::cout << row.total << std::endl;
-}
-
-```
-
 Using aliases also comes in handy when you join tables and have several columns
 of the same name, e.g.
 
@@ -141,7 +124,7 @@ This will result in compile error when accessing `row.id`. One of the columns
 needs an alias.
 
 ```C++
-SQLPP_ALIAS_PROVIDER(barId);
+SQLPP_CREATE_NAME_TAG(barId);
 
 [...]
 
@@ -162,7 +145,7 @@ select(all_of(foo)).from(foo).where(condition);
 `select` will not let you mix aggregates (see [`group_by`](#group-by) and
 [aggregate functions](/docs/aggregate_functions.md)) and non-aggregates, e.g.
 
-````c++
+```c++
 // This will fail to compile as  it mixes aggregate and non-aggregate values.
 db(select(
      foo.id,      // non-aggregate
@@ -187,7 +170,7 @@ select(
     dynamic(maybe1, foo.textN),       // dynamically selected, if maybe1 == true
     dynamic(maybe2, bar.id.as(barId)) // dynamically selected, if maybe2 == true
     ).from(foo.cross_join(bar)).where(condition);
-````
+```
 
 Dynamically selected columns are represented as `std::optional` in the result
 row. In case the condition (e.g. `maybe1`) is false:

docs/sub_select.md

@@ -23,7 +23,7 @@ As seen above, a sub select statement with single column and a single result row
 To use it a sub select as a column, you need to wrap in `sqlpp::value` and give the whole thing a name, e.g.
 
 ```c++
-SQLPP_ALIAS_PROVIDER(cheese_cake); // Declared outside of function
+SQLPP_CREATE_NAME_TAG(cheese_cake); // Declared outside of function
 // ...
 for (const auto& row :
      db(select(all_of(foo),
@@ -56,7 +56,7 @@ A select can be used as a pseudo table in another select. You just have to give
 it a name.
 
 ```c++
-SQLPP_ALIAS_PROVIDER(sub); // Declared outside of functions
+SQLPP_CREATE_NAME_TAG(sub); // Declared outside of functions
 // [...]
 
 auto sub_select = select(all_of(foo)).from(foo).where(foo.id == 42).as(sub);

docs/tables.md

@@ -91,9 +91,9 @@ useful for self-joins, for instance.
 
 ```C++
 // Outside of functions
-SQLPP_ALIAS_PROVIDER(left);
-SQLPP_ALIAS_PROVIDER(right);
-SQLPP_ALIAS_PROVIDER(r_id);
+SQLPP_CREATE_NAME_TAG(left);
+SQLPP_CREATE_NAME_TAG(right);
+SQLPP_CREATE_NAME_TAG(r_id);
 [...]
 
 // Inside a function