%META:TOPICINFO{author="PeterThoeny" date="1044147759" format="1.0" version="1.3"}%
%META:TOPICPARENT{name="TWikiPlugins"}%
%TOC%
%STARTINCLUDE%

---# TWiki::Func Module Documentation

_Official list of stable TWiki functions for Plugin developers_

<noautolink>

---++ Description

This module defines official funtions that [[TWiki.TWikiPlugins][Plugins]] and add-on 
scripts can use to interact with the TWiki engine and content.

Plugins should *only* use functions published in this module. If you use
functions in other TWiki libraries you might impose a security hole and 
you will likely need to change your Plugin when you upgrade TWiki.

---++ Functions: CGI Environment

---+++ getSessionValue( $key ) ==> $value

| Description: | Get a session value from the Session Plugin (if installed) |
| Parameter: =$key= | Session key |
| Return: =$value= | Value associated with key; empty string if not set; undef if session plugin is not installed |

---+++ setSessionValue( $key, $value ) ==> $result

| Description: | Set a session value via the Session Plugin (if installed) |
| Parameter: =$key= | Session key |
| Parameter: =$value= | Value associated with key |
| Return: =$result= | ="1"= if success; undef if session plugin is not installed |

---+++ getSkin( ) ==> $skin

| 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 |

---+++ getUrlHost( ) ==> $host

| Description: | Get protocol, domain and optional port of script URL |
| Return: =$host= | URL host, e.g. ="http://example.com:80"= |

---+++ getScriptUrl( $web, $topic, $script ) ==> $url

| Description: | Compose fully qualified URL |
| Parameter: =$web= | Web name, e.g. ="Main"= |
| Parameter: =$topic= | Topic name, e.g. ="WebNotify"= |
| Parameter: =$script= | Script name, e.g. ="view"= |
| Return: =$url= | URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"= |

---+++ getScriptUrlPath( ) ==> $path

| Description: | Get script URL path |
| Return: =$path= | URL path of TWiki scripts, e.g. ="/cgi-bin"= |

---+++ getViewUrl( $web, $topic ) ==> $url

| Description: | Compose fully qualified view URL |
| Parameter: =$web= | Web name, e.g. ="Main"=. The current web is taken if empty |
| Parameter: =$topic= | Topic name, e.g. ="WebNotify"= |
| Return: =$url= | URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"= |

---+++ getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) ==> $url

| Description: | Compose fully qualified "oops" dialog URL |
| Parameter: =$web= | Web name, e.g. ="Main"=. The current web is taken if empty |
| Parameter: =$topic= | Topic name, e.g. ="WebNotify"= |
| Parameter: =$template= | Oops template name, e.g. ="oopslocked"= |
| Parameter: =$param1= ... =$param4= | Parameter values for %<nop>PARAM1% ... %<nop>PARAM4% variables in template, optional |
| Return: =$url= | URL, e.g. ="http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&amp;param1=joe"= |

---+++ getPubUrlPath( ) ==> $path

| Description: | Get pub URL path |
| Return: =$path= | URL path of pub directory, e.g. ="/pub"= |

---+++ getCgiQuery( ) ==> $query

| 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 |

---+++ writeHeader( $query )

| Description: | Prints a basic content-type HTML header for text/html to standard out |
| Parameter: =$query= | CGI query object |
| Return: | none |

---+++ redirectCgiQuery( $query, $url )

| Description: | Redirect to URL |
| Parameter: =$query= | CGI query object |
| Parameter: =$url= | URL to redirect to |
| Return: | none, never returns |

---++ Functions: Preferences

---+++ extractNameValuePair( $attr, $name ) ==> $value

| Description: | Extract a named or unnamed value from a variable parameter string |
| Parameter: =$attr= | Attribute string |
| Parameter: =$name= | Name, optional |
| Return: =$value= | Extracted value |

	* Example:
		* Variable: =%<nop>TEST{ "nameless" name1="val1" name2="val2" }%=
		* First extract text between ={...}= to get: ="nameless" name1="val1" name2="val2"=
		* Then call this on the text: <br />
		=my $noname = TWiki::Func::extractNameValuePair( $text );= <br />
		=my $name1  = TWiki::Func::extractNameValuePair( $text, "name1" );= <br />
		=my $name2  = TWiki::Func::extractNameValuePair( $text, "name2" );=

