Item1333: add Foswiki::Func::getRequestObject and deprecate getCgiQuery

git-svn-id: http://svn.foswiki.org/trunk@3197 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

UnitTestContrib/test/unit/FuncTests.pm

@@ -906,7 +906,7 @@ sub test_setPreferences {
     Foswiki::Func::setPreferencesValue( "PSIBG", "KJHD" );
     $this->assert_str_equals( "KJHD",
         Foswiki::Func::getPreferencesValue("PSIBG") );
-    my $q = Foswiki::Func::getCgiQuery();
+    my $q = Foswiki::Func::getRequestObject();
 
     ####
     Foswiki::Func::saveTopicText( $this->{test_web},

core/lib/Foswiki/Func.pm

@@ -211,15 +211,17 @@ sub getExternalResource {
 
 =begin TML
 
----+++ getCgiQuery( ) -> $query
+---+++ getRequestObject( ) -> $query
 
-Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set
+Get the request object. This is a subclass of Foswiki::Request. The request
+object can be used to get the parameters passed to the request, either
+via CGI or on the command ine (depending on how the script was called).
 
-Return: =$query= CGI query object; or 0 if script is called as a shell script
+*Since:* 31 Mar 2009
 
 =cut
 
-sub getCgiQuery {
+sub getRequestObject {
     ASSERT($Foswiki::Plugins::SESSION) if DEBUG;
     return $Foswiki::Plugins::SESSION->{request};
 }
@@ -1623,6 +1625,8 @@ sub readTopicText {
 ---+++ getAttachmentList( $web, $topic ) -> @list
 Get a list of the attachments on the given topic.
 
+*Since:* 31 Mar 2009
+
 =cut
 
 sub getAttachmentList {
@@ -1921,7 +1925,7 @@ when the old parameters are restored. if you want to change any parameter
 values, you will need to do that in the current CGI query before redirecting
 e.g.
 <verbatim>
-my $query = Foswiki::Func::getCgiQuery();
+my $query = Foswiki::Func::getRequestObject();
 $query->param(-name => 'text', -value => 'Different text');
 Foswiki::Func::redirectCgiQuery(
   undef, Foswiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
@@ -2929,6 +2933,16 @@ sub getDataDir {
 
 sub getPubDir { return $Foswiki::cfg{PubDir}; }
 
+=begin TML
+
+---+++ getCgiQuery( ) -> $query
+
+*Deprecated* 31 Mar 2009 - use getRequestObject instead.
+
+=cut
+
+sub getCgiQuery { return getRequestObject(); }
+
 # Removed; it was never used
 sub checkDependencies {
     die