Documentation.

docs/http_client.cc

@@ -1,51 +1,76 @@
-li::http_client
+
+/*
+http_client
 ===============================
 
-`li::http_client` is an easy to use http client built around
-the libcurl library.
+## Header
+```c++
+#include <lithium_http_client.hh>
+```
 
+## Introduction
+`li::http_client` is an easy to use blocking http client wrapping the libcurl library.
+Lithium use it internally to test http servers. Thanks to Lithium's metamap and named parameters, it
+simplifies a lot the writing of HTTP requests.
 
-# Tutorial
+### Dependencies
+- libcurl
 
-```c++
-using namespace li;
 
-// Simple GET request:
-auto res = http_get("http://www.google.com");
-// returns an object with a status and a body member.
-std::cout << res.status << std::endl;
-std::cout << res.body << std::endl;
+## Tutorial
 
-// http_post, http_put, http_delete are also avalable.
+*/
 
-// GET and POST Parameters.
-auto res = http_post("http://my_api.com/update_test", 
-                     s::get_parameters = mmm(s::id = 42), 
-                     s::post_parameters = mmm(s::name = "John", s::age = 42));
+#include <lithium_http_client.hh>
 
-// Access to headers.
-auto res = http_get("http://my_api.com/hello", s::fetch_headers);
-// returns an object with a status, body AND headers member.
-for (auto pair : res.headers) {
-  std::cout << pair.first << ":::" << pair.second  << std::endl;
-}
-```
+using namespace li;
+
+int main() 
+{
 
-# What is the s:: namespace ?
+  // Simple GET request:
+  auto res = http_get("http://www.google.com");
+  // returns an object with a status and a body member.
+  std::cout << res.status << std::endl;
+  std::cout << res.body << std::endl;
 
-Everything explained here: https://github.com/matt-42/lithium/tree/master/libraries/symbol#lisymbol
+  // http_post, http_put, http_delete are also avalable.
 
-# Installation / Supported compilers
+  // GET and POST Parameters.
+  auto res = http_post("http://my_api.com/update_test", 
+                      s::get_parameters = mmm(s::id = 42), 
+                      s::post_parameters = mmm(s::name = "John", s::age = 42));
 
-Everything explained here: https://github.com/matt-42/lithium#installation
+  // Access to headers.
+  auto res = http_get("http://my_api.com/hello", s::fetch_headers);
+  // returns an object with a status, body AND headers member.
+  for (auto pair : res.headers) {
+    std::cout << pair.first << ":::" << pair.second  << std::endl;
+  }
+
+}
+/*
+## Reference
+
+```c++
+auto result = http_[get/post/put/delete](std::string url, options...)
+```
 
+Send a get/post/put/delete HTTP request at the provided url. The return value contains the following fields:
+- `int result.status`: The status of the HTTP response
+- `string result.body`: The body of the HTTP response
+- `map<string, string> result.headers`: Only if option `s::fetch_headers` is provided. The headers of the HTTP response.
 
-# Authors
 
-Matthieu Garrigues https://github.com/matt-42
+Available options:
 
+  - `s::get_parameters` : a metamap of the GET parameters. 
+  - `s::post_parameters` : a metamap of the POST parameters.
+  - `s::fetch_headers` : add the headers field to the return value.
+  - `s::disable_check_certificate`: disable SSL certificate check.
+  - `s::json_encoded` : JSON encode the POST parameters (default: url encode) 
+*/
 
-# Support the project
 
-If you find this project helpful, please consider donating:
-https://www.paypal.me/matthieugarrigues
+  
+  

docs/http_server.cc

@@ -7,6 +7,11 @@ int main() {
 http_server
 =================================
 
+## Header
+
+```c++
+#include <lithium_http_server.hh>
+```
 ## Introduction
 
 ### Motivations
@@ -52,7 +57,7 @@ Run it with the cli:
 $ li run ./hello_world.cc
 ```
 
