<<O>>  Difference Topic TWikiFuncModule (r1.6 - 29 Aug 2004 - PeterThoeny)
META TOPICPARENT TWikiPlugins
TOC: No TOC in "TWiki.TWikiFuncModule"
Line: 114 to 114

Functions: Preferences

Added:
>
>

extractParameters( $attr ) ==> %params

Description: Extract all parameters from a variable string and returns a hash of parameters
Parameter: $attr Attribute string
Return: %params Hash containing all parameters. The nameless parameter is stored in key _DEFAULT
Since: TWiki::Plugins::VERSION 1.025 (26 Aug 2004)

  • Example:
    • Variable: %TEST{ "nameless" name1="val1" name2="val2" }%
    • First extract text between {...} to get: "nameless" name1="val1" name2="val2"
    • Then call this on the text:
      my %params = TWiki::Func::extractParameters( $text );
    • The %params hash contains now:
      _DEFAULT => "nameless"
      name1 => "val1"
      name2 => "val2"

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

Description: Extract a named or unnamed value from a variable parameter string
Added:
>
>
Note: Function TWiki::Func::extractParameters is more efficient for extracting several parameters

Parameter: $attr Attribute string
Parameter: $name Name, optional
Return: $value Extracted value
Line: 404 to 422

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

Changed:
<
<
NOTE: The following function is deprecated and should not be used. Use formatTime() instead
>
>
NOTE: This function is deprecated and should not be used. Use formatTime() instead

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")
Line: 472 to 490
Return: none
Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
Changed:
<
<

Functions: I18N related

>
>

Functions: System and I18N related


getRegularExpression( $regexName ) ==> $pattern

Line: 501 to 519

 my $capitalized = qr/[$upper][$alpha]+/;
Changed:
<
<

setTopicRevisionTag( $web, $topic, $rev, $tag ) ==> $success

>
>

checkDependencies( $moduleName, $dependenciesRef ) ==> $error


Changed:
<
<
Description: sets a names tag on the specified revision
Parameter: $web webname
Parameter: $topic topic name
Parameter: $rev the revision we are taging
Parameter: $tag the string to tag with
Return: $success  
TODO: we need an error mechanism!
Since: TWiki::Plugins::VERSION 1.022 (20 April 2004)

checkDependencies

Description: checks a list of Perl dependencies at runtime
Parameter: $context Context description e.g. name of the module being checked
Parameter: $deps List of hashes containing dependency information
Returns: undef if dependencies are OK, an error message otherwise
>
>
Description: Checks a list of Perl dependencies at runtime
Parameter: $moduleName Context description e.g. name of the module being checked
Parameter: $dependenciesRef Reference of list of hashes containing dependency information; see notes below
Return: $error undef if dependencies are OK, an error message otherwise

Since: TWiki::Plugins::VERSION 1.025 (01 Aug 2004)

The dependencies are expressed as a list of hashes. Each hash contains

 <<O>>  Difference Topic TWikiFuncModule (r1.5 - 14 Aug 2004 - PeterThoeny)
META TOPICPARENT TWikiPlugins
TOC: No TOC in "TWiki.TWikiFuncModule"
Line: 18 to 18

 functions in other TWiki libraries you might impose a security hole and you will likely need to change your Plugin when you upgrade TWiki.
Changed:
<
<		 The "Since" field refers to the VERSION number of the TWiki::Plugins module and the date that the function was addded.
>
>		 The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.025. This can be shown by the %PLUGINVERSION{}% variable. The "Since" field in the function documentation refers to the VERSION number and the date that the function was addded.

Functions: CGI Environment

 <<O>>  Difference Topic TWikiFuncModule (r1.4 - 08 Aug 2004 - PeterThoeny)
META TOPICPARENT TWikiPlugins
TOC: No TOC in "TWiki.TWikiFuncModule"
Line: 11 to 11

Description

Changed:
<
<		 This module defines official funtions that Plugins and add-on scripts can use to interact with the TWiki engine and content.
>
>		 This module defines official funtions that 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.

Added:
>
>		 The "Since" field refers to the VERSION number of the TWiki::Plugins module and the date that the function was addded.

Functions: CGI Environment

getSessionValue( $key ) ==> $value

Line: 25 to 28
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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

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

Line: 32 to 36
Parameter: $key Session key
Parameter: $value Value associated with key
Return: $result "1" if success; undef if session plugin is not installed
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (17 Aug 2001)

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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

