Log inRegister

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


Parent package: Foswiki::Configure
Child packages:

    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.