1 rizwank 1.1 %META:TOPICINFO{author="PeterThoeny" date="1093769327" format="1.0" version="1.6"}%
  2             %META:TOPICPARENT{name="TWikiPlugins"}%
  3             %TOC%
  4             %STARTINCLUDE%
  5             
  6             ---# TWiki::Func Module Documentation
  7             
  8             _Official list of stable TWiki functions for Plugin developers_
  9             
 10             <noautolink>
 11             
 12             ---++ Description
 13             
 14             This module defines official funtions that [[TWiki.TWikiPlugins][Plugins]] 
 15             and add-on scripts can use to interact with the TWiki engine and content.
 16             
 17             Plugins should *only* use functions published in this module. If you use
 18             functions in other TWiki libraries you might impose a security hole and 
 19             you will likely need to change your Plugin when you upgrade TWiki.
 20             
 21             The version of the TWiki::Func module is defined by the VERSION number of the 
 22 rizwank 1.1 TWiki::Plugins module, currently 1.025. This can be shown by the 
 23             =%<nop>PLUGINVERSION{}%= variable. The "Since" field in the function documentation 
 24             refers to the VERSION number and the date that the function was addded.
 25             
 26             ---++ Functions: CGI Environment
 27             
 28             ---+++ getSessionValue( $key ) ==> $value
 29             
 30             | Description:		| Get a session value from the Session Plugin (if installed) |
 31             | Parameter: =$key= | Session key |
 32             | Return: =$value=  | Value associated with key; empty string if not set; undef if session plugin is not installed |
 33             | Since:				| TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
 34             
 35             ---+++ setSessionValue( $key, $value ) ==> $result
 36             
 37             | Description:		  | Set a session value via the Session Plugin (if installed) |
 38             | Parameter: =$key=	| Session key |
 39             | Parameter: =$value= | Value associated with key |
 40             | Return: =$result=	| ="1"= if success; undef if session plugin is not installed |
 41             | Since:				  | TWiki::Plugins::VERSION 1.000 (17 Aug 2001) |
 42             
 43 rizwank 1.1 ---+++ getSkin( ) ==> $skin
 44             
 45             | Description:	 | Get the name of the skin, set by the =SKIN= preferences variable or the =skin= CGI parameter |
 46             | Return: =$skin= | Name of skin, e.g. ="gnu"=. Empty string if none |
 47             | Since:			 | TWiki::Plugins::VERSION 1.000 (29 Jul 2001) |
 48             
 49             ---+++ getUrlHost( ) ==> $host
 50             
 51             | Description:	 | Get protocol, domain and optional port of script URL |
 52             | Return: =$host= | URL host, e.g. ="http://example.com:80"= |
 53             | Since:			 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
 54             
 55             ---+++ getScriptUrl( $web, $topic, $script ) ==> $url
 56             
 57             | Description:			| Compose fully qualified URL |
 58             | Parameter: =$web=	 | Web name, e.g. ="Main"= |
 59             | Parameter: =$topic=  | Topic name, e.g. ="WebNotify"= |
 60             | Parameter: =$script= | Script name, e.g. ="view"= |
 61             | Return: =$url=		 | URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"= |
 62             | Since:					| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
 63             
 64 rizwank 1.1 ---+++ getScriptUrlPath( ) ==> $path
 65             
 66             | Description:	 | Get script URL path |
 67             | Return: =$path= | URL path of TWiki scripts, e.g. ="/cgi-bin"= |
 68             | Since:			 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
 69             
 70             ---+++ getViewUrl( $web, $topic ) ==> $url
 71             
 72             | Description:		  | Compose fully qualified view URL |
 73             | Parameter: =$web=	| Web name, e.g. ="Main"=. The current web is taken if empty |
 74             | Parameter: =$topic= | Topic name, e.g. ="WebNotify"= |
 75             | Return: =$url=		| URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"= |
 76             | Since:				  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
 77             
 78             ---+++ getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) ==> $url
 79             
 80             | Description:							  | Compose fully qualified "oops" dialog URL |
 81             | Parameter: =$web=						| Web name, e.g. ="Main"=. The current web is taken if empty |
 82             | Parameter: =$topic=					 | Topic name, e.g. ="WebNotify"= |
 83             | Parameter: =$template=				 | Oops template name, e.g. ="oopslocked"= |
 84             | Parameter: =$param1= ... =$param4= | Parameter values for %<nop>PARAM1% ... %<nop>PARAM4% variables in template, optional |
 85 rizwank 1.1 | Return: =$url=							| URL, e.g. ="http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&amp;param1=joe"= |
 86             | Since:									  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
 87             
 88             ---+++ getPubUrlPath( ) ==> $path
 89             
 90             | Description:	 | Get pub URL path |
 91             | Return: =$path= | URL path of pub directory, e.g. ="/pub"= |
 92             | Since:			 | TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
 93             
 94             ---+++ getCgiQuery( ) ==> $query
 95             
 96             | 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 |
 97             | Return: =$query= | CGI query object; or 0 if script is called as a shell script |
 98             | Since:			  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
 99             