---+++ getPreferencesValue( $key, $web ) ==> $value

| Description: | Get a preferences value from TWiki or from a Plugin |
| Parameter: =$key= | Preferences key |
| 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 |

	* Example for Plugin setting:
		* MyPlugin topic has: =* Set COLOR = red=
		* Use ="MYPLUGIN_COLOR"= for =$key=
		* =my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );=

	* Example for preferences setting:
		* WebPreferences topic has: =* Set WEBBGCOLOR = #FFFFC0=
		* =my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );=

---+++ getPreferencesFlag( $key, $web ) ==> $value

| Description: | Get a preferences flag from TWiki or from a Plugin |
| Parameter: =$key= | Preferences key |
| 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"=) |

	* Example for Plugin setting:
		* MyPlugin topic has: =* Set SHOWHELP = off=
		* Use ="MYPLUGIN_SHOWHELP"= for =$key=
		* =my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );=

---+++ getWikiToolName( ) ==> $name

| Description: | Get toolname as defined in TWiki.cfg |
| Return: =$name= | Name of tool, e.g. ="TWiki"= |

---+++ getMainWebname( ) ==> $name

| Description: | Get name of Main web as defined in TWiki.cfg |
| Return: =$name= | Name, e.g. ="Main"= |

---+++ getTwikiWebname( ) ==> $name

| Description: | Get name of TWiki documentation web as defined in TWiki.cfg |
| Return: =$name= | Name, e.g. ="TWiki"= |

---++ Functions: User Handling and Access Control

---+++ getDefaultUserName( ) ==> $loginName

| Description: | Get default user name as defined in TWiki.cfg's =$defaultUserName= |
| Return: =$loginName= | Default user name, e.g. ="guest"= |

---+++ getWikiName( ) ==> $wikiName

| Description: | Get Wiki name of logged in user |
| Return: =$wikiName= | Wiki Name, e.g. ="JohnDoe"= |

---+++ getWikiUserName( $text ) ==> $wikiName

| Description: | Get Wiki name of logged in user with web prefix |
| Return: =$wikiName= | Wiki Name, e.g. ="Main.JohnDoe"= |

---+++ wikiToUserName( $wikiName ) ==> $loginName

| Description: | Translate a Wiki name to a login name based on [[Main.TWikiUsers]] topic |
| Parameter: =$wikiName= | Wiki name, e.g. ="Main.JohnDoe"= or ="JohnDoe"= |
| Return: =$loginName= | Login name of user, e.g. ="jdoe"= |

---+++ userToWikiName( $loginName, $dontAddWeb ) ==> $wikiName

| Description: | Translate a login name to a Wiki name based on [[Main.TWikiUsers]] topic |
| Parameter: =$loginName= | Login name, e.g. ="jdoe"= |
| Parameter: =$dontAddWeb= | Do not add web prefix if ="1"= |
| Return: =$wikiName= | Wiki name of user, e.g. ="Main.JohnDoe"= or ="JohnDoe"= |

---+++ isGuest( ) ==> $flag

| Description: | Test if logged in user is a guest |
| Return: =$flag= | ="1"= if yes, ="0"= if not |

---+++ permissionsSet( $web ) ==> $flag

| Description: | Test if any access restrictions are set for this web, ignoring settings on individual pages |
| Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
| Return: =$flag= | ="1"= if yes, ="0"= if no |

---+++ checkAccessPermission( $type, $wikiName, $text, $topic, $web ) ==> $flag

| Description: | Check access permission for a topic based on the [[TWiki.TWikiAccessControl]] rules |
| Parameter: =$type= | Access type, e.g. ="VIEW"=, ="CHANGE"=, ="CREATE"= |
| Parameter: =$wikiName= | WikiName of remote user, i.e. ="Main.PeterThoeny"= |
| Parameter: =$text= | Topic text, optional. If empty, topic =$web.$topic= is consulted |
| Parameter: =$topic= | Topic name, required, e.g. ="PrivateStuff"= |
| Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
| Return: =$flag= | ="1"= if access may be granted, ="0"= if not |

