spaceOutWikiWord( $word, $sep ) -> $text

Changed:

<<

Spaces out a wiki word by inserting a string (default: one space) between each word component.
With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.

>>

Spaces out a wiki word by inserting a string between each word component.
Word component boundaries are transitions from lowercase to uppercase or numeric,
from numeric to uppercase or lowercase, and from uppercase to numeric characters.

Parameter $sep defines the separator between the word components, the default is a space.

$TWiki::Plugins::VERSION. The 'Since' field in the function
documentation refers to $TWiki::Plugins::VERSION.

Changed:

<<

Notes on use of $TWiki::Plugins::VERSION (from 1.2 forwards):

>>

Notes on use of $TWiki::Plugins::VERSION 6.00 and later:

Changed:

<<

If the major version (e.g. 1.) is the same then any plugin coded to use any earlier revision of the 1. API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to require plugins to be recoded.

If the minor version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, deprecation of functions in the interface trigger a minor version increment. Note that deprecated functions are not removed, they are merely frozen, and plugin authors are recommended to stop using them.

Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.

>>

The version number is now aligned with the TWiki release version.

A TWiki-6.7.8 release will have a $TWiki::Plugins::VERSION = 6.78.

In an unlikely case where the patch number is 10 or larger, the patch number is added to the previous patch number. For example, TWiki-6.7.9 will have version 6.79, TWiki-6.7.10 will have 6.7910, and TWiki-6.7.11 will have 6.7911. This ensures that the version number can sort properly.

TWiki::Plugins::VERSION also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of TWiki::Plugins::VERSION it relates to.

getExternalResource( $url, \@headers, \%params ) -> $response

Get whatever is at the other end of a URL (using an HTTP GET request). Will
only work for encrypted protocols such as https if the LWP CPAN module is

Line: 121 to 113

Note that the $url may have an optional user and password, as specified by
the relevant RFC. Any proxy set in configure is honored.

Changed:

<<

Optional headers may be supplied of form 'name1', 'value1', 'name2', 'value2'.
Do not add a User-Agent header, it will be added.

>>

Optional parameters may be supplied:

\@headers (an array ref): Additional HTTP headers of form 'name1', 'value1', 'name2', 'value2'. User-Agent header is set to "TWiki::Net/### libwww-perl/#.##" by default, where ### is the revision number of TWiki::Net and #.## is the version of LWP.

$ignorePermissions - Set to "1" if checkAccessPermission() is already performed and OK.

$opts may include:

dontlog

don't log this change in twiki log

comment

comment for save

Line: 1173 to 1220

$name - template file name

$skin - comma-separated list of skins to use (default: current skin)

$web - the web to look in for topics that contain templates (default: current web)

Changed:

<<

Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)

>>

Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)

Since: TWiki::Plugins::VERSION 1.1

Line: 1188 to 1235

expandTemplate( $def ) -> $string

Changed:

<<

Do a , only expanding the template (not expanding any variables other than %TMPL)

>>

Do a %TMPL:P{$def}%, only expanding the template (not expanding any variables other than %TMPL)

$def - template name

Return: the text of the expanded template

Since: TWiki::Plugins::VERSION 1.1

Changed:

<<

A template is defined using a %TMPL:DEF% statement in a template

>>

A template is defined using a %TMPL:DEF% statement in a template

file. See the documentation on TWiki templates for more information.

Line: 1209 to 1256

Changed:

<<

redirectCgiQuery( $query, $url, $passthru )

>>

redirectCgiQuery( $query, $url, $passthru, $viaCache )

Redirect to URL

$query - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.

$url - URL to redirect to

$passthru - enable passthrough.

Added:

>>

$viaCache - forcibly cache a redirect CGI query. It cuts off all the params in a GET url and replace with a "?$cache=..." param. "$viaCache" is meaningful only if "$passthru" is true.

Return: none

Line: 1248 to 1296

addToHEAD( $id, $header, $requires )

Adds $header to the HTML header (the tag).

Changed:

<<

This is useful for Plugins that want to include some javascript custom css.

>>

This is useful for Plugins that want to include some javascript and custom css.

$id - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)

$header - the HTML to be added to the section. The HTML must be valid in a HEAD tag - no checks are performed.

Changed:

<<

requires optional, comma-separated list of id's of other head blocks this one depends on.

>>

requires optional, comma-separated list of id's of other head blocks this one depends on. Those blocks will be loaded first.

All TWiki variables present in $header will be expanded before being inserted into the section.

Line: 1357 to 1405

Changed:

<<

expandVariablesOnTopicCreation ( $text ) -> $text

