Changeset 8022

Timestamp:

07/04/10 11:45:19 (3 years ago)

Author:

CrawfordCurrie

Message:

Item9232: more doccing

Location:

trunk/core

Files:

• bin/configure (modified) (4 diffs)
• lib/Foswiki/Configure/Checker.pm (modified) (10 diffs)
• lib/Foswiki/Configure/Checkers/Store/Implementation.pm (modified) (1 diff)
• lib/Foswiki/Configure/Types/URL.pm (modified) (1 diff)
• lib/Foswiki/Configure/Types/URLPATH.pm (modified) (1 diff)

trunk/core/bin/configure

@@ -32 +32 @@
 not be consistent with the structure of $Foswiki:cfg, so beware). Each
 leaf node has an associated Type (in the Types subdirectory) that has
-collected model and view behaviours for the basic types. The node tree
-is made up of the classes:
+collected model and view behaviours for the basic types.
+
+Class hierarchy
   * Foswiki::Configure::Item
      * Foswiki::Configure::Value - a leaf value
@@ -60 +61 @@
 model for these sections.
 
-These are top-level pluggable UI components. All the main screens are
-implemented as UIs, under Foswiki::Configure::UIs.
+Class hierarchy
+   * Foswiki::Configure::UI
+      * Foswiki::Configure::Checker
+         * Foswiki::Configure::Checkers::* - see below
+      * Foswiki::Configure::UIs::* - components used in building screens
+         * Foswiki::Configure::UIs::Item
+            * Foswiki::Configure::UIs::Section
+               * Foswiki::Configure::UIs::Root
+            * Foswiki::Configure::UIs::Value
 
 ---+++ Checkers
@@ -72 +80 @@
 ---+++ Types
 Types provide some UI support in the form of type-specific prompters.
-this is really an abuse of the Model, but it saves creating
+This is really an abuse of the Model, but it saves creating
 decorator classes for all the Model types.
 
@@ -78 +86 @@
 is visited in depth-first order.
 
+Class hierarchy
+   * Foswiki::Configure::Type - base
+      * Foswiki::Configure::Types::NUMBER - numerical type (perl float values)
+         * Foswiki::Configure::Types::OCTAL - octal (permissions)
+      * Foswiki::Configure::Types::BOOLEAN - boolean type
+         * Foswiki::Configure::Types::LANGUAGE
+      * Foswiki::Configure::Types::PERL - perl structure
+      * Foswiki::Configure::Types::SELECT - select from a list of values
+         * Foswiki::Configure::Types::SELECTCLASS - select a class from a path
+      * Foswiki::Configure::Types::STRING - string type
+         * Foswiki::Configure::Types::REGEX - regular expression
+         * Foswiki::Configure::Types::COMMAND - shell command
+         * Foswiki::Configure::Types::PASSWORD - hidden password
+         * Foswiki::Configure::Types::PATH - file path (/)
+         * Foswiki::Configure::Types::URL - absolute url path (/)
+         * Foswiki::Configure::Types::URLPATH - relative url path (/)
+      * Foswiki::Configure::Types::UNKNOWN - unknown type
+
+TODO:
+The type classes are the obvious place to attach client-side javascript
+validators, thus releasing the server-side checkers to consider the "deeper"
+issues.
 
 =cut

trunk/core/lib/Foswiki/Configure/Checker.pm

@@ -1 +1 @@
 # See bottom of file for license and copyright information
+
+=begin TML
+
+---+ package Foswiki::Configure::Checker;
+
+Base class of all checkers. Checkers give checking and guessing support
+for configuration values. Most of the methods of this class are intended
+to be protected i.e. only available to subclasses.
+
+=cut
 
 package Foswiki::Configure::Checker;
@@ -14 +24 @@
 =begin TML
 
----+++ ObjectMethod check($value) -> $html
+---++ ObjectMethod check($value) -> $html
    * $value - Value object for the thing being checked
 
 Entry point for the value check. Overridden by subclasses.
 
-Returns html formatted by $this->ERROR(), WARN(), NOTE(), guessed() or
-hand made _OR_ and empty string to be inserted in the configure UI
-
-The checker can either check the sanity of the previously saved value,
-or guess a one if none exists:
+Returns html formatted by $this->ERROR(), WARN(), NOTE(), or
+hand made _OR_ an empty string. The output of a checker will normally
+be included in an HTML table, so don't get too carried away.
 
 =cut
@@ -33 +41 @@
     return '';
 }
+
+=begin TML
+
+---++ PROTECTED ObjectMethod guessed($status) -> $html
+
+A checker can either check the sanity of the previously saved value,
+or guess a one if none exists. If the checker guesses, it should call
+=$this->guessed(0)= (passing 1 if the guess was an error).
+
+=cut
 
 sub guessed {
@@ -50 +68 @@
     }
 }
+
+=begin TML
+
+---++ PROTECTED ObjectMethod warnAboutWindowsBackSlashes($path) -> $html
+
+Generate a warning if the supplied pathname includes windows-style
+path separators.
+
+=cut
 
 sub warnAboutWindowsBackSlashes {
@@ -60 +87 @@
     }
 }
