TWiki Enterprise Collaboration Platform

Update of /cvsroot/twiki/twiki/lib/TWiki
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16758/lib/TWiki

Modified Files:
	Func.pm 
Log Message:
put back the getGmTime func, with DEPRECATED marker.

also added a Since field to the pod for Func


Index: Func.pm
===================================================================
RCS file: /cvsroot/twiki/twiki/lib/TWiki/Func.pm,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -r1.17 -r1.18
*** Func.pm	26 Feb 2004 08:26:15 -0000	1.17
--- Func.pm	24 Mar 2004 12:42:17 -0000	1.18
***************
*** 55,58 ****
--- 55,59 ----
  | Parameter: =$key= | Session key |
  | Return: =$value= | Value associated with key; empty string if not set; undef if session plugin is not installed |
+ | Since: | 27 Jul 2001 |
  
  =cut
***************
*** 74,77 ****
--- 75,79 ----
  | Parameter: =$value= | Value associated with key |
  | Return: =$result= | ="1"= if success; undef if session plugin is not installed |
+ | Since: | 17 Aug 2001 |
  
  =cut
***************
*** 90,93 ****
--- 92,96 ----
  | Description: | Get the name of the skin, set by the =SKIN= preferences variable or the =skin= CGI parameter |
  | Return: =$skin= | Name of skin, e.g. ="gnu"=. Empty string if none |
+ | Since: | 29 Jul 2001 |
  
  =cut
***************
*** 105,108 ****
--- 108,112 ----
  | Description: | Get protocol, domain and optional port of script URL |
  | Return: =$host= | URL host, e.g. ="http://example.com:80"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 123,126 ****
--- 127,131 ----
  | Parameter: =$script= | Script name, e.g. ="view"= |
  | Return: =$url= | URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 139,142 ****
--- 144,148 ----
  | Description: | Get script URL path |
  | Return: =$path= | URL path of TWiki scripts, e.g. ="/cgi-bin"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 156,159 ****
--- 162,166 ----
  | Parameter: =$topic= | Topic name, e.g. ="WebNotify"= |
  | Return: =$url= | URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 176,179 ****
--- 183,187 ----
  | Parameter: =$param1= ... =$param4= | Parameter values for %<nop>PARAM1% ... %<nop>PARAM4% variables in template, optional |
  | Return: =$url= | URL, e.g. ="http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&amp;param1=joe"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 193,196 ****
--- 201,205 ----
  | Description: | Get pub URL path |
  | Return: =$path= | URL path of pub directory, e.g. ="/pub"= |
+ | Since: | 14 Jul 2001 |
  
  =cut
***************
*** 208,211 ****
--- 217,221 ----
  | Description: | Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set |
  | Return: =$query= | CGI query object; or 0 if script is called as a shell script |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 224,227 ****
--- 234,238 ----
  | Parameter: =$query= | CGI query object |
  | Return: | none |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 242,245 ****
--- 253,257 ----
  | Parameter: =$url= | URL to redirect to |
  | Return: | none, never returns |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 262,265 ****
--- 274,278 ----
  | Parameter: =$name= | Name, optional |
  | Return: =$value= | Extracted value |
+ | Since: | 7 Dec 2002 |
  
     * Example:
***************
*** 288,291 ****
--- 301,305 ----
  | Parameter: =$web= | Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics |
  | Return: =$value= | Preferences value; empty string if not set |
+ | Since: | 7 Dec 2002 |
  
     * Example for Plugin setting:
***************
*** 315,318 ****
--- 329,333 ----
  | Parameter: =$web= | Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics |
  | Return: =$value= | Preferences flag ="1"= (if set), or ="0"= (for preferences values ="off"=, ="no"= and ="0"=) |
+ | Since: | 7 Dec 2002 |
  
     * Example for Plugin setting:
***************
*** 336,339 ****
--- 351,355 ----
  | Description: | Get toolname as defined in TWiki.cfg |
  | Return: =$name= | Name of tool, e.g. ="TWiki"= |
+ | Since: | 27 Jul 2001 |
  
  =cut