-## Serving HTTP(s)
+## Serving HTTP / HTTPS
 
 ```c++
 void http_serve(http_api api, int port, options...)

docs/json.cc

@@ -1,10 +1,24 @@
+#include <lithium_json.hh>
+int main ()
+{
+  using namespace li;
+  std::string json_str;
 // __documentation_starts_here__
 /*
 json
 ============================
 
+## Header
+
+```c++
+#include <lithium_json.hh>
+```
+
+## Introduction
+
 ``li::json`` is a C++17 JSON serializer/deserializer designed for
-ease of use and performances.
+ease of use and performances. It can decode and encode Lithium metamaps (thanks to metamap
+static introspection), standard C++ containers and any custom types (with some user provided hints)
 
 It handle a subset of other JSON serialization libraries: **Only cases
 where the structure of the object is known at compile time are covered**.
@@ -15,49 +29,100 @@ It these specific cases, metajson is faster and produce smaller binaries.
   - Header only
   - UTF-8 support
   - Exception free
-  - Small codebase: 1200 LOC
+  - Small codebase: 1000 LOC
   - Portable: No architecture specific code.
 
 **Limitations:**
-  - li::json only handles JSON objects with a **static structure known at compile time**.
-  - li::json properly handle decoding and encoding UTF-8 but not the others UTF-{32|16} {big|little} endian encodings.
-  - No explicit errors for ill-formatted json messsages.
+  - It only handles JSON objects with a **static structure known at compile time**.
+  - It properly handle decoding and encoding UTF-8 but not the others UTF-{32|16} {big|little} endian encodings.
+  - No explicit errors for ill-formatted json messsages yet.
 
-**Performances:** Up to **9x** faster than nlohmann/json and **2x**
-  faster than rapidjson*. I did not find usecases where li::json was
-  not the fastest. If you find some, please report.
+**Performances:** Up to **9x** faster than nlohmann/json [2] and **2x**
+  faster than rapidjson [1]. I did not find usecases where it was
+  not the fastest. If you find some, please report an issue.
 
 **Binary code size:** Up to **8x** smaller than nlohmann/json and **2x** smaller than rapidjson*.
 
-[1] https://github.com/miloyip/rapidjson
-
-[2] https://github.com/nlohmann/json
-
-[3] https://github.com/AlDanial/cloc
+- [1] https://github.com/miloyip/rapidjson
+- [2] https://github.com/nlohmann/json
 
-\* Theses numbers are not given by an comprehensive benchmark. They just give a rough idea
+Theses numbers are not given by an comprehensive benchmark. They just give a rough idea
 of metajson performances and does not take into account the fact that other libraries provides
 more features.
 
-## Overview
+## Encoding
+
+```c++
+void json_encode(const O& object);
+```
+
+`json_encode` works out of the box for a set of types:
+- standard C++ scalars: strings, integers, bool: encoded as json values
+- lithium metamaps: encoded as json object
+- `std::vector`: encoded as a json array
+- `std::tuple`: encoded as a json array
+- `std::variant`: encoded as {"idx": variant_index,"value": serialized_value}
+- `std::optional`: when the optional is null, does not encode anything, if an object member is std::optional, skip it if is null.  
+- `std::map`: encoded as json object
+- `std::unordered_map`: encoded as json object
 
-Note: This example use the single header version.
+### Pointers deferencing
+
+When `json_decode` meet an object pointer, it deferences it and serialize the pointer object.
+
+### Encoding custom object types
+
+Since there is no way for Lithium to know the members names your object, you need to describe the member or
+accessor names whenever you serialize:
+- a custom object
+- a vector of custom objects 
+- a map of custom objects
+
+#### json_object
+
+`json_object` takes the list of member or accessor names that you want to serialize.
 
 */
+struct { 
+  int age; 
+  std::string name() { return "Bob"; } 
+} gm;
 
-LI_SYMBOL(name)
-LI_SYMBOL(age)
-LI_SYMBOL(entry)
-LI_SYMBOL(id)
+json_str = json_object(s::age, s::name).encode(gm);
 
-int main ()
-{
-  using li::json_encode;
-  using li::json_decode;
-  using li::json_object;
-  using li::json_vector;
-  using li::json_key;
-  using li::mmm;
+/*
+
+#### `json_vector` for accessed with `array[int_index]`
+
+`json_vector` takes the list of member or accessor names that you want to serialize from the vector elements.
+
+*/
+
+struct A { int age; std::string name; };
+std::vector<A> array{ {12, "John"},  {2, "Alice"},  {32, "Bob"} };
+json_str = json_vector(s::age, s::name).encode(array);
+
+/*
+#### `json_map` for maps accessed with `map[string_key]`
+
+*/
+std::unordered_map<std::string, int> test;
+
+/*
+Some examples:
+
+### Metamaps
+
+*/
+  auto map = mmm(s::age = 12, s::name = std::string("John"));
+  json_str = json_encode(map);
+/*
+### Metamaps
+
+*/
+  auto map = mmm(s::age = 12, s::name = std::string("John"));
+  json_str = json_encode(map);
+/*
 
   std::string json_str;
 
@@ -99,9 +164,6 @@ int main ()
   li::json_encode(std::variant<int,std::string>{"abc"});
   // {"idx":1,"value":"abc"}
   
-  // Arrays of structs
-  std::vector<A> array{ {12, "John"},  {2, "Alice"},  {32, "Bob"} };
-  json_str = json_vector(s::age, s::name).encode(array);
   
   std::cout << json_str << std::endl;
   // [{"age":12,"name":"John"},{"age":2,"name":"Alice"},{"age":32,"name":"Bob"}]

docs/sql.cc

@@ -9,6 +9,13 @@
 SQL
 ================================
 
+## Header
+
+```c++
+#include <lithium_json.hh>
+```
+
+## Introduction
 ``li::sql`` is a set of high performance and easy to use C++ SQL drivers built on top of the C
 drivers provided by the databases. It allows you to target MySQL, PostgreSQL and SQLite under the
 same C++ API which is significantly smaller and easier to learn than the C APIs provided by the
@@ -24,25 +31,19 @@ It features:
 All the three connectors are following the same API so you can use the same way
 a SQLite, MySQL or PostgreSQL database.
 
-## Dependency
+### Dependency
   MariaDB mysqlClient
 
-## Installation
-
-https://github.com/matt-42/lithium/tree/master/INSTALL.md
-
-## Runtime Performances
+### Runtime Performances
 
 All ``li::sql`` abstractions are unwrapped at compile time so it adds almost zero overhead over the
 raw C drivers of the databases. According to the [Techempower
 benchmark](http://tfb-status.techempower.com/), Lithium MySQL and PostgreSQL drivers are part of the
 fastest available.
 
-## Learning Curve
+### Overview
 
-While building a fast DB driver, we did not do any compromise on the ease of use of the library.
-The learning curve of this library is inferior to 5 minutes since it's API has only 5 functions
-(excluding the ORM):
+The API contains only 7 operators (excluding the ORM):
   - `database::connect` to get a connection
   - `connection::operator()` to execute queries
   - `connection::prepare` to build prepared statements