Skip to content

Commit 6b940f2

Browse files
committed
Merge branch '0.8-devel' of github.com:mikhailberis/cpp-netlib into 0.8-devel
2 parents 20dba83 + 66ad9f8 commit 6b940f2

File tree

6 files changed

+196
-13
lines changed

6 files changed

+196
-13
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,5 @@ build
99
_build
1010
bin
1111
*.gch
12+
libs/mime/test/mime-roundtrip
1213

libs/network/doc/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ Contents
9696
techniques.rst
9797
history.rst
9898
install.rst
99+
reference.rst
99100
references.rst
100101

101102
.. _Boost: http://www.boost.org/

libs/network/doc/message.rst

Lines changed: 119 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,16 @@ properties of messages.
4343
:m,n: An instance of **M**.
4444
:S: A string type.
4545
:s,k,v: An instance of **S**.
46+
:O: The source type.
47+
:D: The destination type.
48+
:B: The body type.
49+
:T: The Tag type.
4650

4751
+----------------------------+----------------------+-----------------------------------------+
4852
| Construct | Result | Description |
4953
+============================+======================+=========================================+
54+
| ``typename M::tag`` | T | The nested tag type. |
55+
+----------------------------+----------------------+-----------------------------------------+
5056
| ``M()`` | Instance of M | Default constructible. |
5157
+----------------------------+----------------------+-----------------------------------------+
5258
| ``M(m)`` | Instance of M | Copy constructible. |
@@ -55,33 +61,34 @@ properties of messages.
5561
+----------------------------+----------------------+-----------------------------------------+
5662
| ``swap(m, n);`` | ``void`` | Swappable. |
5763
+----------------------------+----------------------+-----------------------------------------+
58-
| ``source(m);`` | unspecified | Retrieve the source of ``m``. |
64+
| ``source(m);`` | Convertible to O | Retrieve the source of ``m``. |
5965
+----------------------------+----------------------+-----------------------------------------+
60-
| ``destination(m);`` | unspecified | Retrieve the destination of ``m``. |
66+
| ``destination(m);`` | Convertible to D | Retrieve the destination of ``m``. |
6167
+----------------------------+----------------------+-----------------------------------------+
62-
| ``headers(m);`` | unspecified | Get the range of headers of ``m``. The |
63-
| | | result should be convertible to ``H`` |
68+
| ``headers(m);`` | Convertible to H | Retrieve the headers of ``m``. |
6469
+----------------------------+----------------------+-----------------------------------------+
65-
| ``body(m);`` | unspecified | Retrieve the body of ``m``. |
70+
| ``body(m);`` | Convertible to B | Retrieve the body of ``m``. |
6671
+----------------------------+----------------------+-----------------------------------------+
6772
| ``m << source(s);`` | ``M &`` | Set the source of ``m``. |
6873
+----------------------------+----------------------+-----------------------------------------+
69-
| ``source(m,s);`` | ``M &`` | Set the source of ``m``. |
70-
+----------------------------+----------------------+-----------------------------------------+
7174
| ``m << destination(s);`` | ``M &`` | Set the destination of ``m``. |
7275
+----------------------------+----------------------+-----------------------------------------+
73-
| ``destination(m,s);`` | ``M &`` | Set the destination of ``m``. |
74-
+----------------------------+----------------------+-----------------------------------------+
7576
| ``m << header(k, v);`` | ``M &`` | Add a header to ``m``. |
7677
+----------------------------+----------------------+-----------------------------------------+
77-
| ``add_header(m, k, v);`` | ``M &`` | Add a header to ``m``. |
78-
+----------------------------+----------------------+-----------------------------------------+
7978
| ``m << remove_header(k);`` | ``M &`` | Remove a header from ``m``. |
8079
+----------------------------+----------------------+-----------------------------------------+
81-
| ``remove_header(m, k);`` | ``M &`` | Remove a header from ``m``. |
82-
+----------------------------+----------------------+-----------------------------------------+
8380
| ``m << body(s);`` | ``M &`` | Set the body of ``m``. |
8481
+----------------------------+----------------------+-----------------------------------------+
82+
| ``source(m,s);`` | ``void`` | Set the source of ``m``. |
83+
+----------------------------+----------------------+-----------------------------------------+
84+
| ``destination(m,s);`` | ``void`` | Set the destination of ``m``. |
85+
+----------------------------+----------------------+-----------------------------------------+
86+
| ``add_header(m, k, v);`` | ``void`` | Add a header to ``m``. |
87+
+----------------------------+----------------------+-----------------------------------------+
88+
| ``remove_header(m, k);`` | ``void`` | Remove a header from ``m``. |
89+
+----------------------------+----------------------+-----------------------------------------+
90+
| ``clear_headers(m);`` | ``void`` | Clear the headers of ``m``. |
91+
+----------------------------+----------------------+-----------------------------------------+
8592
| ``body(m,s);`` | ``M &`` | Set the body of ``m``. |
8693
+----------------------------+----------------------+-----------------------------------------+
8794

@@ -93,6 +100,105 @@ Concept, a message can be implemented as a POD type and have all
93100
manipulations performed in the directive implementations, as well as
94101
value transformations done in the accessors.
95102