getUrlHost( ) ==> $host

Description: Get protocol, domain and optional port of script URL
Return: $host URL host, e.g. "http://example.com:80"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

Line: 50 to 57
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"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getScriptUrlPath( ) ==> $path

Description: Get script URL path
Return: $path URL path of TWiki scripts, e.g. "/cgi-bin"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

Line: 62 to 71
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"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

Line: 71 to 81
Parameter: $template Oops template name, e.g. "oopslocked"
Parameter: $param1 ... $param4 Parameter values for %PARAM1% ... %PARAM4% variables in template, optional
Return: $url URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&param1=joe"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getPubUrlPath( ) ==> $path

Description: Get pub URL path
Return: $path URL path of pub directory, e.g. "/pub"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

writeHeader( $query )

Description: Prints a basic content-type HTML header for text/html to standard out
Parameter: $query CGI query object
Return: none
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

redirectCgiQuery( $query, $url )

Line: 94 to 108
Parameter: $query CGI query object
Parameter: $url URL to redirect to
Return: none, never returns
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Functions: Preferences

Line: 103 to 118
Parameter: $attr Attribute string
Parameter: $name Name, optional
Return: $value Extracted value
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

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

Line: 118 to 134
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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

  • Example for Plugin setting:
    • MyPlugin? topic has: * Set COLOR = red
Line: 128 to 145
    • WebPreferences topic has: * Set WEBBGCOLOR = #FFFFC0
    • my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );
Added:
>
>

getPluginPreferencesValue( $key ) ==> $value

Description: Get a preferences value from your Plugin
Parameter: $key Plugin Preferences key w/o PLUGINNAME_ prefix.
Return: $value Preferences value; empty string if not set
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)

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")
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

getPluginPreferencesFlag( $key ) ==> $flag

Description: Get a preferences flag from your Plugin
Parameter: $key Plugin Preferences key w/o PLUGINNAME_ prefix.
Return: $flag Preferences flag "1" (if set), or "0" (for preferences values "off", "no" and "0", or values not set at all)
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)

getWikiToolName( ) ==> $name

Description: Get toolname as defined in TWiki.cfg
Return: $name Name of tool, e.g. "TWiki"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

getMainWebname( ) ==> $name

Description: Get name of Main web as defined in TWiki.cfg
Return: $name Name, e.g. "Main"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

getTwikiWebname( ) ==> $name

Description: Get name of TWiki documentation web as defined in TWiki.cfg
Return: $name Name, e.g. "TWiki"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

Functions: User Handling and Access Control

Line: 161 to 196

Description: Get default user name as defined in TWiki.cfg's $defaultUserName
Return: $loginName Default user name, e.g. "guest"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getWikiName( ) ==> $wikiName

Description: Get Wiki name of logged in user
Return: $wikiName Wiki Name, e.g. "JohnDoe"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getWikiUserName( $text ) ==> $wikiName

Description: Get Wiki name of logged in user with web prefix
Return: $wikiName Wiki Name, e.g. "Main.JohnDoe"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

Line: 184 to 223
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"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

isGuest( ) ==> $flag

Description: Test if logged in user is a guest
Return: $flag "1" if yes, "0" if not
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

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

Line: 205 to 247
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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

Functions: Content Handling

Line: 213 to 256
Description: Test if web exists
Parameter: $web Web name, required, e.g. "Sandbox"
Return: $flag "1" if web exists, "0" if not
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

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

Line: 220 to 264
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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

Changed:
<
<

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

>
>

getRevisionInfo($theWebName, $theTopic, $theRev, $attachment ) ==> ( $date, $user, $rev, $comment )


Description: Get revision info of a topic
Changed:
<
<
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" )
>
>
Parameter: $theWebName Web name, optional, e.g. "Main"
Parameter: $theTopic Topic name, required, e.g. "TokyoOffice"
Parameter: $theRev revsion number, or tag name (can be in the format 1.2, or just the minor number)
Parameter: $attachment attachment filename
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" )
$date in epochSec
$user  
$rev  
$comment WHAT COMMENT?
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

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

Line: 234 to 285
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.
Added:
>
>
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

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

Line: 242 to 294
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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

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

Line: 251 to 304
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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

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

Line: 261 to 315
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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

  • Example:
    my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 );
