Reorganize examples:

* The examples/ directory is renamed to example/

* Each program is in its own directory with its own build scripts

CHANGELOG.md

@@ -2,6 +2,7 @@ Version 58:
 
 * Fix unaligned reads in utf8-checker
 * Qualify size_t in message template
+* Reorganize examples
 
 --------------------------------------------------------------------------------
 

CMakeLists.txt

@@ -183,8 +183,8 @@ file(GLOB_RECURSE BEAST_INCLUDES
     ${PROJECT_SOURCE_DIR}/include/beast/*.ipp
 )
 
-file(GLOB_RECURSE EXAMPLES_INCLUDES
-    ${PROJECT_SOURCE_DIR}/examples/*.hpp
+file(GLOB_RECURSE EXAMPLE_INCLUDES
+    ${PROJECT_SOURCE_DIR}/example/*.hpp
   )
 
 file(GLOB_RECURSE EXTRAS_INCLUDES
@@ -192,16 +192,17 @@ file(GLOB_RECURSE EXTRAS_INCLUDES
     ${PROJECT_SOURCE_DIR}/extras/beast/*.ipp
 )
 
-add_subdirectory (examples)
-if (NOT OPENSSL_FOUND)
-    message("OpenSSL not found. Not building SSL tests and examples")
-else()
-    add_subdirectory (examples/ssl)
-    add_subdirectory (test/websocket/ssl)
-endif()
-
 add_subdirectory (test)
 add_subdirectory (test/core)
 add_subdirectory (test/http)
 add_subdirectory (test/websocket)
 add_subdirectory (test/zlib)
+
+add_subdirectory (example)
+
+if (NOT OPENSSL_FOUND)
+    message("OpenSSL not found. Not building SSL tests and examples")
+else()
+    add_subdirectory (example/ssl)
+    add_subdirectory (test/websocket/ssl)
+endif()

Jamroot

@@ -112,4 +112,4 @@ project beast
   ;
 
 build-project test ;
-build-project examples ;
+build-project example ;

appveyor.yml

@@ -97,5 +97,5 @@ install:
 build: off
 
 test_script:
-  - b2 libs/beast/examples toolset=msvc-14.0
+  - b2 libs/beast/example toolset=msvc-14.0
   - b2 libs/beast/test toolset=msvc-14.0

doc/0_main.qbk

@@ -23,7 +23,6 @@
 [template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
 [template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
 [template repo_file[path] '''<ulink url="https://github.com/vinniefalco/Beast/blob/master/'''[path]'''">'''[path]'''</ulink>''']
-
 [template include_file[path][^<'''<ulink url="https://github.com/vinniefalco/Beast/blob/master/include/'''[path]'''">'''[path]'''</ulink>'''>]]
 
 [def __N3747__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]]
@@ -76,12 +75,13 @@
 [def __static_buffer__          [link beast.ref.beast__static_buffer `static_buffer`]]
 [def __static_buffer_n__        [link beast.ref.beast__static_buffer_n `static_buffer_n`]]
 
-[import ../examples/file_body.hpp]
-[import ../examples/http_example.cpp]
-[import ../examples/websocket_example.cpp]
-[import ../examples/echo_op.cpp]
-[import ../examples/doc_core_samples.hpp]
-[import ../examples/doc_http_samples.hpp]
+[import ../example/doc/core_examples.hpp]
+[import ../example/doc/http_examples.hpp]
+[import ../example/echo-op/echo_op.cpp]
+[import ../example/http-client/http_client.cpp]
+[import ../example/http-server/file_body.hpp]
+[import ../example/websocket-client/websocket_client.cpp]
+
 [import ../test/core/doc_snippets.cpp]
 [import ../test/http/doc_snippets.cpp]
 [import ../test/websocket/doc_snippets.cpp]

doc/2_examples.qbk

@@ -17,47 +17,59 @@ in the examples directory.
 
 Use HTTP to make a GET request to a website and print the response:
 
-File: [repo_file examples/http_example.cpp]
+File: [repo_file example/http-client/http_client.cpp]
+
+[example_http_client]
+
 
-[http_example_get]
 
 [heading WebSocket]
 
 Establish a WebSocket connection, send a message and receive the reply:
 
-File: [repo_file examples/websocket_example.cpp]
+File: [repo_file example/websocket-client/websocket_client.cpp]
+
+[example_websocket_client]
+
 
-[websocket_example_client_echo]
 
 [heading WebSocket Echo Server]
 
 This example demonstrates both synchronous and asynchronous
 WebSocket server implementations.
 
-* [repo_file examples/websocket_async_echo_server.hpp]
-* [repo_file examples/websocket_sync_echo_server.hpp]
-* [repo_file examples/websocket_echo.cpp]
+* [repo_file example/websocket-server/main.cpp]
+* [repo_file example/websocket-server/websocket_async_echo_server.hpp]
+* [repo_file example/websocket-server/websocket_sync_echo_server.hpp]
+
+
 
 [heading Secure WebSocket]
 
 Establish a WebSocket connection over an encrypted TLS connection,
 send a message and receive the reply. Requires OpenSSL to build.
 
-* [repo_file examples/ssl/websocket_ssl_example.cpp]
+* [repo_file example/ssl/websocket_ssl_example.cpp]
+
+
 
 [heading HTTPS GET]
 
 This example demonstrates sending and receiving HTTP messages
 over a TLS connection. Requires OpenSSL to build.
 
-* [repo_file examples/ssl/http_ssl_example.cpp]
+* [repo_file example/ssl/http_ssl_example.cpp]
+
+
 
 [heading HTTP Crawl]
 
 This example retrieves the page at each of the most popular domains
 as measured by Alexa.
 
-* [repo_file examples/http_crawl.cpp]
+* [repo_file example/http-crawl/http_crawl.cpp]
+
+
 
 [heading HTTP Server]
 
@@ -65,19 +77,23 @@ This example demonstrates both synchronous and asynchronous server
 implementations. It also provides an example of implementing a [*Body]
 type, in `file_body`.
 
-* [repo_file examples/file_body.hpp]
-* [repo_file examples/http_async_server.hpp]
-* [repo_file examples/http_sync_server.hpp]
-* [repo_file examples/http_server.cpp]
+* [repo_file example/http-server/file_body.hpp]
+* [repo_file example/http-server/http_async_server.hpp]
+* [repo_file example/http-server/http_sync_server.hpp]
+* [repo_file example/http-server/main.cpp]
+
+
 
 [heading Composed Operations]
 
-This program shows how to use Beast's core foundations to build a
+This program shows how to use Beast's network foundations to build a
 composable asynchronous initiation function with associated composed
 operation implementation. This is a complete, runnable version of
 the example described in the Core Foundations document section.
 
-* [repo_file examples/echo_op.cpp]
+* [repo_file example/echo-op/echo_op.cpp]
+
+
 
 [heading Documentation Samples]
 
@@ -85,8 +101,10 @@ Here are all of the example functions and classes presented
 throughout the documentation, they can be included and used
 in your program without modification
 
-* [repo_file examples/doc_core_samples.hpp]
+* [repo_file example/doc/core_examples.hpp]
+
+* [repo_file example/doc/http_examples.hpp]
+
 
-* [repo_file examples/doc_http_samples.hpp]
 
 [endsect]

doc/3_4_composed.qbk

@@ -6,6 +6,7 @@
 ]
 
 [section:composed Composed Operations]
+[block'''<?dbhtml stop-chunking?>''']
 
 Asynchronous operations are started by calling a free function or member
 function known as an ['asynchronous initiation function]. The initiation
@@ -100,7 +101,9 @@ available:
 ]]
 ]
 
-[heading Example: Asynchronous Echo]
+
+
+[section Asynchronous Echo]
 
 Here we develop an asynchronous composed operation called [*echo].
 This operation will read up to the first newline on a stream, and
@@ -112,14 +115,14 @@ initiation function. For our echo operation the only inputs are the
 stream and the completion token. The output is the error code which
 is usually included in all completion handler signatures.
 
-[core_sample_echo_op_1]
+[example_core_echo_op_1]
 
 Now that we have a declaration, we will define the body of the function.
 We want to achieve the following goals: perform static type checking on
 the input parameters, set up the return value as per __N3747__, and launch
 the composed operation by constructing the object and invoking it.
 
-[core_sample_echo_op_2]
+[example_core_echo_op_2]
 
 The initiation function contains a few relatively simple parts. There is
 the customization of the return value type, static type checking, building
@@ -133,7 +136,7 @@ without explaining them in depth.
 Here is the boilerplate present in all composed operations written
 in this style:
 
-[core_sample_echo_op_3]
+[example_core_echo_op_3]
 
 We have the common boilerplate for a composed operation and now we just need
 to implement the function call operator. Our strategy is to make our composed
@@ -147,9 +150,13 @@ care must be taken to ensure that no access to data members are made after the
 move takes place. Here is the implementation of the function call operator for
 this echo operation:
 
-[core_sample_echo_op_4]
+[example_core_echo_op_4]
 
 A complete, runnable version of this example may be found in the examples
 directory.
 
 [endsect]
+
+
+
+[endsect]

doc/3_5_detect_ssl.qbk

@@ -18,23 +18,23 @@ Here is the declaration for a function to detect the SSL client handshake.
 The input to the function is simply a buffer sequence, no stream. This
 allows the detection algorithm to be used elsewhere.
 
-[core_sample_detect_tls_1]
+[example_core_detect_tls_1]
 
 The implementation checks the buffer for the presence of the SSL
 Handshake message octet sequence and returns an apporopriate value:
 
-[core_sample_detect_tls_2]
+[example_core_detect_tls_2]
 
 Now we define a stream operation. We start with the simple,
 synchronous version which takes the stream and buffer as input:
 
-[core_sample_detect_tls_3]
+[example_core_detect_tls_3]
 
 The synchronous algorithm is the model for building the asynchronous
 operation which has more boilerplate. First, we declare the asynchronous
 initiation function:
 
-[core_sample_detect_tls_4]
+[example_core_detect_tls_4]
 
 The implementation of the initiation function is straightforward
 and contains mostly boilerplate. It is to construct the return
@@ -43,13 +43,13 @@ then create the composed operation and launch it. The actual
 code for interacting with the stream is in the composed operation,
 which is written as a separate class.
 
-[core_sample_detect_tls_5]
+[example_core_detect_tls_5]
 
 Now we will declare our composed operation. There is a considerable
 amount of necessary boilerplate to get this right, but the result
 is worth the effort.
 
-[core_sample_detect_tls_6]
+[example_core_detect_tls_6]
 
 The boilerplate is all done, and now we need to implemnt the function
 call operator that turns this composed operation a completion handler
@@ -59,6 +59,6 @@ is a transformation of the synchronous version of `detect_ssl` above,
 but with the inversion of flow that characterizes code written in the
 callback style:
 
-[core_sample_detect_tls_7]
+[example_core_detect_tls_7]
 
 [endsect]

doc/5_06_serializer_buffers.qbk

@@ -6,6 +6,7 @@
 ]
 
 [section:serializer_buffers Buffer-Oriented Serializing]
+[block'''<?dbhtml stop-chunking?>''']
 
 An instance of __serializer__ can be invoked directly, without using
 the provided stream operations. This could be useful for implementing
@@ -53,14 +54,16 @@ C++14 example we print the header first, followed by the body:
 
 [http_snippet_16]
 
-[heading Example: Write To std::ostream]
+
+
+[section Write To std::ostream]
 
 The standard library provides the type `std::ostream` for performing high
 level write operations on character streams. The variable `std::cout` is
 based on this output stream. This example uses the buffer oriented interface
 of __serializer__ to write an HTTP message to a `std::ostream`:
 
-[http_sample_write_ostream]
+[example_http_write_ostream]
 
 [tip
     Serializing to a `std::ostream` could be implemented using an alternate
@@ -69,6 +72,8 @@ of __serializer__ to write an HTTP message to a `std::ostream`:
     left as an exercise for the reader.
 ]
 
+[endsect]
+
 
 
 [endsect]

doc/5_07_parser_buffers.qbk

@@ -6,6 +6,7 @@
 ]
 
 [section:parser_buffers Buffer-Oriented Parsing]
+[block'''<?dbhtml stop-chunking?>''']
 
 A subclass of __basic_parser__ can be invoked directly, without using 
 the provided stream operations. This could be useful for implementing
@@ -59,7 +60,9 @@ The parser provides two options which may be set before parsing begins:
 ]]
 ]
 
-[heading Example: Read From std::istream]
+
+
+[section Read From std::istream]
 
 The standard library provides the type `std::istream` for performing high
 level read operations on character streams. The variable `std::cin` is based
@@ -67,7 +70,7 @@ on this input stream. This example uses the buffer oriented interface of
 __basic_parser__ to build a stream operation which parses an HTTP message
 from a `std::istream`:
 
-[http_sample_read_istream]
+[example_http_read_istream]
 
 [tip
     Parsing from a `std::istream` could be implemented using an alternate
@@ -77,3 +80,7 @@ from a `std::istream`:
 ]
 
 [endsect]
+
+
+
+[endsect]

doc/5_08_custom_parsers.qbk

@@ -34,6 +34,6 @@ Buffers provided by the parser are non-owning references; it is the
 responsibility of the derived class to copy any information it needs before
 returning from the callback.
 
-[http_sample_custom_parser]
+[example_http_custom_parser]
 
 [endsect]

doc/5_09_custom_body.qbk

@@ -6,6 +6,7 @@
 ]
 
 [section:custom_body Custom Body Types]
+[block'''<?dbhtml stop-chunking?>''']
 
 User-defined types are possible for the message body, where the type meets the
 __Body__ requirements. This simplified class declaration
@@ -72,7 +73,9 @@ As long as a suitable reader or writer is available to provide the
 algorithm for transferring buffers in and out of the value type,
 those bodies may be serialized or parsed.
 
-[heading Example: File Body Type]
+
+
+[section File Body Type]
 
 Use of the flexible __Body__ concept customization point enables authors to
 preserve the self-contained nature of the __message__ object while allowing
@@ -83,32 +86,32 @@ to a file on the file system.
 
 First we declare the type itself, along with the required members:
 
-[http_sample_file_body_1]
+[example_http_file_body_1]
 
 The `size` function is a simple call to retrieve the file size:
 
-[http_sample_file_body_2]
+[example_http_file_body_2]
 
 Our implementation of __BodyReader__ will contain a small buffer
 from which the file contents are read. The buffer is provided to
 the implementation on each call until everything has been read in.
 
-[http_sample_file_body_3]
+[example_http_file_body_3]
 
 And here are the definitions for the functions we have declared:
 
-[http_sample_file_body_4]
+[example_http_file_body_4]
 
 Files can be read now, and the next step is to allow writing to files
 by implementing the __BodyWriter__. The style is similar to the reader,
 except that buffers are incoming instead of outgoing. Here's the
 declaration:
 
-[http_sample_file_body_5]
+[example_http_file_body_5]
 
 Finally, here is the implementation of the writer member functions:
 
-[http_sample_file_body_6]
+[example_http_file_body_6]
 
 We have created a full featured body type capable of reading and
 writing files on the filesystem, integrating seamlessly with the
@@ -117,3 +120,7 @@ type, and HTTP servers that use it, are available in the examples
 directory.
 
 [endsect]
+
+
+
+[endsect]

doc/6_0_http_examples.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section HTTP Examples]
+[section More Examples]
 
 These examples in this section are working functions that may be found
 in the examples directory. They demonstrate the usage of the library for
@@ -27,7 +27,7 @@ by information from the header or elsewhere.
 This example illustrates how a server may make the commitment of a body
 type depending on the method verb:
 
-[http_sample_defer_body]
+[example_http_defer_body]
 
 [endsect]
 
@@ -46,7 +46,7 @@ the server response, and finally conditionally send the body using the same
 serializer instance. A synchronous, simplified version (no timeout) of
 this client action looks like this:
 
-[http_sample_send_expect_100_continue]
+[example_http_send_expect_100_continue]
 
 [endsect]
 
@@ -64,7 +64,7 @@ a __parser__ to read the header first, then send an informational HTTP
 response, and finally read the body using the same parser instance. A
 synchronous version of this server action looks like this:
 
-[http_sample_receive_expect_100_continue]
+[example_http_receive_expect_100_continue]
 
 [endsect]
 
@@ -78,7 +78,7 @@ method indicates to the server that the client wishes to receive the
 entire header that would be delivered if the method was GET, except
 that the body is omitted.
 
-[http_sample_do_head_request]
+[example_http_do_head_request]
 
 [endsect]
 
@@ -91,7 +91,7 @@ When a server receives a
 the response should contain the entire header that would be delivered
 if the method was GET, except that the body is omitted.
 
-[http_sample_do_head_response]
+[example_http_do_head_response]
 
 [endsect]
 
@@ -111,7 +111,7 @@ connection sees a header without unnecessary latency. This example brings
 together all of the concepts discussed so far, it uses both a __serializer__
 and a __parser__ to achieve its goal:
 
-[http_sample_relay]
+[example_http_relay]
 
 [endsect]
 
@@ -134,7 +134,7 @@ the pointer and size fields before calling a stream write function.
 This example reads from a child process and sends the output back in an
 HTTP response. The output of the process is sent as it becomes available:
 
-[http_sample_send_cgi_response]
+[example_http_send_cgi_response]
 
 [endsect]
 

example/CMakeLists.txt

@@ -0,0 +1,8 @@
+# Part of Beast
+
+add_subdirectory (echo-op)
+add_subdirectory (http-client)
+add_subdirectory (http-crawl)
+add_subdirectory (http-server)
+add_subdirectory (websocket-client)
+add_subdirectory (websocket-server)

example/Jamfile

@@ -0,0 +1,13 @@
+#
+# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+build-project echo-op ;
+build-project http-client ;
+build-project http-crawl ;
+build-project http-server ;
+build-project websocket-client ;
+build-project websocket-server ;

example/doc/core_examples.hpp

@@ -8,13 +8,19 @@
 #include <boost/assert.hpp>
 #include <boost/config.hpp>
 
+/*  This file contains the functions and classes found in the documentation
+
+    They are compiled and run as part of the unit tests, so you can copy
+    the code and use it in your own projects as a starting point for
+    building a network application.
+*/
 //------------------------------------------------------------------------------
 //
 // Example: Detect TLS/SSL
 //
 //------------------------------------------------------------------------------
 
-//[core_sample_detect_tls_1
+//[example_core_detect_tls_1
 
 #include <beast.hpp>
 #include <boost/logic/tribool.hpp>
@@ -49,7 +55,7 @@ is_ssl_handshake(ConstBufferSequence const& buffers);
 
 using namespace beast;
 
-//[core_sample_detect_tls_2
+//[example_core_detect_tls_2
 
 template<
     class ConstBufferSequence>
@@ -88,7 +94,7 @@ is_ssl_handshake(
 
 //]
 
-//[core_sample_detect_tls_3
+//[example_core_detect_tls_3
 
 /** Detect a TLS/SSL handshake on a stream.
 
@@ -170,7 +176,7 @@ detect_ssl(
 
 //]
 
-//[core_sample_detect_tls_4
+//[example_core_detect_tls_4
 
 /** Detect a TLS/SSL handshake asynchronously on a stream.
 
@@ -228,7 +234,7 @@ async_detect_ssl(
 
 //]
 
-//[core_sample_detect_tls_5
+//[example_core_detect_tls_5
 
 // This is the composed operation.
 template<
@@ -286,7 +292,7 @@ async_detect_ssl(
 
 //]
 
-//[core_sample_detect_tls_6
+//[example_core_detect_tls_6
 
 // Read from a stream to invoke is_tls_handshake asynchronously
 //
@@ -383,7 +389,7 @@ public:
 
 //]
 
-//[core_sample_detect_tls_7
+//[example_core_detect_tls_7
 
 // detect_ssl_op is callable with the signature
 // void(error_code, bytes_transferred),

example/doc/http_examples.hpp

@@ -7,7 +7,12 @@
 
 #include <beast.hpp>
 
-// Contains the HTTP Examples from the documentation.
+/*  This file contains the functions and classes found in the documentation
+
+    They are compiled and run as part of the unit tests, so you can copy
+    the code and use it in your own projects as a starting point for
+    building a network application.
+*/
 
 // The documentation assumes the beast::http namespace
 namespace beast {
@@ -19,7 +24,7 @@ namespace http {
 //
 //------------------------------------------------------------------------------
 
-//[http_sample_send_expect_100_continue
+//[example_http_send_expect_100_continue
 
 /** Send a request with Expect: 100-continue
 
@@ -88,7 +93,7 @@ send_expect_100_continue(
 
 //]
 
-//[http_sample_receive_expect_100_continue
+//[example_http_receive_expect_100_continue
 
 /** Receive a request, handling Expect: 100-continue if present.
 
@@ -155,7 +160,7 @@ receive_expect_100_continue(
 //
 //------------------------------------------------------------------------------
 
-//[http_sample_send_cgi_response
+//[example_http_send_cgi_response
 
 /** Send the output of a child process as an HTTP response.
 
@@ -273,7 +278,7 @@ send_cgi_response(
 //
 //--------------------------------------------------------------------------
 
-//[http_sample_do_head_response
+//[example_http_do_head_response
 
 /** Handle a HEAD request for a resource.
 */
@@ -347,7 +352,7 @@ void do_server_head(
 
 //]
 
-//[http_sample_do_head_request
+//[example_http_do_head_request
 
 /** Send a HEAD request for a resource.
 
@@ -425,7 +430,7 @@ do_head_request(
 //
 //------------------------------------------------------------------------------
 
-//[http_sample_relay
+//[example_http_relay
 
 /** Relay an HTTP message.
 
@@ -552,7 +557,7 @@ relay(
 //
 //------------------------------------------------------------------------------
 
-//[http_sample_write_ostream
+//[example_http_write_ostream
 
 // The detail namespace means "not public"
 namespace detail {
@@ -662,7 +667,7 @@ write_ostream(
 //
 //------------------------------------------------------------------------------
 
-//[http_sample_read_istream
+//[example_http_read_istream
 
 /** Read a message from a `std::istream`.
 
@@ -771,7 +776,7 @@ read_istream(
 //
 //------------------------------------------------------------------------------
 
-//[http_sample_defer_body
+//[example_http_defer_body
 
 /** Handle a form PUT request, choosing a body type depending on the Content-Type.
 
@@ -865,7 +870,7 @@ do_form_request(
 //
 //------------------------------------------------------------------------------
 
-//[http_sample_custom_parser
+//[example_http_custom_parser
 
 template<bool isRequest>
 class custom_parser

example/echo-op/CMakeLists.txt

@@ -0,0 +1,17 @@
+# Part of Beast
+
+GroupSources(extras/beast extras)
+GroupSources(include/beast beast)
+
+GroupSources(example/echo-op "/")
+
+add_executable (echo-op
+    ${BEAST_INCLUDES}
+    echo_op.cpp
+)
+
+if (NOT WIN32)
+    target_link_libraries(echo-op ${Boost_LIBRARIES} Threads::Threads)
+else()
+    target_link_libraries(echo-op ${Boost_LIBRARIES})
+endif()

example/echo-op/Jamfile

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+exe echo-op/echo-op :
+    echo_op.cpp
+    ;

example/echo-op/echo_op.cpp

@@ -11,7 +11,7 @@
 #include <memory>
 #include <utility>
 
-//[core_sample_echo_op_1
+//[example_core_echo_op_1
 
 /** Asynchronously read a line and echo it back.
 
@@ -61,7 +61,7 @@ async_echo(
 
 //]
 
-//[core_sample_echo_op_3
+//[example_core_echo_op_3
 
 // This composed operation reads a line of input and echoes it back.
 //
@@ -181,7 +181,7 @@ public:
 
 //]
 
-//[core_sample_echo_op_4
+//[example_core_echo_op_4
 
 // echo_op is callable with the signature void(error_code, bytes_transferred),
 // allowing `*this` to be used as both a ReadHandler and a WriteHandler.
@@ -228,7 +228,7 @@ operator()(beast::error_code ec, std::size_t bytes_transferred)
 
 //]
 
-//[core_sample_echo_op_2
+//[example_core_echo_op_2
 
 template<class AsyncStream, class Handler>
 class echo_op;

example/http-client/CMakeLists.txt

@@ -0,0 +1,18 @@
+# Part of Beast
+
+GroupSources(extras/beast extras)
+GroupSources(include/beast beast)
+
+GroupSources(example/http-client "/")
+
+add_executable (http-client
+    ${BEAST_INCLUDES}
+    ${EXTRAS_INCLUDES}
+    http_client.cpp
+)
+
+if (NOT WIN32)
+    target_link_libraries(http-client ${Boost_LIBRARIES} Threads::Threads)
+else()
+    target_link_libraries(http-client ${Boost_LIBRARIES})
+endif()

example/http-client/Jamfile

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+exe http-client :
+    http_client.cpp
+    ;

example/http-client/http_client.cpp

@@ -5,7 +5,7 @@
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 //
 
-//[http_example_get
+//[example_http_client
 
 #include <beast/core.hpp>
 #include <beast/http.hpp>

example/http-crawl/CMakeLists.txt

@@ -0,0 +1,20 @@
+# Part of Beast
+
+GroupSources(extras/beast extras)
+GroupSources(include/beast beast)
+
+GroupSources(example/http-crawl "/")
+
+add_executable (http-crawl
+    ${BEAST_INCLUDES}
+    ${EXTRAS_INCLUDES}
+    urls_large_data.hpp
+    urls_large_data.cpp
+    http_crawl.cpp
+)
+
+if (NOT WIN32)
+    target_link_libraries(http-crawl ${Boost_LIBRARIES} Threads::Threads)
+else()
+    target_link_libraries(http-crawl ${Boost_LIBRARIES})
+endif()

example/http-crawl/Jamfile

@@ -5,27 +5,7 @@
 # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 #
 
-exe echo-op :
-    echo_op.cpp
-    ;
-
 exe http-crawl :
     http_crawl.cpp
     urls_large_data.cpp
     ;
-
-exe http-server :
-    http_server.cpp
-    ;
-
-exe http-example :
-    http_example.cpp
-    ;
-
-exe websocket-echo :
-    websocket_echo.cpp
-    ;
-
-exe websocket-example :
-    websocket_example.cpp
-    ;

example/http-server/CMakeLists.txt

@@ -0,0 +1,22 @@
+# Part of Beast
+
+GroupSources(extras/beast extras)
+GroupSources(include/beast beast)
+
+GroupSources(example/http-server "/")
+
+add_executable (http-server
+    ${BEAST_INCLUDES}
+    ${EXTRAS_INCLUDES}
+    file_body.hpp
+    mime_type.hpp
+    http_async_server.hpp
+    http_sync_server.hpp
+    main.cpp
+)
+
+if (NOT WIN32)
+    target_link_libraries(http-server ${Boost_LIBRARIES} Threads::Threads)
+else()
+    target_link_libraries(http-server ${Boost_LIBRARIES})
+endif()

example/http-server/Jamfile

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+exe http-server :
+    main.cpp
+    ;

example/http-server/file_body.hpp

@@ -21,7 +21,7 @@
 namespace beast {
 namespace http {
 
-//[http_sample_file_body_1
+//[example_http_file_body_1
 
 struct file_body
 {
@@ -70,7 +70,7 @@ struct file_body
 
 //]
 
-//[http_sample_file_body_2
+//[example_http_file_body_2
 
 template<bool isRequest, class Fields>
 std::uint64_t
@@ -82,7 +82,7 @@ size(message<isRequest, file_body, Fields> const& m)
 
 //]
 
-//[http_sample_file_body_3
+//[example_http_file_body_3
 
 class file_body::reader
 {
@@ -145,7 +145,7 @@ public:
 
 //]
 
-//[http_sample_file_body_4
+//[example_http_file_body_4
 
 // Here we just stash a reference to the path for later.
 // Rather than dealing with messy constructor exceptions,
@@ -266,7 +266,7 @@ file_body::reader::
 
 //]
 
-//[http_sample_file_body_5
+//[example_http_file_body_5
 
 class file_body::writer
 {
@@ -317,7 +317,7 @@ public:
 
 //]
 
-//[http_sample_file_body_6
+//[example_http_file_body_6
 
 // Just stash a reference to the path so we can open the file later.
 template<bool isRequest, class Fields>

example/ssl/CMakeLists.txt

@@ -3,7 +3,7 @@
 GroupSources(extras/beast extras)
 GroupSources(include/beast beast)
 
-GroupSources(examples/ssl "/")
+GroupSources(example/ssl "/")
 
 include_directories(${OPENSSL_INCLUDE_DIR})
 

example/websocket-client/CMakeLists.txt

@@ -0,0 +1,19 @@
+# Part of Beast
+
+GroupSources(extras/beast extras)
+GroupSources(include/beast beast)
+
+GroupSources(example/websocket-client "/")
+
+add_executable (websocket-client
+    ${BEAST_INCLUDES}
+    ${EXTRAS_INCLUDES}
+    websocket_client.cpp
+)
+
+if (NOT WIN32)
+    target_link_libraries(websocket-client ${Boost_LIBRARIES} Threads::Threads)
+else()
+    target_link_libraries(websocket-client ${Boost_LIBRARIES})
+endif()
+

example/websocket-client/Jamfile

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+exe websocket-client :
+    websocket_client.cpp
+    ;

example/websocket-client/websocket_client.cpp

@@ -5,7 +5,7 @@
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 //
 
-//[websocket_example_client_echo
+//[example_websocket_client
 
 #include <beast/core.hpp>
 #include <beast/websocket.hpp>

example/websocket-server/CMakeLists.txt

@@ -0,0 +1,19 @@
+# Part of Beast
+
+GroupSources(extras/beast extras)
+GroupSources(include/beast beast)
+
+GroupSources(example/websocket-server "/")
+
+add_executable (websocket-server
+    ${BEAST_INCLUDES}
+    main.cpp
+    websocket_async_echo_server.hpp
+    websocket_sync_echo_server.hpp
+)
+
+if (NOT WIN32)
+    target_link_libraries(websocket-server ${Boost_LIBRARIES} Threads::Threads)
+else()
+    target_link_libraries(websocket-server ${Boost_LIBRARIES})
+endif()

example/websocket-server/Jamfile

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+exe websocket-server :
+    main.cpp
+    ;

examples/CMakeLists.txt

@@ -1,87 +0,0 @@
-# Part of Beast
-
-GroupSources(extras/beast extras)
-GroupSources(include/beast beast)
-
-GroupSources(examples "/")
-
-add_executable (echo-op
-    ${BEAST_INCLUDES}
-    echo_op.cpp
-)
-
-if (NOT WIN32)
-    target_link_libraries(echo-op ${Boost_LIBRARIES} Threads::Threads)
-else()
-    target_link_libraries(echo-op ${Boost_LIBRARIES})
-endif()
-
-add_executable (http-crawl
-    ${BEAST_INCLUDES}
-    ${EXTRAS_INCLUDES}
-    urls_large_data.hpp
-    urls_large_data.cpp
-    http_crawl.cpp
-)
-
-if (NOT WIN32)
-    target_link_libraries(http-crawl ${Boost_LIBRARIES} Threads::Threads)
-else()
-    target_link_libraries(http-crawl ${Boost_LIBRARIES})
-endif()
-
-add_executable (http-server
-    ${BEAST_INCLUDES}
-    ${EXTRAS_INCLUDES}
-    file_body.hpp
-    mime_type.hpp
-    http_async_server.hpp
-    http_sync_server.hpp
-    http_server.cpp
-)
-
-if (NOT WIN32)
-    target_link_libraries(http-server ${Boost_LIBRARIES} Threads::Threads)
-else()
-    target_link_libraries(http-server ${Boost_LIBRARIES})
-endif()
-
-
-add_executable (http-example
-    ${BEAST_INCLUDES}
-    ${EXTRAS_INCLUDES}
-    http_example.cpp
-)
-
-if (NOT WIN32)
-    target_link_libraries(http-example ${Boost_LIBRARIES} Threads::Threads)
-else()
-    target_link_libraries(http-example ${Boost_LIBRARIES})
-endif()
-
-
-add_executable (websocket-echo
-    ${BEAST_INCLUDES}
-    websocket_async_echo_server.hpp
-    websocket_sync_echo_server.hpp
-    websocket_echo.cpp
-)
-
-if (NOT WIN32)
-    target_link_libraries(websocket-echo ${Boost_LIBRARIES} Threads::Threads)
-else()
-    target_link_libraries(websocket-echo ${Boost_LIBRARIES})
-endif()
-
-
-add_executable (websocket-example
-    ${BEAST_INCLUDES}
-    ${EXTRAS_INCLUDES}
-    websocket_example.cpp
-)
-
-if (NOT WIN32)
-    target_link_libraries(websocket-example ${Boost_LIBRARIES} Threads::Threads)
-else()
-    target_link_libraries(websocket-example ${Boost_LIBRARIES})
-endif()

examples/doc_websocket_samples.hpp

@@ -1,19 +0,0 @@
-//
-// Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
-//
-// Distributed under the Boost Software License, Version 1.0. (See accompanying
-// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-//
-
-#include <beast.hpp>
-
-// Contains the WebSocket Examples from the documentation.
-
-
-// The documentation assumes the beast::websocket namespace
-
-namespace beast {
-namespace websocket {
-
-} // websocket
-} // beast

test/Jamfile

@@ -25,7 +25,7 @@ unit-test core-tests :
     core/buffers_adapter.cpp
     core/clamp.cpp
     core/consuming_buffers.cpp
-    core/doc_core_samples.cpp
+    core/doc_examples.cpp
     core/doc_snippets.cpp
     core/drain_buffer.cpp
     core/error.cpp
@@ -49,7 +49,7 @@ unit-test http-tests :
     ../extras/beast/unit_test/main.cpp
     http/basic_parser.cpp
     http/buffer_body.cpp
-    http/doc_http_samples.cpp
+    http/doc_examples.cpp
     http/doc_snippets.cpp
     http/dynamic_body.cpp
     http/error.cpp

test/core/CMakeLists.txt

@@ -7,7 +7,7 @@ GroupSources(test/core "/")
 
 add_executable (core-tests
     ${BEAST_INCLUDES}
-    ${EXAMPLES_INCLUDES}
+    ${EXAMPLE_INCLUDES}
     ${EXTRAS_INCLUDES}
     ../../extras/beast/unit_test/main.cpp
     async_result.cpp
@@ -20,7 +20,7 @@ add_executable (core-tests
     buffers_adapter.cpp
     clamp.cpp
     consuming_buffers.cpp
-    doc_core_samples.cpp
+    doc_examples.cpp
     doc_snippets.cpp
     drain_buffer.cpp
     error.cpp

test/core/doc_examples.cpp

@@ -5,7 +5,7 @@
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 //
 
-#include <examples/doc_core_samples.hpp>
+#include "example/doc/core_examples.hpp"
 
 #include <beast/core/flat_buffer.hpp>
 #include <beast/core/ostream.hpp>

test/http/CMakeLists.txt

@@ -1,20 +1,21 @@
 # Part of Beast
 
-GroupSources(examples examples)
+GroupSources(example example)
 GroupSources(extras/beast extras)
 GroupSources(include/beast beast)
+
 GroupSources(test/http "/")
 
 add_executable (http-tests
     ${BEAST_INCLUDES}
-    ${EXAMPLES_INCLUDES}
+    ${EXAMPLE_INCLUDES}
     ${EXTRAS_INCLUDES}
     message_fuzz.hpp
     test_parser.hpp
     ../../extras/beast/unit_test/main.cpp
     basic_parser.cpp
     buffer_body.cpp
-    doc_http_samples.cpp
+    doc_examples.cpp
     doc_snippets.cpp
     dynamic_body.cpp
     empty_body.cpp

test/http/doc_examples.cpp

@@ -5,8 +5,8 @@
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 //
 
-#include <examples/doc_http_samples.hpp>
-#include <examples/file_body.hpp>
+#include "example/doc/http_examples.hpp"
+#include "example/http-server/file_body.hpp"
 
 #include <beast/core/read_size.hpp>
 #include <beast/core/detail/clamp.hpp>