|
|
Boost-Commit : |
From: lists.drrngrvy_at_[hidden]
Date: 2008-08-04 19:37:19
Author: drrngrvy
Date: 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
New Revision: 47979
URL: http://svn.boost.org/trac/boost/changeset/47979
Log:
Minor doc updates (just the first few sections).
Removed:
sandbox/SOC/2007/cgi/trunk/libs/cgi/example/cgi/main.cpp
Text files modified:
sandbox/SOC/2007/cgi/trunk/boost/cgi/common/response.hpp | 28 ----------------------------
sandbox/SOC/2007/cgi/trunk/boost/cgi/impl/response.ipp | 35 ++++++++++++++++++++++++++++++++++-
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/introduction.qbk | 11 +++++------
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/preface.qbk | 24 +++++++++++++++++++++++-
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/tutorial/10_min_intro.cpp | 2 +-
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/tutorial/scaling.qbk | 35 ++++++++++++++++++++++++++---------
sandbox/SOC/2007/cgi/trunk/libs/cgi/example/acgi/echo/main.cpp | 2 +-
sandbox/SOC/2007/cgi/trunk/libs/cgi/example/cgi/echo/main.cpp | 8 ++++----
sandbox/SOC/2007/cgi/trunk/libs/cgi/example/fcgi/hello_world/main.cpp | 12 +++++++-----
9 files changed, 101 insertions(+), 56 deletions(-)
Modified: sandbox/SOC/2007/cgi/trunk/boost/cgi/common/response.hpp
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/boost/cgi/common/response.hpp (original)
+++ sandbox/SOC/2007/cgi/trunk/boost/cgi/common/response.hpp 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -24,34 +24,6 @@
#include "boost/cgi/detail/throw_error.hpp"
#include "boost/cgi/fwd/basic_request_fwd.hpp"
-/// This mess outputs a default Content-type header if the user hasn't set any.
-/** **FIXME** Not implemented; not sure if it should be...
- * BOOST_CGI_ADD_DEFAULT_HEADER should not persiste beyond this file.
- *
- * It basically works like (default first):
- *
- * Debug mode:
- * - Append a "Content-type: text/plain" header;
- * - If BOOST_CGI_DEFAULT_CONTENT_TYPE is defined, set that as the
- * content-type;
- * - If BOOST_CGI_NO_DEFAULT_CONTENT_TYPE is defined, do nothing.
- *
- * Release mode:
- * - Do nothing.
- */
-#if !defined(NDEBUG) && !defined(BOOST_CGI_NO_DEFAULT_CONTENT_TYPE)
-//{
-# if !defined(BOOST_CGI_DEFAULT_CONTENT_TYPE)
-# define BOOST_CGI_DEFAULT_CONTENT_TYPE "Content-type: text/plain"
-# endif // !defined(BOOST_CGI_DEFAULT_CONTENT_TYPE)
-//}
-# define BOOST_CGI_ADD_DEFAULT_HEADER \
- if (headers_.empty()) \
- headers_.push_back(BOOST_CGI_DEFAULT_CONTENT_TYPE"\r\n");
-#else
-# define BOOST_CGI_ADD_DEFAULT_HEADER
-#endif // !defined(NDEBUG) && !defined(BOOST_CGI_NO_DEFAULT_CONTENT_TYPE)
-
namespace cgi {
namespace common {
Modified: sandbox/SOC/2007/cgi/trunk/boost/cgi/impl/response.ipp
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/boost/cgi/impl/response.ipp (original)
+++ sandbox/SOC/2007/cgi/trunk/boost/cgi/impl/response.ipp 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -29,6 +29,39 @@
#include "boost/cgi/detail/throw_error.hpp"
#include "boost/cgi/fwd/basic_request_fwd.hpp"
+/// This mess outputs a default Content-type header if the user hasn't set any.
+/** **FIXME** Not implemented; not sure if it should be...
+ * BOOST_CGI_ADD_DEFAULT_HEADER should not persiste beyond this file.
+ *
+ * It basically works like (default first):
+ *
+ * Debug mode:
+ * - Append a "Content-type: text/plain" header;
+ * - If BOOST_CGI_DEFAULT_CONTENT_TYPE is defined, set that as the
+ * content-type;
+ * - If BOOST_CGI_NO_DEFAULT_CONTENT_TYPE is defined, do nothing.
+ *
+ * Release mode:
+ * - Same.
+ *
+ * Usage:
+ * ------
+ * // Default to a HTML content-type.
+ * #define BOOST_CGI_DEFAULT_CONTENT_TYPE "text/html"
+ */
+#if defined(BOOST_CGI_NO_DEFAULT_CONTENT_TYPE)
+//{
+# define BOOST_CGI_ADD_DEFAULT_HEADER void
+#else
+# if !defined(BOOST_CGI_DEFAULT_CONTENT_TYPE)
+# define BOOST_CGI_DEFAULT_CONTENT_TYPE "text/plain"
+# endif // !defined(BOOST_CGI_DEFAULT_CONTENT_TYPE)
+//}
+# define BOOST_CGI_ADD_DEFAULT_HEADER \
+ if (headers_.empty()) \
+ headers_.push_back("Content-type: "BOOST_CGI_DEFAULT_CONTENT_TYPE"\r\n")
+#endif // defined(BOOST_CGI_NO_DEFAULT_CONTENT_TYPE)
+
namespace cgi {
namespace common {
@@ -327,7 +360,7 @@
template<typename ConstBufferSequence> BOOST_CGI_INLINE
void basic_response<T>::prepare_headers(ConstBufferSequence& headers)
{
- BOOST_CGI_ADD_DEFAULT_HEADER
+ BOOST_CGI_ADD_DEFAULT_HEADER;
// Terminate the headers.
if (!headers_terminated_)
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/introduction.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/introduction.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/introduction.qbk 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -17,16 +17,15 @@
response resp;
resp<< "Hello there, Universe. "
- << "-- " << req.GET("name")
- << content_type("text/plain");
+ << "-- " << req[get]["name"];
- return_(req, resp, 0); // write the response and 'return 0;'
+ return_(req, resp, 0); // write the response and 'return 0;' to the OS
}
``
-Example request:
+An example request:
``
-example.com/program_name?name=Mr.+Allison
+GET example.com/program_name?name=Mr.+Allison HTTP/1.0
``
Output (as viewed in a web browser):
@@ -41,7 +40,7 @@
The __amort_example__ example uses Google cTemplate for dealing with HTML templates. Consider having a look at it, or at the upcoming ''Karma'' part of Boost.Spirit.
]
-[h4 Concepts]
+[h4 Concepts]:
The library provides abstractions which hide details of the varying specifications of CGI, FastCGI and SCGI. The main abstractions are, briefly:
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/preface.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/preface.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/preface.qbk 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -69,11 +69,21 @@
[table
[[Protocol] [`namespace`]]
+
[[CGI] [`namespace boost::cgi`
+
+ OR
+
`namespace cgi::cgi`]]
[[aCGI] [`namespace boost::acgi`
+
+ OR
+
`namespace cgi::acgi`]]
[[FastCGI] [`namespace boost::fcgi`
+
+ OR
+
`namespace cgi::fcgi`]]
]
@@ -81,7 +91,19 @@
Macros are prefixed with `BOOST_CGI_*` .
-[/ **FIXME**] There aren't any tested public macros yet, when there are they will be listed here.
+The only public macros so far are:
+
+[variablelist Valid macros
+
+ [[`BOOST_CGI_DEFAULT_CONTENT_TYPE`] [This defaults to "text/plain" and causes a default "content-type" header to be output, but ['only when you don't output any other headers].
+ ]]
+
+ [[`BOOST_CGI_NO_DEFAULT_CONTENT_TYPE`] [`#define` this when you don't want a default "content-type" header to be output. CGI scripts always need one of these, so you will be responsible for sending one!
+ ]]
+
+]
+
+
[h5 Code snippets]
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/tutorial/10_min_intro.cpp
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/tutorial/10_min_intro.cpp (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/tutorial/10_min_intro.cpp 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -23,7 +23,7 @@
Let's assume you now want to check if the user has a cookie, "user_name", set. We get at it like this:
*/
- std::string user_name( req[cookie]["user_name"] );
+ std::string user_name( req[cookies]["user_name"] );
/*`
If it's set, we'll be polite and say hello. If you are used to CGI programming, you'll notice the lack of any HTTP headers. If you don't want to bother with headers, a default header `'Content-type: text/plain'` is sent, followed by the usual HTTP end-of-line `'\r\n'` and a blank line which indicates the end of the headers and the start of content.
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/tutorial/scaling.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/tutorial/scaling.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/tutorial/scaling.qbk 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -30,8 +30,7 @@
response resp;
- resp<< content_type("text/plain")
- << "Hello, world.";
+ resp<< "Hello, world.";
resp.send(req.client());
req.close(http::ok, 0);
@@ -45,7 +44,7 @@
}
``
-If should be reasonably obvious what's going on above. Let's go through the differences to the original CGI example.
+Hopefully you can guess what's going on above. Let's go through the differences to the original CGI example.
``
acceptor a(s);
@@ -65,20 +64,38 @@
``
a.accept(req);
-req.load();
+req.load(); // equivalent to req.load(parse_env) - the least-expensive useful state for a request.
``
-This accepts one request. An accepted request is in a protocol-dependent state and generally isn't very useful. You must either `load()` or `async_load()` the request to put in a useful state. The arguments to these functions determine what is parsed (**FIXME** these will have to be named, so you can do `req.load(parse_params|parse_post|parse_cookies|etc...)`).
+This accepts one request. An accepted request is in a protocol-dependent state and generally isn't very useful. You must either `load()` or `async_load()` the request to put in a useful state. The arguments to these functions determine what is parsed. You can do things like:
-Beyond this the request is basically the same as a CGI request. As mentioned previously, you must explicitly close the request when you're finished with it:
+``
+req.load(parse_env|parse_post|parse_cookies); // parse everything but GET variables
+req.load(parse_all); // parse everthing
+req.load(parse_env); // parse just environment variables
+req.load(parse_get); // parse environment and GET variables
+req.load(parse_form); // parse environment and then either GET or POST variables, dependent on the REQUEST_METHOD
+``
+
+Beyond the accept/load sequence the request is basically the same as a CGI request as far as a library user is concerned. As mentioned earlier, you must explicitly close the request when you're finished with it:
``
-req.close(http::ok);
+req.close(http::ok, 0);
``
-More information on the available HTTP status codes can be found [link __http_status_codes__ here].
+The first argument should be a valid [@http://wikipedia.org/wiki/List_of_HTTP_status_codes HTTP status code], normalised to lower case and underscores except for '100 Continue', which is normalised to `http::continue_` (because `continue` is a keyword). The second argument is the program status and should be what you would have put in the `return 0;` line at the end of your `main()` function. Zero is the default if the argument is omitted, while non-zero means an error which may cause the HTTP server to kill the process. An alternative way to pass the status is like so:
+
+``
+resp<< http::moved_permanently // Handled specially by the `response`.
+ << "This page is no longer valid."
+ << location("somewhere_else") // The location of the new page
+ << content_type("text/plain"); // The location header has been output, so a content-type
+ // header is needed now.
+resp.send(req.client());
+return req.close(resp.status()); // use return_() instead!
+``
-One final thing to note is the type of error thrown by this library:
+One final thing to note is the type of error thrown by this library, which comes from [@http://boost.org/libs/system Boost.System]:
``
try {
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/example/acgi/echo/main.cpp
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/example/acgi/echo/main.cpp (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/example/acgi/echo/main.cpp 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -135,7 +135,7 @@
format_map(resp, req[post], "POST Variables");
format_map(resp, req[cookies], "Cookie Variables");
- if (req["request_method"] = "GET")
+ if (req["request_method"] == "GET")
{
resp<< "<pre>";
BOOST_FOREACH(char& ch, req.post_buffer())
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/example/cgi/echo/main.cpp
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/example/cgi/echo/main.cpp (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/example/cgi/echo/main.cpp 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -43,10 +43,10 @@
resp<< "Request id = " << req.id() << "<p/>";
- show_map_contents(resp, req[env_data], "Environment Variables");
- show_map_contents(resp, req[get_data], "GET Variables");
- show_map_contents(resp, req[post_data], "POST Variables");
- show_map_contents(resp, req[cookie_data], "Cookie Variables");
+ show_map_contents(resp, req[env], "Environment Variables");
+ show_map_contents(resp, req[get], "GET Variables");
+ show_map_contents(resp, req[post], "POST Variables");
+ show_map_contents(resp, req[cookies], "Cookie Variables");
// Note that this (and any other) HTTP header can go either before or after
// the response contents.
Deleted: sandbox/SOC/2007/cgi/trunk/libs/cgi/example/cgi/main.cpp
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/example/cgi/main.cpp 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
+++ (empty file)
@@ -1,25 +0,0 @@
-#include <string>
-#include <boost/system/error_code.hpp>
-//#include "../../../../boost/cgi/basic_protocol_service_fwd.hpp"
-#include <boost/cgi/cgi.hpp>
-
-int main()
-{
- try{
- cgi::cgi_request req;
-
- std::cerr<< "About to write header";
-
- std::string buf("Content-type: text/html\r\n\r\nHello there, universe!");
- boost::system::error_code ec;
-
- cgi::write(req.client(), cgi::buffer(buf.c_str(), buf.size()));
-
- buf = req.get_("blah");
- cgi::write(req.client(), cgi::buffer(buf.c_str(), buf.size()));
-
- } catch( boost::system::error_code& ec ) {
- //std::cerr<< "error: " << ec.message() << std::endl;
-}
- return 0;
-}
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/example/fcgi/hello_world/main.cpp
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/example/fcgi/hello_world/main.cpp (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/example/fcgi/hello_world/main.cpp 2008-08-04 19:37:17 EDT (Mon, 04 Aug 2008)
@@ -34,27 +34,29 @@
try
{
service s; // This becomes useful with async operations.
- acceptor a(s);
+ acceptor a(s); // The acceptor is for accepting requests
int ret = 0; // the return value
for (;;)
{
- request req(s); // Our request.
+ request req(s); // Our request (reusing this when possible saves expensive
+ // construction/destruction of the request's memory).
for (;;) // Handle requests until something goes wrong
// (an exception will be thrown).
{
a.accept(req);
- response resp; // A response object to make our lives easier.
- ret = handle_request(req, resp);
- if (ret) break; // Use a new request if something went wrong.
+ response resp; // Use the response class to make our lives easier.
+ ret = handle_request(req, resp); // The class defined above.
+ if (ret) break; // Use a new request if something went wrong.
}
if (!a.is_open()) break; // Quit completely if the acceptor bails out.
}
return ret;
}
+// This library throws only this type of exception (see Boost.System documentation).
catch(boost::system::system_error& err)
{
std::cerr<< "System error " << err.code() << ": "
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk