From 790a3cebf9c64038ddb450eabacdec2e85f8f625 Mon Sep 17 00:00:00 2001 From: Marcelo Zimbres Date: Sat, 18 Dec 2021 17:42:05 +0100 Subject: [PATCH] Renames and improves examples. --- Makefile.am | 50 ++-- doc/Doxyfile | 44 ++-- doc/DoxygenLayout.xml | 226 ++++++++++++++++++ doc/aedis.css | 25 ++ doc/htmlfooter.html | 20 ++ doc/htmlheader.html | 54 +++++ examples/containers.cpp | 18 +- examples/{intro1.cpp => intro.cpp} | 2 +- examples/intro2.cpp | 67 ------ examples/intro3.cpp | 89 ------- examples/{custom_response2.cpp => lists.cpp} | 23 +- examples/non_flat_response.cpp | 2 +- .../{helper_queue1.cpp => response_queue.cpp} | 0 ...om_serialization.cpp => serialization.cpp} | 2 +- examples/{intro4.cpp => subscriber.cpp} | 2 +- 15 files changed, 376 insertions(+), 248 deletions(-) create mode 100644 doc/DoxygenLayout.xml create mode 100644 doc/aedis.css create mode 100644 doc/htmlfooter.html create mode 100644 doc/htmlheader.html rename examples/{intro1.cpp => intro.cpp} (98%) delete mode 100644 examples/intro2.cpp delete mode 100644 examples/intro3.cpp rename examples/{custom_response2.cpp => lists.cpp} (87%) rename examples/{helper_queue1.cpp => response_queue.cpp} (100%) rename examples/{custom_serialization.cpp => serialization.cpp} (98%) rename examples/{intro4.cpp => subscriber.cpp} (98%) diff --git a/Makefile.am b/Makefile.am index 0bb0a9ec..1135a898 100644 --- a/Makefile.am +++ b/Makefile.am @@ -42,55 +42,45 @@ libaedis_a_SOURCES += $(top_srcdir)/src/aedis.cpp libaedis_a_CPPFLAGS = $(MY_CPPFLAGS) noinst_PROGRAMS = -noinst_PROGRAMS += intro1 -intro1_SOURCES = $(top_srcdir)/examples/intro1.cpp -intro1_CPPFLAGS = $(MY_CPPFLAGS) -intro1_LDADD = $(MY_LDADD) +noinst_PROGRAMS += intro +intro_SOURCES = $(top_srcdir)/examples/intro.cpp +intro_CPPFLAGS = $(MY_CPPFLAGS) +intro_LDADD = $(MY_LDADD) -noinst_PROGRAMS += intro2 -intro2_SOURCES = $(top_srcdir)/examples/intro2.cpp -intro2_CPPFLAGS = $(MY_CPPFLAGS) -intro2_LDADD = $(MY_LDADD) - -noinst_PROGRAMS += intro3 -intro3_SOURCES = $(top_srcdir)/examples/intro3.cpp -intro3_CPPFLAGS = $(MY_CPPFLAGS) -intro3_LDADD = $(MY_LDADD) - -noinst_PROGRAMS += intro4 -intro4_SOURCES = $(top_srcdir)/examples/intro4.cpp -intro4_CPPFLAGS = $(MY_CPPFLAGS) -intro4_LDADD = $(MY_LDADD) +noinst_PROGRAMS += subscriber +subscriber_SOURCES = $(top_srcdir)/examples/subscriber.cpp +subscriber_CPPFLAGS = $(MY_CPPFLAGS) +subscriber_LDADD = $(MY_LDADD) noinst_PROGRAMS += containers containers_SOURCES = $(top_srcdir)/examples/containers.cpp containers_CPPFLAGS = $(MY_CPPFLAGS) containers_LDADD = $(MY_LDADD) -noinst_PROGRAMS += custom_serialization -custom_serialization_SOURCES = $(top_srcdir)/examples/custom_serialization.cpp -custom_serialization_CPPFLAGS = $(MY_CPPFLAGS) -custom_serialization_LDADD = $(MY_LDADD) +noinst_PROGRAMS += serialization +serialization_SOURCES = $(top_srcdir)/examples/serialization.cpp +serialization_CPPFLAGS = $(MY_CPPFLAGS) +serialization_LDADD = $(MY_LDADD) noinst_PROGRAMS += non_flat_response non_flat_response_SOURCES = $(top_srcdir)/examples/non_flat_response.cpp non_flat_response_CPPFLAGS = $(MY_CPPFLAGS) non_flat_response_LDADD = $(MY_LDADD) -noinst_PROGRAMS += custom_response2 -custom_response2_SOURCES = $(top_srcdir)/examples/custom_response2.cpp -custom_response2_CPPFLAGS = $(MY_CPPFLAGS) -custom_response2_LDADD = $(MY_LDADD) +noinst_PROGRAMS += lists +lists_SOURCES = $(top_srcdir)/examples/lists.cpp +lists_CPPFLAGS = $(MY_CPPFLAGS) +lists_LDADD = $(MY_LDADD) noinst_PROGRAMS += echo_server echo_server_SOURCES = $(top_srcdir)/examples/echo_server.cpp echo_server_CPPFLAGS = $(MY_CPPFLAGS) echo_server_LDADD = $(MY_LDADD) -noinst_PROGRAMS += helper_queue1 -helper_queue1_SOURCES = $(top_srcdir)/examples/helper_queue1.cpp -helper_queue1_CPPFLAGS = $(MY_CPPFLAGS) -helper_queue1_LDADD = $(MY_LDADD) +noinst_PROGRAMS += response_queue +response_queue_SOURCES = $(top_srcdir)/examples/response_queue.cpp +response_queue_CPPFLAGS = $(MY_CPPFLAGS) +response_queue_LDADD = $(MY_LDADD) noinst_PROGRAMS += test test_SOURCES = $(top_srcdir)/tests/general.cpp diff --git a/doc/Doxyfile b/doc/Doxyfile index a4f9d98e..24dac256 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -44,7 +44,7 @@ PROJECT_NUMBER = 1.0.0 # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = An async redis client +PROJECT_BRIEF = "Reference guide" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 @@ -263,12 +263,6 @@ TAB_SIZE = 4 ALIASES = -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all @@ -467,7 +461,7 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = NO +EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. @@ -616,7 +610,7 @@ SORT_MEMBER_DOCS = YES # this will also influence the order of the classes in the class list. # The default value is: NO. -SORT_BRIEF_DOCS = NO +SORT_BRIEF_DOCS = YES # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the # (brief and detailed) documentation of class members so that constructors and @@ -628,7 +622,7 @@ SORT_BRIEF_DOCS = NO # detailed member documentation. # The default value is: NO. -SORT_MEMBERS_CTORS_1ST = NO +SORT_MEMBERS_CTORS_1ST = YES # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will @@ -741,7 +735,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = +LAYOUT_FILE = doc/DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -867,7 +861,6 @@ FILE_PATTERNS = *.c \ *.ipp \ *.i++ \ *.inl \ - *.idl \ *.ddl \ *.odl \ *.h \ @@ -944,7 +937,7 @@ EXCLUDE_PATTERNS = # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* -EXCLUDE_SYMBOLS = +EXCLUDE_SYMBOLS = std # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include @@ -1039,7 +1032,7 @@ USE_MDFILE_AS_MAINPAGE = # also VERBATIM_HEADERS is set to NO. # The default value is: NO. -SOURCE_BROWSER = NO +SOURCE_BROWSER = YES # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. @@ -1154,13 +1147,6 @@ CLANG_DATABASE_PATH = ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -1211,7 +1197,7 @@ HTML_FILE_EXTENSION = .html # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_HEADER = +HTML_HEADER = doc/htmlheader.html # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank doxygen will generate a standard @@ -1221,7 +1207,7 @@ HTML_HEADER = # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_FOOTER = +HTML_FOOTER = doc/htmlfooter.html # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of @@ -1246,7 +1232,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doc/aedis.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1295,7 +1281,7 @@ HTML_COLORSTYLE_GAMMA = 80 # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_TIMESTAMP = NO +HTML_TIMESTAMP = YES # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that @@ -1526,7 +1512,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -DISABLE_INDEX = NO +DISABLE_INDEX = YES # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag @@ -1543,7 +1529,7 @@ DISABLE_INDEX = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. @@ -1553,7 +1539,7 @@ GENERATE_TREEVIEW = NO # Minimum value: 0, maximum value: 20, default value: 4. # This tag requires that the tag GENERATE_HTML is set to YES. -ENUM_VALUES_PER_LINE = 0 +ENUM_VALUES_PER_LINE = 4 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used # to set the initial width (in pixels) of the frame in which the tree is shown. @@ -1604,7 +1590,7 @@ FORMULA_MACROFILE = # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -USE_MATHJAX = NO +USE_MATHJAX = YES # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: diff --git a/doc/DoxygenLayout.xml b/doc/DoxygenLayout.xml new file mode 100644 index 00000000..de17dbcd --- /dev/null +++ b/doc/DoxygenLayout.xml @@ -0,0 +1,226 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/aedis.css b/doc/aedis.css new file mode 100644 index 00000000..81fa0226 --- /dev/null +++ b/doc/aedis.css @@ -0,0 +1,25 @@ +/* Doxygen HTML_EXTRA_STYLESHEET */ + +div.contents { + max-width: 100em; + margin-right: 5em; + margin-left: 5em; +} + +.ui-resizable-e { + background-image:url("splitbar.png"); + background-size:100%; + background-repeat:repeat-y; + background-attachment: scroll; + cursor:ew-resize; + height:100%; + right:0; + top:0; + width:1px; +} + +.pyrootbox { + border: 1px solid #879ecb; + background-color: #f9fafc; + padding: 15px; +} diff --git a/doc/htmlfooter.html b/doc/htmlfooter.html new file mode 100644 index 00000000..d3fb0c03 --- /dev/null +++ b/doc/htmlfooter.html @@ -0,0 +1,20 @@ + + + + + + +
+Aedis - Reference Guide Generated on $datetime (GVA Time) using Doxygen $doxygenversion    +root +
+ + + diff --git a/doc/htmlheader.html b/doc/htmlheader.html new file mode 100644 index 00000000..c9b4f128 --- /dev/null +++ b/doc/htmlheader.html @@ -0,0 +1,54 @@ + + + + + + + + +$projectname: $title +$title + + + +$treeview +$search +$mathjax + +$extrastylesheet + + + + + + + + + + +
+ + +
+ + + + + + + + +
$projectname   + +
+ +
+
+
+ + +
$projectbrief 		$searchbox
+
+ + diff --git a/examples/containers.cpp b/examples/containers.cpp index fa324bc3..135f1620 100644 --- a/examples/containers.cpp +++ b/examples/containers.cpp @@ -26,14 +26,12 @@ namespace net = aedis::net; using net::async_write; using net::buffer; -/** An example on how to serialize containers in a request and read them back. +/** An example on how to serialize containers in a request and read + them back. */ std::string make_request() { - std::vector vec - {1, 2, 3, 4, 5, 6}; - std::set set {"one", "two", "three", "four"}; @@ -48,12 +46,10 @@ std::string make_request() sr.push(command::flushall); // Set the containers in some of the redis built-in data structures. - sr.push_range(command::rpush, "key1", std::cbegin(vec), std::cend(vec)); sr.push_range(command::sadd, "key2", std::cbegin(set), std::cend(set)); sr.push_range(command::hset, "key3", std::cbegin(map), std::cend(map)); // Retrieves the containers back from redis. - sr.push(command::lrange, "key1", 0, -1); sr.push(command::smembers, "key2"); sr.push(command::smembers, "key2"); sr.push(command::hgetall, "key3"); @@ -71,8 +67,7 @@ net::awaitable containers() co_await async_write(socket, buffer(req)); // The expected responses - int rpush, sadd, hset; - std::vector lrange; + int sadd, hset; std::set smembers1; std::unordered_set smembers2; std::map hgetall; @@ -81,25 +76,18 @@ net::awaitable containers() std::string buffer; co_await async_read(socket, buffer); // hello co_await async_read(socket, buffer); // flushall - co_await async_read(socket, buffer, adapt(rpush)); // rpush co_await async_read(socket, buffer, adapt(sadd)); // sadd co_await async_read(socket, buffer, adapt(hset)); // hset - co_await async_read(socket, buffer, adapt(lrange)); // lrange co_await async_read(socket, buffer, adapt(smembers1)); // smembers co_await async_read(socket, buffer, adapt(smembers2)); // smembers co_await async_read(socket, buffer, adapt(hgetall)); // hgetall // Prints the responses. std::cout - << "rpush: " << rpush << "\n" << "sadd: " << sadd << "\n" << "hset: " << hset << "\n" ; - std::cout << "lrange: "; - for (auto const& e: lrange) std::cout << e << " "; - std::cout << std::endl; - std::cout << "smembers1: "; for (auto const& e: smembers1) std::cout << e << " "; std::cout << std::endl; diff --git a/examples/intro1.cpp b/examples/intro.cpp similarity index 98% rename from examples/intro1.cpp rename to examples/intro.cpp index 8945b19c..80c9ec47 100644 --- a/examples/intro1.cpp +++ b/examples/intro.cpp @@ -78,4 +78,4 @@ int main() ioc.run(); } -/// \example intro1.cpp +/// \example intro.cpp diff --git a/examples/intro2.cpp b/examples/intro2.cpp deleted file mode 100644 index d5a65ecc..00000000 --- a/examples/intro2.cpp +++ /dev/null @@ -1,67 +0,0 @@ -/* Copyright (c) 2019 - 2021 Marcelo Zimbres Silva (mzimbres at gmail dot com) -/// \example basic1.cpp - * - * This Source Code Form is subject to the terms of the Mozilla Public - * License, v. 2.0. If a copy of the MPL was not distributed with this - * file, You can obtain one at https://mozilla.org/MPL/2.0/. - */ - -#include -#include -#include "utils.ipp" - -using aedis::command; -using aedis::resp3::serializer; -using aedis::resp3::async_read; -using aedis::resp3::node; -using aedis::resp3::adapt; - -namespace net = aedis::net; -using net::async_write; -using net::buffer; - -/* Similar to the basic1 example but - - 1. Reads the responses in a loop. - 2. Prints the command to which the response belongs to. - - The request class maintains a queue of commands that have been - added to the request. - */ -net::awaitable ping() -{ - try { - serializer sr; - sr.push(command::hello, 3); - sr.push(command::ping); - sr.push(command::quit); - - auto socket = co_await connect(); - co_await async_write(socket, buffer(sr.request())); - - std::string buffer; - std::vector resp; - while (!std::empty(sr.commands)) { - co_await async_read(socket, buffer, adapt(resp)); - - std::cout - << sr.commands.front() << "\n" - << resp << std::endl; - - resp.clear(); - - sr.commands.pop(); - } - } catch (std::exception const& e) { - std::cerr << e.what() << std::endl; - } -} - -int main() -{ - net::io_context ioc; - co_spawn(ioc, ping(), net::detached); - ioc.run(); -} - -/// \example intro2.cpp diff --git a/examples/intro3.cpp b/examples/intro3.cpp deleted file mode 100644 index 6b216847..00000000 --- a/examples/intro3.cpp +++ /dev/null @@ -1,89 +0,0 @@ -/* Copyright (c) 2019 - 2021 Marcelo Zimbres Silva (mzimbres at gmail dot com) - * - * This Source Code Form is subject to the terms of the Mozilla Public - * License, v. 2.0. If a copy of the MPL was not distributed with this - * file, You can obtain one at https://mozilla.org/MPL/2.0/. - */ - -#include -#include -#include "utils.ipp" - -using aedis::command; -using aedis::resp3::serializer; -using aedis::resp3::async_read; -using aedis::resp3::node; -using aedis::resp3::adapt; - -namespace net = aedis::net; -using net::async_write; -using net::buffer; - -/* A slightly more elaborate way dealing with requests and responses. - - This time we send the ping + quit only after the response to the - hello command has been received. We also separate the application - logic out the coroutine for clarity. - */ - -// Adds a new element in the queue if necessary. -void prepare_next(std::queue>& srs) -{ - if (std::empty(srs) || std::size(srs) == 1) - srs.push({}); -} - -/* The function that processes the response has been factored out of - the coroutine to simplify application logic. - */ -void process_response(std::queue>& srs, std::vector const& resp) -{ - std::cout - << srs.front().commands.front() << ":\n" - << resp << std::endl; - - switch (srs.front().commands.front()) { - case command::hello: - prepare_next(srs); - srs.back().push(command::ping); - srs.back().push(command::quit); - break; - default: {}; - } -} - -net::awaitable ping() -{ - try { - std::queue> srs; - srs.push({}); - srs.back().push(command::hello, 3); - - auto socket = co_await connect(); - std::string read_buffer; - - std::vector resp; - while (!std::empty(srs)) { - co_await async_write(socket, buffer(srs.front().request())); - while (!std::empty(srs.front().commands)) { - co_await async_read(socket, read_buffer, adapt(resp)); - process_response(srs, resp); - srs.front().commands.pop(); - } - - srs.pop(); - } - - } catch (std::exception const& e) { - std::cerr << e.what() << std::endl; - } -} - -int main() -{ - net::io_context ioc; - co_spawn(ioc, ping(), net::detached); - ioc.run(); -} - -/// \example intro3.cpp diff --git a/examples/custom_response2.cpp b/examples/lists.cpp similarity index 87% rename from examples/custom_response2.cpp rename to examples/lists.cpp index 4e1236f1..8a4795b6 100644 --- a/examples/custom_response2.cpp +++ b/examples/lists.cpp @@ -50,27 +50,22 @@ net::awaitable ping() auto req = make_request(); co_await async_write(socket, buffer(req)); - std::string rbuffer; + // Responses. + std::vector svec; + std::list slist; + std::deque sdeq; + std::list list; + std::vector vec; + std::deque deq; + std::string rbuffer; co_await async_read(socket, rbuffer); // hello co_await async_read(socket, rbuffer); // rpush - - std::vector svec; // Response as std::vector. co_await async_read(socket, rbuffer, adapt(svec)); // lrange - - std::list slist; // Response as list. co_await async_read(socket, rbuffer, adapt(slist)); // lrange - - std::deque sdeq; // Response as list. co_await async_read(socket, rbuffer, adapt(sdeq)); // lrange - - std::list list; // Response as list. co_await async_read(socket, rbuffer, adapt(list)); // lrange - - std::vector vec; // Response as vector. co_await async_read(socket, rbuffer, adapt(vec)); // lrange - - std::deque deq; // Response as deque. co_await async_read(socket, rbuffer, adapt(deq)); // lrange for (auto e: svec) std::cout << e << " "; @@ -100,4 +95,4 @@ int main() ioc.run(); } -/// \example custom_response2.cpp +/// \example lists.cpp diff --git a/examples/non_flat_response.cpp b/examples/non_flat_response.cpp index 1cdbe819..ed884695 100644 --- a/examples/non_flat_response.cpp +++ b/examples/non_flat_response.cpp @@ -57,4 +57,4 @@ int main() ioc.run(); } -/// \example intro1.cpp +/// \example non_flat_response.cpp diff --git a/examples/helper_queue1.cpp b/examples/response_queue.cpp similarity index 100% rename from examples/helper_queue1.cpp rename to examples/response_queue.cpp diff --git a/examples/custom_serialization.cpp b/examples/serialization.cpp similarity index 98% rename from examples/custom_serialization.cpp rename to examples/serialization.cpp index 133c58d5..009f674d 100644 --- a/examples/custom_serialization.cpp +++ b/examples/serialization.cpp @@ -112,4 +112,4 @@ int main() ioc.run(); } -/// \example custom_serialization.cpp +/// \example serialization.cpp diff --git a/examples/intro4.cpp b/examples/subscriber.cpp similarity index 98% rename from examples/intro4.cpp rename to examples/subscriber.cpp index 809e7353..e83f1240 100644 --- a/examples/intro4.cpp +++ b/examples/subscriber.cpp @@ -76,4 +76,4 @@ int main() ioc.run(); } -/// \example intro4.cpp +/// \example subscriber.cpp