Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit2bf9291

Browse files
committed
I've added the first alpha draft of the docs that are intended for the 0.7 development release.
1 parent165abcb commit2bf9291

File tree

61 files changed

+5861
-0
lines changed

Some content is hidden

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

61 files changed

+5861
-0
lines changed

‎0.7-devel/_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.
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Generic message
2+
===============
3+
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+
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+
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

‎0.7-devel/_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

‎0.7-devel/_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)
[8]ページ先頭
©2009-2025 Movatter.jp