>>

expandVariablesOnTopicCreation ( $text, $web, $topic ) -> $text

Expand the limited set of variables that are always expanded during topic creation

$text - the text to process

Added:

>>

$web - name of web, optional

$topic - name of topic, optional

Return: text with variables expanded

Since: TWiki::Plugins::VERSION 1.1

Line: 1478 to 1528

(ie, with the name of the function instead of the alias) will not work.

Added:

>>

registerExternalHTTPHandler( \&fn )

Should only be called from initPlugin.

Adds a function to modify all the HTTP requests to any external resources.

\&fn - Reference to the function.

The handler function must be of the form:

sub handler(\%session, $url) -> (\@headers, \%params)

where:

\%session - a reference to the TWiki session object (may be ignored)

$url - a URL being requested

The returned \@headers and \%params are added to the request in the same
manner as getExternalResource, except that \%params will not override any
entries that have been set earlier.
All the params explicitly given by the caller of getExternalResource or
postExternalResource will have the highest precedence.

Note: Function TWiki::Func::extractParameters is more efficient for extracting several parameters

entityEncode( $text, $extra ) -> $text

Entity encode text.

$text - Text to encode, may be empty

$extra - Additional characters to include in the set of encoded characters, optional

Return: $text Entity encoded text

Since: TWiki::Plugins::VERSION 6.00

Escape special characters to HTML numeric entities. This is not a generic
encoding, it is tuned specifically for use in TWiki.

HTML4.0 spec:
"Certain characters in HTML are reserved for use as markup and must be
escaped to appear literally. The "<" character may be represented with
an entity, &lt;. Similarly, ">"
is escaped as &gt;, and "&" is escaped
as &amp;. If an attribute value contains a
double quotation mark and is delimited by double quotation marks, then the
quote should be escaped as &quot;.

Other entities exist for special characters that cannot easily be entered
with some keyboards..."

This method encodes HTML special and any non-printable ASCII
characters (except for \n and \r) using numeric entities.

FURTHER this method also encodes characters that are special in TWiki
meta-language.

$extras is an optional param that may be used to include additional
characters in the set of encoded characters. It should be a string
containing the additional chars.

entityDecode( $text ) -> $text

Decode all numeric entities (e.g. &#123;). Does not decode
named entities such as &amp; (use HTML::Entities for that)

$text - Text to decode, may be empty

Return: $text Entity decoded text

Since: TWiki::Plugins::VERSION 6.00

urlEncode( $text ) -> $text

URL encode text, mainly used to encode URL parameters.

$text - Text to encode, may be empty

Return: $text URL encoded text

Since: TWiki::Plugins::VERSION 6.00

Encoding is done by converting characters that are illegal in
URLs to their %NN equivalents. This method is used for encoding
strings that must be embedded verbatim in URLs; it cannot
be applied to URLs themselves, as it escapes reserved
characters such as = and ?.

RFC 1738, Dec. '94:

...Only alphanumerics [0-9a-zA-Z], the special
characters $-_.+!*'(), and reserved characters used for their
reserved purposes may be used unencoded within a URL.

Reserved characters are $&+,/:;=?@ - these are also encoded by
this method.

This URL-encoding handles all character encodings including ISO-8859-*,
KOI8-R, EUC-* and UTF-8.

This may not handle EBCDIC properly, as it generates an EBCDIC URL-encoded
URL, but mainframe web servers seem to translate this outbound before it hits browser
- see CGI::Util::escape for another approach.

Searching

Search for a string in the content of a web. The search is over all content, including meta-data. Meta-data matches will be returned as formatted lines within the topic content (meta-data matches are returned as lines of the format %META:\w+{.*}%)

Line: 1396 to 1484

\%option - reference to an options hash

The \%options hash may contain the following options:

type - if regex will perform a egrep-syntax RE search (default '')

Changed:

<<

casesensitive - false to ignore case (defaulkt true)

>>

casesensitive - false to ignore case (default true)

files_without_match - true to return files only (default false). If files_without_match is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).

The return value is a reference to a hash which maps each matching topic

Line: 1415 to 1503

Since: TWiki::Plugins::VERSION 1.1

Changed:

<<

Plugin-specific file handling

>>

Plugin-specific File Handling

Added:

>>

getWorkArea( $pluginName ) -> $directorypath

Gets a private directory for Plugin use. The Plugin is entirely responsible

isValidWikiWord ( $text ) -> $boolean

extractParameters($attr ) -> %params

Extract all parameters from a variable string and returns a hash of parameters