Line: 289 to 344

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" )
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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" )
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Functions: Rendering

Line: 305 to 362
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 TWikiGuest"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

Line: 312 to 370
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. "<b>bold</b> and <code>fixed font</code>"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

Line: 323 to 382
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;
set to "0" to suppress link for non-existing topics
Return: $text XHTML anchor, e.g. "<a href="/cgi-bin/view/Main/WebNotify#Jump">notify</a>"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

search text( $text ) ==> $text

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

formatTime( $time, $format, $timezone ) ==> $text

Description: Format the time in seconds into the desired time string
Parameter: $time Time in epoc seconds
Parameter: $format Format type, optional. Default e.g. " 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")
Parameter: $timezone either not defined (uses the displaytime setting), "gmtime", or "servertime"
Return: $text Formatted time string
Note: if you used the removed formatGmTime, add a third parameter "gmtime"
Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)

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

Added:
>
>
NOTE: The following function is deprecated and should not be used. Use formatTime() instead

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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Functions: File I/O

Line: 343 to 415

Description: Get data directory (topic file root)
Return: $dir Data directory, e.g. "/twiki/data"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getPubDir( ) ==> $dir

Description: Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName
Return: $dir Pub directory, e.g. "/htdocs/twiki/pub"
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

readTopic( $web, $topic ) ==> ( $meta, $text )

NOTE: The following function is deprecated and should not be used. Use readTopicText() instead
Description: Read topic text and meta data, regardless of access permissions.
Parameter: $web Web name, required, e.g. "Main"
Parameter: $topic Topic name, required, e.g. "TokyoOffice"
Return: ( $meta, $text ) Meta data object and topic text
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

Line: 355 to 438
Parameter: $name Template name, e.g. "view"
Parameter: $skin Skin name, optional, e.g. "print"
Return: $text Template text
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

saveFile( $filename, $text )

Line: 368 to 453
Parameter: $filename Full path name of file
Parameter: $text Text to save
Return: none
Added:
>
>
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
TODO: This should return an error for the different failure modes.

writeWarning( $text )

Description: Log Warning that may require admin intervention to data/warning.txt
Parameter: $text Text to write; timestamp gets added
Return: none
Added:
>
>
Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)

writeDebug( $text )

Description: Log debug message to data/debug.txt
Parameter: $text Text to write; timestamp gets added
Return: none
Added:
>
>
Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)

Functions: I18N related

getRegularExpression( $regexName ) ==> $pattern

Description: Retrieves a TWiki predefined regular expression
Parameter: $regexName Name of the regular expression to retrieve. See notes below
Return: String or precompiled regular expression matching as described below
Since: TWiki::Plugins::VERSION 1.020 (9 Feb 2004)

Notes: TWiki internally precompiles several regular expressions to represent various string entities in an I18N-compatible manner. Plugins are encouraged to use these in matching where appropriate. The following are guaranteed to be present; others may exist, but their use is unsupported and they may be removed in future TWiki versions. Those which are marked "CC" are for use within character classes and may not produce the desired results outside of them.

Name Matches up CC
wikiWordRegex WikiWords N
upperAlpha Upper case characters Y
lowerAlpha Lower case characters Y
mixedAlphaNum Alphanumeric charactecs Y
mixedAlpha Alphabetic characters Y

Example: 

   my $upper = TWiki::Func::getRegularExpression("upperAlpha");
   my $alpha = TWiki::Func::getRegularExpression("mixedAlpha");
   my $capitalized = qr/[$upper][$alpha]+/;

setTopicRevisionTag( $web, $topic, $rev, $tag ) ==> $success

Description: sets a names tag on the specified revision
Parameter: $web webname
Parameter: $topic topic name
Parameter: $rev the revision we are taging
Parameter: $tag the string to tag with
Return: $success  
TODO: we need an error mechanism!
Since: TWiki::Plugins::VERSION 1.022 (20 April 2004)

checkDependencies

Description: checks a list of Perl dependencies at runtime
Parameter: $context Context description e.g. name of the module being checked
Parameter: $deps List of hashes containing dependency information
Returns: undef if dependencies are OK, an error message otherwise
Since: TWiki::Plugins::VERSION 1.025 (01 Aug 2004)

