public package Foswiki::Func

This module defines the main interfaces that extensions
can use to interact with the Foswiki engine and content.

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

Plugins should only call methods in packages documented in
DevelopingPlugins. If you use
functions in other Foswiki libraries you risk creating a security hole, and
you will probably need to change your plugin when you upgrade Foswiki.

Since:date indicates where functions or parameters have been added since
the baseline of the API (Foswiki 1.0.0). The date indicates the
earliest date of a Foswiki release that will support that function or
parameter. See Foswiki:Download.ReleaseDates for version release dates.

Deprecateddate indicates where a function or parameters has been
deprecated. Deprecated
functions will still work, though they should
not be called in new plugins and should be replaced in older plugins
as soon as possible. Deprecated parameters are simply ignored in Foswiki
releases after date.

Untildate indicates where a function or parameter has been removed.
The date indicates the latest date at which Foswiki releases still supported
the function or parameter.

Note that the Foswiki::Func API should always be the first place extension
authors look for methods. Certain other lower-level APIs are also exposed
by the core, but those APIs should only be called if there is no alternative
available through Foswiki::Func. The APIs in question are documented in
DevelopingPlugins.

Environment

getSkin( ) -> $skin

Get the skin path, set by the SKIN and COVER preferences variables or the skin and cover CGI parameters

getUrlHost( ) -> $host

getScriptUrl( $web, $topic, $script, ... ) -> $url

Compose fully qualified URL

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

$topic - Topic name, e.g. 'WebNotify'

$script - Script name, e.g. 'view'

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

getPubUrlPath( ) -> $path

getExternalResource( $url ) -> $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
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).

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

my $response = Foswiki::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
}

getRequestObject( ) -> $query

Get the request object. This is a subclass of Foswiki::Request. The request
object can be used to get the parameters passed to the request, either
via CGI or on the command line (depending on how the script was called).

Note that this method replaces getCgiQuery (which is a synonym for this
method). Code that is expected to run with pre-1.1 versions of Foswiki
can continue to call getCgiQuery for as long as necessary.

Since: 31 Mar 2009

getSessionKeys() -> @keys

Get a list of all the names of session variables. The list is unsorted.

Session keys are stored and retrieved using setSessionValue and
getSessionValue.

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

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

Set a session value.

$key - Session key

$value - Value associated with key

Return: true if function succeeded

clearSessionValue( $key ) -> $boolean

Clear a session value that was set using setSessionValue.

$key - name of value stored in session to be cleared. Note that you cannot clear AUTHUSER.

Return: true if the session value was cleared

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

A comprehensive list of core context identifiers used by Foswiki is found in
IfStatements#Context_identifiers. 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:

%TMPL:DEF{"ON"}% Not off %TMPL:END%
%TMPL:DEF{"OFF"}% Not on %TMPL:END%
%TMPL:P{context="MyID" then="ON" else="OFF"}%

or in a topic:

%IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%

Note: all plugins have an automatically generated context identifier
if they are installed and initialised. For example, if the FirstPlugin is
working, the context ID 'FirstPlugin' will be set.

pushTopicContext($web, $topic)

$web - new web

$topic - new topic

Change the Foswiki context, adding the requested $web.$topic onto the
preferences stack. Any preferences found in $web.$topic will be used
in place of preferences previously set in the stack, provided that they
were not finalized in a lower level. Preferences set in the prior
web.topic are not cleared. $web.$topic replaces and adds to
preferences but does not remove preferences that it does not set.

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.
All other errors will throw an exception.

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.

popTopicContext()

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

Registering extensions

Plugins work either by using handlers to manipulate the text being processed,
or by registering extensions, such as new macros, scripts, or meta-data types.

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 internal macros,
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'. (context-free may be removed in future) 'classic' syntax is appropriate where you want the variable to support classic syntax

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"}%

The variable handler function must be of the form:

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

where:

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

\%params - a reference to a Foswiki::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

$topicObject - is the Foswiki::Meta object for the topic Since 2009-03-06

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

Registered tags differ from tags implemented using the old 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, %options )

Should only be called from initPlugin.

Adds a function to the dispatch table of the REST interface

$alias - The name .

\&fn - Reference to the function.

%options - additional options affecting the handler

The handler function must be of the form:

sub handler(\%session)

where:

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

From the REST interface, the name of the plugin must be used
as the subject of the invokation.

Additional options are set in the %options hash. These options are important
to ensuring that requests to your handler can't be used in cross-scripting
attacks, or used for phishing.

authenticate - use this boolean option to require authentication for the handler. If this is set, then an authenticated session must be in place or the REST call will be rejected with a 401 (Unauthorized) status code. By default, rest handlers do not require authentication.