***************
*** 351,354 ****
--- 367,371 ----
  | Description: | Get name of Main web as defined in TWiki.cfg |
  | Return: =$name= | Name, e.g. ="Main"= |
+ | Since: | 27 Jul 2001 |
  
  =cut
***************
*** 366,369 ****
--- 383,387 ----
  | Description: | Get name of TWiki documentation web as defined in TWiki.cfg |
  | Return: =$name= | Name, e.g. ="TWiki"= |
+ | Since: | 27 Jul 2001 |
  
  =cut
***************
*** 383,386 ****
--- 401,405 ----
  | Description: | Get default user name as defined in TWiki.cfg's =$defaultUserName= |
  | Return: =$loginName= | Default user name, e.g. ="guest"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 398,401 ****
--- 417,421 ----
  | Description: | Get Wiki name of logged in user |
  | Return: =$wikiName= | Wiki Name, e.g. ="JohnDoe"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 413,416 ****
--- 433,437 ----
  | Description: | Get Wiki name of logged in user with web prefix |
  | Return: =$wikiName= | Wiki Name, e.g. ="Main.JohnDoe"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 429,432 ****
--- 450,454 ----
  | Parameter: =$wikiName= | Wiki name, e.g. ="Main.JohnDoe"= or ="JohnDoe"= |
  | Return: =$loginName= | Login name of user, e.g. ="jdoe"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 447,450 ****
--- 469,473 ----
  | Parameter: =$dontAddWeb= | Do not add web prefix if ="1"= |
  | Return: =$wikiName= | Wiki name of user, e.g. ="Main.JohnDoe"= or ="JohnDoe"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 463,466 ****
--- 486,490 ----
  | Description: | Test if logged in user is a guest |
  | Return: =$flag= | ="1"= if yes, ="0"= if not |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 479,482 ****
--- 503,507 ----
  | Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
  | Return: =$flag= | ="1"= if yes, ="0"= if no |
+ | Since: | 27 Jul 2001 |
  
  =cut
***************
*** 500,503 ****
--- 525,529 ----
  | Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
  | Return: =$flag= | ="1"= if access may be granted, ="0"= if not |
+ | Since: | 27 Jul 2001 |
  
  =cut
***************
*** 519,522 ****
--- 545,549 ----
  | Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
  | Return: =$flag= | ="1"= if web exists, ="0"= if not |
+ | Since: | 14 Jul 2001 |
  
  =cut
***************
*** 537,540 ****
--- 564,568 ----
  | Parameter: =$topic= | Topic name, required, e.g. ="TokyoOffice"=, or ="Main.TokyoOffice"= |
  | Return: =$flag= | ="1"= if topic exists, ="0"= if not |
+ | Since: | 14 Jul 2001 |
  
  =cut
***************
*** 556,559 ****
--- 584,588 ----
  | Return: =( $date, $loginName, $rev )= | List with: ( last update date, login name of last user, minor part of top revision number ), e.g. =( 12345 "phoeny", "5" )= |
  | | $date is in epochSeconds |
+ | Since: | 29 Jul 2001 |
  
  =cut
***************
*** 574,577 ****
--- 603,607 ----
  | Parameter: =$topic= | Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"= |
  | Return: =( $oopsUrl, $loginName, $unlockTime )= | The =$oopsUrl= for calling redirectCgiQuery(), user's =$loginName=, and estimated =$unlockTime= in minutes. The =$oopsUrl= and =$loginName= is empty if topic has no edit lock. |
+ | Since: | 31 Dec 2002 |
  
  =cut
***************
*** 602,605 ****
--- 632,636 ----
  | Parameter: =$lock= | Set to =1= to lock topic, =0= to unlock |
  | Return: =$oopsUrl= | Empty string if OK; the =$oopsUrl= for calling redirectCgiQuery() in case lock is already taken when trying to lock topic |
+ | Since: | 31 Dec 2002 |
  
  =cut
***************
*** 627,630 ****
--- 658,662 ----
  | Parameter: =$ignorePermissions=  | Set to ="1"= if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission |
  | Return: =$text= | Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error |
+ | Since: | 31 Dec 2002 |
  
  =cut
