internal package Foswiki

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

• Foswiki::AccessControlException - Exception used raise an access control violation. This exception has the following fields: * web - the web which was being accessed * topic - the topic being accessed (if any) * user - canonical username of the person doing the accessing. Use the methods of the Foswiki::Users class to get more information about the user. * mode - the access mode e.g. CHANGE, VIEW etc * reason a text string giving the reason for the refusal.
• Foswiki::AggregateIterator - implements Foswiki::Iterator
• Foswiki::Attach - A singleton object of this class is used to deal with attachments to topics.
• Foswiki::Attrs - Class of attribute sets, designed for parsing and storing attribute values from a macro e.g. =%MACRO{"joe" fred="bad" joe="mad"}%=
• Foswiki::Cache - Virtual base class for cache implementations. A cache implementation is used by Foswiki::PageCache to store cached data (both page data and meta-data about the cached pages).
• Foswiki::Compatibility - Support for compatibility with old versions. Packaged separately because 99.999999% of the time this won't be needed.
• Foswiki::Configure
• Foswiki::Contrib
• Foswiki::Engine - The engine class is a singleton that implements details about Foswiki's execution mode. This is the base class and implements basic behavior.
• Foswiki::EngineException - Exception used to raise an engine related error. This exception has the following fields: * status - status code to send to client * reason a text string giving the reason for the refusal.
• Foswiki::Form - Object representing a single form definition.
• Foswiki::Func - _Interface for Foswiki extensions developers_
• Foswiki::I18N - Support for strings translation and language detection.
• Foswiki::If
• Foswiki::IncludeHandlers
• Foswiki::Infix
• Foswiki::Iterator - This class cannot be instantiated on its own - it is an interface specification for iterators. See http://en.wikipedia.org/wiki/Iterator_Pattern for more information on the iterator pattern.
• Foswiki::LineIterator - implements Foswiki::Iterator
• Foswiki::ListIterator - implements Foswiki::Iterator
• Foswiki::Logger - Object that interfaces to whatever records Foswiki log files.
• Foswiki::LoginManager - The package is also a Factory for login managers and also the base class for all login managers.
• Foswiki::Macros
• Foswiki::Merge - Support for merging strings
• Foswiki::Meta - Objects of this class act as handles onto real store objects. An object of this class can represent the Foswiki root, a web, or a topic.
• Foswiki::MetaCache - A cache of Meta objects - initially used to speed up searching and sorting, but by foswiki 2.0 hopefully this will be used for all readonly accesses to the store.
• Foswiki::Net - Object that brokers access to network resources.
• Foswiki::OopsException - Exception used to raise a request to output a preformatted page.
• Foswiki::PageCache - Interface to the caching infrastructure.
• Foswiki::Plugin
• Foswiki::Plugins - This module defines the singleton object that handles Plugins loading, initialization and execution.
• Foswiki::Plurals - Handle conversion of plural topic names to singular form.
• Foswiki::Prefs - Preferences are set in topics, using either 'Set' lines embedded in the topic text, or via PREFERENCE meta-data attached to the topic. A preference value has four scopes: * Global scope * Local scope * Web scope * Topic scope
• Foswiki::Query
• Foswiki::Render - This module provides most of the actual HTML rendering code in Foswiki.
• Foswiki::Request - Class to encapsulate request data.
• Foswiki::Response - Class to encapsulate response data.
• Foswiki::Sandbox - This package provides an interface to the outside world. All calls to system functions, or handling of file names, should be brokered by the sysCommand function in this package.
• Foswiki::Search - This module implements all the search functionality.
• Foswiki::Store - This class is a pure virtual base class that specifies the interface between the actual store implementation and the rest of the Foswiki system.
• Foswiki::Templates - Support for Skin Template directives
• Foswiki::Time - Time handling functions.
• Foswiki::UI - Coordinator of execution flow and service functions used by the UI packages
• Foswiki::UserMapping - This is a virtual base class (a.k.a an interface) for all user mappers. It is not useable as a mapping in Foswiki - use the BaseUserMapping for default behaviour.
• Foswiki::Users - This package provides services for the lookup and manipulation of login and wiki names of users, and their authentication.
• Foswiki::Validation - "Validation" is the process of ensuring that an incoming request came from a page we generated. Validation keys are injected into all HTML pages generated by Foswiki, in Foswiki::writeCompletePage. When a request is received from the browser that requires validation, that request must be accompanied by the validation key. The functions in this package support the generation and checking of these validation keys.
• Foswiki::ValidationException - Exception used raise a validation error. See also Foswiki::Validation.
• Foswiki::WebFilter