validate - use this boolean option to require validation of any requests made to this handler. Validation is the process by which a secret key is passed to the server so it can identify the origin of the request. By default, requests made to REST handlers are not validated.

http_allow use this option to specify that the HTTP methods that can be used to invoke the handler. For example, http_allow=>'POST,GET' will constrain the handler to be invoked using POST and GET, but not other HTTP methods, such as DELETE. Normally you will use http_allow=>'POST'. Together with authentication this is an important security tool. Handlers that can be invoked using GET are vulnerable to being called in the src parameter of img tags, a common method for cross-site request forgery (CSRF) attacks. This option is set automatically if authenticate is specified.

Example

This adds the restExample function to the REST dispatch table
for the EmptyPlugin under the 'example' alias, and allows it
to be invoked using the URL

http://server:port/bin/rest/EmptyPlugin/example

note that the URL

http://server:port/bin/rest/EmptyPlugin/restExample

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

Calling REST handlers from the command-line

The rest script allows handlers to be invoked from the command line. The
script is invoked passing the parameters as described in CommandAndCGIScripts.
If the handler requires authentication ( authenticate=>1 ) then this can
be passed in the username and password parameters.

NOTE: If $NO_PREFS_IN_TOPIC is enabled in the plugin, then
preferences set in the plugin topic will be ignored.

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.

User Handling and Access Control

getDefaultUserName( ) -> $loginName

Get default user name as defined in the configuration as DefaultUserLogin

Return: $loginName Default user name, e.g. 'guest'

getCanonicalUserID( $user ) -> $cUID

$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 Foswiki for each user.
BEWARE: While the default TopicUserMapping uses a cUID that looks like a user's
LoginName, some characters are modified to make them compatible with rcs.
Other usermappings may use other conventions - the JoomlaUserMapping
for example, has cUIDs like 'JoomlaeUserMapping_1234'.

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

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

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'

getWikiUserName( $user ) -> $wikiName

return the userWeb.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. "Main.JohnDoe"

wikiToUserName( $id ) -> $loginName

Translate a Wiki name to a login name.

$id - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'. $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.

Note that it is possible for several login names to map to the same wikiname.
This function will only return the first login name that maps to the
wikiname.

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

$loginName - Login name, e.g. 'jdoe'. 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'

userToWikiName will always return a name. If the user does not
exist in the mapping, the $loginName parameter is returned. (backward compatibility)

emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames

$email - email address to look up

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

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.

wikinameToEmails( $user ) -> @emails

$user - wikiname of user to look up

Returns the registered email addresses of the named user. If $user is
undef, returns the registered email addresses for the logged-in user.

isGroup( $group ) -> $boolean

eachGroupMember($group) -> $iterator

Get an iterator over all the members of the named group. Returns undef if
$group is not a valid group. Nested groups are expanded unless the
expand option is set to false.

Use it as follows: Process all users in RadioHeadGroup without expanding nested groups

my $iterator = Foswiki::Func::eachGroupMember('RadioheadGroup', {expand => 'false');
while ($it->hasNext()) {
my $user = $it->next();
# $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
# With expand set to false, group names can also be returned.
# Users are not checked to exist.
}

$id - WikiName of remote user, required, e.g. "RickShaw". $id may also be a login name. If $id is '', 0 or undef then access is always permitted. This is used by other functions if the caller should be able to bypass access checks.

If topic specified but does not exist, the web preferences are checked, allowing the caller to determine "If the topic existed, would the operation be permitted".

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

If missing, the default Users Web (Main) is used.

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

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

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

topicExists( $web, $topic ) -> $boolean

$web and $topic are parsed as described in the documentation for normalizeWebTopicName.
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.

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 Foswiki::Meta. This class is
fully documented in the source code documentation shipped with the
release, or can be inspected in the lib/Foswiki/Meta.pm file.

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

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

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)

getAttachmentList( $web, $topic ) -> @list

Get a list of the attachments on the given topic.

Since: 31 Mar 2009

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.

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

$web - web for topic - must not be tainted

$topic - topic - must not be tainted

$name - attachment name - must not be tainted

$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. 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
Foswiki::AccessControlException. Permissions are checked for the current user.

This is the way 99% of extensions will access attachments.
See Foswiki::Meta::openAttachment for a lower level interface that does
not check access controls.

Manipulating

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

In the event of an error an exception will be thrown. Callers can elect
to trap the exceptions thrown, or allow them to propagate to the calling
environment. May throw Foswiki::OopsException or Error::Simple.