103+
Directives, Modifiers, and Wrappers
104+
```````````````````````````````````
105+
106+
In the Message Concept definition there are three basic constructs that follow a
107+
certain pattern. These patterns are Directives_, Modifiers_, and Wrappers_.
108+
109+
Directives
110+
~~~~~~~~~~
111+
112+
A directive is a function object that is applied to a Message. Directives
113+
encapsulate a set of operations that apply to messages. The general requirement
114+
for a Directive is that it should apply these operations on a message.
115+
116+
A directive may dispatch on the type of the message passed to it at the point of
117+
the function call. Typically, directives are generated using a factory function
118+
that returns the correct directive type.
119+
120+
For a given directive ``foo_directive`` a generator function called ``foo`` is
121+
typically implemented:
122+
123+
.. code-block:: c++
124+
125+
struct foo_directive {
126+
template <class Message>
127+
Message & operator()(Message & m) const {
128+
// do something to m
129+
return m;
130+
}
131+
};
132+
133+
foo_directive const foo() {
134+
return foo_directive();
135+
}
136+
137+
// to apply a directive, we use the << operator
138+
message m;
139+
m << foo();
140+
141+
Modifiers
142+
~~~~~~~~~
143+
144+
A modifier is generally defined as a free function that takes a reference to a
145+
non-const lvalue message as the first parameter, and any number of parameters.
146+
In the concept definition of the Message Concept, a modifier follows the form:
147+
148+
.. code-block:: c++
149+
150+
modifier(message, ...)
151+
152+
Modifiers are meant to imply modifications on a message, which also allows for
153+
easier dispatch based on Argument Dependent Lookup (ADL_) on the type of the
154+
message. Note that Directives_ can be implemented in terms of Modifiers and
155+
vice versa, although that is not required nor specified.
156+
157+
.. _ADL: http://en.wikipedia.org/wiki/Argument-dependent_name_lookup
158+
159+
Wrappers
160+
~~~~~~~~
161+
162+
A Wrapper is basically an implementation detail that ensures that a given
163+
message, when wrapped, can be converted to the associated part of the message. A
164+
wrapper has a type that encapsulates the conversion logic from a message to a
165+
given type.
166+
167+
An example of a Wrapper would be ``source_wrapper`` which would be returned by a
168+
call to the wrapper generator function ``source``. An example implementation of
169+
the ``source_wrapper`` would look like:
170+
171+
.. code-block:: c++
172+
173+
template <class Tag, template <class> class Message>
174+
struct source_wrapper {
175+
Message<Tag> const & m;
176+
explicit source_wrapper(Message<Tag> const & m)
177+
: m(m) {}
178+
typedef typename source<Tag>::type source_type;
179+
operator source_type const & () {
180+
return m.source;
181+
}
182+
operator source_type const () {
183+
return m.source;
184+
}
185+
operator source_type () {
186+
return m.source;
187+
}
188+
};
189+
190+
template <class Tag, template <class> class Message>
191+
source_wrapper<Tag, Message> const
192+
source(Message<Tag> const & message) {
193+
return source_wrapper<Tag, Message>(message);
194+
}
195+
196+
This pattern is similar to an adapter, but the specific notion of wrapping a
197+
data type (in this case, an object of a type that models the Message Concept)
198+
using an intermediary wrapper is what is pertained to by the Wrapper pattern.
199+
In this case, the Wrapper is ``source_wrapper`` while ``source`` is merely a
200+
wrapper generator function.
201+
96202
``basic_message``
97203
`````````````````
98204

libs/network/doc/reference.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2+
Reference Manual
3+
================
4+
5+
This reference manual refers to the API documentation of the public interfaces
6+
to the different client and/or server implementations within :mod:`cpp-netlib`.
7+
8+
.. toctree::
9+
:maxdepth: 2
10+
11+
reference_http_client.rst
12+
reference_http_server.rst
13+
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
2+
HTTP Client API
3+
===============
4+
5+
General
6+
-------
7+
8+
.. FIXME describe the general API for the HTTP Clients
9+
10+
Implementations
11+
---------------
12+
13+
.. FIXME describe the internal implementation, with diagrams if at all possible
14+
and within reasonable efforts.
15+
16+
Synchronous Clients
17+
~~~~~~~~~~~~~~~~~~~
18+
19+
.. FIXME show the table of tags that enable the synchronous implementation.
20+
21+
Asynchronous Clients
22+
~~~~~~~~~~~~~~~~~~~~
23+
24+
.. FIXME show the table of tags that enable the asynchronous implementation.
25+
26+
Member Functions
27+
----------------
28+
29+
.. FIXME show the table of publicly-accessible member functions.
30+
31+
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
2+
HTTP Server API
3+
===============
4+
5+
General
6+
-------
7+
8+
.. FIXME describe the general API for the HTTP Servers
9+
10+
Implementations
11+
---------------
12+
13+
.. FIXME describe the internal implementation, with diagrams if at all possible
14+
and within reasonable efforts.
15+
16+
Synchronous Servers
17+
~~~~~~~~~~~~~~~~~~~
18+
19+
.. FIXME show the table of tags that enable the synchronous implementation.
20+
21+
Asynchronous Servers
22+
~~~~~~~~~~~~~~~~~~~~
23+
24+
.. FIXME show the table of tags that enable the asynchronous implementation.
25+
26+
Member Functions
27+
----------------
28+
29+
.. FIXME show the table of publicly-accessible member functions.
30+
31+

0 commit comments

Comments
 (0)