move header files into include/promise-cpp/

Author: xhawk18

CMakeLists.txt

@@ -18,10 +18,10 @@ project(promise)
 option(PROMISE_BUILD_SHARED "Build shared library" OFF)
 
 set(my_headers
-    include/promise.hpp
-    include/any.hpp
-    include/add_ons.hpp
-    include/call_traits.hpp
+    include/promise-cpp/promise.hpp
+    include/promise-cpp/any.hpp
+    include/promise-cpp/add_ons.hpp
+    include/promise-cpp/call_traits.hpp
 )
 
 set(my_sources

Readme.md

@@ -1,13 +1,16 @@
 # C++ promise/A+ library in Javascript style.
 
 <!-- TOC -->
-
-- [C++ promise/A+ library in Javascript style.](#c-promisea-library-in-javascript-style)
   - [What is promise-cpp ?](#what-is-promise-cpp-)
+  - [Features](#features)
   - [Examples](#examples)
     - [Examples list](#examples-list)
     - [Compiler required](#compiler-required)
-    - [Build tips](#build-tips)
+    - [Usage](#usage)
+      - [Used as header only library](#used-as-header-only-library)
+      - [Used as static library](#used-as-static-library)
+      - [Used as shared library](#used-as-shared-library)
+      - [Build tips about asio examples](#build-tips-about-asio-examples)
     - [Sample code 1](#sample-code-1)
     - [Sample code 2](#sample-code-2)
   - [Global functions](#global-functions)
@@ -35,28 +38,36 @@
     - [DeferLoop::doContinue();](#deferloopdocontinue)
     - [DeferLoop::doBreak(const RET_ARG... &ret_arg);](#deferloopdobreakconst-ret_arg-ret_arg)
   - [And more ...](#and-more-)
-    - [about exceptions](#about-exceptions)
-    - [about the chaining parameter](#about-the-chaining-parameter)
+    - [About exceptions](#about-exceptions)
+    - [About the chaining parameter](#about-the-chaining-parameter)
     - [Match rule for chaining parameters](#match-rule-for-chaining-parameters)
       - [Resolved parameters](#resolved-parameters)
       - [Rejected parameters](#rejected-parameters)
       - [Omit parameters](#omit-parameters)
-    - [copy the promise object](#copy-the-promise-object)
-    - [handle uncaught exceptional or rejected parameters](#handle-uncaught-exceptional-or-rejected-parameters)
+    - [Copy the promise object](#copy-the-promise-object)
+    - [Handle uncaught exceptional or rejected parameters](#handle-uncaught-exceptional-or-rejected-parameters)
     - [about multithread](#about-multithread)
-
 <!-- /TOC -->
 
 ## What is promise-cpp ?
 
-Promise-cpp is **header only** library that implements promise/A+ standard. (To support header only, compiled with macro PROMISE_HEADONLY)
-  
-Promise-cpp is easy to use, just #include "promise.hpp" is enough. With promise-cpp, you can resolve or reject any type of data without writing complex template code.
+Promise-cpp is library that implements promise/A+ standard, which can be the base component in event-looped asychronized programming. It is NOT std::promise.
+
+## Features
+
+Similar to Javascript Promise API.
+
+Type safety: the resolved/rejected arguments can be captured by the "then" function with same arguments type.
+
+Exceptions supports: cpp exception will be received by the "on_rejected" function.
 
-Promise-cpp is depended only on STL (c++11 or higher).
-Although some of the asio examples are linked against boost library, promise-cpp itself is absolutely **workable without boost library** and can be used together with other asynchronized libraries.
+Optional header-only configuration enabled with the PROMISE_HEADONLY macro
 
-Promise-cpp can be the base component in event-looped asychronized programming, which is NOT std::promise.
+Easy to use, just #include "promise-cpp/promise.hpp" is enough, code based on standard c++11 syntax, no external dependencies required.
+
+Easy to integrate with other libararies (see examples of [asio](example/asio_timer.cpp), [qt](example/qt_timer) and [mfc](example/mfc_timer)).
+
+Useful extended functions on promise object: doWhile, raceAndResolve, raceAndReject
 
 ## Examples
 
@@ -92,7 +103,25 @@ The library has passed test on these compilers --
 
 * clang 3.4.2
 
-### Build tips
+### Usage
+
+#### Used as header only library
+
+To use as header only library, just define macro PROMISE_HEADONLY when compiling.
+
+#### Used as static library
+
+```
+cmake /path/to/promise_source
+```
+
+#### Used as shared library
+
+```
+cmake -DPROMISE_BUILD_SHARED=ON /path/to/promise_source
+```
+
+#### Build tips about asio examples
 
 Some of the [examples](example) use boost::asio as io service, and use boost::beast as http service. 
 You need to [boost_1_66](https://www.boost.org/doc/libs/1_66_0/more/getting_started/index.html)
@@ -104,12 +133,6 @@ For examples, you can build with boost library --
 > cmake -DBOOST_ROOT=/path/to/boost_source /path/to/promise_source
 ```
 
-If you do not have boost installed, just build by --
-
-```
-> cmake /path/to/promise_source
-```
-
 ### Sample code 1
 
 Example of asio http client. [(full code here)](example/asio_http_client.cpp)
@@ -195,7 +218,7 @@ int main() {
 ## Global functions
 
 ### Promise newPromise(FUNC func);
-Creates a new Promise object with a user-defined function.
+Creates a new promise object with a user-defined function.
 The user-defined functions, used as parameters by newPromise, must have a parameter Defer d. 
 for example --
 
@@ -222,7 +245,7 @@ return reject("some_error");
 
 ### Promise all(const PROMISE_LIST &promise_list);
 Wait until all promise objects in "promise_list" are resolved or one of which is rejected.
-The "promise_list" can be any container that has Promise object as element type.
+The "promise_list" can be any container that has promise object as element type.
 
 > for (Promise &promise : promise_list) { ... }
 
@@ -244,7 +267,7 @@ all(promise_list).then([](){
 Returns a promise that resolves or rejects as soon as one of
 the promises in the iterable resolves or rejects, with the value
 or reason from that promise.
-The "promise_list" can be any container that has Promise object as element type.
+The "promise_list" can be any container that has promise object as element type.
 
 > for (Promise &promise : promise_list) { ... }
 
@@ -446,7 +469,7 @@ Break the doWhile loop (ret_arg will be transferred).
 
 ## And more ...
 
-### about exceptions
+### About exceptions
 To throw any object in the callback functions above, including on_resolved, on_rejected, on_always, 
 will same as d.reject(the_throwed_object) and returns immediately.
 for example --
@@ -460,7 +483,7 @@ return newPromise([](Defer d){
 ```
 For the better performance, we suggest to use function reject instead of throw.
 
-### about the chaining parameter
+### About the chaining parameter
 Any type of parameter can be used when call resolve, reject or throw, except that the plain string or array.
 To use plain string or array as chaining parameters, we may wrap it into an object.
 
@@ -533,15 +556,19 @@ newPromise([](Defer d){
 
 The reject parameters follows the the same omit rule as resolved parameters.
 
-### copy the promise object
+### Copy the promise object
 To copy the promise object is allowed and effective, please do that when you need.
 
 ```cpp
 Promise promise = newPromise([](Defer d){});
 Promise promise2 = promise;  //It's safe and effective
 ```
 
-### handle uncaught exceptional or rejected parameters
+<!--
+ ### Life time of the internal storage inside a promise chain
+-->
+
+### Handle uncaught exceptional or rejected parameters
 
 The uncaught exceptional or rejected parameters are ignored by default. We can specify a handler function to do with these parameters --
 

add_ons/asio/io.hpp

@@ -27,7 +27,7 @@
 #ifndef INC_ASIO_IO_HPP_
 #define INC_ASIO_IO_HPP_
 
-#include "../../include/promise.hpp"
+#include "promise-cpp/promise.hpp"
 #include <boost/asio/ip/tcp.hpp>
 #include <boost/asio/connect.hpp>
 #include <boost/beast/core.hpp>

add_ons/asio/timer.hpp

@@ -41,7 +41,7 @@
 //   void clearTimeout(Promise promise);
 //
 
-#include "../../include/promise.hpp"
+#include "promise-cpp/promise.hpp"
 #include <chrono>
 #include <boost/asio.hpp>
 #include <boost/asio/steady_timer.hpp>

add_ons/qt/promise_qt.cpp

@@ -40,7 +40,7 @@
 //   void clearTimeout(Promise promise);
 //
 
-#include "../../include/promise.hpp"
+#include "promise-cpp/promise.hpp"
 #include "promise_qt.hpp"
 #include <chrono>
 #include <QObject>

add_ons/qt/promise_qt.hpp

@@ -41,7 +41,7 @@
 //   void clearTimeout(Defer d);
 //
 
-#include "../../include/promise.hpp"
+#include "promise-cpp/promise.hpp"
 #include <chrono>
 #include <QObject>
 #include <QTimerEvent>

add_ons/simple_task/simple_task.hpp

@@ -38,7 +38,7 @@
 #include <chrono>
 #include <thread>
 #include <utility>
-#include "../../include/promise.hpp"
+#include "promise-cpp/promise.hpp"
 
 
 class Service {

add_ons/windows/promise_windows.hpp

@@ -42,7 +42,7 @@
 //   void clearTimeout(Defer d);
 //
 
-#include "../../include/promise.hpp"
+#include "promise-cpp/promise.hpp"
 #include <chrono>
 #include <map>
 #include <windows.h>

example/asio_http_client.cpp

@@ -34,7 +34,6 @@
 #include <memory>
 #include <string>
 #include <regex>
-#include "promise.hpp"
 #include "add_ons/asio/io.hpp"
 
 using namespace promise;

example/asio_http_server.cpp

@@ -37,10 +37,6 @@
 #include <vector>
 
 
-// Boost asio use mulithread in this example,
-// so we enable multithread mode of "promise library".
-#define PM_MULTITHREAD
-#include "promise.hpp"
 #include "add_ons/asio/io.hpp"
 
 using namespace promise;

example/chain_defer_test.cpp

@@ -1,4 +1,4 @@
-#include "promise.hpp"
+#include "promise-cpp/promise.hpp"
 #include <sstream>
 #include <iostream>
 

example/mfc_timer/CMakeLists.txt

@@ -22,10 +22,10 @@ set(PROJECT_SOURCES
     res/mfc_timer.ico
     res/mfctimer.rc2
 
-    ../../include/promise.hpp
-    ../../include/any.hpp
-    ../../include/add_ons.hpp
-    ../../include/call_traits.hpp
+    ../../include/promise-cpp/promise.hpp
+    ../../include/promise-cpp/any.hpp
+    ../../include/promise-cpp/add_ons.hpp
+    ../../include/promise-cpp/call_traits.hpp
     ../../add_ons/windows/promise_windows.hpp
 )
 

example/qt_timer/CMakeLists.txt

@@ -32,10 +32,10 @@ set(PROJECT_SOURCES
     mainwindow.cpp
     mainwindow.h
     mainwindow.ui
-    ../../include/promise.hpp
-    ../../include/any.hpp
-    ../../include/add_ons.hpp
-    ../../include/call_traits.hpp
+    ../../include/promise-cpp/promise.hpp
+    ../../include/promise-cpp/any.hpp
+    ../../include/promise-cpp/add_ons.hpp
+    ../../include/promise-cpp/call_traits.hpp
     ../../add_ons/qt/promise_qt.hpp
 )
 

example/simple_benchmark_test.cpp

@@ -30,7 +30,7 @@
 #include <iostream>
 #include <string>
 #include <chrono>
-#include "promise.hpp"
+#include "promise-cpp/promise.hpp"
 #include "add_ons/simple_task/simple_task.hpp"
 
 using namespace promise;

example/simple_timer.cpp

@@ -30,7 +30,7 @@
 #include <chrono>
 #include <thread>
 #include <utility>
-#include "promise.hpp"
+#include "promise-cpp/promise.hpp"
 #include "add_ons/simple_task/simple_task.hpp"
 
 using namespace promise;

example/test0.cpp

@@ -26,7 +26,7 @@
  */
 #include <stdio.h>
 #include <string>
-#include "promise.hpp"
+#include "promise-cpp/promise.hpp"
 
 using namespace promise;