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::FileUtil

Basic file utilities used by Configure and admin scripts

readdir utility

Returns NFC normalized unicode characters

StaticMethod findFileOnTree($dir, $pattern, $reject) ->> $fullpath

Recursive search for a file matching the specified pattern, searching $dir and all subdirectories of $dir, Anything matching $reject is not considered, to avoid searching the ,pfv subdirectories..

This is used by checkers and bootstrap to see if there are any ",v" rcs files in the Store.

Example:

findFileOnTree( $Foswiki::cfg{DataDir}, qr/,v$/, qr/,pfv$/ );

really only need to find the first occurance, we have no need for the full list, just whether or not any exist. File::Find returns the complete list of matching files.

StaticMethod findFileOnPath($filename) ->> $fullpath

Find a file on the @INC path, or undef if not found.

$filename may be a simple file name e.g. Example.pm or may be a /-separated path e.g. Net/Util or a class path e.g. Net::Util

Note that a terminating .pm is required to find a perl module.

StaticMethod lscFileName() → $localsite_cfg_path

Determine the pathname of LocalSite.cfg. This file must be on the path, but may not exist yet; it it doesn't, then Foswiki.spec must be and LocalSite.cfg will be placed in the same directory.

StaticMethod findPackages( $pattern ) → @list

Finds all packages that match the pattern in @INC

• $pattern is a wildcard expression that matches classes e.g. Foswiki::Plugins::*Plugin. * is the only wildcard supported.

Return a list of package names.

StaticMethod checkCanCreateFile($path) → $report

Check that the given path can be created (or, if it already exists, can be written). If the existing path is a directory, recursively check for rw permissions using checkTreePerms.

Returns a message if the check fails or undef if the check passed.

StaticMethod checkTreePerms($path, $perms, %options) → \%report

Perform a recursive check of the specified path. No failures will return, otherwise a string report is generated.

$perms is a string of permissions to check:

Basic checks:

• r - File or directory is readable
• w - File or directory is writable
• x - File is executable.

Enhanced checks:

• d - Directory permission matches the permissions in {Store}{dirPermission}
• f - File permission matches the permission in {Store}{filePermission} (FUTURE)
• p - Verify that a WebPreferences exists for each web
• n - Verify normalization of the directory location

%options may include the following:

• filter is a regular expression. Files matching the regex if present will not be checked. This is used to skip hidden files and those with different permission requirements.
• maxFileCount - limit on number of files checked
• maxFileErrors - limit on number of fileError messages generated Default is 10
• maxExcessPerms - limit on number of excessPerms messages generated Default is 10
• maxMissingFile - limit on number of missing file messages generated Default is 10

The returned \%report contains the following fields:

• fileCount - number of files checked
• fileErrors - number of file errors errors encountered
• excessPerms - number of excess permissions encountered
• missingFile - number of missing files encountered
• messages - ref of an array containing individual file messages, limited as per the options.

In addition to the basic and enhanced checks specified in the $perms string, directories are always checked to determine if they have the 'x' permission.

Note that the enhanced checks are important especially on hosted sites. In some environments, the Foswiki perl scripts run under a different user/group than the web server. Basic checks will pass, but the server may still be unable to access the file. The enhanced checks will detect this condition.

StaticMethod checkGNUProgram($prog, $reporter, $reqVersion )

Check for the availability of a GNU program.

If $reqVersion is provided, (Simple decimmal number) then a warning is issued if older version is detected.

Since Windows (without Cygwin) makes it hard to capture stderr ('2>&1' works only on Win2000 or higher), and Windows will usually have GNU tools in any case (installed for Foswiki since there's no built-in diff, grep, patch, etc), we only check for these tools on Unix/Linux and Cygwin.

Errors are reported by calling ERROR and/or WARN on $reporter

StaticMethod copytree($from, $to) → @errors

Copy a directory tree from one place to another. Errors are reported in @errors, empty if it succeeds. A partial copy may happen if the copy fails mid-way.

StaticMethod listDir($dir, [$dflag], [$path] )

Recursively list the files in directory $dir. Optional $dflag can be set to 1 to cause the list to exclude the directory names from the list.

If $path is used internally for the recursive directory list. It is appended to the Directory. The list of files in @names is relative to the $dir directory. Subroutine called recursively for each subdirectory encountered.

StaticMethod createArchive($name, $dir, $delete )

Create an archive of the passed directory.

• $name is the directory to be backed up and the filename of the archive to be created. $name will be given a suffix of the backup type - depends on what type of backup tools are installed.
• $dir is the root directory of the backups - typically the working/configure/backup directory
• $delete - set if the directory being backed up should be deleted after archive is created.

StaticMethod unpackArchive($archive [,$dir] ) → ( $dir, $err )

Unpack an archive. The unpacking method is determined from the file extension e.g. .zip, .tgz. .tar, etc. If $dir is not given, unpack to a temporary directory, the name of which is returned.

Errors are reported by returnng a non-null $err

StaticMethod getPerlLocation( )

This routine will read in the first line of the bin/configure script and recover the location of the perl interpreter.

Optional parameter is file used to retrieve the shebang. If not specified, defaults to the configure script

StaticMethod rewriteShebang($file, $newShebang, $taint )

Rewrite the #! (shebang) line of the target script with the specified script name. Clear any taint flag by default, or set it if $taint is true.

This is used in 2 places: - The Package installer - used when installing extensions - In tools/rewriteshebang.pl

StaticMethod canNfcFilenames($testdir)

Determine if the file system is NFC or NFD. Write a UTF8 filename to the data directory, and then read the directory. If the filename is returned in NFD format, then the NFCNormalizeFilename flag is enabled.

returns:

• 1 if NFC filenames are accepted by the filesystem
• 0 if the NFC is converted to NFD
• undef in any other case (errors)