Line: 1630 to 1733

name2 => "val2"

Added:

>>

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

Extract a named or unnamed value from a variable parameter string

Line: 1649 to 1753

my $val2 = TWiki::Func::extractNameValuePair( $text, "name2" );

Added:

>>

Deprecated functions

From time-to-time, the TWiki developers will add new functions to the interface (either to TWikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release, and probably longer, though this cannot be guaranteed.

Line: 1666 to 1771

The following functions are retained for compatibility only. You should
stop using them as soon as possible.

getCanonicalUserID( $user ) -> $cUID

Added:

>>

$user can be a login, wikiname or web.wikiname

Return the cUID of the specified user. A cUID is a unique identifier which
is assigned by TWiki for each user.
BEWARE: While the default TWikiUserMapping uses a cUID that looks like a user's
LoginName, some characters are modified to make them compatible with rcs.

If $user is undefined Get the cUID of logged in user, and will generally be
'BaseUserMapping_666'

>>

If $user is undefined, it assumes the currently logged-in user.

Changed:

<<

$user can be a cUID, login, wikiname or web.wikiname

Return: $cUID an internal unique and transportable escaped identifier for
registered users (they can be autogenerated for an authenticated but unregistered
user)

>>

Return: $cUID, an internal unique and portable escaped identifier for
registered users. This may be autogenerated for an authenticated but
unregistered user.

Since: TWiki::Plugins::VERSION 1.2

Line: 433 to 431

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Changed:

<<

wikiToUserName( $wikiName ) -> $loginName

Translate a Wiki name (or login name or cUID, if it can) to a login name.

$wikiName - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'

>>

wikiToUserName( $id ) -> $loginName

Translate a Wiki name to a login name.

$id - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'. Since TWiki 4.2.1, $id may also be a login name. This will normally be transparent, but should be borne in mind if you have login names that are also legal wiki names.

Return: $loginName Login name of user, e.g. 'jdoe', or undef if not
matched.

Line: 450 to 452

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

Translate a login name to a Wiki name

Changed:

<<

$loginName - Login name, e.g. 'jdoe'

>>

$loginName - Login name, e.g. 'jdoe'. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.

$dontAddWeb - Do not add web prefix if "1"

Return: $wikiName Wiki name of user, e.g. 'Main.JohnDoe' or 'JohnDoe'

Changed:

<<

userToWikiName will always return a name, if the user does not

>>

userToWikiName will always return a name. If the user does not

exist in the mapping, the $loginName parameter is returned. (backward compatibility)

Refer to EmptyPlugin and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.

Line: 20 to 20

The version of the TWiki::Func module is defined by the VERSION number of the
TWiki::Plugins module, currently 6.02. This can be shown

Changed:

<<

by the %PLUGINVERSION% variable. The 'Since' field in the function
documentation refers to the VERSION number and the date that the function
was addded.

Note: Beware! These methods should only ever be called
from the context of a TWiki Plugin. They require a Plugins SESSION context to be
established before they are called, and will not work if simply called from
another TWiki module. For example,

use TWiki;
print TWiki::Func::getSkin(),"\n";

will fail with Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83.

If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example,
the script:

by the %PLUGINVERSION% TWiki variable, and accessed in code using
$TWiki::Plugins::VERSION. The 'Since' field in the function
documentation refers to $TWiki::Plugins::VERSION.

Notes on use of $TWiki::Plugins::VERSION (from 1.2 forwards):

If the major version (e.g. 1.) is the same then any plugin coded to use any earlier revision of the 1. API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to require plugins to be recoded.

If the minor version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, deprecation of functions in the interface trigger a minor version increment. Note that deprecated functions are not removed, they are merely frozen, and plugin authors are recommended to stop using them.

Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.

TWiki::Plugins::VERSION also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of TWiki::Plugins::VERSION it relates to.

A full history of the changes to this API can be found at the end of this
topic.

... - an arbitrary number of name,value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX

>>

... - an arbitrary number of name=>value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX

getExternalResource( $url ) -> $response

getPubUrlPath( ) -> $path

Get whatever is at the other end of a URL (using an HTTP GET request). Will
only work for encrypted protocols such as https if the LWP CPAN module is
installed.

Note that the $url may have an optional user and password, as specified by
the relevant RFC. Any proxy set in configure is honoured.

The $response is an object that is known to implement the following subset of
the methods of LWP::Response. It may in fact be an LWP::Response object,
but it may also not be if LWP is not available, so callers may only assume
the following subset of methods is available:

code()

message()

header($field)

content()

is_error()

is_redirect()

Note that if LWP is not available, this function:

can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another protocol is required, you are strongly recommended to require LWP.

Will not parse multipart content

In the event of the server returning an error, then is_error() will return
true, code() will return a valid HTTP status code
as specified in RFC 2616 and RFC 2518, and message() will return the
message that was received from
the server. In the event of a client-side error (e.g. an unparseable URL)
then is_error() will return true and message() will return an explanatory
message. code() will return 400 (BAD REQUEST).

Changed:

<<

Get pub URL path

>>

Note: Callers can easily check the availability of other HTTP::Response methods
as follows:

Changed:

<<

Return: $path URL path of pub directory, e.g. "/pub"

>>

my $response = TWiki::Func::getExternalResource($url);
if (!$response->is_error() && $response->isa('HTTP::Response')) {
... other methods of HTTP::Response may be called
} else {
... only the methods listed above may be called
}

Context identifiers can be used to communicate between Plugins, and between

Line: 210 to 243

Since: TWiki::Plugins::VERSION 1.1

Added:

>>

pushTopicContext($web, $topic)

$web - new web

$topic - new topic

Change the TWiki context so it behaves as if it was processing $web.$topic
from now on. All the preferences will be reset to those of the new topic.
Note that if the new topic is not readable by the logged in user due to
access control considerations, there will not be an exception. It is the
duty of the caller to check access permissions before changing the topic.

It is the duty of the caller to restore the original context by calling
popTopicContext.

Note that this call does not re-initialise plugins, so if you have used
global variables to remember the web and topic in initPlugin, then those
values will be unchanged.

Since: TWiki::Plugins::VERSION 1.2

popTopicContext()

Returns the TWiki context to the state it was in before the
pushTopicContext was called.

Since: TWiki::Plugins::VERSION 1.2

Preferences

Line: 281 to 341

preferences set in the plugin topic will be ignored.

Added:

>>

setPreferencesValue($name, $val)

Set the preferences value so that future calls to getPreferencesValue will
return this value, and %$name% will expand to the preference when used in
future variable expansions.

The preference only persists for the rest of this request. Finalised
preferences cannot be redefined using this function.

Returns 1 if the preference was defined, and 0 otherwise.

getWikiToolName( ) -> $name

Get toolname as defined in TWiki.cfg

Line: 319 to 389

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Changed:

<<

getWikiName( ) -> $wikiName

>>

getCanonicalUserID( $user ) -> $cUID

Return the cUID of the specified user. A cUID is a unique identifier which
is assigned by TWiki for each user.
BEWARE: While the default TWikiUserMapping uses a cUID that looks like a user's
LoginName, some characters are modified to make them compatible with rcs.
Additionally, other usermappings will use other conventions - the JoomlauserMapping
for example, has cUIDs like 'JoomlaeUserMapping_1234'.

If $user is undefined Get the cUID of logged in user, and will generally be
'BaseUserMapping_666'

$user can be a cUID, login, wikiname or web.wikiname

Return: $cUID an internal unique and transportable escaped identifier for
registered users (they can be autogenerated for an authenticated but unregistered
user)

Changed:

<<

Get Wiki name of logged in user

>>

Since: TWiki::Plugins::VERSION 1.2

getWikiName( $user ) -> $wikiName

return the WikiName of the specified user
if $user is undefined Get Wiki name of logged in user

$user can be a cUID, login, wikiname or web.wikiname

Return: $wikiName Wiki Name, e.g. 'JohnDoe'

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Changed:

<<

getWikiUserName( ) -> $wikiName

>>

getWikiUserName( $user ) -> $wikiName

return the userWeb.WikiName of the specified user
if $user is undefined Get Wiki name of logged in user

Find the wikinames of all users who have the given email address as their
registered address. Since several users could register with the same email
address, this returns a list of wikinames rather than a single wikiname.

eachChangeSince($web, $time) -> $iterator

Get an iterator over the list of all the changes in the given web between
$time and now. $time is a time in seconds since 1st Jan 1970, and is not
guaranteed to return any changes that occurred before (now -
{Store}{RememberChangesFor}). {Store}{RememberChangesFor}) is a
setting in configure. Changes are returned in most-recent-first
order.