internal package Foswiki

Foswiki operates by creating a singleton object (known as the Session object) that acts as a point of reference for all the different modules in the system. This package is the class for this singleton, and also contains the vast bulk of the basic constants and the per- site configuration mechanisms.

Global variables are avoided wherever possible to avoid problems with CGI accelerators such as mod_perl.

Public Data members

• request Pointer to the Foswiki::Request
• response Pointer to the Foswiki::Response
• context Hash of context ids
• plugins Foswiki::Plugins singleton
• prefs Foswiki::Prefs singleton
• remoteUser Login ID when using ApacheLogin. Maintained for compatibility only, do not use.
• requestedWebName Name of web found in URL path or web URL parameter
• scriptUrlPath URL path to the current script. May be dynamically extracted from the URL path if {GetScriptUrlFromCgi}. Only required to support {GetScriptUrlFromCgi} and not consistently used. Avoid.
• security Foswiki::Access singleton
• store Foswiki::Store singleton
• topicName Name of topic found in URL path or topic URL parameter
• urlHost Host part of the URL (including the protocol) determined during intialisation and defaulting to {DefaultUrlHost}
• user Unique user ID of logged-in user
• users Foswiki::Users singleton
• webName Name of web found in URL path, or web URL parameter, or {UsersWebName}

ObjectMethod writeCompletePage( $text, $pageType, $contentType )

Write a complete HTML page with basic header to the browser.

