From 7e15c7a3074e3b58a8c9886993e0a6d5f9acfb3d Mon Sep 17 00:00:00 2001
From: Jan Travnicek <Jan.Travnicek@fit.cvut.cz>
Date: Wed, 16 May 2018 09:59:48 +0200
Subject: [PATCH] wip on the documentation

---
 docs/userGuide/userGuide.tex | 99 +++++++++++++++++++++++++++++++++++-
 1 file changed, 97 insertions(+), 2 deletions(-)

diff --git a/docs/userGuide/userGuide.tex b/docs/userGuide/userGuide.tex
index f1a6c6af4d..685f74034a 100644
--- a/docs/userGuide/userGuide.tex
+++ b/docs/userGuide/userGuide.tex
@@ -194,12 +194,107 @@ The command line interface binary can at start react to changes of algorithms pr
 
 A limited graphical interface allowing to desing complex algorithm is also provided. The limitation is in the number of available algorithms, which is a static subset of all algorithms. The graphical interface is planed to be extended to support all registered algorithm similarly to the command line interface.
 
-This document will mostly focus on describing current status of the command line interface so called aql.
-
 \mainmatter
 
+\chapter{Structure of the code}
+
+The library consists of modules compiled to libraries and some accessors represented by binaries. Modules provide the functionality - either some core code, datatypes, or algorithms. Accessors are usually programmed as a single file with main function. The accessor binary allows interaction with implemented algorithms from bash, or other shell like environment. One more complex accessor binary \emph{aql} exists. This aql accessor itself provides  command line interface to all algorithms.
+
+\section{Structure and overall description of modules}
+
+Each module can be compiled separately. It shares a common makefile, which is parametrized with a configuration. Source files of the module are placed into \emph{src} directory. Modules are tested with appended unit tests. Unit tests are placed in a separate directory \emph{test-src}.
+
+When compiled the modules object files are, depending on the target type, placed into \emph{obj-debug} or \emph{obj-release} directory. Resulting shared library is placed into \emph{lib-debug} or \emph{lib-release}. Similarly object files of unit tests are placed into \emph{obj-test-debug} or \emph{obj-test-release}. An executable binary representing unit tests can be located in \emph{tet-bin-debug} or \emph{test-bin-release} directory.
+
+Compilation of each module requires its dependencies to be compiled as well. One can deside whether to compile only the module itself, only unit tests, or both. When both the code and tests are compiled, the tests are also executed. The respective targets are \emph{build-code-debug} (\emph{build-code-releae}), \emph{build-test-debug} (\emph{build-test-release}), or simply \emph{debug} (\emph{release}).
+
+Compilation may be tuned with some parameters in configuration file. Library name can be specified with LIBRARY parameter, the name of the test binary with TESTBIN. Dependencies split into those of the module and some additional ones required by unit tests. Of those the compilation environment also distinguish other linked modules (LINK\_LIBRARIES) and system libraries which require to be linked to the shared library of the module (SYSTEM\_LIBRARIES). Include paths can be also specified for system libraries with SYSTEM\_INCLUDE\_PATHS. Prefix TEST\_ is used for both types of linked libraries and specification of includes for dependencies of unit tests.
+
+\section{Existing modules}
+
+The algorithm library toolkit consists of these modules: alib2std, alib2measure, alib2abstraction, alib2common, alib2xml, alib2data, alib2aux, alib2str, alib2raw, alib2algo, and alib2cli. Additionaly there are some more modules available mainly for testing purposes: alib2data\_experimental, alib2algo\_experimental, alib2elgo, alib2graph\_data, alib2graph\_algo, and alib2dummy.
+
+\subsection{Standard library extensiton}
+The module alib2std provides extensions to the c++ standard library. The extensition are placed in namespace \emph{ext}, not to colide with the same classes, functions ... in namespace \emph{std} and also because the standard disallowes placing anything new into the std namespace exept specilisations of templated types.
+
+This module exists to simplify some common operations with standard library containers, to serve as a place for backported code from newer standards then used currently. To name a few exaples now consider three-way comparison of standard library containers, print of containers to standard stream with overloaded operator, implementation of copy on write shared pointer, and some standard library containers modified to store array of pointers instead of array of values, while providing almost the same interface.
+
+To use these extended features use prepared includes. For example to use extensitions of standard vector include \emph{alib2/vector}.
+
+\subsection{alib2measure}
+The measure module contains datastructures needed for measurements. Execution of code can be measured usign this module when include \emph{measure} is used. Mmasurements are represented by frames where each frame can contain subframes. Each frame rememberes an ammount of time spend within the frame (not including the subframes), difference in memory usage caused by dynamic allocations and deallocations, and value general purpose counters.
+
+\subsection{alib2abstraction}
+Abstraction is one of the most fundamental concepts of the library. Implementation of it is generalized to a separate module to allow reuse if needed. This module greatly co-operates with alib2cli module.
+
+Every algorithm, cast operation, and datatype implemented in the algorithm library toolkit is so called registered to the internal structures of the abstraction module. The registration allows later execution of each algorithm from the command line iterface.
+
+The registration is achieved through construction of global variables placed to unnamed namespaces or via a function call.
+
+\subsection{alib2common}
+
+\subsection{alib2xml}
+
+\subsection{alib2data}
+
+\subsection{alib2aux}
+
+\subsection{alib2str}
+
+\subsection{alib2raw}
+
+\subsection{alib2algo}
+
+\subsection{alib2cli}
+
+\chapter{Concepts used in the implementation}
+
+\section{Abstraction}
+
+As mentioned the alib2abstraction module provides a facility to register algorithms, casts, datatypes, etc... to its internal structures for later execution on demand from command line interface. Here in this section more detailed description of use and internal behavior of the abstraction concept is provided.
+
+First the documentation focuses on the registration of algorithms, later casts and variables printing and other posibilities.
+
+\subsection{Registration of algorithms via constructors}
+Variables, when constructed, carry on information about the registered algorithm to inside of the abstraction module. Such an approach was chosen to easily hook some code before the execution of main function, so that all registrations are done beforehand at a load time of shared library.
+
+The registration of algorithms is performed via \emph{registration::AbstractRegister} class. The class is templated with types Algorithm, ReturnType, and by means of variadic template also ParameterTypes. The Algorithm type will serve as a source of identifier naming the algorithm. ReturnType and ParameterTypes are exact types of returned value and parameters including const qualifications, reference specifiers, etc. Constructor of the class accepts a function pointer, optionaly algorithm category (unused yet), and optionaly strings representing parameter names (up to the number of parameters specified by templates). Parameter names default to arg0 to argn.
+
+The function pointer must exactly match the requirements set up by ReturnType and ParameterTypes.
+
+auto RegExpEmptyFormalRegExp = registration::AbstractRegister < regexp::properties::RegExpEmpty, bool, const regexp::FormalRegExp < > \& > ( regexp::properties::RegExpEmpty::languageIsEmpty );
+
+Already registered algorithm, cast, printer of datatype can be re-registered as an algorithm. Such a registration is available via \emph{registration::WrapperRegister} class. The class is templated with types Algorithm and ParameterTypes with the same meaning as in case of AbstractRegister. The class constructor accepts a function pointer to a delegate function capable of looking up the actual registered algorthm, cast, ... Also paramter names can be specified as well.
+
+auto xmlParse = registration::WrapperRegister < xml::Parse, ext::deque < sax::Token > \&\& > ( xml::Parse::abstractionFromTokens, "arg0" );
+
+Last option is register a method. The class allowing this kind of registration is \emph{registration::MethodRegister}. It is parametrized again with types Algorithm, ReturnType, additionally ObjectType, and again ParameterTypes. The ObjectType is a decayed type of object on which to call the registered method. Constructor of the method registration class accepts pointer to method, string representing the method name, and optionaly names of parameters.
+
+auto fooBar = registration::MethodRegister < Foo, int, Foo, int > ( \& Foo::bar, "bar" );
+
+The registration::AbstractRegister and registration::MethodRegister also register the exact return type for a normalization automatically.
+
+\subsection{Registration of algorithms via function call}
+The constructors from previous section are merely a tool to call a registrator functions. If the existence of global registration object can be avoided, the respective function can be called directly. Hence any algorithm can be registered at any time before or during the execution of main function. Registration functions do not register for normalization.
+
+The basic registration is of a callback to the algorithm. That is equivalent to use of registration::AbstractRegister class (except for the normalization). The call is to \emph{abstraction::AlgorithmRegistry::registerAlgorithm} which is parametrized with following types: Algorithm, ReturnType and ParameterTypes. As parameters the registration accepts the callback of the algorithm, the category and parameter names. The same requirements for the callback as specified for the registration via constructor apply. The parameter names are accepted in a form of standard c++ array of strings of size equal to the number of parameters.
+
+abstraction::AlgorithmRegistry::registerAlgorithm < Divide > ( Divide::divide, abstraction::AlgorithmCategories::AlgorithmCategory::DEFAULT, std::array < std::string, 2 > ( "numerator", "denominator" ) );
+
+The wrapper of alredy registered abstraction can be registered as algorithm via function call too. The function is \emph{abstraction::AlgorithmRegistry::registerWrapper} and it is templated by Algorithm and ParameterTypes. The call accepts a callback to the same delegate function as in the case of registration via constructor. Parameter names must be specified by a string array of size equal to the number of parameters (ParameterTypes template).
+
+abstraction::AlgorithmRegistry::registerWrapper < xml::Compose, const Type \& > ( xml::Compose::abstractionFromType, std::array < std::string, 1 > { { "arg0" } } );
+
+The method registration, as last of options, is done via \emph{abstraction::AlgorithmRegistry::registerMethod} function. The template parameters are Algorithm, ObjectType, ReturnType, and ParameterTypes. The call parameters are a method pointer, a method name, and parameter names.
+
+abstraction::AlgorithmRegistry::registerMethod < ComponentName > ( getMethod, "get", emptyNames );
+
+\section{Normalization}
+
 \chapter{The query language}
 
+This chapter will mostly focus on describing current status of the command line interface so called aql.
+
 \lipsum[1-13]
 
 \chapter{Builtin commands}
-- 
GitLab