Use it as follows:

my $iterator = TWiki::Func::eachChangeSince(
$web, time() - 7 * 24 * 60 * 60); # the last 7 days
while ($it->hasNext()) {
my $change = $it->next();
# $change is a perl hash that contains the following fields:
# topic => topic name
# user => wikiname - wikiname of user who made the change
# time => time of the change
# revision => revision number *after* the change
# more => more info about the change (e.g. 'minor')
}

$web and $topic are parsed as described in the documentation for normalizeWebTopicName.

Added:

>>

Specifically, the Main is used if $web is not specified and $topic has no web specifier.
To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.

Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

Line: 526 to 757

$web Web name, e.g. "Main", or empty

$topic Topic name, e.g. "MyTopic", or "Main.MyTopic"

Changed:

<<

$lock 1 to lease the topic, 0 to clear the lease=

>>

$lock 1 to lease the topic, 0 to clear an existing lease

Takes out a "lease" on the topic. The lease doesn't prevent
anyone from editing and changing the topic, but it does redirect them

Line: 643 to 874

NOTE: if you are trying to get revision info for a topic, use
$meta->getRevisionInfo instead if you can - it is significantly

Changed:

<<

more efficient, and returns a user object that contains other user
information.

NOTE: prior versions of TWiki may under some circumstances have returned
the login name of the user rather than the wiki name; the code documentation
was totally unclear, and we have been unable to establish the intent.
However the wikiname is obviously more useful, so that is what is returned.

