Menu
▾
▴
[TWiki-Dev] CVS: twiki/lib/TWiki Func.pm,1.17,1.18
|
From: sven d. <sv...@us...> - 2004-03-24 12:52:55
|
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&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. ="<b>bold</b> and <code>fixed font</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. ="<a href="/cgi-bin/view/Main/WebNotify#Jump">notify</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 |