Note: The ignorepermissions option is only available in Foswiki 1.1 and
later.

moveTopic( $web, $topic, $newWeb, $newTopic )

$web source web - required

$topic source topic - required

$newWeb dest web

$newTopic dest topic

Renames the topic. Throws an exception if something went wrong.
If $newWeb is undef, it defaults to $web. If $newTopic is undef, it defaults
to $topic.

Renames the attachment. 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 $Foswiki::cfg{TrashWebName}.TrashAttament to delete it.

Copies the attachment. 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 $Foswiki::cfg{TrashWebName}.TrashAttament to delete it.

Finding changes

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 = Foswiki::Func::eachChangeSince(
$web, time() - 7 * 24 * 60 * 60); # the last 7 days
while ($iterator->hasNext()) {
my $change = $iterator->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')
}

summariseChanges($web, $topic, $orev, $nrev, $tml) -> $text

Generate a summary of the changes between rev $orev and rev $nrev of the
given topic.

$web, $topic - topic (required)

$orev - older rev (required)

$nrev - later rev (may be undef for the latest)

$tml - if true will generate renderable TML (i.e. HTML with NOPs. if false will generate a summary suitable for use in plain text (mail, for example)

Generate a (max 3 line) summary of the differences between the revs.

If there is only one rev, a topic summary will be returned.

If $tml is not set, all HTML will be removed.

In non-tml, lines are truncated to 70 characters. Differences are shown using + and - to indicate added and removed text.

If access is denied to either revision, then it will be treated as blank
text.

Controlling page output

writeHeader()

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

$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 installation. If $passthru is set to a true value, then Foswiki
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.

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.

decodeFormatTokens($str) -> $unencodedString

Foswiki 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 Foswiki uses escapes in the format string. For example:

%MYTAG{format="$percentWURBLE$percent"}%

This lets you enter arbitrary strings into parameters without worrying that
Foswiki 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.

Avoid using this if you can; rewriting attachment names uses some very
nasty heuristics that cannot be changed because of compatibility issues.
It is much better use point-of-source validation to ensure only valid
attachment names are uploaded.

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.

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.

Note that the ability to read/write $Foswiki::cfg{LogFileName} is
maintained for compatibility but is deprecated (should not be used
in new code intended to work only with Foswiki 1.1 and later) and will
not work with any installation that stores logs in a database.

writeWarning( $text )

Log a warning that may require admin intervention to the warnings log (data/warn*.txt)

$text - Text to write; timestamp gets added

writeDebug( $text )

Log debug message to the debug log

$text - Text to write; timestamp gets added

eachEventSince($time, $level) -> $iterator

$time - a time in the past (seconds since the epoch)

$level - log level to return events for.

Get an iterator over the list of all the events at the given level
between $time and now. Events are written to the event log using
writeEvent. The Foswiki core will write other events that will
also be returned.

If the chosen Logger does not support querying the logs, an empty
iterator will be returned. The supplied PlainFile and Compatibility loggers
will return events only if the log files have not been archived.

Deprecated functions

From time-to-time, the Foswiki developers will add new functions to the interface (either to Foswiki::Func, 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 release, and probably longer, though this cannot be guaranteed.

Updated plugins may still need to define deprecated handlers for compatibility with old Foswiki 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 Foswiki::Plugins version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler for compatibility with Foswiki::Plugins versions before 1.1, we would add this to the plugin:

If the currently-running code version is 1.1 or later, then the handler will not be called and the warning will not be issued. Wersions of Foswiki::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.

getPubDir( ) -> $dir

getCgiQuery( ) -> $query

Deprecated 31 Mar 2009 - use getRequestObject instead if you can. Code
that is expected to run with pre-1.1 versions of Foswiki will still need to
use this method, as getRequestObject will not be available.

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

*Deprecated: 6 Aug 2009. Use readTopic instead.
This method returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. Use readTopic instead, which is a lot safer and supports the full set of read options.

The reason is that all <script> markup should be added to a dedicated zone, script,
and so any usage of ADDTOHEAD - which adds to the head zone - will be unable to
satisfy ordering requirements when the requirements exist in another zone ( script ).

Deprecated 17 Oct 2010 - use query( ...).
WARNING: This function has been deprecated in foswiki 1.1.0 for scalability reasons

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/s to search in - string can have the same form as the web param of SEARCH

\@topics - reference to a list of topics to search (if undef, then the store will search all topics in the specified web/webs.)

\%option - reference to an options hash

The \%options hash may contain the following options:

type - regex, keyword, query - defaults to regex

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

TODO: topic, excludetopic and other params as per SEARCH

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