>>

more efficient.

Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

Line: 692 to 917

$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

Changed:

<<

This method is more efficient than readTopic, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer..

>>

This method is more efficient than readTopic, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer.

writeHeader( $query, $contentLength )

$query - CGI query object. If not given, the default CGI query will be used. In most cases you should not pass this parameter.

$contentLength - Length of content

>>

$query - CGI query object. If not given, the default CGI query will be used (optional, in most cases you should not pass this parameter)

$contentLength - Length of content (optional, in most cases you should not pass this parameter)

Return: none

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Line: 879 to 1104

same TWiki installation. If $passthru is set to a true value, then TWiki
will save the current URL parameters, and then try to restore them on the
other side of the redirect. Parameters are stored on the server in a cache

Changed:

<<

file (see {PassthroughDir} in =configure).

>>

file.

Note that if $passthru is set, then any parameters in $url will be lost
when the old parameters are restored. if you want to change any parameter

(ie, with the name of the function instead of the alias) will not work.

Added:

>>

decodeFormatTokens($str) -> $unencodedString

TWiki has an informal standard set of tokens used in format
parameters that are used to block evaluation of paramater strings.
For example, if you were to write

%MYTAG{format="%WURBLE%"}%

then %WURBLE would be expanded before %MYTAG is evaluated. To avoid
this TWiki uses escapes in the format string. For example:

%MYTAG{format="$percntWURBLE$percnt"}%

This lets you enter arbitrary strings into parameters without worrying that
TWiki will expand them before your plugin gets a chance to deal with them
properly. Once you have processed your tag, you will want to expand these
tokens to their proper value. That's what this function does.

spaceOutWikiWord( $word, $sep ) -> $text

Spaces out a wiki word by inserting a string (default: one space) between each word component.
With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.

Since: TWiki::Plugins::VERSION 1.2

writeWarning( $text )

Log Warning that may require admin intervention to data/warning.txt

Line: 1287 to 1565

Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)

Added:

>>

isTrue( $value, $default ) -> $boolean

Returns 1 if $value is true, and 0 otherwise. "true" means set to
something with a Perl true value, with the special cases that "off",
"false" and "no" (case insensitive) are forced to false. Leading and
trailing spaces in $value are ignored.

If the value is undef, then $default is returned. If $default is
not specified it is taken as 0.

You are setting different access controls in the text to those defined in the stored topic,

You already have the topic text in hand, and want to help TWiki avoid having to read it again,

You are providing a $meta parameter.

$topic - Topic name, required, e.g. 'PrivateStuff'

$web - Web name, required, e.g. 'Sandbox'

Added:

>>

$meta - Meta-data object, as returned by readTopic. Optional. If undef, but $text is defined, then access controls will be parsed from $text. If defined, then metadata embedded in $text will be ignored. This parameter is always ignored if $text is undefined. Settings in $meta override Set settings in $text.

A perl true result indicates that access is permitted.

Added:

>>

Note the wierd parameter order is due to compatibility constraints with
earlier TWiki releases.

Tip if you want, you can use this method to check your own access control types. For example, if you:

represent various string entities in an I18N-compatible manner. Plugins

>>

represent various string entities in an I18N-compatible manner. Plugins

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

... - an arbitrary number of name,value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX

redirectCgiQuery( $query, $url )

redirectCgiQuery( $query, $url, $passthru )

$query - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.

$url - URL to redirect to

Changed:

<<

Return: none, never returns

>>

$passthru - enable passthrough.

