Skip to content

Commit 91a45ce

Browse files
glynosglynos
committed
Alpha docs for 0.7 release.
1 parent d8000d3 commit 91a45ce

File tree

283 files changed

+5855
-14825
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

283 files changed

+5855
-14825
lines changed

‎_sources/directives.txt

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
Directives
2+
==========
3+
4+
The library also uses a technique for allowing message-passing
5+
semantics in a chainable fashion in the form of directives. The basic
6+
concept for directives is, in a general sense, an encapsulated
7+
transformation that can be applied to objects that abide by the
8+
directive protocol.
9+
10+
Using the object-oriented notion of message passing, where an object
11+
accepts a message (usually a function call) we define a simple DSEL in
12+
order for the protocol to be supported by certain object types. In the
13+
:mod:`cpp-netlib` the protocol implemented is similar to that of the
14+
standard iostream formatting system:
15+
16+
.. code-block:: c++
17+
18+
object << directive1(...)
19+
<< directive2(...)
20+
...
21+
<< directiveN(...);
22+
23+
In :mod:`cpp-netlib` the directives are simple function objects that
24+
take a target object as reference and returns a reference to the same
25+
object as a result. In code the directive pattern looks like the
26+
following:
27+
28+
.. code-block:: c++
29+
30+
struct directive_type {
31+
template <class Input>
32+
Input & operator()(Input & input) const {
33+
// do something to input
34+
return input;
35+
}
36+
};
37+
38+
To simplify directive creation, usually factory or generator functions
39+
are defined to return concrete objects of the directive's type.
40+
41+
.. code-block:: c++
42+
43+
inline
44+
directive_type directive(...) {
45+
return directive_type();
46+
}
47+
48+
The trivial implementation of the directive protocol then boils down
49+
to the specialization of the shift-left operator on the target type.
50+
51+
.. code-block:: c++
52+
53+
template <class Directive>
54+
inline target_type & operator<<
55+
(target_type & x, Directive const & f) {
56+
return f(x);
57+
}
58+
59+
The rationale for implementing directives include the following:
60+
61+
* **Encapsulation** - by moving logic into the directive types the
62+
target object's interface can remain rudimentary and even hidden
63+
to the user's immediate attention. Adding this layer of
64+
indirection also allows for changing the underlying
65+
implementations while maintaining the same syntactic and semantic
66+
properties.
67+
* **Flexibility** - by allowing the creation of directives that are
68+
independent from the target object's type, generic operations can
69+
be applied based on the concept being modeled by the target
70+
type. The flexibility also afforded comes in the directive's
71+
generator function, which can also generate different concrete
72+
directive specializations based on parameters to the function.
73+
* **Extensibility** - because the directives are independent of the
74+
target object's type, new directives can be added and supported
75+
without having to change the target object at all.
76+
* **Reuse** - truly generic directives can then be used for a broad
77+
set of target object types that model the same concepts supported
78+
by the directive. Because the directives are self-contained
79+
objects, the state and other object references it keeps are only
80+
accessible to it and can be re-used in different contexts as well.
81+
82+
Extending a system that uses directives is trivial in header-only
83+
systems because new directives are simply additive. The protocol is
84+
simple and can be applied to a broad class of situations.
85+
86+
In a header-only library, the static nature of the wiring and chaining
87+
of the operations lends itself to compiler abuse. A deep enough
88+
nesting of the directives can lead to prolonged compilation times.

‎_sources/generic_message.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Generic message
2+
===============
3+

