[Boost-commit] svn:boost r38754 - in sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide: . tutorial

From: lists.drrngrvy_at_[hidden]
Date: 2007-08-18 11:13:53

Author: drrngrvy
Date: 2007-08-18 11:13:49 EDT (Sat, 18 Aug 2007)
New Revision: 38754
URL: http://svn.boost.org/trac/boost/changeset/38754

Log:
Fixes from last update.
Added:
   sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/10_min_intro.cpp   (contents, props changed)
   sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_variables.qbk   (contents, props changed)
   sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/quickstart.qbk   (contents, props changed)
   sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/requests.qbk   (contents, props changed)
Text files modified: 
   sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk |     2 ++                                      
   1 files changed, 2 insertions(+), 0 deletions(-)

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 11:13:49 EDT (Sat, 18 Aug 2007)
@@ -35,6 +35,8 @@
 
 [include:accepting tutorial/accepting.qbk]
 
+[include:loading tutorial/loading.qbk]
+
 [include:wrapping_up wrapping_up.qbk]
 
 

Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/10_min_intro.cpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/10_min_intro.cpp	2007-08-18 11:13:49 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,56 @@
+#include <string>
+#include <boost/cgi/cgi.hpp>
+using namespace cgi;
+
+//[main
+/*` It is assumed you have included <boost/cgi/cgi.hpp> and are `using namespace cgi`. */
+int main(int,char**)
+{
+  request req;
+
+  /*` At this point, the environment variables are accessible. This includes cookie and form variables too, which by default are all parsed.
+
+ The `reply` class provides a streaming interface for writing replies. You ['can] write to the request object directly, but for now we're going to just use the `reply`, which is simpler. Writing to a `reply` is buffered - whereas writing to the request directly isn't - so if an error occurs, you can simply `clear()` the reply and send an error message, which is much cleaner than sending half a reply to the client, followed by "... Sorry, I just broke!".
+  */
+  reply rep;
+
+  /*` Say now you want to check if the user has a cookie, "user_name", set. We get at it like this: */
+  std::string user_name( req.meta_cookie("user_name") );
+
+  /*` If it's set, we'll be polite and say hello. */
+  if (!user_name.empty())
+  {
+    rep<< "Hello there, " << user_name << ". How are you?";
+
+    /*` That's all we want to say for now, so just send this back and quit. */
+    rep.send(req);
+
+    return 0;
+  }
+
+  /*` If the cookie isn't set, we will check if the user has posted a __GET__/__POST__ form with their name. */
+  user_name = req.meta_form("user_name");
+
+  if (!user_name.empty())
+  {
+    /*` If they have told us their name, we should set a cookie so we remember it next time. Then we can say hello and exit. There are two ways to set a cookie: either directly using `req.set_cookie("user_name", user_name)` or the method below. Again, the request object isn't buffered, so we are going to keep using the `reply` in case something breaks and we end up not wanting to set the cookie. The cookie we set below will expire when the user closes their browser.
+    */
+    rep<< cookie("user_name", user_name)
+       << "Hello there, " << user_name << ". You're new around here.";
+
+    rep.send(req);
+  }
+
+  /*` If we have no idea who they are, we'll send a form asking them for their name. The default `"Content-type"` header is `"text/plain"`, we'll change this to `"text/html"` so the user's browser will display the form. You can do this using `req.set_header("Content-type", "text/html")` or `rep<< header("Content-type", "text/html")`. Since writing with raw strings is error-prone, the shortcut below is available. */
+  rep<< content_type("text/html")
+     << "Hello there. What's your name?" "<p />"
+        "<form method='POST'>"
+        "<input type='text' name='user_name' />"
+        "<input type='submit' />";
+
+  rep.send(req);
+
+  /*` And that's all we want to do for now, so we can close the program. */
+  return 0;
+}
+//]

Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_variables.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_variables.qbk	2007-08-18 11:13:49 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,55 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / 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)
+ /]
+
+[def __xss_footnote__ It is generally accepted that a CGI program should pay attention to where meta-data has come from (eg. [@http://www.google.com/search?q=XSS XSS]). 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.]
+
+
+[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 [@http://tinyurl.com/3cqrd5 `::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-variables associated to that request.
+
+[table Meta-variable accessor functions
+  [[Function signature] [Purpose]]
+  [
+   [`std::string meta_env(const std::string&)`]
+   [Takes the name of the environment variable wanted and returns the value associated with it.]
+  ]
+  [
+   [`std::string meta_get(const std::string&)`]
+   [Takes the name of the __GET__ variable and returns the value associated with it (if any).]
+  ]
+  [
+   [`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).
+
+    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.
+
+   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)`]
+   [Takes the name of the cookie variable and returns the value associated with it (if any).]
+  ]
+  [
+   [`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).[footnote __xss_footnote__]
+
+   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`?]
+
+[endsect]

Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/quickstart.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/quickstart.qbk	2007-08-18 11:13:49 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,22 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / 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)
+ /]
+
+[section:quickstart Quickstart: 'Scripting']
+
+CGI is a simple protocol: you read __POST__ data from `stdin`, other data from environment variables (ie. via [@http://tinyurl.com/3cqrd5 `::getenv()`]) and write your output to `stdout`. This section introduces the '__CGI__' interface, which offers a subset of the library's functionality. This is not essential reading, but it is recommended that you at least scan through it as the techniques still apply to the rest of the library. Afterwards, if you wish to scale your program to __FastCGI__ or __SCGI__, or just provide a custom logging layer or asynchronous read/writes (with vanilla CGI) then the rest of the tutorial will show you how to.
+
+[h3 10 minute intro]
+
+The following example can be found [@../../src/user_guide/tutorial/10_min_intro.cpp here].
+
+[import 10_min_intro.cpp]
+
+[main]
+
+That's all quite simple, right?
+
+[endsect]

Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/requests.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/requests.qbk	2007-08-18 11:13:49 EDT (Sat, 18 Aug 2007)
@@ -0,0 +1,24 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / 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)
+ /]
+
+[section Request Objects]
+
+The class [classref cgi::basic_request `cgi::basic_request<>`] is the main entry point to the library. The following `typedef`s are provided for typical usage:
+``
+cgi_request  // CGI
+acgi_request // aCGI
+fcgi_request // FastCGI
+scgi_request // SCGI
+``
+
+The `cgi_request` is a bit different to the other types, in that it doesn't need to be constructed with a __ProtocolService__. This simplification makes it ideal for, and its use is detailed in, the  '[link __scripting__ scripting]' quickstart. The other request types, however, have a distinct advantage in that they provide you with asynchronous functions.
+
+[include:meta_data meta_variables.qbk]
+
+[/link ]
+
+[endsect]