---++ Functions: Content Handling

---+++ webExists( $web ) ==> $flag

| Description: | Test if web exists |
| Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
| Return: =$flag= | ="1"= if web exists, ="0"= if not |

---+++ topicExists( $web, $topic ) ==> $flag

| Description: | Test if topic exists |
| Parameter: =$web= | Web name, optional, e.g. ="Main"= |
| Parameter: =$topic= | Topic name, required, e.g. ="TokyoOffice"=, or ="Main.TokyoOffice"= |
| Return: =$flag= | ="1"= if topic exists, ="0"= if not |

---+++ getRevisionInfo( $web, $topic ) ==> ( $date, $loginName, $rev )

| Description: | Get revision info of a topic |
| Parameter: =$web= | Web name, optional, e.g. ="Main"= |
| Parameter: =$topic= | Topic name, required, e.g. ="TokyoOffice"= |
| Return: =( $date, $loginName, $rev )= | List with: ( last update date, login name of last user, minor part of top revision number ), e.g. =( "01 Jan 2003", "phoeny", "5" )= |

---+++ checkTopicEditLock( $web, $topic ) ==> ( $oopsUrl, $loginName, $unlockTime )

| Description: | Check if topic has an edit lock by a user |
| Parameter: =$web= | Web name, e.g. ="Main"=, or empty |
| 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. |

---+++ setTopicEditLock( $web, $topic, $lock ) ==> $oopsUrl

| Description: | Lock topic for editing, or unlock when done |
| Parameter: =$web= | Web name, e.g. ="Main"=, or empty |
| Parameter: =$topic= | Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"= |
| 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 |

---+++ readTopicText( $web, $topic, $rev, $ignorePermissions ) ==> $text

| Description: | Read topic text, including meta data |
| Parameter: =$web= | Web name, e.g. ="Main"=, or empty |
| Parameter: =$topic= | Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"= |
| 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. |
| 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 |

---+++ saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) ==> $oopsUrl

| 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. |
| Parameter: =$web= | Web name, e.g. ="Main"=, or empty |
| Parameter: =$topic= | Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"= |
| Parameter: =$text= | Topic text to save, assumed to include meta data |
| Parameter: =$ignorePermissions=  | Set to ="1"= if checkAccessPermission() is already performed and OK |
| 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 |

	* Example: <br />
	=my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 );= <br />
	=if( $oopsUrl ) {= <br />
	=&nbsp;	TWiki::Func::redirectCgiQuery( $query, $oopsUrl );	# assuming valid query= <br />
	=&nbsp;	return;= <br />
	=}= <br />
	=my $text = TWiki::Func::readTopicText( $web, $topic );		  # read topic text= <br />
	=# check for oops URL in case of error:= <br />
	=if( $text =~ /^http.*?\/oops/ ) {= <br />
	=&nbsp;	TWiki::Func::redirectCgiQuery( $query, $text );= <br />
	=&nbsp;	return;= <br />
	=}= <br />
	=# do topic text manipulation like:= <br />
	=$text =~ s/old/new/g;= <br />
	=# do meta data manipulation like:= <br />
	=$text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;= <br />
	=$oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text= <br />
	=TWiki::Func::setTopicEditLock( $web, $topic, 0 );				 # unlock topic= <br />
	=if( $oopsUrl ) {= <br />
	=&nbsp;	TWiki::Func::redirectCgiQuery( $query, $oopsUrl );= <br />
	=&nbsp;	return;= <br />
	=}=

---+++ getPublicWebList( ) ==> @webs

| 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" )= |

---+++ getTopicList( $web ) ==> @topics

| Description: | Get list of all topics in a web |
| Parameter: =$web= | Web name, required, e.g. ="Sandbox"= |
| Return: =@topics= | Topic list, e.g. =( "WebChanges",  "WebHome", "WebIndex", "WebNotify" )= |