‎_sources/getting_started.txt

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
.. _getting_started:
2+
3+
*****************
4+
Getting started
5+
*****************
6+
7+
Installing an official release
8+
==============================
9+
10+
All stable versions of :mod:`cpp-netlib` can be downloaded from Github:
11+
``http://github.com/cpp-netlib/cpp-netlib/downloads``. Each release
12+
is available as gzipped (Using the command ``tar xzf
13+
cpp-netlib.tar.gz``) or bzipped (Using ``tar xjf cpp-netlib.tar.bz2``)
14+
tarball, or as a zipfile (``unzip cpp-netlib.zip``, or on Windows
15+
using a tool such as 7zip_).
16+
17+
.. _7zip: http://www.7-zip.org/
18+
19+
Installing a development version
20+
================================
21+
22+
The :mod:`cpp-netlib` uses Git_ for source control, so to use any
23+
development versions Git must be installed on your system.
24+
25+
Using the command line, the command to get the latest code is:
26+
27+
::
28+
29+
shell$ git clone git://github.com/mikhailberis/cpp-netlib.git
30+
31+
This should be enough information get to started. To do more complex
32+
things with Git, such as pulling changes or checking out a new branch,
33+
refer to the `Git documentation`_.
34+
35+
Windows users need to use msysGit_, and to invoke the command above
36+
from a shell.
37+
38+
For fans of Subversion_, the same code can be checked out from
39+
`http://svn.github.com/mikhailberis/cpp-netlib.git`.
40+
41+
.. _Git: http://git-scm.com/
42+
.. _`Git documentation`: http://git-scm.com/documentation
43+
.. _msysGit: http://code.google.com/p/msysgit/downloads/list
44+
.. _Subversion: http://subversion.tigris.org/
45+
46+
Getting Boost
47+
=============
48+
49+
:mod:`cpp-netlib` depends on Boost_. It should work for Boost 1.41.0 and
50+
above. If Boost is not installed on your system, the environment
51+
variable ``BOOST_ROOT`` must be defined, which must be the full path
52+
name of the top directory of the Boost distribution. Although Boost is
53+
mostly header only, applications built using :mod:`cpp-netlib` still
54+
requires linking with `Boost.System`_.
55+
56+
.. _Boost: http://www.boost.org/doc/libs/release/more/getting_started/index.html
57+
.. _`Boost.System`: http://www.boost.org/libs/system/index.html
58+
59+
Getting CMake
60+
=============
61+
62+
The :mod:`cpp-netlib` uses CMake_.
63+
64+
.. _CMake: http://www.cmake.org/
65+
66+
Instructions for Windows Users
67+
==============================
68+
69+
Instructions for Linux Users
70+
============================
71+
72+
Building and Running the Examples
73+
=================================
74+

‎_sources/hello_world_client.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _hello_world_http_client:
2+
3+
***************************
4+
"Hello world" HTTP client
5+
***************************
6+
7+

‎_sources/hello_world_server.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. _hello_world_http_server:
2+
3+
***************************
4+
"Hello world" HTTP server
5+
***************************
6+
7+
:mod:`cpp-netlib` provides the framework to develop embedded HTTP
8+
servers. This example

‎_sources/history.txt

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Project history
2+
===============
3+
4+
The :mod:`cpp-netlib` was founded by Dean Michael Berris in 2007.
5+
Initially it consisted of a message template and an HTTP client. It
6+
found a home on Sourceforge_ but was migrated at the end of 2009 to
7+
Github_ where development is actively continued by a committed
8+
community.
9+
10+
.. _Sourceforge: http://sourceforge.net/projects/cpp-netlib/
11+
.. _Github: http://github.com/cpp-netlib/cpp-netlib
12+
13+
.. toctree::
14+
:maxdepth: 2
15+
16+
motivation.rst
17+
objectives.rst