The dependencies are expressed as a list of hashes. Each hash contains the name of a package and (optionally) a boolean constraint on the VERSION variable in that package. It is usually used from the initPlugin method like this: 

   if( $TWiki::Plugins::VERSION >= 1.025 ) {
      my @deps = (
            { package => 'TWiki::Plugins::CalendarPlugin', constraint => '>= 5.030' },
            { package => 'Time::ParseDate' },
            { package => 'Apache::VMonitor' }
      );
      my $err = TWiki::Func::checkDependencies( $pluginName, \@deps );
      if( $err ) {
            TWiki::Func::writeWarning( $err );
            print STDERR $err; # print to webserver log file
            return 0; # plugin initialisation failed
      }
   }

Copyright and License

Changed:
<
<		 Copyright (C) 2000-2003 Peter Thoeny, Peter@Thoeny.com
>
>		 Copyright (C) 2000-2004 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

 <<O>>  Difference Topic TWikiFuncModule (r1.3 - 02 Feb 2003 - PeterThoeny)
META TOPICPARENT TWikiPlugins
TOC: No TOC in "TWiki.TWikiFuncModule"
Line: 157 to 157

Functions: User Handling and Access Control

Changed:
<
<

getDefaultUserName( ) ==> $user

>
>

getDefaultUserName( ) ==> $loginName


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

getWikiName( ) ==> $wikiName

Line: 196 to 196
Parameter: $web Web name, required, e.g. "Sandbox"
Return: $flag "1" if yes, "0" if no
Changed:
<
<

checkAccessPermission( $type, $user, $text, $topic, $web ) ==> $flag

>
>

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"
Changed:
<
<
Parameter: $user WikiName of remote user, i.e. "Main.PeterThoeny"
>
>
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"
Line: 221 to 221
Parameter: $topic Topic name, required, e.g. "TokyoOffice", or "Main.TokyoOffice"
Return: $flag "1" if topic exists, "0" if not
Changed:
<
<

getRevisionInfo( $web, $topic ) ==> ( $date, $user, $rev )

>
>

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"
Changed:
<
<
Return: ( $date, $user, $rev ) List with: ( last update date, WikiName of last user, minor part of top revision number ), e.g. ( "01 Jan 2003", "PeterThoeny", "5" )
>
>
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 )

Line: 274 to 274

     TWiki::Func::redirectCgiQuery( $query, $text );
    return;
}
Changed:
<
<		 # do topic manipulation like:
>
>		 # do topic text manipulation like:

$text =~ s/old/new/g;
Added:
>
>		 # do meta data manipulation like:
$text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;

$oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
TWiki::Func::setTopicEditLock( $web, $topic, 0 );             # unlock topic
if( $oopsUrl ) {
 <<O>>  Difference Topic TWikiFuncModule (r1.2 - 31 Dec 2002 - PeterThoeny)
META TOPICPARENT TWikiPlugins
TOC: No TOC in "TWiki.TWikiFuncModule"
Line: 198 to 198

checkAccessPermission( $type, $user, $text, $topic, $web ) ==> $flag

Changed:
<
<
Description: Check access permission for a topic based on the TWikiAccessControl rules
Parameter: $type Access type, e.g. "VIEW", "CHANGE", ="CREATE="
>
>
Description: Check access permission for a topic based on the TWiki.TWikiAccessControl rules
Parameter: $type Access type, e.g. "VIEW", "CHANGE", "CREATE"

Parameter: $user 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"
Line: 228 to 228
Parameter: $topic Topic name, required, e.g. "TokyoOffice"
Return: ( $date, $user, $rev ) List with: ( last update date, WikiName of last user, minor part of top revision number ), e.g. ( "01 Jan 2003", "PeterThoeny", "5" )
Added:
>
>

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:
    my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 );
    if( $oopsUrl ) {
        TWiki::Func::redirectCgiQuery( $query, $oopsUrl );   # assuming valid query
        return;
    }
    my $text = TWiki::Func::readTopicText( $web, $topic );        # read topic text
    # check for oops URL in case of error:
    if( $text =~ /^http.*?\/oops/ ) {
        TWiki::Func::redirectCgiQuery( $query, $text );
        return;
    }
    # do topic manipulation like:
    $text =~ s/old/new/g;
    $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
    TWiki::Func::setTopicEditLock( $web, $topic, 0 );             # unlock topic
    if( $oopsUrl ) {
        TWiki::Func::redirectCgiQuery( $query, $oopsUrl );
        return;
    }