---++ Functions: Rendering

---+++ expandCommonVariables( $text, $topic, $web ) ==> $text

| Description: | Expand all common =%<nop>VARIABLES%= |
| Parameter: =$text= | Text with variables to expand, e.g. ="Current user is %<nop>WIKIUSER%"= |
| Parameter: =$topic= | Current topic name, e.g. ="WebNotify"= |
| 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"= |

---+++ renderText( $text, $web ) ==> $text

| Description: | Render text from TWiki markup into XHTML as defined in [[TWiki.TextFormattingRules]] |
| Parameter: =$text= | Text to render, e.g. ="*bold* text and =fixed font="= |
| Parameter: =$web= | Web name, optional, e.g. ="Main"=. The current web is taken if missing |
| Return: =$text= | XHTML text, e.g. ="&lt;b>bold&lt;/b> and &lt;code>fixed font&lt;/code>"= |

---+++ internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) ==> $text

| 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()= |
| Parameter: =$pre= | Text occuring before the TWiki link syntax, optional |
| Parameter: =$web= | Web name, required, e.g. ="Main"= |
| Parameter: =$topic= | Topic name to link to, required, e.g. ="WebNotify"= |
| Parameter: =$label= | Link label, required. Usually the same as =$topic=, e.g. ="notify"= |
| Parameter: =$anchor= | Anchor, optional, e.g. ="#Jump"= |
| Parameter: =$createLink= | Set to ="1"= to add question linked mark after topic name if topic does not exist;<br /> set to ="0"= to suppress link for non-existing topics |
| Return: =$text= | XHTML anchor, e.g. ="&lt;a href="/cgi-bin/view/Main/WebNotify#Jump">notify&lt;/a>"= |

---+++ search text( $text ) ==> $text

| Description: | This is not a function, just a how-to note. Use: =expandCommonVariables("%<nop>SEARCH{...}%" );= |
| Parameter: =$text= | Search variable |
| Return: ="$text"= | Search result in [[TWiki.FormattedSearch]] format |

---+++ formatGmTime( $time, $format ) ==> $text

| 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 |

---++ Functions: File I/O

---+++ getDataDir( ) ==> $dir

| Description: | Get data directory (topic file root) |
| Return: =$dir= | Data directory, e.g. ="/twiki/data"= |

---+++ getPubDir( ) ==> $dir

| Description: | Get pub directory (file attachment root). Attachments are in =$dir/Web/TopicName= |
| Return: =$dir= | Pub directory, e.g. ="/htdocs/twiki/pub"= |

---+++ readTemplate( $name, $skin ) ==> $text

| Description: | Read a template or skin file. Embedded [[TWiki.TWikiTemplates][template directives]] get expanded |
| Parameter: =$name= | Template name, e.g. ="view"= |
| Parameter: =$skin= | Skin name, optional, e.g. ="print"= |
| Return: =$text= | Template text |

---+++ readFile( $filename ) ==> $text

| Description: | Read text file, low level. NOTE: For topics use readTopicText() |
| Parameter: =$filename= | Full path name of file |
| Return: =$text= | Content of file |

---+++ saveFile( $filename, $text )

| Description: | Save text file, low level. NOTE: For topics use saveTopicText() |
| Parameter: =$filename= | Full path name of file |
| Parameter: =$text= | Text to save |
| Return: | none |

---+++ writeWarning( $text )

| Description: | Log Warning that may require admin intervention to data/warning.txt |
| Parameter: =$text= | Text to write; timestamp gets added |
| Return: | none |

---+++ writeDebug( $text )

| Description: | Log debug message to data/debug.txt |
| Parameter: =$text= | Text to write; timestamp gets added |
| Return: | none |

---++ Copyright and License

Copyright (C) 2000-2003 Peter Thoeny, Peter@Thoeny.com

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details, published at 
http://www.gnu.org/copyleft/gpl.html

</noautolink>

__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"}%=.

-- Main.PeterThoeny - 31 Dec 2002

%STOPINCLUDE%