• $text is the text of the page script (<html> to </html> if it's HTML)
• $pageType - May be "edit", which will cause headers to be generated that force caching for 24 hours, to prevent BackFromPreviewLosesText bug, which caused data loss with IE5 and IE6.
• $contentType - page content type | text/html

This method removes noautolink and nop tags before outputting the page unless $contentType is text/plain.

ObjectMethod generateHTTPHeaders( $pageType, $contentType, $text, $cachedPage )

All parameters are optional.

• $pageType - May be "edit", which will cause headers to be generated that force caching for 24 hours, to prevent BackFromPreviewLosesText bug, which caused data loss with IE5 and IE6.
• $contentType - page content type | text/html
• $text - page content
• $cachedPage - a pointer to the page container as fetched from the page cache

ObjectMethod redirectto($url) → $url

If the CGI parameter 'redirectto' is present on the query, then will validate that it is a legal redirection target (url or topic name). If 'redirectto' is not present on the query, performs the same steps on $url.

Returns undef if the target is not valid, and the target URL otherwise.

StaticMethod splitAnchorFromUrl( $url ) → ( $url, $anchor )

Takes a full url (including possible query string) and splits off the anchor. The anchor includes the # sign. Returns an empty string if not found in the url.

ObjectMethod redirect( $url, $passthrough )

• $url - url or topic to redirect to
• $passthrough - (optional) parameter to pass through current query parameters (see below)

Redirects the request to $url, unless

1. It is overridden by a plugin declaring a redirectCgiQueryHandler (a dangerous, deprecated handler!)
2. $session->{request} is undef or

Thus a redirect is only generated when in a CGI context.

Normally this method will ignore parameters to the current query. Sometimes, for example when redirecting to a login page during authentication (and then again from the login page to the original requested URL), you want to make sure all parameters are passed on, and for this $passthrough should be set to true. In this case it will pass all parameters that were passed to the current query on to the redirect target. If the request_method for the current query was GET, then all parameters will be passed by encoding them in the URL (after ?). If the request_method was POST, then there is a risk the URL would be too big for the receiver, so it caches the form data and passes over a cache reference in the redirect GET.

NOTE: Passthrough is only meaningful if the redirect target is on the same server.

ObjectMethod cacheQuery() → $queryString

Caches the current query in the params cache, and returns a rewritten query string for the cache to be picked up again on the other side of a redirect.

We can't encode post params into a redirect, because they may exceed the size of the GET request. So we cache the params, and reload them when the redirect target is reached.

ObjectMethod getCGISession() → $cgisession

Get the CGI::Session object associated with this session, if there is one. May return undef.

ObjectMethod getLoginManager() → $loginManager

Get the Foswiki::LoginManager object associated with this session, if there is one. May return undef.

StaticMethod isValidWikiWord( $name ) → $boolean

Check for a valid WikiWord or WikiName

StaticMethod isValidTopicName( $name [, $nonww] ) → $boolean

Check for a valid topic $name. If $nonww, then accept non wiki-words (though they must still be composed of only valid, unfiltered characters)

StaticMethod isValidWebName( $name, $system ) → $boolean

STATIC Check for a valid web name. If $system is true, then system web names are considered valid (names starting with _) otherwise only user web names are valid

If $Foswiki::cfg{EnableHierarchicalWebs} is off, it will also return false when a nested web name is passed to it.

StaticMethod isValidEmailAddress( $name ) → $boolean

STATIC Check for a valid email address name.

ObjectMethod getSkin () → $string

Get the currently requested skin path

ObjectMethod getScriptUrl( $absolute, $script, $web, $topic, ... ) → $scriptURL

Returns the URL to a Foswiki script, providing the web and topic as "path info" parameters. The result looks something like this: "http://host/foswiki/bin/$script/$web/$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

If $absolute is set, generates an absolute URL. $absolute is advisory only; Foswiki can decide to generate absolute URLs (for example when run from the command-line) even when relative URLs have been requested.

The default script url is taken from {ScriptUrlPath}, unless there is an exception defined for the given script in {ScriptUrlPaths}. Both {ScriptUrlPath} and {ScriptUrlPaths} may be absolute or relative URIs. If they are absolute, then they will always generate absolute URLs. if they are relative, then they will be converted to absolute when required (e.g. when running from the command line, or when generating rss). If $script is not given, absolute URLs will always be generated.

If either the web or the topic is defined, will generate a full url (including web and topic). Otherwise will generate only up to the script name. An undefined web will default to the main web name.

ObjectMethod getPubUrl($absolute, $web, $topic, $attachment) → $url

Composes a pub url. If $absolute is set, returns an absolute URL. If $absolute is set, generates an absolute URL. $absolute is advisory only; Foswiki can decide to generate absolute URLs (for example when run from the command-line) even when relative URLs have been requested.

$web, $topic and $attachment are optional. A partial URL path will be generated if one or all is not given.

ObjectMethod deepWebList($filter, $web) → @list

Deep list subwebs of the named web. $filter is a Foswiki::WebFilter object that is used to filter the list. The listing of subwebs is dependent on $Foswiki::cfg{EnableHierarchicalWebs} being true.

Webs are returned as absolute web pathnames.

ObjectMethod normalizeWebTopicName( $web, $topic ) → ( $web, $topic )

Normalize a Web.TopicName

See Foswiki::Func for a full specification of the expansion (not duplicated here)

WARNING if there is no web specification (in the web or topic parameters) the web defaults to $Foswiki::cfg{UsersWebName}. If there is no topic specification, or the topic is '0', the topic defaults to the web home topic name.

WARNING if the input topic name is tainted, then the output web and topic names will be tainted.

ClassMethod new( $defaultUser, $query, \%initialContext )

Constructs a new Foswiki session object. A unique session object exists for ever transaction with Foswiki, for example every browser request, or every script run. Session objects do not persist between mod_perl runs.

• $defaultUser is the username (not the wikiname) of the default user you want to be logged-in, if none is available from a session or browser. Used mainly for unit tests and debugging, it is typically undef, in which case the default user is taken from $Foswiki::cfg{DefaultUserName}.
• $query the Foswiki::Request query (may be undef, in which case an empty query is used)
• \%initialContext - reference to a hash containing context name=value pairs to be pre-installed in the context hash. May be undef.

ObjectMethod renderer()

Get a reference to the renderer object. Done lazily because not everyone needs the renderer.

ObjectMethod attach()

Get a reference to the attach object. Done lazily because not everyone needs the attach.

ObjectMethod templates()

Get a reference to the templates object. Done lazily because not everyone needs the templates.

ObjectMethod i18n()

Get a reference to the i18n object. Done lazily because not everyone needs the i18ner.

ObjectMethod logger()

ObjectMethod search()

Get a reference to the search object. Done lazily because not everyone needs the searcher.

ObjectMethod net()

Get a reference to the net object. Done lazily because not everyone needs the net.

ObjectMethod DESTROY()

called by Perl when the Foswiki object goes out of scope (maybe should be used kist to ASSERT that finish() was called..

ObjectMethod finish()

Break circular references.

ObjectMethod logEvent( $action, $webTopic, $extra, $user )

• $action - what happened, e.g. view, save, rename
• $webTopic - what it happened to
• $extra - extra info, such as minor flag
• $user - login name of user - default current user, or failing that the user agent

Write the log for an event to the logfile

StaticMethod validatePattern( $pattern ) → $pattern

Validate a pattern provided in a parameter to $pattern so that dangerous chars (interpolation and execution) are disabled.

ObjectMethod inlineAlert($template, $def, ... ) → $string

Format an error for inline inclusion in rendered output. The message string is obtained from the template 'oops'.$template, and the DEF $def is selected. The parameters (...) are used to populate %PARAM1%..%PARAMn%

StaticMethod parseSections($text) → ($string,$sectionlistref)

Generic parser for sections within a topic. Sections are delimited by STARTSECTION and ENDSECTION, which may be nested, overlapped or otherwise abused. The parser builds an array of sections, which is ordered by the order of the STARTSECTION within the topic. It also removes all the SECTION tags from the text, and returns the text and the array of sections.

Each section is a Foswiki::Attrs object, which contains the attributes {type, name, start, end} where start and end are character offsets in the string after all section tags have been removed. All sections are required to be uniquely named; if a section is unnamed, it will be given a generated name. Sections may overlap or nest.

See test/unit/Fn_SECTION.pm for detailed testcases that round out the spec.

ObjectMethod expandMacrosOnTopicCreation ( $topicObject )

• $topicObject - the topic

Expand only that subset of Foswiki variables that are expanded during topic creation, in the body text and PREFERENCE meta only. The expansion is in-place inside the topic object.

# SMELL: no plugin handler

StaticMethod entityEncode( $text, $extras ) → $encodedText

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

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

StaticMethod entityDecode ( $encodedText ) → $text

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

StaticMethod urlEncodeAttachment ( $text )

For attachments, URL-encode specially to 'freeze' any characters >127 in the site charset (e.g. ISO-8859-1 or KOI8-R), by doing URL encoding into native charset ($siteCharset) - used when generating attachment URLs, to enable the web server to serve attachments, including images, directly.

This encoding is required to handle the cases of:

- browsers that generate UTF-8 URLs automatically from site charset URLs - now quite common - web servers that directly serve attachments, using the site charset for filenames, and cannot convert UTF-8 URLs into site charset filenames

The aim is to prevent the browser from converting a site charset URL in the web page to a UTF-8 URL, which is the default. Hence we 'freeze' the URL into the site character set through URL encoding.

In two cases, no URL encoding is needed: For EBCDIC mainframes, we assume that site charset URLs will be translated (outbound and inbound) by the web server to/from an EBCDIC character set. For sites running in UTF-8, there's no need for Foswiki to do anything since all URLs and attachment filenames are already in UTF-8.

StaticMethod urlEncode( $string ) → encoded string

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

StaticMethod urlDecode( $string ) → decoded string

Reverses the encoding done in urlEncode.

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

StaticMethod spaceOutWikiWord( $word, $sep ) → $string

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.

ObjectMethod innerExpandMacros(\$text, $topicObject)

Expands variables by replacing the variables with their values. Some example variables: %TOPIC%, %SCRIPTURL%, %WIKINAME%, etc. $web and $incs are passed in for recursive include expansion. They can safely be undef. The rules for tag expansion are:

1. Tags are expanded left to right, in the order they are encountered.
2. Tags are recursively expanded as soon as they are encountered - the algorithm is inherently single-pass
3. A tag is not "encountered" until the matching }% has been seen, by which time all tags in parameters will have been expanded
4. Tag expansions that create new tags recursively are limited to a set number of hierarchical levels of expansion

StaticMethod takeOutBlocks( \$text, $tag, \%map ) → $text

• $text - Text to process
• $tag - XML-style tag.
• \%map - Reference to a hash to contain the removed blocks

Return value: $text with blocks removed

Searches through $text and extracts blocks delimited by an XML-style tag, storing the extracted block, and replacing with a token string which is not affected by TML rendering. The text after these substitutions is returned.

StaticMethod putBackBlocks( \$text, \%map, $tag, $newtag, $callBack ) → $text

Return value: $text with blocks added back

• \$text - reference to text to process
• \%map - map placeholders to blocks removed by takeOutBlocks
• $tag - Tag name processed by takeOutBlocks
• $newtag - Tag name to use in output, in place of $tag. If undefined, uses $tag.
• $callback - Reference to function to call on each block being inserted (optional)

Reverses the actions of takeOutBlocks.

Each replaced block is processed by the callback (if there is one) before re-insertion.

Parameters to the outermost cut block are replaced into the open tag, even if that tag is changed. This allows things like <verbatim class=''> to be changed to <pre class=''>

If you set $newtag to '', replaces the taken-out block with the contents of the block, not including the open/close. This is used for <literal>, for example.

ObjectMethod enterContext( $id, $val )

Add the context id $id into the set of active contexts. The $val can be anything you like, but should always evaluate to boolean TRUE.

An example of the use of contexts is in the use of tag expansion. The commonTagsHandler in plugins is called every time tags need to be expanded, and the context of that expansion is signalled by the expanding module using a context id. So the forms module adds the context id "form" before invoking common tags expansion.

Contexts are not just useful for tag expansion; they are also relevant when rendering.

Contexts are intended for use mainly by plugins. Core modules can use $session->inContext( $id ) to determine if a context is active.

ObjectMethod leaveContext( $id )

Remove the context id $id from the set of active contexts. (see enterContext for more information on contexts)

ObjectMethod inContext( $id )

Return the value for the given context id (see enterContext for more information on contexts)

StaticMethod registerTagHandler( $tag, $fnref, $syntax )

STATIC Add a tag handler to the function tag handlers.

• $tag name of the tag e.g. MYTAG
• $fnref Function to execute. Will be passed ($session, \%params, $web, $topic )
• $syntax somewhat legacy - 'classic' or 'context-free' (context-free may be removed in future)

$syntax parameter: Way back in prehistory, back when the dinosaur still roamed the earth, Crawford tried to extend the tag syntax of macros such that they could be processed by a context-free parser (hence the "context-free") and bring them into line with HTML. This work was banjaxed by one particular tyrranosaur, who felt that the existing syntax was perfect. However by that time Crawford had used it in a couple of places - most notable in the action tracker.

The syntax isn't vastly different from what's there; the differences are:

1. Use either type of quote for parameters
2. Optional quotes on parameter values e.g. recurse=on
3. Standardised use of \ for escapes
4. Boolean (valueless) options (i.e. recurse instead of recurse="on"

ObjectMethod expandMacros( $text, $topicObject ) → $text

Processes %VARIABLE%, and %TOC% syntax; also includes 'commonTagsHandler' plugin hook.

Returns the text of the topic, after file inclusion, variable substitution, table-of-contents generation, and any plugin changes from commonTagsHandler.

$topicObject may be undef when, for example, expanding templates, or one-off strings at a time when meta isn't available.

DO NOT CALL THIS DIRECTLY; use $topicObject->expandMacros instead.

ObjectMethod addToZone($zone, $id, $data, $requires)

Add $data identified as $id to $zone, which will later be expanded (with renderZone() - implements %RENDERZONE%). $ids are unique within the zone that they are added - dependencies between $ids in different zones will not be resolved, except for the special case of head and script zones when {MergeHeadAndScriptZones} is enabled.

In this case, they are treated as separate zones when adding to them, but as one merged zone when rendering, i.e. a call to render either head or script zones will actually render both zones in this one call. Both zones are undef'd afterward to avoid double rendering of content from either zone, to support proper behaviour when head and script are rendered with separate calls even when {MergeHeadAndScriptZones} is set. See ZoneTests/explicit_RENDERZONE*.

This behaviour allows an addToZone('head') call to require an id that has been added to script only.

• $zone - name of the zone
• $id - unique identifier
• $data - content
• $requires - optional, comma-separated string of $id identifiers that should precede the content

Note: Read the developer supplement at Foswiki:Development.AddToZoneFromPluginHandlers if you are calling addToZone() from a rendering or macro/tag-related plugin handler

Implements %ADDTOZONE%.

StaticMethod readFile( $filename ) → $text

Returns the entire contents of the given file, which can be specified in any format acceptable to the Perl open() function. Fast, but inherently unsafe.

WARNING: Never, ever use this for accessing topics or attachments! Use the Store API for that. This is for global control files only, and should be used only if there is absolutely no alternative.

StaticMethod expandStandardEscapes($str) → $unescapedStr

Expands standard escapes used in parameter values to block evaluation. See FormatTokens for a full list of supported tokens.

ObjectMethod webExists( $web ) → $boolean

Test if web exists

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

A web has to have a preferences topic to be a web.

ObjectMethod topicExists( $web, $topic ) → $boolean

Test if topic exists

• $web - Web name, optional, e.g. 'Main'
• $topic - Topic name, required, e.g. 'TokyoOffice', or "Main.TokyoOffice"

ObjectMethod getWorkArea( $key ) → $directorypath

Gets a private directory uniquely identified by $key. The directory is intended as a work area for plugins etc. The directory will exist.

ObjectMethod getApproxRevTime ( $web, $topic ) → $epochSecs

Get an approximate rev time for the latest rev of the topic. This method is used to optimise searching. Needs to be as fast as possible.

SMELL: is there a reason this is in Foswiki.pm, and not in Search?