|
|
Boost-Commit : |
From: lists.drrngrvy_at_[hidden]
Date: 2007-08-18 10:40:36
Author: drrngrvy
Date: 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
New Revision: 38753
URL: http://svn.boost.org/trac/boost/changeset/38753
Log:
Documentation update.
Added:
sandbox/SOC/2007/cgi/boost/cgi/acgi/request_impl.hpp (contents, props changed)
sandbox/SOC/2007/cgi/boost/cgi/acgi/service.hpp (contents, props changed)
sandbox/SOC/2007/cgi/boost/cgi/cgi/request_impl.hpp (contents, props changed)
sandbox/SOC/2007/cgi/boost/cgi/cgi/service.hpp (contents, props changed)
sandbox/SOC/2007/cgi/boost/cgi/gateway_impl/scgi_gateway_impl.hpp (contents, props changed)
sandbox/SOC/2007/cgi/boost/cgi/gateway_service/scgi_gateway_service.hpp (contents, props changed)
Text files modified:
sandbox/SOC/2007/cgi/boost/cgi/basic_request.hpp | 18 ++++++++++-
sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 | 20 +++++++++----
sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk | 41 +++++++++++++++++++++++----
sandbox/SOC/2007/cgi/libs/cgi/doc/src/future_development.qbk | 60 +++++++++++++++++++++++++++++++++++++++
sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk | 24 ++++-----------
sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk | 12 ++++++-
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide.qbk | 20 +++++--------
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk | 6 ++-
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/headers.qbk | 29 ++++++++++++++-----
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk | 32 ++++++++++-----------
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk | 18 +++++++----
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk | 13 ++++++--
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk | 10 ++++--
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk | 29 +++++++++++--------
14 files changed, 234 insertions(+), 98 deletions(-)
Added: sandbox/SOC/2007/cgi/boost/cgi/acgi/request_impl.hpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/boost/cgi/acgi/request_impl.hpp 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,41 @@
+// -- acgi_request_impl.hpp --
+//
+// Copyright (c) Darren Garvey 2007.
+// 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)
+//
+////////////////////////////////////////////////////////////////
+#ifndef CGI_ACGI_REQUEST_IMPL_HPP_INCLUDED__
+#define CGI_ACGI_REQUEST_IMPL_HPP_INCLUDED__
+
+#include "service.hpp"
+#include "boost/cgi/detail/cgi_request_impl_base.hpp"
+#include "boost/cgi/connections/async_stdio.hpp"
+
+// Make this ProtocolService-independent
+
+namespace cgi {
+
+ // Forward declaration
+ class acgi_service_impl;
+
+ class acgi_request_impl
+ : public cgi_request_impl_base<acgi_request_impl, async_stdio_connection>
+ {
+ public:
+ typedef cgi_service protocol_service_type;
+
+ acgi_request_impl()
+ : cgi_request_impl_base<acgi_request_impl, connection_type>()
+ {
+ }
+
+ protected:
+ //acgi_request_impl(); // private default constructor
+ friend class acgi_service_impl;
+ };
+
+} // namespace cgi
+
+#endif // CGI_ASYNC_CGI_REQUEST_IMPL_HPP_INCLUDED__
Added: sandbox/SOC/2007/cgi/boost/cgi/acgi/service.hpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/boost/cgi/acgi/service.hpp 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,46 @@
+// -- cgi_service.hpp --
+//
+// Copyright (c) Darren Garvey 2007.
+// 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)
+//
+////////////////////////////////////////////////////////////////
+#ifndef CGI_CGI_SERVICE_HPP_INCLUDED__
+#define CGI_CGI_SERVICE_HPP_INCLUDED__
+
+#include "boost/cgi/tags.hpp"
+#include "boost/cgi/connections/stdio.hpp"
+#include "boost/cgi/connections/async_stdio.hpp"
+#include "boost/cgi/gateway_impl/acgi_gateway_impl.hpp"
+#include "boost/cgi/gateway_service/acgi_gateway_service.hpp"
+#include "boost/cgi/basic_protocol_service.hpp"
+
+namespace cgi {
+
+ /// typedef for typical usage
+ /**
+ * Works with both cgi_request and acgi_request.
+ */
+ typedef basic_protocol_service<tags::acgi> cgi_service;
+
+ /// A service 'owned' by a single user-supplied io_service
+ //typedef basic_protocol_service<tags::acgi> cgi_sub_service;
+
+ /// A service with a pool of io_services underneath
+ /*
+ template<int IoServiceCount, typename PoolingPolicy = tags::round_robin>
+ struct cgi_service_pool
+ : public basic_protocol_service<tags::acgi, IoServiceCount, PoolingPolicy>
+ {
+ cgi_service_pool(int concurrency_hint = 0)
+ : basic_protocol_service<tags::acgi, IoServiceCount, PoolingPolicy>
+ (concurrency_hint)
+ {
+ }
+ };
+ */
+
+} // namespace cgi
+
+#endif // CGI_CGI_SERVICE_HPP_INCLUDED__
Modified: sandbox/SOC/2007/cgi/boost/cgi/basic_request.hpp
==============================================================================
--- sandbox/SOC/2007/cgi/boost/cgi/basic_request.hpp (original)
+++ sandbox/SOC/2007/cgi/boost/cgi/basic_request.hpp 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -124,9 +124,10 @@
}
/// Set a header
- void set_header(const std::string& name, const std::string& val)
+ void set_header(const std::string& name, const std::string& val
+ , const std::string& expires)
{
- this->service.set_header(this->impl, name, val);
+ this->service.set_header(this->impl, name, val, expires);
}
/// Set a cookie
@@ -135,6 +136,19 @@
this->service.set_cookie(this->impl, name, val);
}
+ /// Delete a cookie
+ void del_cookie(const std::string& name)
+ {
+ this->service.set_cookie(this->impl, name, val
+ , "Mon, 01-Jan-1945 00:00:01 GMT");
+ }
+
+ /// Delete all cookies
+ void del_cookies()
+ {
+ this->service.del_cookies();
+ }
+
/// Synchronously read/parse the request meta-data
/**
* Note: 'loading' including reading/parsing STDIN if parse_stdin == true
Added: sandbox/SOC/2007/cgi/boost/cgi/cgi/request_impl.hpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/boost/cgi/cgi/request_impl.hpp 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,98 @@
+// -- cgi_request_impl.hpp --
+//
+// Copyright (c) Darren Garvey 2007.
+// 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)
+//
+////////////////////////////////////////////////////////////////
+#ifndef CGI_CGI_REQUEST_IMPL_HPP_INCLUDED__
+#define CGI_CGI_REQUEST_IMPL_HPP_INCLUDED__
+
+#include <map>
+#include <string>
+#include <boost/noncopyable.hpp>
+#include <boost/shared_ptr.hpp>
+
+#include "boost/cgi/http/status_code.hpp"
+#include "boost/cgi/connections/stdio.hpp"
+#include "boost/cgi/role_type.hpp"
+#include "boost/cgi/status_type.hpp"
+#include "boost/cgi/map.hpp"
+#include "boost/cgi/detail/cgi_request_impl_base.hpp"
+
+// Make this ProtocolService-independent
+
+namespace cgi {
+
+ // Forward declaration
+ //template<typename>
+ class cgi_service_impl;
+
+
+ /// Implementation for a standard CGI request
+ /**
+ * Note: This isn't noncopyable since there's no real reason it can't be
+ * copied around. Since basic_request is noncopyable, basic copying will be
+ * restricted but if someone really wants to copy the data, then they can.
+ */
+ class cgi_request_impl
+ : public cgi_request_impl_base<stdio_connection>
+ {
+ public:
+ /// Constructor
+ /**
+ * Since this request type is synchronous, there is no need for an
+ * io_service, so the passed ProtocolService is just ignored.
+ */
+ template<typename ProtocolService>
+ cgi_request_impl(ProtocolService& pserv)
+ : cgi_request_impl_base<connection_type>(pserv)
+ {
+ }
+
+ cgi_request_impl()
+ : cgi_request_impl_base<connection_type>()
+ {
+ }
+
+ protected:
+ friend class cgi_service_impl;//<cgi_request_impl>;
+ };
+
+ //template<> inline const std::string&
+ //cgi_request_impl::var<tags::ENV>(const std::string& name)
+ //{
+ // return ::getenv(name.c_str());
+ //}
+
+ /// Get a request map of all the environment meta-variables (slow)
+ /**
+ * -- NOT IMPLEMENTED FOR NOW --
+ *
+ * In the case of a CGI request, the environment meta-data is usually stored
+ * in the process environment, which means there is no direct access to all
+ * of them as a map_type&. In other words, this function call will have to
+ * load all of the variables into memory and then return the map
+ */
+ //template<> inline cgi_request_impl::map_type&
+ //cgi_request_impl::var<tags::ENV>()
+ //{
+ // throw std::logic_error("Can't get all environment vars as a map_type&");
+ //}
+
+ //template<> inline cgi_request_impl::map_type&
+ //cgi_request_impl::var<tags::HTTP>() { return http_map_; }
+
+ //template<> inline cgi_request_impl::map_type&
+ //cgi_request_impl::var<tags::COOKIE>() { return cookie_map_; }
+
+ //template<> inline cgi_request_impl::map_type&
+ //cgi_request_impl::var<tags::GET>() { return get_map_; }
+
+ //template<> inline cgi_request_impl::map_type&
+ //cgi_request_impl::var<tags::POST>() { return post_map_; }
+
+} // namespace cgi
+
+#endif // CGI_CGI_REQUEST_IMPL_HPP_INCLUDED__
Added: sandbox/SOC/2007/cgi/boost/cgi/cgi/service.hpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/boost/cgi/cgi/service.hpp 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,46 @@
+// -- cgi_service.hpp --
+//
+// Copyright (c) Darren Garvey 2007.
+// 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)
+//
+////////////////////////////////////////////////////////////////
+#ifndef CGI_CGI_SERVICE_HPP_INCLUDED__
+#define CGI_CGI_SERVICE_HPP_INCLUDED__
+
+#include "boost/cgi/tags.hpp"
+#include "boost/cgi/connections/stdio.hpp"
+#include "boost/cgi/connections/async_stdio.hpp"
+#include "boost/cgi/gateway_impl/acgi_gateway_impl.hpp"
+#include "boost/cgi/gateway_service/acgi_gateway_service.hpp"
+#include "boost/cgi/basic_protocol_service.hpp"
+
+namespace cgi {
+
+ /// typedef for typical usage
+ /**
+ * Works with both cgi_request and acgi_request.
+ */
+ typedef basic_protocol_service<tags::acgi> cgi_service;
+
+ /// A service 'owned' by a single user-supplied io_service
+ //typedef basic_protocol_service<tags::acgi> cgi_sub_service;
+
+ /// A service with a pool of io_services underneath
+ /*
+ template<int IoServiceCount, typename PoolingPolicy = tags::round_robin>
+ struct cgi_service_pool
+ : public basic_protocol_service<tags::acgi, IoServiceCount, PoolingPolicy>
+ {
+ cgi_service_pool(int concurrency_hint = 0)
+ : basic_protocol_service<tags::acgi, IoServiceCount, PoolingPolicy>
+ (concurrency_hint)
+ {
+ }
+ };
+ */
+
+} // namespace cgi
+
+#endif // CGI_CGI_SERVICE_HPP_INCLUDED__
Added: sandbox/SOC/2007/cgi/boost/cgi/gateway_impl/scgi_gateway_impl.hpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/boost/cgi/gateway_impl/scgi_gateway_impl.hpp 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,32 @@
+// -- scgi_gateway_impl.hpp --
+//
+// Copyright (c) Darren Garvey 2007.
+// 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)
+//
+////////////////////////////////////////////////////////////////
+#ifndef CGI_SCGI_GATEWAY_IMPL_HPP_INCLUDED__
+#define CGI_SCGI_GATEWAY_IMPL_HPP_INCLUDED__
+
+#include <boost/noncopyable.hpp>
+
+namespace cgi {
+
+ // Forward declaration
+ class scgi_gateway_service;
+
+
+ class scgi_gateway_impl
+ : private boost::noncopyable
+ {
+ public:
+ scgi_gateway_impl() {}
+ ~scgi_gateway_impl() {}
+ protected:
+ friend class scgi_gateway_service;
+ };
+
+} // namespace cgi
+
+#endif // CGI_SCGI_GATEWAY_IMPL_HPP_INCLUDED__
Added: sandbox/SOC/2007/cgi/boost/cgi/gateway_service/scgi_gateway_service.hpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/boost/cgi/gateway_service/scgi_gateway_service.hpp 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,55 @@
+// -- scgi_gateway_service.hpp --
+//
+// Copyright (c) Darren Garvey 2007.
+// 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)
+//
+////////////////////////////////////////////////////////////////
+#ifndef CGI_SCGI_GATEWAY_SERVICE_HPP_INCLUDED__
+#define CGI_SCGI_GATEWAY_SERVICE_HPP_INCLUDED__
+
+#include <set>
+#include <boost/bind.hpp>
+#include <boost/shared_ptr.hpp>
+
+#include "../connections/tcp_socket.hpp"
+
+namespace cgi {
+
+ class scgi_gateway_service
+ {
+ public:
+
+ struct implementation_type
+ {
+ typedef tcp_connection connection_type;
+ typedef boost::shared_ptr<connection_type> connection_ptr;
+ private:
+ std::set<connection_ptr> connections_;
+ };
+
+ scgi_gateway_service() {}
+ ~scgi_gateway_service() {}
+
+ template<typename T> void construct(T&) {}
+ template<typename T> void destroy(T&) {}
+ template<typename T> void start(T&) {}
+ template<typename T> void stop(T&) {}
+
+ void stop(implementation_type& impl)
+ {
+ std::for_each(impl.connections_.begin(), impl.connections_.end()
+ , boost::bind(&implementation_type::connection_type::stop
+ , *_1));
+ }
+
+ void reset(implementation_type& impl)
+ {
+ stop(impl);
+ }
+ };
+
+} // namespace cgi
+
+#endif // CGI_SCGI_GATEWAY_SERVICE_HPP_INCLUDED__
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -25,9 +25,9 @@
[ glob ../../../boost/cgi/request_impl/*.hpp ]
[ glob ../../../boost/cgi/request_service/*.hpp ]
:
- <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+ <doxygen:param>HIDE_UNDOC_MEMBERS=NO
<doxygen:param>EXTRACT_PRIVATE=NO
- <doxygen:param>EXTRACT_ALL=YES
+ #<doxygen:param>EXTRACT_ALL=YES
<doxygen:param>SEARCH_INCLUDES=YES
<doxygen:param>INCLUDE_PATH=$(BOOST_ROOT)
;
@@ -39,12 +39,20 @@
cgi_xml
cgi_dox
:
- <xsl:param>boost.root=/usr/local/src/boost
+ <xsl:param>boost.root=/usr/local/src/cgi/svn.boost.org/
<xsl:param>boost.libraries=/usr/local/src/boost/libs/libraries.htm
- <xsl:param>boost.images=http://beta.boost.org/images
- <xsl:param>toc.max.depth=0
+# <xsl:param>boost.images=http://beta.boost.org/images
+ # the depth (of sub-pages) the TOC shows
+ <xsl:param>toc.max.depth=1
+
+ #
<xsl:param>toc.section.depth=2
- <xsl:param>chunk.section.depth=10
+
+ # how many sections are on the first page
+ <xsl:param>chunk.first.sections=1
+
+ # To chunk (together) or not to chunk (divide)
+ <xsl:param>chunk.section.depth=1 # chunk
;
#install html
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -24,7 +24,11 @@
[def __scgi__ [@http://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface SCGI]]
[def __fcgi__ [@http://en.wikipedia.org/wiki/FastCGI FastCGI]]
-[def __asio__ [@http://asio.sourceforge.net Asio]]
+[def __FastCGI__ [link boost.cgi.reference.protocols.fcgi FastCGI]]
+[def __SCGI__ [link boost.cgi.reference.protocols.scgi SCGI]]
+
+[def __boost__ [@http://boost.org/ Boost]]
+[def __asio__ [@http://asio.sourceforge.net Boost.Asio]]
[def __reading_the_docs__ [link boost.cgi.intro.reading_the_docs reading the docs]]
[def __naming_conventions__ [link boost.cgi.intro.naming_conventions naming conventions]]
@@ -55,18 +59,43 @@
[/ 'tut' is the id of the Tutorial, which is in the User's Guide]
[def __headers__ boost.cgi.ug.gs.headers]
-[def __accepting__ boost.cgi.ug.tut.accepting]
-[def __loading__ boost.cgi.ug.tut.loading]
+[def __accepting__ boost.cgi.ug.tutorial.accepting]
+[def __loading__ boost.cgi.ug.tutorial.loading]
+
+[important
+This manual does [*not] document a library that is a part of __Boost__. The major part of it has been developed this summer as part of the Google Summer of Code, '[@http://code.google.com/soc GSoC07]'. Everything from here on in is alpha-grade, some bits more than others; [link boost.cgi.preface.comments_and_support comments] are welcome.
+These documents are either hosted at [@http://sourceforge.net/projects/cgi/ sourceforge], or at [@http://svn.boost.org/svn/boost/browser/sandbox/SOC/2007/cgi svn.boost.org]. For free!
+]
[include preface.qbk]
-[include introduction.qbk]
+[include:intro introduction.qbk]
+
+[section:gs Getting Started]
+
+This section of the documentation is probably best read before the [link __tutorial__ tutorial]. In a nutshell, this is a quick and dirty run-through of how to get and install the library [-and configure your server].
+
+[include:building user_guide/building.qbk]
+
+[include:server_config user_guide/server_configuration.qbk]
-[include user_guide.qbk]
+[include:headers user_guide/headers.qbk]
+
+[endsect]
+
+[include:tutorial user_guide/tutorial.qbk]
+
+[include:protocols user_guide/protocols.qbk]
+
+[include:examples user_guide/examples.qbk]
+
+[/include:ug user_guide.qbk]
[xinclude ../cgi_dox.boostbook]
-[include future_development.qbk]
+[include:future future_development.qbk]
+
+[include:server_support user_guide/server_support.qbk]
[/include acknowledgements.qbk]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/future_development.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/future_development.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/future_development.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -17,7 +17,9 @@
[h4 FastCGI support.]
-Complete FastCGI support is essential to any modern CGI library.
+FastCGI support is essential to any modern CGI library. There is currently ['no] known FastCGI library for C or C++ that aims to implement the complete [@http://www.fastcgi.com/devkit/doc/fcgi-spec.html FastCGI 1.0] specification.
+
+There are a couple of issues that have yet to be worked out, but in general the new framework is known to 'fit' with all the details of FastCGI and lends itself to an efficient implementation (hopefully).
[h4 Access to error output streams]
@@ -46,8 +48,64 @@
Yet another possibility, is that a member function `as<>` can be provided as a shortcut to `boost::lexical_cast<>`. This could greatly improve readability of web programs, where lexical casting is very common and may make programs overly verbose.
+Compare:
+``
+cgi::request req;
+cgi::reply rep;
+
+cgi::map::iterator iter = req.meta_form().find("number");
+if (iter != cgi::map::iterator::end())
+{
+ rep<< "You picked no numbers...";
+}
+else
+{
+ int sum(0);
+ rep<< "Your numbers are: ";
+ for(; iter != cgi::map::iterator::end(); ++iter)
+ {
+ rep<< iter->second << " ";
+ sum += boost::lexical_cast<int>(iter->second);
+ }
+
+ rep<< std::endl
+ << "Your numbers add up to: " << sum;
+}
+
+rep.send(req);
+``
+to:
+``
+cgi::request req;
+cgi::reply rep;
+
+cgi::param parm = req.meta_form("number");
+if (parm.empty())
+{
+ rep<< "You picked no numbers...";
+}
+else
+{
+ int sum(0);
+ for(; parm != parm.end(); ++parm)
+ {
+ rep<< parm << " ";
+ sum += parm.as<int>());
+ }
+
+ rep<< std::endl
+ << "Your numbers add up to: " << sum;
+}
+
+rep.send(req);
+``
+
[h4 Concept Documentation]
Even though this library introduces very few new concepts, they are not currently documented. Links to Boost.Asio's concept documentation is also required (essentially as part of a reworking of the doxygen reference section).
+[/h4 Support for wide characters]
+
+[/The library generally works on octets, but there should be some way to ]
+
[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -23,32 +23,22 @@
}
``
-This CGI library reasonably high-level library for web programming. Herein the controller portion of the Model-View-Controller idiom is implemented. The intricacies of dealing with the widely varying specifications of CGI, FastCGI and SCGI are abstracted into three main sub-parts:
+This CGI library reasonably high-level library for web programming. Herein the controller portion of the Model-View-Controller idiom is implemented. The intricacies of dealing with the widely varying specifications of CGI, FastCGI and SCGI are abstracted into three main parts:
* Accepting,
* Loading, and
-* Handling
+* Handling.
-This is all described in more detail in the [link __tutorial__ tutorial].
+Sometimes all a problem calls for is a thin interface to request data and '''I/O''' streams, without any need to be hyper-efficient: in other words, like a short CGI script that you can with [@http://tinyurl.com/2ss4ae perl], [@http://tinyurl.com/39b37l python], [@http://tinyurl.com/3yg4m8 php], etc. To allow this, the library and documentation are split into two parts: 'scripting' and 'everything else'. The code excerpt above is an example of a 'script' which, as you can see, skips the 'accepting' and 'loading' stages.
-If a program's purpose is to serve the wider world, it should be written with scalability in mind. The `cgi::srequest` (the 's' is for 'synchronous' - ie. asynchronous operations cannot be used with it) that the [link __quickstart__ quickstart] introduces is simple to use and ideal for shorter, light-use programs, such as admin scripts. However when it comes to heavily used web applications CGI has an inherent limitation: there must be a complete heavyweight process for each client.
+If a program's purpose is to serve the wider world, it should be written with scalability in mind. When it comes to heavily used web applications CGI has an inherent limitation: there must be a complete heavyweight process ['for every request].
-[note
-Even though a `cgi::srequest` is set up differently to asynchronous request types, the alternative `cgi::request` (or the explicit form `cgi::acgi_request`) can be used in exactly the same way as FastCGI and SCGI requests. This symmetry makes migrating code between different protocols trivial (see [link __interoperability__ interoperability] for more) and aids debugging of server configuration issues.
-]
-
-FastCGI and SCGI both remove this restriction and there is support for them - of widely varying quality and completeness (see [link __server_support__ here]) - in most HTTP servers. These protocols add an extra layer to your CGI programs, as you now must manage the request queue.
-
-In return for the added complexity, your programs become complete servers, capable of handling arbitrary numbers of requests during each invocation (assuming they don't crash!): Database connections can be kept open between requests; ready-parsed XML files can be cached; processing of a client request can even be continued in the case of the client crashing - the reply can be cached and returned to them when they return - saving precious CPU cycles.
-
-Parsing of request meta-data can be done at any point in the program, or not at all (eg. for a hit-counter). Reading and parsing of data is referred to as '[link __loading__ loading]' and this follows '[link __accepting__ accepting]' a request.
-
-Fortunately, this layer can be largely isolated from the rest of your program logic and development of both can continue in parallel. The two parts share a [link __ProtocolService__ ProtocolService], such as a `cgi::fcgi_service` (similar in use to an [link __asio_io_service__ asio::io_service] for those familiar with [link __asio__ Boost.Asio]).
-
-The [link __examples__ examples] are divided like this, to keep them concise.
+The __FastCGI__ and __SCGI__ protocols are essentially reworkings of CGI which remove this restriction. They offer other advantages too, the support of which - of widely varying quality and completeness ([-more [link __server_support__ here]]) - comes for most HTTP servers. These protocols add an extra layer to your CGI programs, as you now must manage the request queue.
+In return for the added complexity, your programs become complete servers, capable of handling arbitrary numbers of requests during each invocation (assuming they don't crash!). This gives you the freedom to keep database connections open between requests, or cache ready-parsed responses, for example. Processing of a client request can even be continued in the case of the client crashing - the reply can then be stored and given to them when they return - saving precious CPU cycles.
+It might sound like a handful but, fortunately, management of the request queue can be largely isolated from the handling of each request. That means that after you have set up a 'server' (ie. something that gathers requests), requests can be handled in the same way as they would be with a conventional CGI program.
[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -7,11 +7,13 @@
[section Preface]
-[: [*['All science is either Physics, or stamp collecting.]] [br] -- Ernest Rutherford.]
+[: [*['All science is either Physics, or stamp collecting.]]
+
+-- Ernest Rutherford.]
[h3 Overview]
-Boost.CGI is a library for writing CGI programs in Standard C++. It can be used to write anything from simple 'adming scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio. Currently the __cgi__, [-__scgi__ and __fcgi__] protocols are supported.
+Boost.CGI is a library for writing CGI programs in Standard C++. It can be used to write anything from simple 'adming scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio, a cross-platform networking library in boost-style C++. Currently the __cgi__, [-__scgi__ and __fcgi__] protocols are supported, within a framework that should allow code to be reused with as-yet-unwritten protocols without any real modification.
[h3 Motivation]
@@ -52,4 +54,10 @@
As you are probably used to, it is assumed that code snippets in this manual have the correct `#include`s and "`using namespace cgi;`" prepended to them. Information about the correct headers to include can be found [link __headers__ here].
+[h3 Comments and Support]
+
+Use cases, example requests, puzzles and problems should be sent to the mailing list:
+
+* ''' cgi-talk @ lists.sf \.\ net''', or thereabouts.
+
[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -5,27 +5,23 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:ug User's Guide]
-
-This section of the docs is for all users of the library. For details about the internals of the library see either the __sources__ or the __reference__ section.
-
[section:gs Getting Started]
-This section of the documentation is probably best read before the __tutorial__. In a nutshell, this is a quick and dirty run-through of how to get and install the library [-and configure your server].
+This section of the documentation is probably best read before the [link __tutorial__ tutorial]. In a nutshell, this is a quick and dirty run-through of how to get and install the library [-and configure your server].
-[include user_guide/building.qbk]
+[include:building user_guide/building.qbk]
-[include user_guide/server_configuration.qbk]
+[include:server_config user_guide/server_configuration.qbk]
-[include user_guide/server_support.qbk]
+[include:headers user_guide/headers.qbk]
[endsect]
-[include user_guide/protocols.qbk]
+[/include:protocols user_guide/protocols.qbk]
-[include user_guide/tutorial.qbk]
+[/include:tutorial user_guide/tutorial.qbk]
-[include user_guide/examples.qbk]
+[/include:examples user_guide/examples.qbk]
-[endsect]
+[/endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -27,9 +27,11 @@
[
[Boost.System]
[No]
- [1. Download the latest Boost distro, 'boost'.[br][br]
+ [1. Download the latest Boost distro, 'boost'.
+
2. Set the environment variable BOOST_ROOT on your system to the download location.
- 3. Go to the directory BOOST_ROOT and invoke `bjam` (see above). This should finish without any fails.]
+
+ 3. Go to the directory BOOST_ROOT and invoke `bjam` (see above), passing it `--with-system install` on the command line. This should finish without any fails.]
]
[
[Documentation]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/headers.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/headers.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/headers.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -11,9 +11,9 @@
Depending on what protocol you plan on using, you should include [*one] of the following headers:
``
-#include <boost/cgi.hpp> // include header files for any protocol
+#include <boost/cgi.hpp> // include header files for any protocol
-#include <boost/cgi/cgi.hpp> // include all headers required for (sync) CGI usage
+#include <boost/cgi/cgi.hpp> // include all headers required for (sync) CGI usage
#include <boost/cgi/acgi.hpp> // include all headers required for aCGI usage
@@ -28,22 +28,35 @@
``
#define BOOST_CGI_IMPLICIT_SCGI 1
#include <boost/cgi.hpp>
-cgi::request req;
+cgi::service service; // implicit SCGI service
+cgi::request req(service); // implicit SCGI request
``
Is equivalent to:
``
#include <boost/cgi/scgi.hpp>
-cgi::request req;
+cgi::service service; // implicit SCGI service
+cgi::request req(service); // implicit SCGI request
``
Which is equivalent to:
``
-#include <boost/cgi.hpp> // or <boost/cgi/scgi.hpp>, here
-cgi::scgi_request req;
+#include <boost/cgi.hpp>
+cgi::scgi_service service; // SCGI service
+cgi::scgi_request req(service); // SCGI request
+``
+and:
+``
+#include <boost/cgi/scgi.hpp>
+cgi::scgi_service service; // SCGI service
+cgi::scgi_request req(service); // SCGI request
``
But:
``
#include <boost/cgi.hpp>
-cgi::request req; // error
+cgi::service service; // error: cgi::service does not name a type
+cgi::request req(service); // error: cgi::request does not name a type
``
+will not work.
+
+Note that the explicit form - `scgi_request`/`scgi_service` - is always valid, assuming you have (implicitly or otherwise) included, for example, `<boost/cgi/scgi/request.hpp>`.
-[endsect]
+[endsect] [/ headers]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -25,10 +25,23 @@
Synchronous and asynchronous CGI support are considered distinct within the library for now (*more*), so the latter is referred to explicitly as aCGI. SimpleCGI is generally shortened to SCGI while FastCGI is used verbatim.
]
+[section:comparison Feature Comparison]
+
+[table
+ [[Feature ] [Protocol ]]
+ [[ ] [CGI] [aCGI] [FastCGI] [SCGI ]]
+ [[Requires __ProtocolService__] [No ] [Yes ] [Yes ] [Yes ]]
+ [[Is natively asynchronous ] [No ] [No ] [Yes ] [Yes ]]
+ [[Has native error stream ] [Yes] [Yes ] [Yes ] [Shared]]
+]
+
+[endsect] [/ comparison]
+
+
[section:cgi CGI and aCGI]
-The distinction between CGI and aCGI is that aCGI uses __asio__'s io_service to perform asynchronous operations - whereas CGI does not provide such operations - and is also more complicated to use. A distinction has been made with the sole purpose of lowering the entry barrier to the library and to provide a means of migrating programs over to use this library.
+The distinction between CGI and aCGI is that aCGI uses __asio__'s `io_service` to perform asynchronous operations - whereas CGI does not provide such operations - and is also more complicated to setup. A distinction has been made with the sole purpose of lowering the entry barrier to the library and to provide a means of migrating programs over to use this library. There is also currently a small speed gain to be had by not constructing an `io_service` when it isn't needed.
[h4 Differences Between CGI and aCGI Programs]
@@ -106,23 +119,8 @@
SCGI uses a connection-per-request approach. Environment data is sent first and the CGI POST data follows. All data sent back to the server over the connection is forwarded as is to the client. The connection is closed after the request has been handled.
-Although far less optimized than FastCGI, SCGI is still a large step up from CGI
-
+Although far less optimized than FastCGI, SCGI is still a significant step up from CGI.
[endsect] [/ scgi]
-
-[section:comparison Feature Comparison]
-
-[table
- [[Feature ] [Protocol ]]
- [[ ] [CGI] [aCGI] [FastCGI] [SCGI ]]
- [[Requires io_service ] [No ] [Yes ] [Yes ] [Yes ]]
- [[Is natively asynchronous] [No ] [No ] [Yes ] [Yes ]]
- [[Has native error stream ] [Yes] [Yes ] [Yes ] [Shared]]
-]
-
-[endsect] [/ comparison]
-
-
[endsect] [/ protocols]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -5,7 +5,11 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:tut Tutorial]
+[section Tutorial]
+
+As mentioned in the [link __intro__ introduction], there are two ways of using this library: for 'scripting' and everything else.
+
+The thing that differentiates 'scripts' from everything else is the [link __ProtocolService__ ProtocolService] (this is similar in use to an [link __asio_io_service__ `io_service`] for those familiar with __asio__).
Except for when using CGI synchronously, a typical program will have two fundamental parts:
@@ -19,19 +23,19 @@
[h4 Handling requests]
-* Using the [link __meta_data__ meta-data];
+* [link __meta_data__ Accessing the data] associated with a request;
* [link __writing__ Writing] a reply;
-* [link boost.cgi.ug.handling_requests.wrapping_up Wrapping up];
+* [link __wrapping_up__ Wrapping up];
-[include tutorial/accepting.qbk]
+[include tutorial/quickstart.qbk]
-[include tutorial/loading.qbk]
+[include:requests tutorial/requests.qbk]
-[include tutorial/meta_data.qbk]
+[include:accepting tutorial/accepting.qbk]
-[include wrapping_up.qbk]
+[include:wrapping_up wrapping_up.qbk]
[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -7,11 +7,18 @@
[section:accepting Accepting Requests]
-A `basic_request_acceptor<>` is responsible for accepting requests. There are [link __naming_conventions__ common typedefs] for ease of use, as with `basic_request<>`s. A program written for SCGI or FastCGI will generally have one acceptor running in a loop. A `cgi_request` cannot be used with an acceptor, but an `acgi_request` will work fine: ie. only the first accept will succeed.
+A `basic_request_acceptor<>` is responsible for accepting requests. The following `typedefs` are provided for typical use:
+``
+acgi_acceptor // aCGI
+fcgi_acceptor // FastCGI
+scgi_acceptor // SCGI
+``
+
+Note: `cgi_request` cannot be used with an acceptor, but an `acgi_request` will work fine: ie. only the first accept will succeed. A program written for SCGI or FastCGI will generally have one acceptor running in a loop.
-Accepting requests is considered distinct to the [link __loading__ loading] stage for several reasons, the most significant of which is to allow for multiplexing protocols like FastCGI work with the library.
+Accepting requests is considered distinct to the [link __loading__ loading] stage for several reasons, the most significant of which is to allow for multiplexing protocols like FastCGI work with the other protocols.
-All you need do is create an `*_acceptor` by passing an instance of a __ProtocolService__ to its constructor. The following member functions are available (take xcgi to imply one of fcgi/scgi/acgi):
+A `basic_request_acceptor<>` takes an instance of a __ProtocolService__ in its constructor. The following member functions are available (take xcgi to imply one of fcgi/scgi/acgi):
[table
[[Function signature] [Purpose]]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -7,18 +7,22 @@
[section:loading Loading Requests]
-After a request has been accepted, it must also be 'loaded'. Before being loaded the request is in an undefined state and in general it is unsafe to try to do anything except read from/write to the client. For CGI, the request's constructor calls load implicitly (this is optional behaviour [footnote]), in most other situations, one of the following functions are used:
+After a request has been accepted, it must also be 'loaded'. Before being loaded the request is in an undefined state and in general it is unsafe to call any `meta_*` function. For CGI, the request's constructor calls load implicitly (this is optional behaviour [footnote]), in most other situations, one of the following functions are used:
[table
[[Function signature] [Purpose]]
[
[`void basic_request<>::load(bool parse_stdin = true)`]
- [Loads the request meta-data into internal `cgi::map`s.[br][br]If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, an exception is thrown.]
+ [Loads the request meta-data into internal `cgi::map`s.
+
+ If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, an exception is thrown.]
]
[
[`boost::system::error_code&
basic_request<>::load(boost::system::error_code& ec, bool parse_stdin = true)`]
- [Loads the request meta-data into internal `cgi::map`s.[br][br]If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, ec is set to the value of the error such that `!ec == false`.]
+ [Loads the request meta-data into internal `cgi::map`s.
+
+ If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, ec is set to the value of the error such that `!ec == false`.]
]
[
[`void basic_request<>::async_load(bool parse_stdin, Handler handler)`]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk 2007-08-18 10:40:33 EDT (Sat, 18 Aug 2007)
@@ -5,15 +5,18 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:meta_data Request Meta-data]
+[def __xss_footnote__ It is generally accepted that a CGI program should pay attention to where meta-data has come from.[footnote citations w.r.t. XSS and GET/POST/HTTP_COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where the source of the variable doesn't matter. For example, a language toggle (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.]
-[note
-A request [*must] be [link __loading__ loaded] before the meta-data can be accessed. The ['only] exception to this rule is calling `meta_env()` on CGI and aCGI request objects. These are (essentially) equivalent to a call to `::getenv()` and will always work. However, exploit this 'feature' cautiously as it will render a program unsuitable for use with the more scalable protocols on offer.
+
+[section:variables Using Request Variables]
+
+[warning
+A request [*must] be [link __loading__ loaded] before the meta-data can be accessed. The ['only] exception to this rule is calling `meta_env()` on CGI and aCGI request objects. These are (essentially) equivalent to a call to `::getenv()` and will always work. However, exploit this 'feature' cautiously as it won't work with FastCGI or SCGI requests.
]
-There are six member functions of `basic_request<>` that provide access to the meta-data associated to that request.
+There are six member functions of `basic_request<>` that provide access to the meta-variables associated to that request.
-[table Meta-data accessor functions
+[table Meta-variable accessor functions
[[Function signature] [Purpose]]
[
[`std::string meta_env(const std::string&)`]
@@ -25,11 +28,15 @@
]
[
[`std::string meta_post(const std::string&, bool greedy = true)`]
- [Takes the name of a __POST__ variable and returns the value associated with it (if any).[br][br] If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]
+ [Takes the name of a __POST__ variable and returns the value associated with it (if any).
+
+ If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]
]
[
[`std::string meta_form(const std::string&, bool greedy = true)`]
- [Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). Note that this will only search the type referred to by the environment variable `"REQUEST_METHOD"`, so it is generally safe to use.[br][br]If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]
+ [Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). Note that this will only search the type referred to by the environment variable `"REQUEST_METHOD"`, so it is generally safe to use.
+
+ If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]
]
[
[`std::string meta_cookie(const std::string& name)`]
@@ -37,12 +44,10 @@
]
[
[`std::string meta_var(const std::string& name, bool greedy = true)`]
- [Takes the name of [*any] meta-variable and returns the value associated with it (if any).[br][br] If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.]
- ]
-]
+ [Takes the name of [*any] meta-variable and returns the value associated with it (if any).[footnote __xss_footnote__]
-[warning
-It is generally accepted that a CGI program should pay attention to where meta-data has come from.[footnote citations w.r.t. XSS and GET/POST/HTTP_COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where the source of the variable doesn't matter. For example, a language toggle (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.
+ If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.]
+ ]
]
[/ should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
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