Skip to content

Commit b3708a4

Browse files
deanberrisdeanberris
committed
Adding most current version of the documentation to the gh-pages for cpp-netlib.
0 parents  commit b3708a4

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

+7059
-0
lines changed

‎_images/boost.png

13.1 KB
Loading

‎_sources/directives.txt

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
Directives
2+
==========
3+
4+
The :mod:`cpp-netlib` 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+
.. todo::
60+
61+
An example using a directive.
62+
63+
The rationale for implementing directives include the following:
64+
65+
* **Encapsulation** - by moving logic into the directive types the
66+
target object's interface can remain rudimentary and even hidden
67+
to the user's immediate attention. Adding this layer of
68+
indirection also allows for changing the underlying
69+
implementations while maintaining the same syntactic and semantic
70+
properties.
71+
* **Flexibility** - by allowing the creation of directives that are
72+
independent from the target object's type, generic operations can
73+
be applied based on the concept being modeled by the target
74+
type. The flexibility also afforded comes in the directive's
75+
generator function, which can also generate different concrete
76+
directive specializations based on parameters to the function.
77+
* **Extensibility** - because the directives are independent of the
78+
target object's type, new directives can be added and supported
79+
without having to change the target object at all.
80+
* **Reuse** - truly generic directives can then be used for a broad
81+
set of target object types that model the same concepts supported
82+
by the directive. Because the directives are self-contained
83+
objects, the state and other object references it keeps are only
84+
accessible to it and can be re-used in different contexts as well.
85+
86+
Extending a system that uses directives is trivial in header-only
87+
systems because new directives are simply additive. The protocol is
88+
simple and can be applied to a broad class of situations.
89+
90+
In a header-only library, the static nature of the wiring and chaining
91+
of the operations lends itself to compiler abuse. A deep enough
92+
nesting of the directives can lead to prolonged compilation times.

‎_sources/examples.txt

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Examples
2+
========
3+
4+
The :mod:`cpp-netlib` is a practical library that is designed to aid
5+
the development of applications for that need to communicate using
6+
common networking protocols. The following set of examples describe a
7+
series of realistic examples that use the :mod:`cpp-netlib` for these
8+
kinds of application.
9+
10+
.. toctree::
11+
:maxdepth: 2
12+
13+
examples_http.rst
14+
.. examples_xmpp.rst

‎_sources/examples_http.txt

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
HTTP examples
2+
=============
3+
4+
The HTTP component of the :mod:`cpp-netlib` contains a client and server.
5+
The examples that follow show how to use both for programs that can be
6+
embedded into larger applications.
7+
8+
.. toctree::
9+
:maxdepth: 2
10+
11+
http_client.rst
12+
hello_world_server.rst
13+
hello_world_client.rst

‎_sources/generic_message.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Generic message
2+
===============
3+
4+
.. todo::
5+
6+
Is this section repeated?

‎_sources/getting_started.txt

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
.. _getting_started:
2+
3+
*****************
4+
Getting Started
5+
*****************
6+
7+
Downloading an official release
8+
===============================
9+
10+
All stable versions of :mod:`cpp-netlib` can be downloaded from
11+
Github_. Each release is available as gzipped (Using the command
12+
``tar xzf cpp-netlib.tar.gz``) or bzipped (Using ``tar xjf
13+
cpp-netlib.tar.bz2``) tarball, or as a zipfile (``unzip
14+
cpp-netlib.zip``, or on Windows using a tool such as 7zip_).
15+
16+
.. _Github: http://github.com/cpp-netlib/cpp-netlib/downloads
17+
.. _7zip: http://www.7-zip.org/
18+
19+
Downloading 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+
.. note:: The :mod:`cpp-netlib` project is hosted on GitHub_ and follows the
47+
prescribed development model for GitHub_ based projects. This means in case
48+
you want to submit patches, you will have to create a fork of the project
49+
(read up on forking_) and then submit a pull request (read up on submitting
50+
`pull requests`_).
51+
52+
.. _forking: http://help.github.com/forking/
53+
.. _`pull requests`: http://help.github.com/pull-requests/
54+
55+
Getting Boost
56+
=============
57+
58+
:mod:`cpp-netlib` depends on Boost_. It should work for any version
59+
of Boost above 1.41.0. If Boost is not installed on your system, the
60+
latest package can be found on the `Boost web-site`_. The environment
61+
variable ``BOOST_ROOT`` must be defined, which must be the full path
62+
name of the top directory of the Boost distribution. Although Boost
63+
is mostly header only, applications built using :mod:`cpp-netlib`
64+
still requires linking with `Boost.System`_, `Boost.Date_time`_, and
65+
`Boost.Regex`_.
66+
67+
.. _Boost: http://www.boost.org/doc/libs/release/more/getting_started/index.html
68+
.. _`Boost web-site`: http://www.boost.org/users/download/
69+
.. _`Boost.System`: http://www.boost.org/libs/system/index.html
70+
.. _`Boost.Date_time`: http://www.boost.org/libs/date_time/index.html
71+
.. _`Boost.Regex`: http://www.boost.org/libs/regex/index.html
72+
73+
.. note:: You can follow the steps in the `Boost Getting Started`_ guide to
74+
install Boost into your development system.
75+
76+
.. _`Boost Getting Started`:
77+
http://www.boost.org/doc/libs/release/more/getting_started/index.html
78+
79+
Getting CMake
80+
=============
81+
82+
The :mod:`cpp-netlib` uses CMake_ to generate platform-specific build files. If
83+
you intend to run the test suite, you can follow the instructions below.
84+
Otherwise, you don't need CMake to use :mod:`cpp-netlib` in your project. The
85+
:mod:`cpp-netlib` requires CMake version 2.8 or higher.
86+
87+
.. _CMake: http://www.cmake.org/
88+
89+
Let's assume that you have unpacked the :mod:`cpp-netlib` at the top of your
90+
HOME directory. On Unix-like systems you will typically be able to change into
91+
your HOME directory using the command ``cd ~``. This sample below assumes that
92+
the ``~/cpp-netlib`` directory exists, and is the top-level directory of the
93+
:mod:`cpp-netlib` release.
94+
95+
Building with CMake
96+
===================
97+
98+
To build the tests that come with cpp-netlib, we first need to configure the
99+
build system to use our compiler of choice. This is done by running the
100+
``cmake`` command at the top-level directory of :mod:`cpp-netlib` with
101+
additional parameters::
102+
103+
$ cd ~/cpp-netlib
104+
$ cmake -DCMAKE_BUILD_TYPE=Debug \
105+
> -DCMAKE_C_COMPILER=gcc \
106+
> -DCMAKE_CXX_COMPILER=g++ \
107+
> .
108+
109+
On Linux, this will generate the appropriate Makefiles that will enable you to
110+
build and run the tests and examples that come with :mod:`cpp-netlib`. To build
111+
the tests, you can run ``make`` in the same top-level directory of
112+
:mod:`cpp-netlib`::
113+
114+
$ make
115+
116+
.. note:: Just like with traditional GNU Make, you can add the ``-j`` parameter
117+
to specify how many parallel builds to run. In case you're in a sufficiently
118+
powerful system and would like to parallelize the build into 4 jobs, you can
119+
do this with::
120+
121+
make -j4
122+
123+
As a caveat, :mod:`cpp-netlib` is heavy on template metaprogramming and will
124+
require a lot of computing and memory resources to build the individual
125+
tests. Do this at the risk of thrashing_ your system.
126+
127+
.. _thrashing: http://en.wikipedia.org/wiki/Thrashing_(computer_science)
128+
129+
Once the build has completed, you can now run the test suite by issuing::
130+
131+
$ make test
132+
133+
Building On Windows
134+
~~~~~~~~~~~~~~~~~~~
135+
136+
If you're using the Microsoft Visual C++ compiler or the Microsoft Visual Studio
137+
IDE and you would like to build cpp-netlib from within Visual Studio, you can
138+
look for the solution and project files as the artifacts of the call to
139+
``cmake`` -- the file should be named ``cpp-netlib.sln`` (the solution) along
140+
with a number of project files for Visual Studio.
141+
142+
Reporting Issues, Getting Support
143+
=================================
144+
145+
In case you find yourself stuck or if you've found a bug (or you want to just
146+
join the discussion) you have a few options to choose from.
147+
148+
For reporting bugs, feature requests, and asking questions about the
149+
implementation and/or the documentation, you can go to the GitHub issues page
150+
for the project at http://github.com/mikhailberis/cpp-netlib/issues.
151+
152+
You can also opt to join the developers mailing list for a more personal
153+
interaction with the developers of the project. You can join the mailing list
154+
through https://lists.sourceforge.net/lists/listinfo/cpp-netlib-devel.
155+
156+
You may also choose to get commercial support from the maintainers of the
157+
project, in which case you can reach them through:
158+
159+
Dean Michael Berris - <me@deanberris.com>
160+
161+
Glyn Matthews
162+
163+
Mike Dickey
164+
165+

‎_sources/hello_world_client.txt

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. _hello_world_http_client:
2+
3+
***************************
4+
"Hello world" HTTP client
5+
***************************
6+
7+
.. todo::
8+
9+
Take the HTTP client example and server example and describe
10+
what's happening.
11+
12+
::
13+
14+
./hello_world_client http://127.0.0.1/

0 commit comments

Comments
 (0)