+
+=begin TML
+
+---++ PROTECTED ObjectMethod guessMajorDir($cfg, $dir, $silent) -> $html
+
+Try and guess the path of one of the major directories, by looking relative
+to the absolute pathname of the dir where configure is being run.
+
+=cut
 
 sub guessMajorDir {
@@ -80 +116 @@
 
 =begin TML
----+++ ObjectMethod checkTreePerms($path, $perms, $filter) -> 'html'
-
-Called by a Checker to perform
-a recursive check of the specified path.  The recursive check 
+
+---++ PROTECTED ObjectMethod checkTreePerms($path, $perms, $filter) -> $html
+
+Perform a recursive check of the specified path.  The recursive check 
 is limited to the configured "PathCheckLimit".  This prevents excessive
 delay on installations with large data or pub directories.  The
@@ -203 +239 @@
 }
 
+=begin TML
+
+---++ PROTECTED ObjectMethod checkCanCreateFile($path) -> $html
+
+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 or the empty string if the check passed.
+
+=cut
+
 sub checkCanCreateFile {
     my ( $this, $name ) = @_;
@@ -235 +283 @@
 }
 
-# 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.
+=begin TML
+
+---++ PROTECTED ObjectMethod checkGnuProgram($prog) -> $html
+
+Check for the availability of a GNU program.
+
+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.
+
+=cut
+
 sub checkGnuProgram {
     my ( $this, $prog ) = @_;
@@ -279 +336 @@
 }
 
-# Check for a compilable RE
+=begin TML
+
+---++ PROTECTED ObjectMethod checkRE($keys) -> $html
+Check that the configuration item identified by the given keys represents
+a compilable perl regular expression.
+
+=cut
+
 sub checkRE {
     my ( $this, $keys ) = @_;
@@ -295 +359 @@
 }
 
-sub copytree {
-    my ( $this, $from, $to ) = @_;
-    my $e = '';
-
-    if ( -d $from ) {
-        if ( !-e $to ) {
-            mkdir($to) || return "Failed to mkdir $to: $!<br />";
-        }
-        elsif ( !-d $to ) {
-            return "Existing $to is in the way<br />";
-        }
-
-        my $d;
-        return "Failed to copy $from: $!<br />" unless opendir( $d, $from );
-        foreach my $f ( grep { !/^\./ } readdir $d ) {
-            $f =~ /(.*)/;
-            $f = $1;    # untaint
-            $e .= $this->copytree( "$from/$f", "$to/$f" );
-        }
-        closedir($d);
-    }
-
-    if ( !$e && !-e $to ) {
-        require File::Copy;
-        if ( !File::Copy::copy( $from, $to ) ) {
-            $e = "Failed to copy $from to $to: $!<br />";
-        }
-    }
-    return $e;
-}
-
 my $rcsverRequired = 5.7;
+
+=begin TML
+
+---++ PROTECTED ObjectMethod checkRCSProgram($prog) -> $html
+Specific to RCS, this method checks that the given program is available.
+Check is only activated when the selected store implementation is RcsWrap.
+
+=cut
 
 sub checkRCSProgram {

trunk/core/lib/Foswiki/Configure/Checkers/Store/Implementation.pm

@@ -18 +18 @@
 RcsWrap does not work well on Windows, please use RcsLite.
 EOF
-    }
-    
-    if ( $Foswiki::cfg{Store}{Implementation} =~ /RcsWrap/ ) {
-
-        # Check that GNU diff is found in PATH; used by rcsdiff
-        $mess .= $this->checkGnuProgram('diff');
-
-        # Check all the RCS programs
-        $mess .= $this->checkRCSProgram('initBinaryCmd');
-        $mess .= $this->checkRCSProgram('initTextCmd');
-        $mess .= $this->checkRCSProgram('tmpBinaryCmd');
-        $mess .= $this->checkRCSProgram('ciCmd');
-        $mess .= $this->checkRCSProgram('ciDateCmd');
-        $mess .= $this->checkRCSProgram('coCmd');
-        $mess .= $this->checkRCSProgram('histCmd');
-        $mess .= $this->checkRCSProgram('infoCmd');
-        $mess .= $this->checkRCSProgram('histCmd');
-        $mess .= $this->checkRCSProgram('diffCmd');
-        $mess .= $this->checkRCSProgram('lockCmd');
-        $mess .= $this->checkRCSProgram('unlockCmd');
-        $mess .= $this->checkRCSProgram('delRevCmd');
     }
 

trunk/core/lib/Foswiki/Configure/Types/URL.pm

@@ -6 +6 @@
 use warnings;
 
-use Foswiki::Configure::Type ();
-our @ISA = ('Foswiki::Configure::Type');
+use Foswiki::Configure::Types::STRING ();
+our @ISA = ('Foswiki::Configure::Types::STRING');
 
 sub new {

trunk/core/lib/Foswiki/Configure/Types/URLPATH.pm

@@ -8 +8 @@
 use Foswiki::Configure::Types::STRING ();
 our @ISA = ('Foswiki::Configure::Types::STRING');
+
+sub new {
+    my $class = shift;
+
+    return bless( { name => 'URLPATH' }, $class );
+}
 
 1;