Complete examples in beast html documentation

README.md

@@ -1,4 +1,4 @@
-# Beast
+# Beast [![Build Status](https://travis-ci.org/vinniefalco/Beast.svg?branch=master)](https://travis-ci.org/vinniefalco/Beast)
 
 Beast provides implementations of the HTTP and WebSocket protocols
 built on top of Boost.Asio and other parts of boost.
@@ -9,4 +9,17 @@ Requirements:
 * C++11 or greater
 * OpenSSL (optional)
 
-Documentation: http://vinniefalco.github.io/beast/
+Linking applications with beast:
+
+You need to include the .cpp file `src/beast_http_nodejs_parser.cpp`
+in the build script or Makefile for your program in order to link.
+
+Links:
+
+* [Home](http://vinniefalco.github.io/)
+* [Repository](https://github.com/vinniefalco/Beast)
+* [Documentation](http://vinniefalco.github.io/beast/)
+* [Autobahn.testsuite results](http://vinniefalco.github.io/autobahn/index.html)
+
+Please report issues or questions here:
+https://github.com/vinniefalco/Beast/issues

doc/beast.qbk

@@ -91,55 +91,81 @@ in C. To link an application that uses Beast, it is necessary to add a single
 [section:example Examples]
 
 These usage examples are intended to quickly impress upon readers the
-flavor of the library.
+flavor of the library. They are complete programs which may be built
+and run. Source code and build scripts for these programs may be found
+in the examples directory.
 
 [note
-    All examples and identifiers mentioned in this document are written as
-    if the following statements are in effect:
-```
-    #include <boost/asio.hpp>
-    #include <beast/http.hpp>
-    #include <beast/websocket.hpp>
-    using namespace beast;
-    using namespace boost::asio;
-```
+    To link these programs, please add the file
+    `src/beast_http_nodejs_parser.cpp` to your build script or Makefile
 ]
 
-Use HTTP to request the root page from a website and receive the response:
+Use HTTP to request the root page from a website and print the response:
 ```
-    std::string const host = "boost.org";
-    io_service ios;
-    ip::tcp::resolver r(ios);
-    ip::tcp::socket sock(ios);
-    connect(sock, r.resolve(ip::tcp::resolver::query{host, "http"}));
+#include <beast/http.hpp>
+#include <boost/asio.hpp>
+#include <iostream>
+#include <string>
 
-    http::request<http::empty_body> req(http::method_t::http_get, "/", 11);
+int main()
+{
+    // Normal boost::asio setup
+    std::string const host = "boost.org";
+    boost::asio::io_service ios;
+    boost::asio::ip::tcp::resolver r(ios);
+    boost::asio::ip::tcp::socket sock(ios);
+    boost::asio::connect(sock,
+        r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"}));
+
+    using namespace beast::http;
+
+    // Send HTTP request using beast
+    request<empty_body> req({method_t::http_get, "/", 11});
     req.headers.replace("Host", host + ":" + std::to_string(sock.remote_endpoint().port()));
     req.headers.replace("User-Agent", "Beast");
     write(sock, req);
 
-    http::response<http::streambuf_body> resp;
-    read(sock, resp);
-    ...
+    // Receive and print HTTP response using beast
+    beast::streambuf sb;
+    response<streambuf_body> resp;
+    read(sock, sb, resp);
+    std::cout << resp;
+}
 ```
 
 Establish a WebSocket connection, send a message and receive the reply:
 ```
-    std::string const host = "boost.org";
-    io_service ios;
-    tcp::resolver r(ios);
-    tcp::socket sock(ios);
-    connect(sock, r.resolve(tcp::resolver::query{host, "ws"}));
+#include <beast/websocket.hpp>
+#include <beast/buffers_debug.hpp>
+#include <boost/asio.hpp>
+#include <iostream>
+#include <string>
 
-    websocket::stream<ip::tcp::socket&> ws(sock);
-    ws.handshake();
-    ws.write(ws, buffer("Hello, world!"));
+int main()
+{
+    // Normal boost::asio setup
+    std::string const host = "echo.websocket.org";
+    boost::asio::io_service ios;
+    boost::asio::ip::tcp::resolver r(ios);
+    boost::asio::ip::tcp::socket sock(ios);
+    boost::asio::connect(sock,
+        r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
 
-    streambuf sb;
-    websocket::opcode op;
-    ws.read(ws, op, sb);
+    using namespace beast::websocket;
 
-    ws.close(); // WebSocket protocol close
+    // WebSocket connect and send message using beast
+    stream<boost::asio::ip::tcp::socket&> ws(sock);
+    ws.handshake(host, "/");
+    ws.write(boost::asio::buffer("Hello, world!"));
+
+    // Receive WebSocket message, print and close using beast
+    beast::streambuf sb;
+    opcode op;
+    ws.read(op, sb);
+    ws.close(close_code::normal);
+    std::cout <<
+        beast::debug::buffers_to_string(sb.data()) << "\n";
+}
 ```
 
 [endsect]

examples/Jamfile

@@ -22,3 +22,14 @@ exe wsproto_echo :
     ../src/beast_http_nodejs_parser.cpp
     wsproto_echo.cpp
     ;
+
+exe http_example :
+    ../src/beast_http_nodejs_parser.cpp
+    http_example.cpp
+    ;
+
+exe websocket_example :
+    ../src/beast_http_nodejs_parser.cpp
+    websocket_example.cpp
+    ;
+

examples/http_example.cpp

@@ -0,0 +1,36 @@
+//
+// Copyright (c) 2013-2016 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/http.hpp>
+#include <boost/asio.hpp>
+#include <iostream>
+#include <string>
+
+int main()
+{
+    // Normal boost::asio setup
+    std::string const host = "boost.org";
+    boost::asio::io_service ios;
+    boost::asio::ip::tcp::resolver r(ios);
+    boost::asio::ip::tcp::socket sock(ios);
+    boost::asio::connect(sock,
+        r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"}));
+
+    using namespace beast::http;
+
+    // Send HTTP request using beast
+    request<empty_body> req({method_t::http_get, "/", 11});
+    req.headers.replace("Host", host + ":" + std::to_string(sock.remote_endpoint().port()));
+    req.headers.replace("User-Agent", "Beast");
+    write(sock, req);
+
+    // Receive and print HTTP response using beast
+    beast::streambuf sb;
+    response<streambuf_body> resp;
+    read(sock, sb, resp);
+    std::cout << resp;
+}

examples/websocket_example.cpp

@@ -0,0 +1,38 @@
+//
+// Copyright (c) 2013-2016 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/websocket.hpp>
+#include <beast/buffers_debug.hpp>
+#include <boost/asio.hpp>
+#include <iostream>
+#include <string>
+
+int main()
+{
+    // Normal boost::asio setup
+    std::string const host = "echo.websocket.org";
+    boost::asio::io_service ios;
+    boost::asio::ip::tcp::resolver r(ios);
+    boost::asio::ip::tcp::socket sock(ios);
+    boost::asio::connect(sock,
+        r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
+
+    using namespace beast::websocket;
+
+    // WebSocket connect and send message using beast
+    stream<boost::asio::ip::tcp::socket&> ws(sock);
+    ws.handshake(host, "/");
+    ws.write(boost::asio::buffer("Hello, world!"));
+
+    // Receive WebSocket message, print and close using beast
+    beast::streambuf sb;
+    opcode op;
+    ws.read(op, sb);
+    ws.close(close_code::normal);
+    std::cout <<
+        beast::debug::buffers_to_string(sb.data()) << "\n";
+}