Ignore:
Timestamp:
11/28/08 13:33:03 (3 years ago)
Author:
CrawfordCurrie
Message:

Item175: Added Foswiki::Time to published APIs and deprecated the duplicates in Foswiki::Func, cleaned up versioning of published APIs and added VERSION to each. Item295: changed =pod to =begin TML

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/core/lib/Foswiki/Func.pm

    r966 r1041  
    11# See bottom of file for license and copyright information 
    22 
    3 =pod 
     3=begin TML 
    44 
    55---+ package Foswiki::Func 
    66 
    7 <!-- STARTINCLUDE required for huge CompleteDocumentation topic --> 
    8 %STARTINCLUDE% 
    9  
    10 _Official Foswiki interface for Plugin developers_ 
    11  
    12 This module defines the interfaces that [[%SYSTEMWEB%.Plugins][Plugins]] 
     7_Interface for Foswiki extensions developers_ 
     8 
     9This module defines the main interfaces that extensions 
    1310can use to interact with the Foswiki engine and content. 
    1411 
    … …  
    1613and starter documentation on how to write a Plugin. 
    1714 
    18 Plugins should *only* use functions described here. If you use 
    19 functions in other Foswiki libraries you might create a security hole and 
     15Plugins should *only* call methods in packages documented in 
     16System.DevelopingPlugins. If you use 
     17functions in other Foswiki libraries you risk creating a security hole, and 
    2018you will probably need to change your plugin when you upgrade Foswiki. 
    2119 
    22 Deprecated functions will still work in older code, though they should 
     20%TOC% 
     21 
     22API version $Date$ (revision $Rev$) 
     23 
     24*Since* _date_ indicates where functions or parameters have been added since 
     25the baseline of the API (TWiki release 4.2.3). The _date_ indicates the 
     26earliest date of a Foswiki release that will support that function or 
     27parameter. 
     28 
     29*Deprecated* _date_ indicates where a function or parameters has been 
     30[[http://en.wikipedia.org/wiki/Deprecation][deprecated]]. Deprecated 
     31functions will still work, though they should 
    2332_not_ be called in new plugins and should be replaced in older plugins 
    24 as soon as possible. 
    25  
    26 The compatibility history of this module is given by the VERSION number 
    27 of the Foswiki::Plugins module. 
    28  
    29 Notes on use of =$Foswiki::Plugins::VERSION=: 
    30    * If the *major* version (e.g. =1.=) is the same then any plugin coded 
    31      to use any *earlier* revision of the =1.= API will still work. No 
    32      function has been removed from the interface, nor has any API published 
    33      in that version changed in such a way as to *require* plugins to be 
    34      recoded. 
    35    * If the *minor* version (e.g. =1.1.=) is incremented there may be changes 
    36      in the API that may help improve the coding of some plugins - for 
    37      example, new interfaces giving access to previously hidden core functions. 
    38      In addition, *deprecation* of functions in the interface trigger a minor 
    39      version increment. Note that deprecated functions are not _removed_, they 
    40      are merely frozen, and plugin authors are recommended to stop using them. 
    41    * Any additional digits in the version number relate to minor changes, such 
    42      as the addition of parameters to the existing functions, or addition of 
    43      utility functions that are unlikely to require significant changes to 
    44      existing plugins. 
    45    * =$Foswiki::Plugins::VERSION= also applies to the plugin handlers. The 
    46      handlers are documented in the !EmptyPlugin, and that module indicates 
    47      what version of =Foswiki::Plugins::VERSION= it relates to. 
    48  
    49 =cut 
     33as soon as possible. Deprecated parameters are simply ignored in Foswiki 
     34releases after _date_. 
     35 
     36*Until* _date_ indicates where a function or parameter has been removed. 
     37The _date_ indicates the latest date at which Foswiki releases still supported 
     38the function or parameter. 
     39 
     40=cut 
     41 
     42# THIS PACKAGE IS PART OF THE PUBLISHED API USED BY EXTENSION AUTHORS. 
     43# DO NOT CHANGE THE EXISTING APIS (well thought out extensions are OK) 
     44# AND ENSURE ALL POD DOCUMENTATION IS COMPLETE AND ACCURATE. 
     45# 
     46# Deprecated functions should not be removed, but should be moved to to the 
     47# deprecated functions section. 
    5048 
    5149package Foswiki::Func; 
    … …  
    5856require Foswiki::Plugins; 
    5957 
    60 =pod 
     58=begin TML 
    6159 
    6260---++ Environment 
    … …  
    6462=cut 
    6563 
    66 =pod 
     64=begin TML 
    6765 
    6866---+++ getSkin( ) -> $skin 
    … …  
    7270Return: =$skin= Comma-separated list of skins, e.g. ='gnu,tartan'=. Empty string if none. 
    7371 
    74 *Since:* Foswiki::Plugins::VERSION 1.000 (29 Jul 2001) 
    75  
    7672=cut 
    7773 
    … …  
    8278} 
    8379 
    84 =pod 
     80=begin TML 
    8581 
    8682---+++ getUrlHost( ) -> $host 
    … …  
    9086Return: =$host= URL host, e.g. ="http://example.com:80"= 
    9187 
    92 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    93  
    9488=cut 
    9589 
    … …  
    10094} 
    10195 
    102 =pod 
     96=begin TML 
    10397 
    10498---+++ getScriptUrl( $web, $topic, $script, ... ) -> $url 
    … …  
    112106Return: =$url=       URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"= 
    113107 
    114 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    115  
    116108=cut 
    117109 
    … …  
    126118} 
    127119 
    128 =pod 
     120=begin TML 
    129121 
    130122---+++ getViewUrl( $web, $topic ) -> $url 
    … …  
    135127Return: =$url=      URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"= 
    136128 
    137 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    138  
    139129=cut 
    140130 
    … …  
    147137} 
    148138 
    149 =pod 
     139=begin TML 
    150140 
    151141---+++ getPubUrlPath( ) -> $path 
    … …  
    154144 
    155145Return: =$path= URL path of pub directory, e.g. ="/pub"= 
    156  
    157 *Since:* Foswiki::Plugins::VERSION 1.000 (14 Jul 2001) 
    158146 
    159147=cut 
    … …  
    163151} 
    164152 
    165 =pod 
     153=begin TML 
    166154 
    167155---+++ getExternalResource( $url ) -> $response 
    … …  
    210198</verbatim> 
    211199 
    212 *Since:* Foswiki::Plugins::VERSION 1.2 
    213  
    214200=cut 
    215201 
    … …  
    222208} 
    223209 
    224 =pod 
     210=begin TML 
    225211 
    226212---+++ getCgiQuery( ) -> $query 
    … …  
    230216Return: =$query= CGI query object; or 0 if script is called as a shell script 
    231217 
    232 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    233  
    234218=cut 
    235219 
    … …  
    239223} 
    240224 
    241 =pod 
     225=begin TML 
    242226 
    243227---+++ getSessionKeys() -> @keys 
    … …  
    246230Session keys are stored and retrieved using =setSessionValue= and 
    247231=getSessionValue=. 
    248  
    249 *Since:* Foswiki::Plugins::VERSION 1.2 
    250232 
    251233=cut 
    … …  
    258240} 
    259241 
    260 =pod 
     242=begin TML 
    261243 
    262244---+++ getSessionValue( $key ) -> $value 
    … …  
    266248Return: =$value=  Value associated with key; empty string if not set 
    267249 
    268 *Since:* Foswiki::Plugins::VERSION 1.000 (27 Feb 200) 
    269  
    270250=cut 
    271251 
    … …  
    279259} 
    280260 
    281 =pod 
     261=begin TML 
    282262 
    283263---+++ setSessionValue( $key, $value ) -> $boolean 
    … …  
    288268Return: true if function succeeded 
    289269 
    290 *Since:* Foswiki::Plugins::VERSION 1.000 (17 Aug 2001) 
    291  
    292270=cut 
    293271 
    … …  
    300278} 
    301279 
    302 =pod 
     280=begin TML 
    303281 
    304282---+++ clearSessionValue( $key ) -> $boolean 
    … …  
    309287Return: true if the session value was cleared 
    310288 
    311 *Since:* Foswiki::Plugins::VERSION 1.1 
    312  
    313289=cut 
    314290 
    … …  
    320296} 
    321297 
    322 =pod 
     298=begin TML 
    323299 
    324300---+++ getContext() -> \%hash 
    … …  
    365341working, the context ID 'FirstPlugin' will be set. 
    366342 
    367 *Since:* Foswiki::Plugins::VERSION 1.1 
    368  
    369343=cut 
    370344 
    … …  
    374348} 
    375349 
    376 =pod 
     350=begin TML 
    377351 
    378352---+++ pushTopicContext($web, $topic) 
    … …  
    391365global variables to remember the web and topic in =initPlugin=, then those 
    392366values will be unchanged. 
    393  
    394 *Since:* Foswiki::Plugins::VERSION 1.2 
    395367 
    396368=cut 
    … …  
    415387} 
    416388 
    417 =pod 
     389=begin TML 
    418390 
    419391---+++ popTopicContext() 
    … …  
    421393Returns the Foswiki context to the state it was in before the 
    422394=pushTopicContext= was called. 
    423  
    424 *Since:* Foswiki::Plugins::VERSION 1.2 
    425395 
    426396=cut 
    … …  
    436406} 
    437407 
    438 =pod 
     408=begin TML 
    439409 
    440410---++ Preferences 
    … …  
    442412=cut 
    443413 
    444 =pod 
     414=begin TML 
    445415 
    446416---+++ getPreferencesValue( $key, $web ) -> $value 
    … …  
    450420   * =$web= - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics 
    451421Return: =$value=  Preferences value; empty string if not set 
    452  
    453 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    454422 
    455423   * Example for Plugin setting: 
    … …  
    479447} 
    480448 
    481 =pod 
     449=begin TML 
    482450 
    483451---+++ getPluginPreferencesValue( $key ) -> $value 
    … …  
    488456 
    489457__Note__: This function will will *only* work when called from the Plugin.pm file itself. it *will not work* if called from a sub-package (e.g. Foswiki::Plugins::MyPlugin::MyModule) 
    490  
    491 *Since:* Foswiki::Plugins::VERSION 1.021 (27 Mar 2004) 
    492458 
    493459*NOTE:* If =$NO_PREFS_IN_TOPIC= is enabled in the plugin, then 
    … …  
    505471} 
    506472 
    507 =pod 
     473=begin TML 
    508474 
    509475---+++ getPreferencesFlag( $key, $web ) -> $value 
    … …  
    514480Return: =$value=  Preferences flag ='1'= (if set), or ="0"= (for preferences values ="off"=, ="no"= and ="0"=) 
    515481 
    516 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    517  
    518482   * Example for Plugin setting: 
    519483      * MyPlugin topic has: =* Set SHOWHELP = off= 
    … …  
    533497} 
    534498 
    535 =pod 
     499=begin TML 
    536500 
    537501---+++ getPluginPreferencesFlag( $key ) -> $boolean 
    … …  
    542506 
    543507__Note__: This function will will *only* work when called from the Plugin.pm file itself. it *will not work* if called from a sub-package (e.g. Foswiki::Plugins::MyPlugin::MyModule) 
    544  
    545 *Since:* Foswiki::Plugins::VERSION 1.021 (27 Mar 2004) 
    546508 
    547509*NOTE:* If =$NO_PREFS_IN_TOPIC= is enabled in the plugin, then 
    … …  
    557519} 
    558520 
    559 =pod 
     521=begin TML 
    560522 
    561523---+++ setPreferencesValue($name, $val) 
    … …  
    576538} 
    577539 
    578 =pod 
     540=begin TML 
    579541 
    580542---++ User Handling and Access Control 
    … …  
    584546Return: =$loginName= Default user name, e.g. ='guest'= 
    585547 
    586 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    587  
    588548=cut 
    589549 
    … …  
    592552} 
    593553 
    594 =pod 
     554=begin TML 
    595555 
    596556---+++ getCanonicalUserID( $user ) -> $cUID 
    … …  
    608568registered users. This may be autogenerated for an authenticated but 
    609569unregistered user. 
    610  
    611 *Since:* Foswiki::Plugins::VERSION 1.2 
    612570 
    613571=cut 
    … …  
    633591} 
    634592 
    635 =pod 
     593=begin TML 
    636594 
    637595---+++ getWikiName( $user ) -> $wikiName 
    … …  
    643601 
    644602Return: =$wikiName= Wiki Name, e.g. ='JohnDoe'= 
    645  
    646 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    647603 
    648604=cut 
    … …  
    660616} 
    661617 
    662 =pod  
     618=begin TML  
    663619  
    664620---+++ getWikiUserName( $user ) -> $wikiName 
    … …  
    670626 
    671627Return: =$wikiName= Wiki Name, e.g. ="Main.JohnDoe"= 
    672  
    673 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    674628 
    675629=cut 
    … …  
    687641} 
    688642 
    689 =pod 
     643=begin TML 
    690644 
    691645---+++ wikiToUserName( $id ) -> $loginName 
    692646Translate a Wiki name to a login name. 
    693647   * =$id= - Wiki name, e.g. ='Main.JohnDoe'= or ='JohnDoe'=. 
    694      Since TWiki 4.2.1, $id may also be a login name. This will normally 
     648     $id may also be a login name. This will normally 
    695649     be transparent, but should be borne in mind if you have login names 
    696650     that are also legal wiki names. 
    … …  
    704658 
    705659returns undef if the WikiName is not found. 
    706  
    707 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    708660 
    709661=cut  
    … …  
    723675} 
    724676 
    725 =pod 
     677=begin TML 
    726678 
    727679---+++ userToWikiName( $loginName, $dontAddWeb ) -> $wikiName 
    … …  
    735687userToWikiName will always return a name. If the user does not 
    736688exist in the mapping, the $loginName parameter is returned. (backward compatibility) 
    737  
    738 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    739689 
    740690=cut 
    … …  
    755705} 
    756706 
    757 =pod 
     707=begin TML 
    758708 
    759709---+++ emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames 
    … …  
    763713registered address. Since several users could register with the same email 
    764714address, this returns a list of wikinames rather than a single wikiname. 
    765  
    766 *Since:* Foswiki::Plugins::VERSION 1.2 
    767715 
    768716=cut 
    … …  
    789737} 
    790738 
    791 =pod 
     739=begin TML 
    792740 
    793741---+++ wikinameToEmails( $user ) -> @emails 
    … …  
    797745 
    798746$user may also be a login name, or the name of a group. 
    799  
    800 *Since:* Foswiki::Plugins::VERSION 1.2 
    801747 
    802748=cut 
    … …  
    825771} 
    826772 
    827 =pod 
     773=begin TML 
    828774 
    829775---+++ isGuest( ) -> $boolean 
    830776 
    831777Test if logged in user is a guest (WikiGuest) 
    832  
    833 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    834778 
    835779=cut 
    … …  
    841785} 
    842786 
    843 =pod 
     787=begin TML 
    844788 
    845789---+++ isAnAdmin( $id ) -> $boolean 
    … …  
    848792the currently logged-in user is assumed. 
    849793   * $id can be either a login name or a WikiName 
    850  
    851 *Since:* Foswiki::Plugins::VERSION 1.2 
    852794 
    853795=cut 
    … …  
    859801} 
    860802 
    861 =pod 
     803=begin TML 
    862804 
    863805---+++ isGroupMember( $group, $id ) -> $boolean 
    … …  
    872814 
    873815   * $id can be a login name or a WikiName 
    874  
    875 *Since:* Foswiki::Plugins::VERSION 1.2 
    876816 
    877817=cut 
    … …  
    894834} 
    895835 
    896 =pod 
     836=begin TML 
    897837 
    898838---+++ eachUser() -> $iterator 
    … …  
    910850 
    911851*WARNING* on large sites, this could be a long list! 
    912  
    913 *Since:* Foswiki::Plugins::VERSION 1.2 
    914852 
    915853=cut 
    … …  
    923861} 
    924862 
    925 =pod 
     863=begin TML 
    926864 
    927865---+++ eachMembership($id) -> $iterator 
    … …  
    929867     If =$id= is =undef=, defaults to the currently logged-in user. 
    930868Get an iterator over the names of all groups that the user is a member of. 
    931  
    932 *Since:* Foswiki::Plugins::VERSION 1.2 
    933869 
    934870=cut 
    … …  
    950886} 
    951887 
    952 =pod 
     888=begin TML 
    953889 
    954890---+++ eachGroup() -> $iterator 
    … …  
    966902*WARNING* on large sites, this could be a long list! 
    967903 
    968 *Since:* Foswiki::Plugins::VERSION 1.2 
    969  
    970904=cut 
    971905 
    … …  
    976910} 
    977911 
    978 =pod 
     912=begin TML 
    979913 
    980914---+++ isGroup( $group ) -> $boolean 
    … …  
    990924} 
    991925 
    992 =pod 
     926=begin TML 
    993927 
    994928---+++ eachGroupMember($group) -> $iterator 
    … …  
    1006940 
    1007941*WARNING* on large sites, this could be a long list! 
    1008  
    1009 *Since:* Foswiki::Plugins::VERSION 1.2 
    1010942 
    1011943=cut 
    … …  
    1023955} 
    1024956 
    1025 =pod 
     957=begin TML 
    1026958 
    1027959---+++ checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -> $boolean 
    … …  
    1057989in =ThatWeb.ThisTopic=, then a call to =checkAccessPermissions('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)= will return =true=. 
    1058990 
    1059 *Since:* Foswiki::Plugins::VERSION 1.000 (27 Feb 2001) 
    1060  
    1061991=cut 
    1062992 
    … …  
    10721002} 
    10731003 
    1074 =pod 
     1004=begin TML 
    10751005 
    10761006---++ Webs, Topics and Attachments 
    … …  
    10781008=cut 
    10791009 
    1080 =pod 
     1010=begin TML 
    10811011 
    10821012---+++ getListOfWebs( $filter [, $web] ) -> @webs 
    … …  
    10981028</verbatim> 
    10991029 
    1100 *Since:* Foswiki::Plugins::VERSION 1.1 
    1101  
    11021030=cut 
    11031031 
    … …  
    11071035} 
    11081036 
    1109 =pod 
     1037=begin TML 
    11101038 
    11111039---+++ webExists( $web ) -> $boolean 
    … …  
    11141042   * =$web= - Web name, required, e.g. ='Sandbox'= 
    11151043 
    1116 *Since:* Foswiki::Plugins::VERSION 1.000 (14 Jul 2001) 
    1117  
    11181044=cut 
    11191045 
    … …  
    11251051} 
    11261052 
    1127 =pod 
     1053=begin TML 
    11281054 
    11291055---+++ createWeb( $newWeb, $baseWeb, $opts ) 
    … …  
    11511077</verbatim> 
    11521078 
    1153 *Since:* Foswiki::Plugins::VERSION 1.1 
    1154  
    11551079=cut 
    11561080 
    … …  
    11611085} 
    11621086 
    1163 =pod 
     1087=begin TML 
    11641088 
    11651089---+++ moveWeb( $oldName, $newName ) 
    … …  
    11891113</verbatim> 
    11901114 
    1191 *Since:* Foswiki::Plugins::VERSION 1.1 
    1192  
    11931115=cut 
    11941116 
    … …  
    12001122} 
    12011123 
    1202 =pod 
     1124=begin TML 
    12031125 
    12041126---+++ eachChangeSince($web, $time) -> $iterator 
    … …  
    12371159} 
    12381160 
    1239 =pod 
     1161=begin TML 
    12401162 
    12411163---+++ getTopicList( $web ) -> @topics 
    … …  
    12451167Return: =@topics= Topic list, e.g. =( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )= 
    12461168 
    1247 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    1248  
    12491169=cut 
    12501170 
    … …  
    12561176} 
    12571177 
    1258 =pod 
     1178=begin TML 
    12591179 
    12601180---+++ topicExists( $web, $topic ) -> $boolean 
    … …  
    12681188To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty. 
    12691189 
    1270 *Since:* Foswiki::Plugins::VERSION 1.000 (14 Jul 2001) 
    1271  
    12721190=cut 
    12731191 
    … …  
    12781196} 
    12791197 
    1280 =pod 
     1198=begin TML 
    12811199 
    12821200---+++ checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime ) 
    … …  
    12871205Return: =( $oopsUrl, $loginName, $unlockTime )= - The =$oopsUrl= for calling redirectCgiQuery(), user's =$loginName=, and estimated =$unlockTime= in minutes, or ( '', '', 0 ) if no lease exists. 
    12881206   * =$script= The script to invoke when continuing with the edit 
    1289  
    1290 *Since:* Foswiki::Plugins::VERSION 1.010 (31 Dec 2002) 
    12911207 
    12921208=cut 
    … …  
    13271243} 
    13281244 
    1329 =pod 
     1245=begin TML 
    13301246 
    13311247---+++ setTopicEditLock( $web, $topic, $lock ) 
    … …  
    13421258It is *impossible* to fully lock a topic. Concurrent changes will be 
    13431259merged. 
    1344  
    1345 *Since:* Foswiki::Plugins::VERSION 1.010 (31 Dec 2002) 
    13461260 
    13471261=cut 
    … …  
    13621276} 
    13631277 
    1364 =pod 
     1278=begin TML 
    13651279 
    13661280---+++ saveTopic( $web, $topic, $meta, $text, $options ) -> $error 
    … …  
    13771291Return: error message or undef. 
    13781292 
    1379 *Since:* Foswiki::Plugins::VERSION 1.000 (29 Jul 2001) 
    1380  
    13811293For example, 
    13821294<verbatim> 
    … …  
    14011313} 
    14021314 
    1403 =pod 
     1315=begin TML 
    14041316 
    14051317---+++ saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl 
    … …  
    14141326 
    14151327This method is a lot less efficient and much more dangerous than =saveTopic=. 
    1416  
    1417 *Since:* Foswiki::Plugins::VERSION 1.010 (31 Dec 2002) 
    14181328 
    14191329<verbatim> 
    … …  
    14911401} 
    14921402 
    1493 =pod 
     1403=begin TML 
    14941404 
    14951405---+++ moveTopic( $web, $topic, $newWeb, $newTopic ) 
    … …  
    15061416 
    15071417Rename a topic to the $Foswiki::cfg{TrashWebName} to delete it. 
    1508  
    1509 *Since:* Foswiki::Plugins::VERSION 1.1 
    15101418 
    15111419<verbatim> 
    … …  
    15391447} 
    15401448 
    1541 =pod 
     1449=begin TML 
    15421450 
    15431451---+++ getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment )  
    … …  
    15581466more efficient. 
    15591467 
    1560 *Since:* Foswiki::Plugins::VERSION 1.000 (29 Jul 2001) 
    1561  
    15621468=cut 
    15631469 
    … …  
    15701476} 
    15711477 
    1572 =pod 
     1478=begin TML 
    15731479 
    15741480---+++ getRevisionAtTime( $web, $topic, $time ) -> $rev 
    … …  
    15811487(either because the topic isn't that old, or there was a problem) 
    15821488 
    1583 *Since:* Foswiki::Plugins::VERSION 1.1 
    1584  
    15851489=cut 
    15861490 
    … …  
    15901494} 
    15911495 
    1592 =pod 
     1496=begin TML 
    15931497 
    15941498---+++ readTopic( $web, $topic, $rev ) -> ( $meta, $text ) 
    … …  
    16081512topic. 
    16091513 
    1610 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    1611  
    16121514=cut 
    16131515 
    … …  
    16201522} 
    16211523 
    1622 =pod 
     1524=begin TML 
    16231525 
    16241526---+++ readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text 
    … …  
    16321534 
    16331535This method is more efficient than =readTopic=, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer. 
    1634  
    1635 *Since:* Foswiki::Plugins::VERSION 1.010 (31 Dec 2002) 
    16361536 
    16371537=cut 
    … …  
    16651565} 
    16661566 
    1667 =pod 
     1567=begin TML 
    16681568 
    16691569---+++ attachmentExists( $web, $topic, $attachment ) -> $boolean 
    … …  
    16751575$web and $topic are parsed as described in the documentation for =normalizeWebTopicName=. 
    16761576 
    1677 *Since:* Foswiki::Plugins::VERSION 1.1 
    1678  
    16791577=cut 
    16801578 
    … …  
    16891587} 
    16901588 
    1691 =pod 
     1589=begin TML 
    16921590 
    16931591---+++ readAttachment( $web, $topic, $name, $rev ) -> $data 
    … …  
    17191617</verbatim> 
    17201618 
    1721 *Since:* Foswiki::Plugins::VERSION 1.1 
    1722  
    17231619=cut 
    17241620 
    … …  
    17371633} 
    17381634 
    1739 =pod 
     1635=begin TML 
    17401636 
    17411637---+++ saveAttachment( $web, $topic, $attachment, \%opts ) 
    … …  
    17701666</verbatim> 
    17711667 
    1772 *Since:* Foswiki::Plugins::VERSION 1.1 
    1773  
    17741668=cut 
    17751669 
    … …  
    17901684} 
    17911685 
    1792 =pod 
     1686=begin TML 
    17931687 
    17941688---+++ moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment ) 
    … …  
    18261720</verbatim> 
    18271721 
    1828 *Since:* Foswiki::Plugins::VERSION 1.1 
    1829  
    18301722=cut 
    18311723 
    … …  
    18471739} 
    18481740 
    1849 =pod 
     1741=begin TML 
    18501742 
    18511743---++ Assembling Pages 
    … …  
    18531745=cut 
    18541746 
    1855 =pod 
     1747=begin TML 
    18561748 
    18571749---+++ readTemplate( $name, $skin ) -> $text 
    … …  
    18621754Return: =$text=    Template text 
    18631755 
    1864 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    1865  
    18661756=cut 
    18671757 
    … …  
    18731763} 
    18741764 
    1875 =pod 
     1765=begin TML 
    18761766 
    18771767---+++ loadTemplate ( $name, $skin, $web ) -> $text 
    … …  
    18821772Return: expanded template text (what's left after removal of all %TMPL:DEF% statements) 
    18831773 
    1884 *Since:* Foswiki::Plugins::VERSION 1.1 
    1885  
    18861774Reads a template and extracts template definitions, adding them to the 
    18871775list of loaded templates, overwriting any previous definition. 
    … …  
    18981786} 
    18991787 
    1900 =pod 
     1788=begin TML 
    19011789 
    19021790---+++ expandTemplate( $def  ) -> $string 
    … …  
    19061794Return: the text of the expanded template 
    19071795 
    1908 *Since:* Foswiki::Plugins::VERSION 1.1 
    1909  
    19101796A template is defined using a %TMPL:DEF% statement in a template 
    19111797file. See the documentation on Foswiki templates for more information. 
    … …  
    19181804} 
    19191805 
    1920 =pod 
     1806=begin TML 
    19211807 
    19221808---+++ writeHeader() 
    … …  
    19241810Prints a basic content-type HTML header for text/html to standard out. 
    19251811 
    1926 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    1927  
    19281812=cut 
    19291813 
    … …  
    19331817} 
    19341818 
    1935 =pod 
     1819=begin TML 
    19361820 
    19371821---+++ redirectCgiQuery( $query, $url, $passthru ) 
    … …  
    19671851Foswiki installation. 
    19681852 
    1969 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    1970  
    19711853=cut 
    19721854 
    … …  
    19771859} 
    19781860 
    1979 =pod 
     1861=begin TML 
    19801862 
    19811863---+++ addToHEAD( $id, $header, $requires ) 
    … …  
    19911873Note that this is _not_ the same as the HTTP header, which is modified through the Plugins =modifyHeaderHandler=. 
    19921874 
    1993 *Since:* Foswiki::Plugins::VERSION 1.1 
    1994  
    1995 example: 
     1875Example: 
    19961876<verbatim> 
    19971877Foswiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/Foswiki/PatternSkin/layout.css" media="all" />'); 
    … …  
    20061886} 
    20071887 
    2008 =pod 
     1888=begin TML 
    20091889 
    20101890---+++ expandCommonVariables( $text, $topic, $web, $meta ) -> $text 
    … …  
    20141894   * =$topic= - Current topic name, e.g. ='WebNotify'= 
    20151895   * =$web=   - Web name, optional, e.g. ='Main'=. The current web is taken if missing 
    2016    * =$meta=  - topic meta-data to use while expanding (Since Foswiki::Plugins::VERSION 1.2) 
     1896   * =$meta=  - topic meta-data to use while expanding 
    20171897Return: =$text=     Expanded text, e.g. ='Current user is <nop>WikiGuest'= 
    2018  
    2019 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    20201898 
    20211899See also: expandVariablesOnTopicCreation 
    … …  
    20321910} 
    20331911 
    2034 =pod 
     1912=begin TML 
    20351913 
    20361914---+++ renderText( $text, $web ) -> $text 
    … …  
    20411919Return: =$text=    XHTML text, e.g. ='&lt;b>bold&lt;/b> and &lt;code>fixed font&lt;/code>'= 
    20421920 
    2043 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    2044  
    20451921=cut 
    20461922 
    … …  
    20521928} 
    20531929 
    2054 =pod 
     1930=begin TML 
    20551931 
    20561932---+++ internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text 
    … …  
    20651941Return: =$text=          XHTML anchor, e.g. ='&lt;a href='/cgi-bin/view/Main/WebNotify#Jump'>notify&lt;/a>'= 
    20661942 
    2067 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    2068  
    20691943=cut 
    20701944 
    … …  
    20771951} 
    20781952 
    2079 =pod 
     1953=begin TML 
    20801954 
    20811955---++ E-mail 
    … …  
    21041978Leave a blank line between the last header field and the message body. 
    21051979 
    2106 *Since:* Foswiki::Plugins::VERSION 1.1 
    2107  
    21081980=cut 
    21091981 
    … …  
    21151987} 
    21161988 
    2117 =pod 
    2118  
    2119 ---+++ wikiToEmail( $wikiName ) -> $email 
    2120  
    2121    * =$wikiname= - wiki name of the user 
    2122 Get the e-mail address(es) of the named user. If the user has multiple 
    2123 e-mail addresses (for example, the user is a group), then the list will 
    2124 be comma-separated. 
    2125  
    2126 *Since:* Foswiki::Plugins::VERSION 1.1 
    2127  
    2128 *Deprecated* in favour of wikinameToEmails, because this function only 
    2129 returns a single email address, where a user may in fact have several. 
    2130  
    2131 $wikiName may also be a login name. 
    2132  
    2133 =cut 
    2134  
    2135 sub wikiToEmail { 
    2136     my ($user) = @_; 
    2137     my @emails = wikinameToEmails($user); 
    2138     if ( scalar(@emails) ) { 
    2139         return $emails[0]; 
    2140     } 
    2141     return ''; 
    2142 } 
    2143  
    2144 =pod 
     1989=begin TML 
    21451990 
    21461991---++ Creating New Topics 
    … …  
    21481993=cut 
    21491994 
    2150 =pod 
     1995=begin TML 
    21511996 
    21521997---+++ expandVariablesOnTopicCreation ( $text ) -> $text 
    … …  
    21552000   * =$text= - the text to process 
    21562001Return: text with variables expanded 
    2157  
    2158 *Since:* Foswiki::Plugins::VERSION 1.1 
    21592002 
    21602003Expands only the variables expected in templates that must be statically 
    … …  
    21812024} 
    21822025 
    2183 =pod 
     2026=begin TML 
    21842027 
    21852028---++ Special handlers 
    … …  
    21892032=cut 
    21902033 
    2191 =pod= 
     2034=begin TML= 
    21922035 
    21932036---+++ registerTagHandler( $var, \&fn, $syntax ) 
    … …  
    21992042   * =\&fn= - Reference to the handler function. 
    22002043   * =$syntax= can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic syntax i.e. to accept the standard =%<nop>MYVAR{ "unnamed" param1="value1" param2="value2" }%= syntax, as well as an unquoted default parameter, such as =%<nop>MYVAR{unquoted parameter}%=. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR{param1=value1, value 2, param3="value 3", param4='value 5"}% 
    2201  
    2202 *Since:* Foswiki::Plugins::VERSION 1.1 
    22032044 
    22042045The variable handler function must be of the form: 
    … …  
    22582099} 
    22592100 
    2260 =pod= 
     2101=begin TML= 
    22612102 
    22622103---+++ registerRESTHandler( $alias, \&fn, ) 
    … …  
    22672108   * =$alias= - The name . 
    22682109   * =\&fn= - Reference to the function. 
    2269  
    2270 *Since:* Foswiki::Plugins::VERSION 1.1 
    22712110 
    22722111The handler function must be of the form: 
    … …  
    23222161} 
    23232162 
    2324 =pod 
     2163=begin TML 
    23252164 
    23262165---+++ decodeFormatTokens($str) -> $unencodedString 
    … …  
    23522191alphanumeric characters*. You have been warned! 
    23532192 
    2354 *Since:* Foswiki::Plugins::VERSION 1.2 
    2355  
    23562193=cut 
    23572194 
    … …  
    23602197} 
    23612198 
    2362 =pod 
     2199=begin TML 
    23632200 
    23642201---++ Searching 
    … …  
    23662203=cut 
    23672204 
    2368 =pod 
     2205=begin TML 
    23692206 
    23702207---+++ searchInWebContent($searchString, $web, \@topics, \%options ) -> \%map 
    … …  
    23932230</verbatim> 
    23942231 
    2395 *Since:* Foswiki::Plugins::VERSION 1.1 
    2396  
    23972232=cut 
    23982233 
    … …  
    24042239} 
    24052240 
    2406 =pod 
     2241=begin TML 
    24072242 
    24082243---++ Plugin-specific file handling 
    … …  
    24102245=cut 
    24112246 
    2412 =pod 
     2247=begin TML 
    24132248 
    24142249---+++ getWorkArea( $pluginName ) -> $directorypath 
    … …  
    24232258to keep their areas tidy. 
    24242259 
    2425 *Since:* Foswiki::Plugins::VERSION 1.1 (Dec 2005) 
    2426  
    24272260=cut 
    24282261 
    … …  
    24332266} 
    24342267 
    2435 =pod 
     2268=begin TML 
    24362269 
    24372270---+++ readFile( $filename ) -> $text 
    … …  
    24422275 
    24432276__NOTE:__ Use this function only for the Plugin workarea, *not* for topics and attachments. Use the appropriate functions to manipulate topics and attachments. 
    2444  
    2445 *Since:* Foswiki::Plugins::VERSION 1.000 (07 Dec 2002) 
    24462277 
    24472278=cut 
    … …  
    24582289} 
    24592290 
    2460 =pod 
     2291=begin TML 
    24612292 
    24622293---+++ saveFile( $filename, $text ) 
    … …  
    24682299 
    24692300__NOTE:__ Use this function only for the Plugin workarea, *not* for topics and attachments. Use the appropriate functions to manipulate topics and attachments. 
    2470  
    2471 *Since:* Foswiki::Plugins::VERSION 1.000 (07 Dec 2002) 
    24722301 
    24732302=cut 
    … …  
    24832312} 
    24842313 
    2485 =pod 
     2314=begin TML 
    24862315 
    24872316---++ General Utilities 
    … …  
    24892318=cut 
    24902319 
    2491 =pod 
     2320=begin TML 
    24922321 
    24932322---+++ getRegularExpression( $name ) -> $expr 
    … …  
    24962325   * =$name= - Name of the expression to retrieve.  See notes below 
    24972326Return: String or precompiled regular expression matching as described below. 
    2498  
    2499 *Since:* Foswiki::Plugins::VERSION 1.020 (9 Feb 2004) 
    25002327 
    25012328__Note:__ Foswiki internally precompiles several regular expressions to 
    … …  
    25412368} 
    25422369 
    2543 =pod 
     2370=begin TML 
    25442371 
    25452372---+++ normalizeWebTopicName($web, $topic) -> ($web, $topic) 
    … …  
    25492376   * =$topic= - Topic name, may be a web.topic string, required. 
    25502377Return: the parsed Web/Topic pair 
    2551  
    2552 *Since:* Foswiki::Plugins::VERSION 1.1 
    25532378 
    25542379| *Input*                               | *Return*  | 
    … …  
    25792404} 
    25802405 
    2581 =pod 
     2406=begin TML 
    25822407 
    25832408---+++ StaticMethod sanitizeAttachmentName($fname) -> ($fileName, $origName) 
    … …  
    25902415file names to legal server names. 
    25912416 
    2592 *Since:* Foswiki::Plugins::VERSION 1.2 
    2593  
    25942417=cut 
    25952418 
    … …  
    25992422} 
    26002423 
    2601 =pod 
     2424=begin TML 
    26022425 
    26032426---+++ spaceOutWikiWord( $word, $sep ) -> $text 
    … …  
    26062429With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space. 
    26072430 
    2608 *Since:* Foswiki::Plugins::VERSION 1.2 
    2609  
    26102431=cut 
    26112432 
    … …  
    26162437} 
    26172438 
    2618 =pod 
     2439=begin TML 
    26192440 
    26202441---+++ writeWarning( $text ) 
    … …  
    26242445Return:            none 
    26252446 
    2626 *Since:* Foswiki::Plugins::VERSION 1.020 (16 Feb 2004) 
    2627  
    26282447=cut 
    26292448 
    … …  
    26372456} 
    26382457 
    2639 =pod 
     2458=begin TML 
    26402459 
    26412460---+++ writeDebug( $text ) 
    … …  
    26452464Return:            none 
    26462465 
    2647 *Since:* Foswiki::Plugins::VERSION 1.020 (16 Feb 2004) 
    2648  
    26492466=cut 
    26502467 
    … …  
    26562473} 
    26572474 
    2658 =pod 
    2659  
    2660 ---+++ formatTime( $time, $format, $timezone ) -> $text 
    2661  
    2662 Format the time in seconds into the desired time string 
    2663    * =$time=     - Time in epoc seconds 
    2664    * =$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'=), or any string with tokens ='$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz'= for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively 
    2665    * =$timezone= - either not defined (uses the displaytime setting), 'gmtime', or 'servertime' 
    2666 Return: =$text=        Formatted time string 
    2667 | Note:                  | if you used the removed formatGmTime, add a third parameter 'gmtime' | 
    2668  
    2669 *Since:* Foswiki::Plugins::VERSION 1.020 (26 Feb 2004) 
    2670  
    2671 =cut 
    2672  
    2673 sub formatTime { 
    2674  
    2675     #   my ( $epSecs, $format, $timezone ) = @_; 
    2676     require Foswiki::Time; 
    2677     return Foswiki::Time::formatTime(@_); 
    2678 } 
    2679  
    2680 =pod 
     2475=begin TML 
    26812476 
    26822477---+++ isTrue( $value, $default ) -> $boolean 
    … …  
    26902485not specified it is taken as 0. 
    26912486 
    2692 *Since:* $Foswiki::Plugins::VERSION 1.2 
    2693  
    26942487=cut 
    26952488 
    … …  
    27012494} 
    27022495 
    2703 =pod 
     2496=begin TML 
    27042497 
    27052498---+++ isValidWikiWord ( $text ) -> $boolean 
    … …  
    27082501   * =$text= - Word to test 
    27092502 
    2710 *Since:* Foswiki::Plugins::VERSION 1.100 (Dec 2005) 
    2711  
    27122503=cut 
    27132504 
    … …  
    27162507} 
    27172508 
    2718 =pod 
     2509=begin TML 
    27192510 
    27202511---+++ extractParameters($attr ) -> %params 
    … …  
    27232514   * =$attr= - Attribute string 
    27242515Return: =%params=  Hash containing all parameters. The nameless parameter is stored in key =_DEFAULT= 
    2725  
    2726 *Since:* Foswiki::Plugins::VERSION 1.025 (26 Aug 2004) 
    27272516 
    27282517   * Example: 
    … …  
    27492538} 
    27502539 
    2751 =pod 
     2540=begin TML 
    27522541 
    27532542---+++ extractNameValuePair( $attr, $name ) -> $value 
    … …  
    27582547   * =$name= - Name, optional 
    27592548Return: =$value=   Extracted value 
    2760  
    2761 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    27622549 
    27632550   * Example: 
    … …  
    27762563} 
    27772564 
    2778 =pod 
     2565=begin TML 
    27792566 
    27802567---++ Deprecated functions 
    … …  
    27992586Get script URL path 
    28002587 
    2801 *DEPRECATED* since 1.1 - use =getScriptUrl= instead. 
     2588*Deprecated* 28 Nov 2008 - use =getScriptUrl= instead. 
    28022589 
    28032590Return: =$path= URL path of bin scripts, e.g. ="/cgi-bin"= 
    … …  
    28072594using it. 
    28082595 
    2809 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    2810  
    28112596=cut 
    28122597 
    … …  
    28172602 
    28182603 
    2819 =pod 
     2604=begin TML 
    28202605 
    28212606---+++ getWikiToolName( ) -> $name 
    28222607 
    2823 *DEPRECATED* in Foswiki; use $Foswiki::cfg{WikiToolName} instead 
     2608*Deprecated* 28 Nov 2008 in Foswiki; use $Foswiki::cfg{WikiToolName} instead 
    28242609 
    28252610=cut 
    … …  
    28272612sub getWikiToolName { return $Foswiki::cfg{WikiToolName}; } 
    28282613 
    2829 =pod 
     2614=begin TML 
    28302615 
    28312616---+++ getMainWebname( ) -> $name 
    28322617 
    2833 *DEPRECATED* in Foswiki; use $Foswiki::cfg{UsersWebName} instead 
     2618*Deprecated* 28 Nov 2008 in Foswiki; use $Foswiki::cfg{UsersWebName} instead 
    28342619 
    28352620=cut 
    … …  
    28372622sub getMainWebname { return $Foswiki::cfg{UsersWebName}; } 
    28382623 
    2839 =pod 
     2624=begin TML 
    28402625 
    28412626---+++ getTwikiWebname( ) -> $name 
    28422627 
    2843 *DEPRECATED* in Foswiki; use $Foswiki::cfg{SystemWebName} instead 
     2628*Deprecated* 28 Nov 2008 in Foswiki; use $Foswiki::cfg{SystemWebName} instead 
    28442629 
    28452630=cut 
    … …  
    28472632sub getTwikiWebname { return $Foswiki::cfg{SystemWebName}; } 
    28482633 
    2849 =pod 
     2634=begin TML 
    28502635 
    28512636---+++ getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url 
    … …  
    28582643Return: =$url=                     URL, e.g. ="http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&amp;param1=joe"= 
    28592644 
    2860 *DEPRECATED* since 1.1, the recommended approach is to throw an oops exception. 
     2645*Deprecated* 28 Nov 2008, the recommended approach is to throw an oops exception. 
    28612646<verbatim> 
    28622647   use Error qw( :try ); 
    … …  
    28792664   return 0; 
    28802665</verbatim> 
    2881  
    2882 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    28832666 
    28842667=cut 
    … …  
    28962679} 
    28972680 
    2898 =pod 
     2681=begin TML 
     2682 
     2683---+++ wikiToEmail( $wikiName ) -> $email 
     2684 
     2685   * =$wikiname= - wiki name of the user 
     2686Get the e-mail address(es) of the named user. If the user has multiple 
     2687e-mail addresses (for example, the user is a group), then the list will 
     2688be comma-separated. 
     2689 
     2690*Deprecated* 28 Nov 2008 in favour of wikinameToEmails, because this function only 
     2691returns a single email address, where a user may in fact have several. 
     2692 
     2693$wikiName may also be a login name. 
     2694 
     2695=cut 
     2696 
     2697sub wikiToEmail { 
     2698    my ($user) = @_; 
     2699    my @emails = wikinameToEmails($user); 
     2700    if ( scalar(@emails) ) { 
     2701        return $emails[0]; 
     2702    } 
     2703    return ''; 
     2704} 
     2705 
     2706=begin TML 
    28992707 
    29002708---+++ permissionsSet( $web ) -> $boolean 
    … …  
    29042712   * =$web= - Web name, required, e.g. ='Sandbox'= 
    29052713 
    2906 *Since:* Foswiki::Plugins::VERSION 1.000 (27 Feb 2001) 
    2907  
    2908 *DEPRECATED* since 1.2 - use =getPreferencesValue= instead to determine 
     2714*Deprecated* 28 Nov 2008 - use =getPreferencesValue= instead to determine 
    29092715what permissions are set on the web, for example: 
    29102716<verbatim> 
    … …  
    29362742} 
    29372743 
    2938 =pod 
     2744=begin TML 
    29392745 
    29402746---+++ getPublicWebList( ) -> @webs 
    29412747 
    2942 *DEPRECATED* since 1.1 - use =getListOfWebs= instead. 
     2748*Deprecated* 28 Nov 2008 - use =getListOfWebs= instead. 
    29432749 
    29442750Get list of all public webs, e.g. all webs *and subwebs* that do not have the =NOSEARCHALL= flag set in the WebPreferences 
    … …  
    29462752Return: =@webs= List of all public webs *and subwebs* 
    29472753 
    2948 *Since:* Foswiki::Plugins::VERSION 1.000 (07 Dec 2002) 
    2949  
    29502754=cut 
    29512755 
    … …  
    29552759} 
    29562760 
    2957 =pod 
     2761=begin TML 
     2762 
     2763---+++ formatTime( $time, $format, $timezone ) -> $text 
     2764 
     2765*Deprecated* 28 Nov 2008 - use =Foswiki::Time::formatTime= instead (it has an identical interface). 
     2766 
     2767Format the time in seconds into the desired time string 
     2768   * =$time=     - Time in epoch seconds 
     2769   * =$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'=), or any string with tokens ='$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz'= for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively 
     2770   * =$timezone= - either not defined (uses the displaytime setting), 'gmtime', or 'servertime' 
     2771Return: =$text=        Formatted time string 
     2772| Note:                  | if you used the removed formatGmTime, add a third parameter 'gmtime' | 
     2773 
     2774=cut 
     2775 
     2776sub formatTime { 
     2777 
     2778    #   my ( $epSecs, $format, $timezone ) = @_; 
     2779    require Foswiki::Time; 
     2780    return Foswiki::Time::formatTime(@_); 
     2781} 
     2782 
     2783=begin TML 
    29582784 
    29592785---+++ formatGmTime( $time, $format ) -> $text 
    29602786 
    2961 *DEPRECATED* since 1.1 - use =formatTime= instead. 
     2787*Deprecated* 28 Nov 2008 - use =Foswiki::Time::formatTime= instead. 
    29622788 
    29632789Format the time to GM time 
    … …  
    29662792Return: =$text=      Formatted time string 
    29672793 
    2968 *Since:* Foswiki::Plugins::VERSION 1.000 (7 Dec 2002) 
    2969  
    29702794=cut 
    29712795 
    … …  
    29732797 
    29742798    #   my ( $epSecs, $format ) = @_; 
    2975  
    2976 # FIXME: Write warning based on flag (disabled for now); indicate who is calling this function 
    2977     ## writeWarning( 'deprecated use of Func::formatGmTime' ); 
    2978  
    29792799    require Foswiki::Time; 
    29802800    return Foswiki::Time::formatTime( @_, 'gmtime' ); 
    29812801} 
    29822802 
    2983 =pod 
     2803=begin TML 
    29842804 
    29852805---+++ getDataDir( ) -> $dir 
    29862806 
    2987 *DEPRECATED* since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead 
     2807*Deprecated* 28 Nov 2008 - use the "Webs, Topics and Attachments" functions to manipulate topics instead 
    29882808 
    29892809=cut 
    … …  
    29932813} 
    29942814 
    2995 =pod 
     2815=begin TML 
    29962816 
    29972817---+++ getPubDir( ) -> $dir 
    29982818 
    2999 *DEPRECATED* since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead 
     2819*Deprecated* 28 Nov 2008 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead 
    30002820 
    30012821=cut 
Note: See TracChangeset for help on using the changeset viewer.