PerlDoc

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:

---

Parent package: Foswiki::Configure
Child packages:

More ...Less ...

internal package Foswiki::Configure::Dependency

This module defines a dependency required by a Foswiki module and provides functions to test if the dependency is installed, and compare versions with the required version.

It is also used to examine the installed version of a Foswiki module.

ClassMethod new( %opts )

Create an object instance representing a single dependency, as read from DEPENDENCIES

• %opts
  • name             => unqualified name e.g. SafeWikiPlugin
  • module           => qualified module e.g Foswiki::Plugins::SafeWikiPlugin
    • If a qualified module is not provided, all possible Foswiki/TWiki module types are searched for type=perl
  • type             => perl|cpan|external
    • perl is a Foswiki or TWiki module. external is used for any program other than a perl module. External dependencies are not checked.
  • version          => version condition e.g. ">1.2.3"
  • trigger          => ONLYIF condition (Specifies a version of another module, such as the Foswiki Func API)
  • description      => text

• Instance variables set by calling studyInstallation() or indirectly by calling check()
  • installed        => True if module is installed
  • installedVersion => $VERSION string from module
  • installedRelease => $RELEASE string from module (or $VERSION)
  • notes            => text   Notes on condition of module (ex. fails due to missing dependency)

ObjectMethod check() → ($ok, $msg)

Check whether the dependency is satisfied by a currently-installed module.

• Return: ($ok, $msg)
  • $ok is a boolean indicating success/failure
  • $msg is a helpful message describing the failure

ObjectMethod studyInstallation()

Check the current installation, populating the {installedRelease} and {installedVersion} fields, and returning true if the extension is installed. {notes} will also be set when certain conditions are discovered (example: missing dependencies or other compile failures).

• Return: $ok
  • $ok is a boolean indicating success/failure. If the module is found and a VERSION and RELEASE are discovered, the method returns true.

ObjectMethod compare_versions ($condition, $release)

Compare versions (provided as $RELEASE, $VERSION) with a release specifier

Returns the boolean result of the comparison

StaticMethod extractModuleVersion ($moduleName, $magic) → ($moduleFound, $moduleVersion, $modulePath)

Locates a module in @INC and parses it to determine its version. If the second parameter is true, it magically handles Foswiki.pm's version construction.

Returns: $moduleFound - True if the module was found (and could be opended for read) $moduleVersion - The module version that was extracted, or undef if none was found. $modulePath - The full path to the module.

Require was used previously, but it doesn't scale and can have side-effects such a loading many unused dependencies, even LocalSite.cfg if it's a Foswiki module.

Since $VERSION is usually declared early in a module, we can also avoid reading most of (most) files.

This parser was inspired by Module::Extract::VERSION, though this is simplified and has special magic for the Foswiki build.

StaticMethod checkPerlModules(@mods)

Examine the status of perl modules. Takes an array of references to hashes. Each module hash needs: name - e.g. Car::Wreck usage - description of what it's for disposition - 'required', 'recommended' minimumVersion - lowest acceptable $Module::VERSION

If the module is installed, the hash will be updated to add installedVersion - the version installed (or 'Unknown version' or 'Not installed')

The result of the check is written to the check_result field.