***************
*** 654,657 ****
--- 686,690 ----
  | Parameter: =$dontNotify= | Set to ="1"= if not to notify users of the change |
  | Return: =$oopsUrl= | Empty string if OK; the =$oopsUrl= for calling redirectCgiQuery() in case of error |
+ | Since: | 31 Dec 2002 |
  
     * Example: <br />
***************
*** 716,719 ****
--- 749,753 ----
  | Description: | Get list of all public webs, e.g. all webs that do not have the =NOSEARCHALL= flag set in the WebPreferences |
  | Return: =@webs= | List of all public webs, e.g. =( "Main",  "Know", "TWiki" )= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 732,735 ****
--- 766,770 ----
  | Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
  | Return: =@topics= | Topic list, e.g. =( "WebChanges",  "WebHome", "WebIndex", "WebNotify" )= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 753,756 ****
--- 788,792 ----
  | Parameter: =$web= | Web name, optional, e.g. ="Main"=. The current web is taken if missing |
  | Return: =$text= | Expanded text, e.g. ="Current user is <nop>TWikiGuest"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 771,774 ****
--- 807,811 ----
  | Parameter: =$web= | Web name, optional, e.g. ="Main"=. The current web is taken if missing |
  | Return: =$text= | XHTML text, e.g. ="&lt;b>bold&lt;/b> and &lt;code>fixed font&lt;/code>"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 793,796 ****
--- 830,834 ----
  | Parameter: =$createLink= | Set to ="1"= to add question linked mark after topic name if topic does not exist;<br /> set to ="0"= to suppress link for non-existing topics |
  | Return: =$text= | XHTML anchor, e.g. ="&lt;a href="/cgi-bin/view/Main/WebNotify#Jump">notify&lt;/a>"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 818,822 ****
  ---+++ formatTime( $time, $format, $timezone ) ==> $text
  