Return: none

Print output to STDOUT that will cause a 302 redirect to a new URL.
Nothing more should be printed to STDOUT after this method has been called.

The $passthru parameter allows you to pass the parameters that were passed
to the current query on to the target URL, as long as it is another URL on the
same TWiki installation. If $passthru is set to a true value, then TWiki
will save the current URL parameters, and then try to restore them on the
other side of the redirect. Parameters are stored on the server in a cache
file (see {PassthroughDir} in =configure).

Note that if $passthru is set, then any parameters in $url will be lost
when the old parameters are restored. if you want to change any parameter
values, you will need to do that in the current CGI query before redirecting
e.g.

$passthru does nothing if $url does not point to a script in the current
TWiki installation.

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Line: 984 to 1042

would let you do this:
%EXEC{"ps -Af" silent="on"}%

Added:

>>

Registered tags differ from tags implemented using the old TWiki approach (text substitution in commonTagsHandler) in the following ways:

registered tags are evaluated at the same time as system tags, such as %SERVERTIME. commonTagsHandler is only called later, when all system tags have already been expanded (though they are expanded again after commonTagsHandler returns).

registered tag names can only contain alphanumerics and _ (underscore)

registering a tag FRED defines both %FRED{...}%and also%FRED%.

registered tag handlers cannot return another tag as their only result (e.g. return '%SERVERTIME%';). It won't work.

registerRESTHandler( $alias, \&fn, )

Added:

>>

Should only be called from initPlugin.

Adds a function to the dispatch table of the REST interface

Line: 1147 to 1213

Parse a web and topic name, supplying defaults as appropriate.

$web - Web name, identifying variable, or empty string

$topic - Topic name, may be a web.topic string, required.

Changed:

<<

Return: the parsed Web/Topic pai

>>

Return: the parsed Web/Topic pair

Since: TWiki::Plugins::VERSION 1.1

Line: 1156 to 1222

( '', 'Topic' )

( 'Main', 'Topic' )

( '', '' )

( 'Main', 'WebHome' )

( '', 'Web/Topic' )

( 'Web', 'Topic' )

Added:

>>

( '', 'Web/Subweb/Topic' )

( 'Web/Subweb', 'Topic' )

( '', 'Web.Topic' )

( 'Web', 'Topic' )

Added:

>>

( '', 'Web.Subweb.Topic' )

( 'Web/Subweb', 'Topic' )

( 'Web1', 'Web2.Topic' )

( 'Web2', 'Topic' )

Changed:

<<

( 'Main', 'Topic' )

( 'Main', 'Topic' )

( 'TWiki', 'Topic' )

( 'TWiki', 'Topic' )

where Main and TWiki are the web names set in $cfg{UsersWebName} and $cfg{SystemWebName} respectively.

>>

Note that hierarchical web names (SubWeb) are only available if hierarchical webs are enabled in configure.

The symbols %USERSWEB%, %SYSTEMWEB%, %DOCWEB%, %MAINWEB% and %TWIKIWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:

Read an attachment from the store for a topic, and return it as a string. The names of attachments on a topic can be recovered from the meta-data returned by readTopic. If the attachment does not exist, or cannot be read, undef will be returned.

>>

Read an attachment from the store for a topic, and return it as a string. The
names of attachments on a topic can be recovered from the meta-data returned
by readTopic. If the attachment does not exist, or cannot be read, undef
will be returned. If the revision is not specified, the latest version will
be returned.

View permission on the topic is required for the
read to be successful. Access control violations are flagged by a

Changed:

<<

TWiki::AccessControlException. Permissions are checked for the user
passed in.

>>

TWiki::AccessControlException. Permissions are checked for the current user.

Package TWiki::Func

This module defines official functions that Plugins
can use to interact with the TWiki engine and content.

Refer to EmptyPlugin and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.

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

Deprecated functions will still work in older code, though they should
not be called in new Plugins and should be replaced in older Plugins
as soon as possible.

The version of the TWiki::Func module is defined by the VERSION number of the
TWiki::Plugins module, currently 6.02. 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.

Note: Beware! These methods should only ever be called
from the context of a TWiki Plugin. They require a Plugins SESSION context to be
established before they are called, and will not work if simply called from
another TWiki module. For example,

use TWiki;
print TWiki::Func::getSkin(),"\n";

will fail with Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83.

If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example,
the script:

getPubUrlPath( ) -> $path

getCgiQuery( ) -> $query

Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set

Return: $query CGI query object; or 0 if script is called as a shell script

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getSessionValue( $key ) -> $value

Get a session value from the client session module