‎_sources/http.txt

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
HTTP implementation
2+
===================
3+
4+
HTTP client
5+
```````````
6+
7+
The cpp-netlib HTTP client is composed of three template classes:
8+
9+
.. code-block:: c++
10+
11+
namespace http {
12+
template <class Tag> basic_request;
13+
template <class Tag> basic_response;
14+
template <class Tag> basic_client;
15+
typedef basic_request<default_> request;
16+
typedef basic_response<default_> response;
17+
typedef basic_client<default_> client;
18+
}
19+
20+
21+
Each of these use again the tag-based static polymorphism that was described in
22+
previous sections. A default, human-readable typedef is provided for each one
23+
of the ``basic_request``, ``basic_response`` and ``basic_client``.
24+
``basic_request`` and ``basic_response`` each model the message concept. They
25+
make use of directives to set and get HTTP headers, body etc. The code snippet
26+
below shows how to set the HTTP header field "Connection" with the option
27+
"close" using the DSEL described in the directives section:
28+
29+
.. code-block:: c++
30+
31+
using namespace boost::network;
32+
http::request request("http://www.boost.org/");
33+
request << header("Connection", "close");
34+
35+
The ``basic_client`` implements all HTTP methods as member functions (HEAD,
36+
GET, POST, PUT, DELETE). Therefore, the code to make an HTTP request looks
37+
trivially simple:
38+
39+
.. code-block:: c++
40+
41+
using namespace boost::network;
42+
http::client client;
43+
http::request request("http://www.boost.org/");
44+
http::response response = client.get(request);
45+
46+
Accessing data from ``http::response`` is also done using directives. To
47+
get the response headers, we use the ``headers`` directive which returns,
48+
in the default case, a map of strings to strings:
49+
50+
.. code-block:: c++
51+
52+
using namespace boost::network;
53+
typedef headers_range<http_client::response>::type response_headers;
54+
boost::range_iterator<response_headers>::type iterator;
55+
56+
response_headers headers_ = headers(response);
57+
for (iterator it = headers_.begin(); it != headers_.end(); ++it) {
58+
std::cout << it->first << ": " << it->second << std::endl;
59+
}
60+
std::cout << std::endl;
61+
62+
HTTP server
63+
```````````
64+
65+
As with the HTTP client, the HTTP server that is provided with cpp-netlib is
66+
extensible through the tag mechanism and is embeddable. The template class
67+
declaration of ``basic_server`` is given below:
68+
69+
.. code-block:: c++
70+
71+
namespace http {
72+
template <class Tag, class RequestHandler> basic_server;
73+
}
74+
75+
The second template argument is used to specify the request handler type. The
76+
request handler type is a functor type which should overload the function call
77+
operator (``RequestHandler::operator()`` should be overloaded) that takes two
78+
parameters: the first one being a reference to a ``const basic_request<Tag>``
79+
and the second being a reference to a ``basic_response<Tag>`` instance.
80+
81+
All the logic for parsing the HTTP request and building the ``const
82+
basic_request<Tag>`` object resides internally in the ``basic_server`` template.
83+
Processing the request is delegated to the ``RequestHandler`` type, and the
84+
assumption of which would be that the response is formed inside the
85+
``RequestHandler`` function call operator overload.
86+
87+
The ``basic_server`` template however is only an underlying implementation while
88+
the user-visible implementation is the ``http::server`` template. This simply
89+
specializes the ``basic_server`` template to use the ``default_`` tag and
90+
forwards the ``RequestHandler`` parameter:
91+
92+
.. code-block:: c++
93+
94+
namespace http {
95+
template <class RequestHandler> server
96+
: public basic_server<default_, RequestHandler>
97+
{};
98+
}
99+
100+
To use the forwarding server type you just supply the request handler
101+
implementation as the parameter. For example, an "echo" server example might
102+
look something like this:
103+
104+
.. code-block:: c++
105+
106+
using namespace boost::network;
107+
struct echo;
108+
typedef http::server<echo> echo_server;
109+
110+
struct echo {
111+
void operator () (const echo_server::request &request,
112+
echo_server::response &response) const {
113+
response = echo_server::response::stock_reply(
114+
echo_server::response::ok,
115+
body(request));
116+
}
117+
};
118+
119+
120+
Here, all we're doing is returning the original request body with an HTTP OK
121+
response (200).
122+
123+
HTTP URI
124+
````````
125+
126+
Firstly, cpp-netlib provides a specialization and ``typedef`` for an HTTP URI:
127+
128+
.. code-block:: c++
129+
130+
namespace http {
131+
template <class T> class basic_uri;
132+
typedef basic_uri<default_> uri;
133+
}
134+
135+
``basic_uri`` provides a parser which breaks down a URI string passed to it's
136+
constructor into different parts.
137+
138+
.. code-block:: c++
139+
140+
using namespace boost::network::uri;
141+
http::uri uri_("http://www.boost.org/");
142+
assert(valid(uri_));
143+
assert(scheme(uri_) == "http");
144+
assert(host(uri_) == "www.boost.org")
145+
assert(port(uri_) == 80)
146+
assert(path(uri_) == "/");
147+
148+
The syntax of the HTTP URI are defined in RFC 1738 section 3.3 [#]_ and the
149+
default URI provided with cpp-netlib conforms to this. In such a way,
150+
specializations that conform to any URI scheme can be provided.
151+
152+
.. [#] http://tools.ietf.org/html/rfc1738

0 commit comments

Comments
 (0)