! | Description: | Format the time int seconds into the desired time string |
  | Parameter: =$time= | Time in epoc seconds |
  | Parameter: =$format= | Format type, optional. Default e.g. ="31 Dec 2002 - 19:30"=, can be ="iso"= (e.g. ="2002-12-31T19:30Z"=), ="rcs"= (e.g. ="2001/12/31 23:59:59"=, ="http"= for HTTP header format (e.g. ="Thu, 23 Jul 1998 07:21:56 GMT"=) |
--- 856,860 ----
  ---+++ formatTime( $time, $format, $timezone ) ==> $text
  
! | Description: | Format the time in seconds into the desired time string |
  | Parameter: =$time= | Time in epoc seconds |
  | Parameter: =$format= | Format type, optional. Default e.g. ="31 Dec 2002 - 19:30"=, can be ="iso"= (e.g. ="2002-12-31T19:30Z"=), ="rcs"= (e.g. ="2001/12/31 23:59:59"=, ="http"= for HTTP header format (e.g. ="Thu, 23 Jul 1998 07:21:56 GMT"=) |
***************
*** 824,827 ****
--- 862,866 ----
  | Return: =$text= | Formatted time string |
  | Note: | if you used the removed formatGmTime, add a third parameter "gmtime" |
+ | Since: | 26 Feb 2004 |
  
  =cut
***************
*** 829,833 ****
  sub formatTime
  {
! #   my $epSecs = @_;
      return &TWiki::formatTime( @_ );
  }
--- 868,872 ----
  sub formatTime
  {
! #   my ( $epSecs, $format, $timezone ) = @_;
      return &TWiki::formatTime( @_ );
  }
***************
*** 836,839 ****
--- 875,902 ----
  =pod
  
+ ---+++ formatGmTime( $time, $format ) ==> $text
+ 
+ *WARNING: DO _NOT_USE THIS FUNCTION - IT IS DEPRECATED AND WILL BE REMOVED IN A FUTURE VERSION*
+ | Description: | Format the time to GM time |
+ | Parameter: =$time= | Time in epoc seconds |
+ | Parameter: =$format= | Format type, optional. Default e.g. ="31 Dec 2002 - 19:30"=, can be ="iso"= (e.g. ="2002-12-31T19:30Z"=), ="rcs"= (e.g. ="2001/12/31 23:59:59"=, ="http"= for HTTP header format (e.g. ="Thu, 23 Jul 1998 07:21:56 GMT"=) |
+ | Return: =$text= | Formatted time string |
+ | Since: | 7 Dec 2002 |
+ 
+ =cut
+ # -------------------------
+ sub formatGmTime
+ {
+ #   my ( $epSecs, $format ) = @_;
+ 
+     writeWarning( "DEPRECATED use of Func::formatGmTime" );
+ 
+     return &formatTime( @_, "gmtime" );
+ }
+ 
+ 
+ # =========================
+ =pod
+ 
  ---++ Functions: File I/O
  
***************
*** 842,845 ****
--- 905,909 ----
  | Description: | Get data directory (topic file root) |
  | Return: =$dir= | Data directory, e.g. ="/twiki/data"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 857,860 ****
--- 921,925 ----
  | Description: | Get pub directory (file attachment root). Attachments are in =$dir/Web/TopicName= |
  | Return: =$dir= | Pub directory, e.g. ="/htdocs/twiki/pub"= |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 866,879 ****
  
  # =========================
! # NOTE: The following function is deprecated and should not be used. Use readTopicText() instead
! # ---+++ readTopic( $web, $topic ) ==> ( $meta, $text )
! # | Description: | Read topic text and meta data, regardless of access permissions. |
! # | Parameter: =$web= | Web name, required, e.g. ="Main"= |
! # | Parameter: =$topic= | Topic name, required, e.g. ="TokyoOffice"= |
! # | Return: =( $meta, $text )= | Meta data object and topic text |
  # -------------------------
  sub readTopic
  {
  #   my( $web, $topic ) = @_;
      return &TWiki::Store::readTopic( @_ );
  }
--- 931,954 ----
  
  # =========================
! =pod
! 
! ---+++ readTopic( $web, $topic ) ==> ( $meta, $text )
! 
! *WARNING: DO _NOT_USE THIS FUNCTION - IT IS DEPRECATED AND WILL BE REMOVED IN A FUTURE VERSION*
! NOTE: The following function is deprecated and should not be used. Use readTopicText() instead
! | Description: | Read topic text and meta data, regardless of access permissions. |
! | Parameter: =$web= | Web name, required, e.g. ="Main"= |
! | Parameter: =$topic= | Topic name, required, e.g. ="TokyoOffice"= |
! | Return: =( $meta, $text )= | Meta data object and topic text |
! | Since: | 7 Dec 2002 |
! 
! =cut
  # -------------------------
  sub readTopic
  {
  #   my( $web, $topic ) = @_;
+ 
+     writeWarning( "DEPRECATED use of Func::readTopic" );
+ 
      return &TWiki::Store::readTopic( @_ );
  }
***************
*** 888,891 ****
--- 963,967 ----
  | Parameter: =$skin= | Skin name, optional, e.g. ="print"= |
  | Return: =$text= | Template text |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 905,908 ****
--- 981,985 ----
  | Parameter: =$filename= | Full path name of file |
  | Return: =$text= | Content of file |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 923,926 ****
--- 1000,1004 ----
  | Parameter: =$text= | Text to save |
  | Return: | none |
+ | Since: | 7 Dec 2002 |
  
  =cut
***************
*** 940,943 ****
--- 1018,1022 ----
  | Parameter: =$text= | Text to write; timestamp gets added |
  | Return: | none |
+ | Since: | 16 Feb 2004 |
  
  =cut
***************
*** 957,960 ****
--- 1036,1040 ----
  | Parameter: =$text= | Text to write; timestamp gets added |
  | Return: | none |
+ | Since: | 16 Feb 2004 |
  
  =cut
***************
*** 977,980 ****
--- 1057,1061 ----
  | Return: | String or precompiled regular expression matching as described below |
  | Introduced: | VERSION 1.020 (Feb 2004) |
+ | Since: | 9 Feb 2004 |
  
  __Notes:__ TWiki internally precompiles several regular expressions to represent various string entities