getPublicWebList( ) ==> @webs

Description: Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL flag set in the WebPreferences
Line: 251 to 306

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

Changed:
<
<
Description: Render text from TWiki markup into XHTML as defined in TextFormattingRules
>
>
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. "<b>bold</b> and <code>fixed font</code>"
Line: 271 to 326

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

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

Line: 292 to 347
Description: Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName
Return: $dir Pub directory, e.g. "/htdocs/twiki/pub"
Deleted:
<
<

readTopic( $web, $opic ) ==> ( $meta, $text )

Description: Read topic text and meta data, regardless of access permissions. NOTE: This function will be deprecated in a future release when meta data handling is changed
Parameter: $web Web name, required, e.g. "Main"
Parameter: $topic Topic name, required, e.g. "TokyoOffice"
Return: ( $meta, $text ) Meta data object and topic text

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

Changed:
<
<
Description: Read a template or skin file. Embedded TWikiTemplates directives get expanded
>
>
Description: Read a template or skin file. Embedded 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

Changed:
<
<
Description: Read text file, low level
>
>
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 )

Changed:
<
<
Description: Save text file, low level
>
>
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
Line: 350 to 398

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 PerlDocPlugin and replace above text with %PERLDOC{"TWiki::Func"}%.

Changed:
<
<		 -- PeterThoeny - 07 Dec 2002
>
>		 -- PeterThoeny - 31 Dec 2002

 <<O>>  Difference Topic TWikiFuncModule (r1.1 - 08 Dec 2002 - PeterThoeny)
Line: 1 to 1
Added:
>
>
META TOPICPARENT TWikiPlugins

TWiki::Func Module Documentation

Official list of stable TWiki functions for Plugin developers

Description

This module defines official funtions that 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 %PARAM1% ... %PARAM4% variables in template, optional
Return: $url URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&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: %TEST{ "nameless" name1="val1" name2="val2" }%
    • First extract text between {...} to get: "nameless" name1="val1" name2="val2"
    • Then call this on the text:
      my $noname = TWiki::Func::extractNameValuePair( $text );
      my $name1  = TWiki::Func::extractNameValuePair( $text, "name1" );
      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( ) ==> $user

Description: Get default user name as defined in TWiki.cfg's $defaultUserName
Return: $user 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, $user, $text, $topic, $web ) ==> $flag

Description: Check access permission for a topic based on the TWikiAccessControl rules
Parameter: $type Access type, e.g. "VIEW", "CHANGE", ="CREATE="
Parameter: $user 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, $user, $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, $user, $rev ) List with: ( last update date, WikiName of last user, minor part of top revision number ), e.g. ( "01 Jan 2003", "PeterThoeny", "5" )

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 %VARIABLES%
Parameter: $text Text with variables to expand, e.g. "Current user is %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 TWikiGuest"

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

Description: Render text from TWiki markup into XHTML as defined in 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. "<b>bold</b> and <code>fixed font</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;
set to "0" to suppress link for non-existing topics
Return: $text XHTML anchor, e.g. "<a href="/cgi-bin/view/Main/WebNotify#Jump">notify</a>"

search text( $text ) ==> $text

Description: This is not a function, just a how-to note. Use: expandCommonVariables("%SEARCH{...}%" );
Parameter: $text Search variable
Return: "$text" Search result in 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"

readTopic( $web, $opic ) ==> ( $meta, $text )

Description: Read topic text and meta data, regardless of access permissions. NOTE: This function will be deprecated in a future release when meta data handling is changed
Parameter: $web Web name, required, e.g. "Main"
Parameter: $topic Topic name, required, e.g. "TokyoOffice"
Return: ( $meta, $text ) Meta data object and topic text

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

Description: Read a template or skin file. Embedded TWikiTemplates 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
Parameter: $filename Full path name of file
Return: $text Content of file

saveFile( $filename, $text )

Description: Save text file, low level
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

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 PerlDocPlugin and replace above text with %PERLDOC{"TWiki::Func"}%.

-- PeterThoeny - 07 Dec 2002

View topic | Diffs | r1.6 | > | r1.5 | > | r1.4 | More
Revision r1.1 - 08 Dec 2002 - 06:40 - PeterThoeny
Revision r1.6 - 29 Aug 2004 - 08:48 - PeterThoeny