100             ---+++ writeHeader( $query )
101             
102             | Description:		  | Prints a basic content-type HTML header for text/html to standard out |
103             | Parameter: =$query= | CGI query object |
104             | Return:				 | none |
105             | Since:				  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
106 rizwank 1.1 
107             ---+++ redirectCgiQuery( $query, $url )
108             
109             | Description:		  | Redirect to URL |
110             | Parameter: =$query= | CGI query object |
111             | Parameter: =$url=	| URL to redirect to |
112             | Return:				 | none, never returns |
113             | Since:				  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
114             
115             ---++ Functions: Preferences
116             
117             ---+++ extractParameters( $attr ) ==> %params
118             
119             | Description:		 | Extract all parameters from a variable string and returns a hash of parameters |
120             | Parameter: =$attr= | Attribute string |
121             | Return: =%params=  | Hash containing all parameters. The nameless parameter is stored in key =_DEFAULT= |
122             | Since:				 | TWiki::Plugins::VERSION 1.025 (26 Aug 2004) |
123             
124             	* Example:
125             		* Variable: =%<nop>TEST{ "nameless" name1="val1" name2="val2" }%=
126             		* First extract text between ={...}= to get: ="nameless" name1="val1" name2="val2"=
127 rizwank 1.1 		* Then call this on the text: <br />
128             		=my %params = TWiki::Func::extractParameters( $text );=
129             		* The =%params= hash contains now: <br />
130             		=_DEFAULT => "nameless"= <br />
131             		=name1 => "val1"= <br />
132             		=name2 => "val2"=
133             
134             ---+++ extractNameValuePair( $attr, $name ) ==> $value
135             
136             | Description:		 | Extract a named or unnamed value from a variable parameter string |
137             | Note:				  | Function TWiki::Func::extractParameters is more efficient for extracting several parameters |
138             | Parameter: =$attr= | Attribute string |
139             | Parameter: =$name= | Name, optional |
140             | Return: =$value=	| Extracted value |
141             | Since:				 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
142             
143             	* Example:
144             		* Variable: =%<nop>TEST{ "nameless" name1="val1" name2="val2" }%=
145             		* First extract text between ={...}= to get: ="nameless" name1="val1" name2="val2"=
146             		* Then call this on the text: <br />
147             		=my $noname = TWiki::Func::extractNameValuePair( $text );= <br />
148 rizwank 1.1 		=my $val1  = TWiki::Func::extractNameValuePair( $text, "name1" );= <br />
149             		=my $val2  = TWiki::Func::extractNameValuePair( $text, "name2" );=
150             
151             ---+++ getPreferencesValue( $key, $web ) ==> $value
152             
153             | Description:		| Get a preferences value from TWiki or from a Plugin |
154             | Parameter: =$key= | Preferences key |
155             | Parameter: =$web= | Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics |
156             | Return: =$value=  | Preferences value; empty string if not set |
157             | Since:				| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
158             
159             	* Example for Plugin setting:
160             		* MyPlugin topic has: =* Set COLOR = red=
161             		* Use ="MYPLUGIN_COLOR"= for =$key=
162             		* =my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );=
163             
164             	* Example for preferences setting:
165             		* WebPreferences topic has: =* Set WEBBGCOLOR = #FFFFC0=
166             		* =my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );=
167             
168             ---+++ getPluginPreferencesValue( $key ) ==> $value
169 rizwank 1.1 
170             | Description:		| Get a preferences value from your Plugin |
171             | Parameter: =$key= | Plugin Preferences key w/o PLUGINNAME_ prefix. |
172             | Return: =$value=  | Preferences value; empty string if not set |
173             | Since:				| TWiki::Plugins::VERSION 1.021 (27 Mar 2004) |
174             
175             ---+++ getPreferencesFlag( $key, $web ) ==> $value
176             
177             | Description:		| Get a preferences flag from TWiki or from a Plugin |
178             | Parameter: =$key= | Preferences key |
179             | Parameter: =$web= | Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics |
180             | Return: =$value=  | Preferences flag ="1"= (if set), or ="0"= (for preferences values ="off"=, ="no"= and ="0"=) |
181             | Since:				| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
182             
183             	* Example for Plugin setting:
184             		* MyPlugin topic has: =* Set SHOWHELP = off=
185             		* Use ="MYPLUGIN_SHOWHELP"= for =$key=
186             		* =my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );=
187             
188             ---+++ getPluginPreferencesFlag( $key ) ==> $flag
189             
190 rizwank 1.1 | Description:		| Get a preferences flag from your Plugin |
191             | Parameter: =$key= | Plugin Preferences key w/o PLUGINNAME_ prefix. |
192             | Return: =$flag=	| Preferences flag ="1"= (if set), or ="0"= (for preferences values ="off"=, ="no"= and ="0"=, or values not set at all) |
193             | Since:				| TWiki::Plugins::VERSION 1.021 (27 Mar 2004) |
194             
195             ---+++ getWikiToolName( ) ==> $name
196             
197             | Description:	 | Get toolname as defined in TWiki.cfg |
198             | Return: =$name= | Name of tool, e.g. ="TWiki"= |
199             | Since:			 | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
200             
201             ---+++ getMainWebname( ) ==> $name
202             
203             | Description:	 | Get name of Main web as defined in TWiki.cfg |
204             | Return: =$name= | Name, e.g. ="Main"= |
205             | Since:			 | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
206             
207             ---+++ getTwikiWebname( ) ==> $name
208             
209             | Description:	 | Get name of TWiki documentation web as defined in TWiki.cfg |
210             | Return: =$name= | Name, e.g. ="TWiki"= |
211 rizwank 1.1 | Since:			 | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
212             
213             ---++ Functions: User Handling and Access Control
214             
215             ---+++ getDefaultUserName( ) ==> $loginName
216             
217             | Description:			| Get default user name as defined in TWiki.cfg's =$defaultUserName= |
218             | Return: =$loginName= | Default user name, e.g. ="guest"= |
219             | Since:					| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
220             
221             ---+++ getWikiName( ) ==> $wikiName
222             
223             | Description:		  | Get Wiki name of logged in user |
224             | Return: =$wikiName= | Wiki Name, e.g. ="JohnDoe"= |
225             | Since:				  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
226             
227             ---+++ getWikiUserName( $text ) ==> $wikiName
228             
229             | Description:		  | Get Wiki name of logged in user with web prefix |
230             | Return: =$wikiName= | Wiki Name, e.g. ="Main.JohnDoe"= |
231             | Since:				  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
232 rizwank 1.1 
233             ---+++ wikiToUserName( $wikiName ) ==> $loginName
234             
235             | Description:			  | Translate a Wiki name to a login name based on [[Main.TWikiUsers]] topic |
236             | Parameter: =$wikiName= | Wiki name, e.g. ="Main.JohnDoe"= or ="JohnDoe"= |
237             | Return: =$loginName=	| Login name of user, e.g. ="jdoe"= |
238             | Since:					  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
239             
240             ---+++ userToWikiName( $loginName, $dontAddWeb ) ==> $wikiName
241             
242             | Description:				 | Translate a login name to a Wiki name based on [[Main.TWikiUsers]] topic |
243             | Parameter: =$loginName=  | Login name, e.g. ="jdoe"= |
244             | Parameter: =$dontAddWeb= | Do not add web prefix if ="1"= |
245             | Return: =$wikiName=		| Wiki name of user, e.g. ="Main.JohnDoe"= or ="JohnDoe"= |
246             | Since:						 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
247             
248             ---+++ isGuest( ) ==> $flag
249             
250             | Description:	 | Test if logged in user is a guest |
251             | Return: =$flag= | ="1"= if yes, ="0"= if not |
252             | Since:			 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
253 rizwank 1.1 
254             ---+++ permissionsSet( $web ) ==> $flag
255             
256             | Description:		| Test if any access restrictions are set for this web, ignoring settings on individual pages |
257             | Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
258             | Return: =$flag=	| ="1"= if yes, ="0"= if no |
259             | Since:				| TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
260             
261             ---+++ checkAccessPermission( $type, $wikiName, $text, $topic, $web ) ==> $flag
262             
263             | Description:			  | Check access permission for a topic based on the [[TWiki.TWikiAccessControl]] rules |
264             | Parameter: =$type=	  | Access type, e.g. ="VIEW"=, ="CHANGE"=, ="CREATE"= |
265             | Parameter: =$wikiName= | WikiName of remote user, i.e. ="Main.PeterThoeny"= |
266             | Parameter: =$text=	  | Topic text, optional. If empty, topic =$web.$topic= is consulted |
267             | Parameter: =$topic=	 | Topic name, required, e.g. ="PrivateStuff"= |
268             | Parameter: =$web=		| Web name, required, e.g. ="Sandbox"= |
269             | Return: =$flag=		  | ="1"= if access may be granted, ="0"= if not |
270             | Since:					  | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
271             
272             ---++ Functions: Content Handling
273             
274 rizwank 1.1 ---+++ webExists( $web ) ==> $flag
275             
276             | Description:		| Test if web exists |
277             | Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
278             | Return: =$flag=	| ="1"= if web exists, ="0"= if not |
279             | Since:				| TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
280             
281             ---+++ topicExists( $web, $topic ) ==> $flag
282             
283             | Description:		  | Test if topic exists |
284             | Parameter: =$web=	| Web name, optional, e.g. ="Main"= |
285             | Parameter: =$topic= | Topic name, required, e.g. ="TokyoOffice"=, or ="Main.TokyoOffice"= |
286             | Return: =$flag=	  | ="1"= if topic exists, ="0"= if not |
287             | Since:				  | TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
288             
289             ---+++ getRevisionInfo($theWebName, $theTopic, $theRev, $attachment ) ==> ( $date, $user, $rev, $comment ) 
290             | Description:			  | Get revision info of a topic |
291             | Parameter: =$theWebName= | Web name, optional, e.g. ="Main"= |
292             | Parameter: =$theTopic=	| Topic name, required, e.g. ="TokyoOffice"= |
293             | Parameter: =$theRev=	  | revsion number, or tag name (can be in the format 1.2, or just the minor number) |
294             | Parameter: =$attachment=					  |attachment filename |
295 rizwank 1.1 | Return: =( $date, $user, $rev, $comment )= | List with: ( last update date, login name of last user, minor part of top revision number ), e.g. =( 1234561, "phoeny", "5" )= |
296             | $date | in epochSec |
297             | $user | |
298             | $rev |  |
299             | $comment | WHAT COMMENT? |
300             | Since:										  | TWiki::Plugins::VERSION 1.000 (29 Jul 2001) |
301             
302             ---+++ checkTopicEditLock( $web, $topic ) ==> ( $oopsUrl, $loginName, $unlockTime )
303             
304             | Description:												| Check if topic has an edit lock by a user |
305             | Parameter: =$web=										 | Web name, e.g. ="Main"=, or empty |
306             | Parameter: =$topic=									  | Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"= |
307             | 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. |
308             | Since:														| TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
309             
310             ---+++ setTopicEditLock( $web, $topic, $lock ) ==> $oopsUrl
311             
312             | Description:		  | Lock topic for editing, or unlock when done |
313             | Parameter: =$web=	| Web name, e.g. ="Main"=, or empty |
314             | Parameter: =$topic= | Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"= |
315             | Parameter: =$lock=  | Set to =1= to lock topic, =0= to unlock |
316 rizwank 1.1 | Return: =$oopsUrl=  | Empty string if OK; the =$oopsUrl= for calling redirectCgiQuery() in case lock is already taken when trying to lock topic |
317             | Since:				  | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
318             
319             ---+++ readTopicText( $web, $topic, $rev, $ignorePermissions ) ==> $text
320             
321             | Description:							| Read topic text, including meta data |
322             | Parameter: =$web=					 | Web name, e.g. ="Main"=, or empty |
323             | Parameter: =$topic=				  | Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"= |
324             | Parameter: =$rev=					 | Topic revision to read, optional. Specify the minor part of the revision, e.g. ="5"=, not ="1.5"=; the top revision is returned if omitted or empty. |
325             | Parameter: =$ignorePermissions=  | Set to ="1"= if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission |
326             | Return: =$text=						| Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error |
327             | Since:									| TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
328             
329             ---+++ saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) ==> $oopsUrl
330             
331             | Description:							| Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists. |
332             | Parameter: =$web=					 | Web name, e.g. ="Main"=, or empty |
333             | Parameter: =$topic=				  | Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"= |
334             | Parameter: =$text=					| Topic text to save, assumed to include meta data |
335             | Parameter: =$ignorePermissions=  | Set to ="1"= if checkAccessPermission() is already performed and OK |
336             | Parameter: =$dontNotify=			| Set to ="1"= if not to notify users of the change |
337 rizwank 1.1 | Return: =$oopsUrl=					| Empty string if OK; the =$oopsUrl= for calling redirectCgiQuery() in case of error |
338             | Since:									| TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
339             
340             	* Example: <br />
341             	=my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 );= <br />
342             	=if( $oopsUrl ) {= <br />
343             	=&nbsp;	TWiki::Func::redirectCgiQuery( $query, $oopsUrl );	# assuming valid query= <br />
344             	=&nbsp;	return;= <br />
345             	=}= <br />
346             	=my $text = TWiki::Func::readTopicText( $web, $topic );		  # read topic text= <br />
347             	=# check for oops URL in case of error:= <br />
348             	=if( $text =~ /^http.*?\/oops/ ) {= <br />
349             	=&nbsp;	TWiki::Func::redirectCgiQuery( $query, $text );= <br />
350             	=&nbsp;	return;= <br />
351             	=}= <br />
352             	=# do topic text manipulation like:= <br />
353             	=$text =~ s/old/new/g;= <br />
354             	=# do meta data manipulation like:= <br />
355             	=$text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;= <br />
356             	=$oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text= <br />
357             	=TWiki::Func::setTopicEditLock( $web, $topic, 0 );				 # unlock topic= <br />
358 rizwank 1.1 	=if( $oopsUrl ) {= <br />
359             	=&nbsp;	TWiki::Func::redirectCgiQuery( $query, $oopsUrl );= <br />
360             	=&nbsp;	return;= <br />
361             	=}=
362             
363             ---+++ getPublicWebList( ) ==> @webs
364             
365             | Description:	 | Get list of all public webs, e.g. all webs that do not have the =NOSEARCHALL= flag set in the WebPreferences |
366             | Return: =@webs= | List of all public webs, e.g. =( "Main",  "Know", "TWiki" )= |
367             | Since:			 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
368             
369             ---+++ getTopicList( $web ) ==> @topics
370             
371             | Description:		| Get list of all topics in a web |
372             | Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
373             | Return: =@topics= | Topic list, e.g. =( "WebChanges",  "WebHome", "WebIndex", "WebNotify" )= |
374             | Since:				| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
375             
376             ---++ Functions: Rendering
377             
378             ---+++ expandCommonVariables( $text, $topic, $web ) ==> $text
379 rizwank 1.1 
380             | Description:		  | Expand all common =%<nop>VARIABLES%= |
381             | Parameter: =$text=  | Text with variables to expand, e.g. ="Current user is %<nop>WIKIUSER%"= |
382             | Parameter: =$topic= | Current topic name, e.g. ="WebNotify"= |
383             | Parameter: =$web=	| Web name, optional, e.g. ="Main"=. The current web is taken if missing |
384             | Return: =$text=	  | Expanded text, e.g. ="Current user is <nop>TWikiGuest"= |
385             | Since:				  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
386             
387             ---+++ renderText( $text, $web ) ==> $text
388             
389             | Description:		 | Render text from TWiki markup into XHTML as defined in [[TWiki.TextFormattingRules]] |
390             | Parameter: =$text= | Text to render, e.g. ="*bold* text and =fixed font="= |
391             | Parameter: =$web=  | Web name, optional, e.g. ="Main"=. The current web is taken if missing |
392             | Return: =$text=	 | XHTML text, e.g. ="&lt;b>bold&lt;/b> and &lt;code>fixed font&lt;/code>"= |
393             | Since:				 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
394             
395             ---+++ internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) ==> $text
396             
397             | Description:				 | Render topic name and link label into an XHTML link. Normally you do not need to call this funtion, it is called internally by =renderText()= |
398             | Parameter: =$pre=		  | Text occuring before the TWiki link syntax, optional |
399             | Parameter: =$web=		  | Web name, required, e.g. ="Main"= |
400 rizwank 1.1 | Parameter: =$topic=		| Topic name to link to, required, e.g. ="WebNotify"= |
401             | Parameter: =$label=		| Link label, required. Usually the same as =$topic=, e.g. ="notify"= |
402             | Parameter: =$anchor=	  | Anchor, optional, e.g. ="#Jump"= |
403             | 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 |
404             | Return: =$text=			 | XHTML anchor, e.g. ="&lt;a href="/cgi-bin/view/Main/WebNotify#Jump">notify&lt;/a>"= |
405             | Since:						 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
406             
407             ---+++ search text( $text ) ==> $text
408             
409             | Description:		 | This is not a function, just a how-to note. Use: =expandCommonVariables("%<nop>SEARCH{...}%" );= |
410             | Parameter: =$text= | Search variable |
411             | Return: =$text=  | Search result in [[TWiki.FormattedSearch]] format |
412             
413             ---+++ formatTime( $time, $format, $timezone ) ==> $text
414             
415             | Description:				| Format the time in seconds into the desired time string |
416             | Parameter: =$time=	  | Time in epoc seconds |
417             | Parameter: =$format=	| Format type, optional. Default e.g. =" TWiki::Plugins::VERSION 1.010 (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"=) |
418             | Parameter: =$timezone= | either not defined (uses the displaytime setting), "gmtime", or "servertime" |
419             | Return: =$text=		  | Formatted time string |
420             | Note:						| if you used the removed formatGmTime, add a third parameter "gmtime" |
421 rizwank 1.1 | Since:					  | TWiki::Plugins::VERSION 1.020 (26 Feb 2004) |
422             
423             ---+++ formatGmTime( $time, $format ) ==> $text
424             
425             | NOTE:					 | <b>This function is deprecated and should not be used. Use formatTime() instead</b> |
426             | Description:			| Format the time to GM time |
427             | Parameter: =$time=	| Time in epoc seconds |
428             | 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"=) |
429             | Return: =$text=		| Formatted time string |
430             | Since:					| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
431             
432             ---++ Functions: File I/O
433             
434             ---+++ getDataDir( ) ==> $dir
435             
436             | Description:	| Get data directory (topic file root) |
437             | Return: =$dir= | Data directory, e.g. ="/twiki/data"= |
438             | Since:			| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
439             
440             ---+++ getPubDir( ) ==> $dir
441             
442 rizwank 1.1 | Description:	| Get pub directory (file attachment root). Attachments are in =$dir/Web/TopicName= |
443             | Return: =$dir= | Pub directory, e.g. ="/htdocs/twiki/pub"= |
444             | Since:			| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
445             
446             ---+++ readTopic( $web, $topic ) ==> ( $meta, $text )
447             
448             | NOTE:							 | <b>The following function is deprecated and should not be used. Use readTopicText() instead</b> |
449             | Description:					| Read topic text and meta data, regardless of access permissions. |
450             | Parameter: =$web=			 | Web name, required, e.g. ="Main"= |
451             | Parameter: =$topic=		  | Topic name, required, e.g. ="TokyoOffice"= |
452             | Return: =( $meta, $text )= | Meta data object and topic text |
453             | Since:							| TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
454             
455             ---+++ readTemplate( $name, $skin ) ==> $text
456             
457             | Description:		 | Read a template or skin file. Embedded [[TWiki.TWikiTemplates][template directives]] get expanded |
458             | Parameter: =$name= | Template name, e.g. ="view"= |
459             | Parameter: =$skin= | Skin name, optional, e.g. ="print"= |
460             | Return: =$text=	 | Template text |
461             | Since:				 | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
462             
463 rizwank 1.1 ---+++ readFile( $filename ) ==> $text
464             
465             | Description:			  | Read text file, low level. NOTE: For topics use readTopicText() |
466             | Parameter: =$filename= | Full path name of file |
467             | Return: =$text=		  | Content of file |
468             | Since:					  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
469             
470             ---+++ saveFile( $filename, $text )
471             
472             | Description:			  | Save text file, low level. NOTE: For topics use saveTopicText() |
473             | Parameter: =$filename= | Full path name of file |
474             | Parameter: =$text=	  | Text to save |
475             | Return:					 | none |
476             | Since:					  | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
477             | TODO:						| This should return an error for the different failure modes. |
478             
479             ---+++ writeWarning( $text )
480             
481             | Description:		 | Log Warning that may require admin intervention to data/warning.txt |
482             | Parameter: =$text= | Text to write; timestamp gets added |
483             | Return:				| none |
484 rizwank 1.1 | Since:				 | TWiki::Plugins::VERSION 1.020 (16 Feb 2004) |
485             
486             ---+++ writeDebug( $text )
487             
488             | Description:		 | Log debug message to data/debug.txt |
489             | Parameter: =$text= | Text to write; timestamp gets added |
490             | Return:				| none |
491             | Since:				 | TWiki::Plugins::VERSION 1.020 (16 Feb 2004) |
492             
493             ---++ Functions: System and I18N related
494             
495             ---+++ getRegularExpression( $regexName ) ==> $pattern
496             
497             | Description:				| Retrieves a TWiki predefined regular expression |
498             | Parameter: =$regexName= | Name of the regular expression to retrieve.  See notes below |
499             | Return:					  | String or precompiled regular expression matching as described below |
500             | Since:						| TWiki::Plugins::VERSION 1.020 (9 Feb 2004) |
501             
502             __Notes:__ TWiki internally precompiles several regular expressions to represent various string entities
503             in an I18N-compatible manner.  Plugins are encouraged to use these in matching where appropriate.
504             The following are guaranteed to be present; others may exist, but their use is unsupported and
505 rizwank 1.1 they may be removed in future TWiki versions.  Those which are marked "CC" are for use within
506             character classes and may not produce the desired results outside of them.
507             
508             | *Name* | *Matches* | *CC* |
509             | upperAlpha | Upper case characters | Y |
510             | lowerAlpha | Lower case characters | Y |
511             | mixedAlpha | Alphabetic characters | Y |
512             | mixedAlphaNum | Alphanumeric charactecs | Y |
513             | wikiWordRegex | WikiWords | N |
514             
515             Example:
516             <pre>
517             	my $upper = TWiki::Func::getRegularExpression("upperAlpha");
518             	my $alpha = TWiki::Func::getRegularExpression("mixedAlpha");
519             	my $capitalized = qr/[$upper][$alpha]+/;
520             </pre>
521             
522             ---+++ checkDependencies( $moduleName, $dependenciesRef ) ==> $error
523             
524             | Description: | Checks a list of Perl dependencies at runtime |
525             | Parameter: =$moduleName= | Context description e.g. name of the module being checked |
526 rizwank 1.1 | Parameter: =$dependenciesRef= | Reference of list of hashes containing dependency information; see notes below |
527             | Return: =$error= | undef if dependencies are OK, an error message otherwise |
528             | Since: | TWiki::Plugins::VERSION 1.025 (01 Aug 2004) |
529             
530             The dependencies are expressed as a list of hashes. Each hash contains
531             the name of a package and (optionally) a boolean constraint on the VERSION
532             variable in that package. It is usually used from the =initPlugin= method
533             like this:
534             <verbatim>
535             	if( $TWiki::Plugins::VERSION >= 1.025 ) {
536             		my @deps = (
537             				{ package => 'TWiki::Plugins::CalendarPlugin', constraint => '>= 5.030' },
538             				{ package => 'Time::ParseDate' },
539             				{ package => 'Apache::VMonitor' }
540             		);
541             		my $err = TWiki::Func::checkDependencies( $pluginName, \@deps );
542             		if( $err ) {
543             				TWiki::Func::writeWarning( $err );
544             				print STDERR $err; # print to webserver log file
545             				return 0; # plugin initialisation failed
546             		}
547 rizwank 1.1 	}
548             </verbatim>
549             
550             ---++ Copyright and License
551             
552             Copyright (C) 2000-2004 Peter Thoeny, Peter@Thoeny.com
553             
554             This program is free software; you can redistribute it and/or
555             modify it under the terms of the GNU General Public License
556             as published by the Free Software Foundation; either version 2
557             of the License, or (at your option) any later version.
558             
559             This program is distributed in the hope that it will be useful,
560             but WITHOUT ANY WARRANTY; without even the implied warranty of
561             MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
562             GNU General Public License for more details, published at 
563             http://www.gnu.org/copyleft/gpl.html
564             
565             </noautolink>
566             
567             __NOTE:__ Above text is copied from the TWiki::Plugins/PerlDocPlugin output of =TWiki::Func= in =twiki= format. In case you want to get dynamically updated documentation based on the actual Perl module, install the <nop>PerlDocPlugin and replace above text with =%<nop>PERLDOC{"TWiki::Func"}%=.
568 rizwank 1.1 
569             -- Main.PeterThoeny - 31 Dec 2002
570             
571             %STOPINCLUDE%
572