$key - Session key

Return: $value Value associated with key; empty string if not set

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 200)

setSessionValue( $key, $value ) -> $boolean

Set a session value via the client session module

$key - Session key

$value - Value associated with key

Return: true if function succeeded

Since: TWiki::Plugins::VERSION 1.000 (17 Aug 2001)

clearSessionValue( $key ) -> $boolean

Clear a session value via the client session module

$key - Session key

Return: true if function succeeded

Since: TWiki::Plugins::VERSION 1.1

getContext() -> \%hash

Get a hash of context identifiers representing the currently active
context.

The context is a set of identifiers that are set
during specific phases of TWiki processing. For example, each of
the standard scripts in the 'bin' directory each has a context
identifier - the view script has 'view', the edit script has 'edit'
etc. So you can easily tell what 'type' of script your Plugin is
being called within. The core context identifiers are listed
in the TWikiTemplates topic. Please be careful not to
overwrite any of these identifiers!

Context identifiers can be used to communicate between Plugins, and between
Plugins and templates. For example, in FirstPlugin.pm, you might write:

Webs, Topics and Attachments

Gets a list of webs, filtered according to the spec in the $filter,
which may include one of:

'user' (for only user webs)

'template' (for only template webs i.e. those starting with "_")

$filter may also contain the word 'public' which will further filter
out webs that have NOSEARCHALL set on them.
'allowed' filters out webs the current user can't read.

For example, the deprecated getPublicWebList function can be duplicated
as follows:

my @webs = TWiki::Func::getListOfWebs( "user,public" );

Since: TWiki::Plugins::VERSION 1.1

webExists( $web ) -> $boolean

Test if web exists

$web - Web name, required, e.g. 'Sandbox'

Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

createWeb( $newWeb, $baseWeb, $opts )

$newWeb is the name of the new web.

$baseWeb is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.

setTopicEditLock( $web, $topic, $lock )

$web Web name, e.g. "Main", or empty

$topic Topic name, e.g. "MyTopic", or "Main.MyTopic"

$lock 1 to lease the topic, 0 to clear the lease=

Takes out a "lease" on the topic. The lease doesn't prevent
anyone from editing and changing the topic, but it does redirect them
to a warning screen, so this provides some protection. The edit script
always takes out a lease.

It is impossible to fully lock a topic. Concurrent changes will be
merged.

NOTE: if you are trying to get revision info for a topic, use
$meta->getRevisionInfo instead if you can - it is significantly
more efficient, and returns a user object that contains other user
information.

NOTE: prior versions of TWiki may under some circumstances have returned
the login name of the user rather than the wiki name; the code documentation
was totally unclear, and we have been unable to establish the intent.
However the wikiname is obviously more useful, so that is what is returned.

Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

getRevisionAtTime( $web, $topic, $time ) -> $rev

Get the revision number of a topic at a specific time.

$web - web for topic

$topic - topic

$time - time (in epoch secs) for the rev

