Item14152: Started with new extensions documentation.

Finally...

- Added Empty extension.

- Foswiki::Extensions reject to register the Empty extension.

- Minor cleanups.

EmptyExtension/lib/Foswiki/Extension/Empty.pm

@@ -0,0 +1,110 @@
+# See bottom of file for license and copyright information
+
+package Foswiki::Extension::Empty;
+
+=begin TML
+
+---+ Class Foswiki::Extension::Empty
+
+This is a template module demostrating basic functionality provided by %WIKITOOLNAME%
+extensions framework.
+
+__NOTE:__ This documention is yet incomplete for now and only focused on
+documenting key parts of the new Extensions model.
+
+=cut
+
+use Foswiki::Class qw(extension);
+extends qw(Foswiki::Extension);
+
+=begin TML
+
+---++ The Ecosystem
+
+Extensions exists as a list of objects managed by =Foswiki::App= =extensions=
+attribute which is actually an object of =Foswiki::Extensions= class. The latter
+provides API for extension manipulation routines like loading and registering an
+extension; registering extension's components like overriding methods or
+classes; find an extenion object by name; etc.
+
+An extension should be registered in =Foswiki::Extension= namespace. I.e. if we
+create a =Sample= extension then its full name would be
+=Foswiki::Extension::Sample=. Though this rule is not strictly imposed but it
+comes in handy when one wants to refer to an extension by its short name. The
+extension manager uses string stored in its =extPrefix= read only attribute to
+form an extension full name; by default the attribute is initialized with
+=Foswiki::Extension= string and there is no legal way to change it during
+application's life cycle.
+
+It is also mandatory for an extension class to subclass =Foswiki::Extension=.
+The manager would reject a class registration if this rule is broken.
+
+At any given moment of time there is only one active set of extensions
+accessible via the application's =extensions= attribute. It means that if there
+is a registered =Sample= extension then whenever we a ask for the extension's
+object then we can be sure that there is no more than signle active one exists.
+This is an important rule for some of [[#ExportedSubs][exported subroutines]].
+
+=Foswiki::Extensions= module has its own =$VERSION= global var. It represents
+%WIKITOOLNAME% API version and is used to check an extension compatibility.
+
+---++ Starting a new extension module
+
+Choose a name for an extension. Check if it's not alredy used. Start the module
+with the following lines:
+
+<verbatim>
+package Foswiki::Extension::<your chosen name>;
+
+use Foswiki::Class qw(extension);
+extends qw(Foswiki::Extension);
+
+use version 0.77; our $VERSION = version->declare(0.0.1);
+our $API_VERSION = version->declare("2.99.0");
+</verbatim>
+
+=$API_VERSION= declares the minimal version of =Foswiki::Extensions= module
+required.
+
+=cut
+
+use version 0.77; our $VERSION = version->declare(0.0.1);
+our $API_VERSION = version->declare("2.99.0");
+
+=begin TML
+
+#ExportedSubs
+---++ Foswiki::Class exported subroutines
+
+Being used with =extension= parameter =Foswiki::Class= exports a set of
+subroutines 
+
+=cut
+
+=begin TML
+
+---++ SEE ALSO
+
+=Foswiki::Extensions=, =Foswiki::Extension=, =Foswiki::Class=.
+
+=cut
+
+1;
+__END__
+Foswiki - The Free and Open Source Wiki, http://foswiki.org/
+
+Copyright (C) 2016 Foswiki Contributors. Foswiki Contributors
+are listed in the AUTHORS file in the root of this distribution.
+NOTE: Please extend that file, not this notice.
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version. For
+more details read LICENSE in the root of this distribution.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+As per the GPL, removal of this notice is prohibited.

core/lib/Foswiki/Class.pm

@@ -166,13 +166,8 @@ sub import {
             # Install BUILD method if callbacks feature requested.
             # Otherwise Foswiki::Aux::Callbacks fails to apply cleanly.
             unless ( defined $ns->{BUILD} && defined *{ $ns->{BUILD} }{CODE} ) {
-                say STDERR "Installing BUILD";
                 install_modifier( $target, fresh => BUILD => sub { } );
             }
-            else {
-                say STDERR "BUILD exists for $target: ", $ns->{BUILD}, "//",
-                  *{ $ns->{BUILD} }{CODE};
-            }
         }
         $class->_apply_roles;
     };
@@ -200,8 +195,6 @@ sub _inject_code {
 sub _apply_roles {
     my $class = shift;
     foreach my $target ( keys %_assignedRoles ) {
-        say STDERR "Applying to $target: ", join ",",
-          map { "{$_}" } @{ $_assignedRoles{$target} };
         Moo::Role->apply_roles_to_package( $target,
             @{ $_assignedRoles{$target} } );
         $class->_maybe_reset_handlemoose($target);

core/lib/Foswiki/Exception.pm

@@ -5,13 +5,13 @@ use v5.14;
 
 =begin TML
 
----+ package Foswiki::Exception
+---+ Class Foswiki::Exception
 
 Base class for all Foswiki exceptions. This is still a concept only.
 
 Basic principles behind exceptions:
 
-   1. Exceptions are using =CPAN:Try::Tiny=. Use of =CPAN:Error= module is no longer
+   1. Exceptions are using =Try::Tiny=. Use of =CPAN:Error= module is no longer
       recommended.
    1. Exception classes are inheriting from =Foswiki::Exception=.
    1. =Foswiki::Exception= is an integral part of Fowiki's OO system and inheriting from =Foswiki::Object=.

core/lib/Foswiki/Extensions.pm

@@ -1,8 +1,16 @@
 # See bottom of file for license and copyright information
 
 package Foswiki::Extensions;
-use strict;
-use warnings;
+
+=begin TML
+
+---++!! Class Foswiki::Extensions
+
+[[https://foswiki.org/Development/OONewPluginModel][Foswiki OONewPluginModel topic]]
+could serve as a temporary explanasion of why this module extists and what
+functionality it is expected to provide.
+
+=cut
 
 use File::Spec     ();
 use IO::Dir        ();
@@ -516,6 +524,10 @@ sub mapClass {
 Returns extensions disabled for this installation or host. %disabled hash keys
 are extension names, values are text reasons for disabling the extension.
 
+*NOTE* Extension =Foswiki::Extension::Empty= is hard coded into the list of
+disabled extensions because its purpose is to be a template for developing
+functional extensions.
+
 =cut
 
 sub prepareDisabledExtensions {
@@ -535,6 +547,9 @@ sub prepareDisabledExtensions {
         $envDisabled = [ split /,/, $envDisabled ];
     }
 
+    # Never enable extension Empty. It's purpose is to serve as a template only.
+    push @$envDisabled, 'Empty';
+
     %disabled =
       map {
         $this->normalizeExtName($_) =>
@@ -925,6 +940,14 @@ sub isRegistered {
     return $registeredModules{$extModule} // 0;
 }
 
+=begin TML
+
+---++ SEE ALSO
+
+=Foswiki::Extension::Empty=, =Foswiki::Class=.
+
+=cut
+
 1;
 __END__
 Foswiki - The Free and Open Source Wiki, http://foswiki.org/

core/lib/Foswiki/IncludeHandlers/doc.pm

@@ -297,7 +297,7 @@ sub _renderTitle {
 sub _doclink ($) {
     my $app    = shift;
     my $module = $_[0];
-    $module =~ /^/; # Do it to reset $n match variables.
+    $module =~ /^/;                # Do it to reset $n match variables.
     $module =~ s/^_(.+)(_)$/$1/;
     my $formatChar = $2 // '';
     my $title = $_[1] || $module;

core/lib/Foswiki/Infix/OP.pm

@@ -1,9 +1,7 @@
 # See bottom of file for license and copyright information
 package Foswiki::Infix::OP;
-use v5.14;
 
-use Moo;
-use namespace::clean;
+use Foswiki::Class;
 extends qw(Foswiki::Object);
 
 =begin TML

core/lib/Foswiki/Infix/Parser.pm

@@ -31,8 +31,7 @@ use Try::Tiny;
 use Foswiki::Infix::Error ();
 use Foswiki::Infix::Node  ();
 
-use Moo;
-use namespace::clean;
+use Foswiki::Class;
 extends qw(Foswiki::Object);
 
 # Set to 1 for debug

core/lib/Foswiki/Macros/QUERY.pm

@@ -65,8 +65,7 @@ sub expand {
         return '';
     }
     unless ($evalParser) {
-        require Foswiki::Query::Parser;
-        $evalParser = new Foswiki::Query::Parser();
+        $evalParser = $this->app->create('Foswiki::Query::Parser');
     }
 
     $this->evaluatingEval->{$expr}++;

core/lib/Foswiki/Query/OP_lt.pm

@@ -9,8 +9,7 @@
 package Foswiki::Query::OP_lt;
 use v5.14;
 
-use Moo;
-use namespace::clean;
+use Foswiki::Class;
 extends qw(Foswiki::Query::ConditionalOP);
 with qw(Foswiki::Query::OP);
 

core/lib/Foswiki/Query/Parser.pm

@@ -14,8 +14,6 @@ Foswiki::Infix::Node)
 
 package Foswiki::Query::Parser;
 
-use strict;
-use warnings;
 use Assert;
 
 BEGIN {
@@ -66,8 +64,7 @@ use Foswiki::Query::OP_int    ();    # 1000
 
 use Foswiki::Query::OP_ob ();        # 1100
 
-use Moo;
-use namespace::clean;
+use Foswiki::Class;
 extends 'Foswiki::Infix::Parser';
 
 has words => (