Return: Single-digit revision number, or undef if it couldn't be determined
(either because the topic isn't that old, or there was a problem)

Since: TWiki::Plugins::VERSION 1.1

readTopic( $web, $topic, $rev ) -> ( $meta, $text )

Read topic text and meta data, regardless of access permissions.

$web - Web name, required, e.g. 'Main'

$topic - Topic name, required, e.g. 'TokyoOffice'

$rev - revision to read (default latest)

Return: ( $meta, $text ) Meta data object and topic text

$meta is a perl 'object' of class TWiki::Meta. This class is
fully documented in the source code documentation shipped with the
release, or can be inspected in the lib/TWiki/Meta.pm file.

This method ignores topic access permissions. You should be careful to use checkAccessPermissions to ensure the current user has read access to the topic.

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

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

Read topic text, including meta data

$web - Web name, e.g. 'Main', or empty

$topic - Topic name, e.g. 'MyTopic', or "Main.MyTopic"

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

$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

This method is more efficient than readTopic, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer..

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

attachmentExists( $web, $topic, $attachment ) -> $boolean

Test if attachment exists

$web - Web name, optional, e.g. Main.

$topic - Topic name, required, e.g. TokyoOffice, or Main.TokyoOffice

$attachment - attachment name, e.g.=logo.gif=

$web and $topic are parsed as described in the documentation for normalizeWebTopicName.

Since: TWiki::Plugins::VERSION 1.1

readAttachment( $web, $topic, $name, $rev ) -> $data

$web - web for topic

$topic - topic

$name - attachment name

$rev - revision to read (default latest)

Read an attachment from the store for a topic, and return it as a string. The names of attachments on a topic can be recovered from the meta-data returned by readTopic. If the attachment does not exist, or cannot be read, undef will be returned.

View permission on the topic is required for the
read to be successful. Access control violations are flagged by a
TWiki::AccessControlException. Permissions are checked for the user
passed in.

Renames the topic. Throws an exception on error or access violation.
If $newWeb is undef, it defaults to $web. If $newTopic is undef, it defaults
to $topic. If $newAttachment is undef, it defaults to $attachment. If all of $newWeb, $newTopic and $newAttachment are undef, it is an error.

The destination topic must already exist, but the destination attachment must
not exist.

Rename an attachment to $TWiki::cfg{TrashWebName}.TrashAttament to delete it.

Special handlers

Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.

registerTagHandler( $var, \&fn, $syntax )

Should only be called from initPlugin.

Register a function to handle a simple variable. Handles both %VAR% and %VAR{...}%. Registered variables are treated the same as TWiki internal variables, and are expanded at the same time. This is a lot more efficient than using the commonTagsHandler.

$var - The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name must match /^[A-Z][A-Z0-9_]*$/ or it won't work.

\&fn - Reference to the handler function.

$syntax can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard %MYVAR{ "unnamed" param1="value1" param2="value2" }% syntax, as well as an unquoted default parameter, such as %MYVAR{unquoted parameter}%. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR{param1=value1, value 2, param3="value 3", param4='value 5"}%

Since: TWiki::Plugins::VERSION 1.1

The variable handler function must be of the form:

sub handler(\%session, \%params, $topic, $web)

where:

\%session - a reference to the TWiki session object (may be ignored)

\%params - a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with _DEFAULT being the name for the default parameter.

$topic - name of the topic in the query

$web - name of the web in the query

for example, to execute an arbitrary command on the server, you might do this:

Searching

Search for a string in the content of a web. The search is over all content, including meta-data. Meta-data matches will be returned as formatted lines within the topic content (meta-data matches are returned as lines of the format %META:\w+{.*}%)

$searchString - the search string, in egrep format

$web - The web to search in

\@topics - reference to a list of topics to search

\%option - reference to an options hash

The \%options hash may contain the following options:

type - if regex will perform a egrep-syntax RE search (default '')

casesensitive - false to ignore case (defaulkt true)

files_without_match - true to return files only (default false). If files_without_match is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).

The return value is a reference to a hash which maps each matching topic
name to a list of the lines in that topic that matched the search,
as would be returned by 'grep'.

Plugin-specific file handling

getWorkArea( $pluginName ) -> $directorypath

Gets a private directory for Plugin use. The Plugin is entirely responsible
for managing this directory; TWiki will not read from it, or write to it.

The directory is guaranteed to exist, and to be writable by the webserver
user. By default it will not be web accessible.

The directory and it's contents are permanent, so Plugins must be careful
to keep their areas tidy.

Since: TWiki::Plugins::VERSION 1.1 (Dec 2005)

readFile( $filename ) -> $text

Read file, low level. Used for Plugin workarea.

$filename - Full path name of file

Return: $text Content of file, empty if not found

NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.

Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)

saveFile( $filename, $text )

Save file, low level. Used for Plugin workarea.

$filename - Full path name of file

$text - Text to save

Return: none

NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.

Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)

General Utilities

getRegularExpression( $name ) -> $expr

Retrieves a TWiki predefined regular expression or character class.

$name - Name of the 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)

Note: TWiki internally precompiles several regular expressions to
represent various string entities in an I18N-compatible manner. Plugins
authors 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.

In the table below, the expression marked type 'String' are intended for
use within character classes (i.e. for use within square brackets inside
a regular expression), for example:

Deprecated functions

From time-to-time, the TWiki developers will add new functions to the interface (either to TWikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release, and probably longer, though this cannot be guaranteed.

Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can suppress the warnings in %FAILEDPLUGINS%.

This is done by defining a map from the handler name to the TWiki::Plugins version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler for compatibility with TWiki::Plugins versions before 1.1, we would add this to the plugin:

If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of TWiki::Plugins before 1.1 will still call the handler as required.

The following functions are retained for compatibility only. You should
stop using them as soon as possible.

getScriptUrlPath( ) -> $path

Get script URL path

DEPRECATED since 1.1 - use getScriptUrl instead.

Return: $path URL path of TWiki scripts, e.g. "/cgi-bin"

WARNING: you are strongly recommended not to use this function, as the
{ScriptUrlPaths} URL rewriting rules will not apply to urls generated
using it.