BUILT! A TWikiReleaseTrackerPlugin::Shell CommandSet for the TRT

See TWikiReleaseTrackerPluginCommands

Motive

TRT differencing is only available via the web
I had shied away from building yet-another-script with dubious semantics
I want to try out Rafael's TWikiShellContrib
The TRT produces diffs - sometimes you want them via the shell rather than over the web

Current interface

The TRT provides a CommonTagsHandler

Macro	CGI Entry point
%DIFFWIKI	handleDiffWiki	Calls either listFiles, dumpIndex, IndexDistributions ::indexLocalInstallation, or compareFile
%DIFFWIKIINDEX	handleShowIndex	Calls either FileDigest ::getDistributions or FileDigest ::getFilenames
%WIKIVERSIONASDISTNAME	handleConvertWikiVersion	Calls TWiki::Contrib::DistributionContrib::TWikiReleaseNames::wikiVersionToDistributionName

The CGI Entry point deal with extraction of parameters from CGI into passed parameters.

Whether this is separable depends on the degree of encapsulation: if modular I should be able to route calls from the shell instead.

listFiles

loadIndexes()
builds an HTML response (why is this not TML - I don't remember?! I think something to do with newlines breaking TML tables)
sets up a callback sub ($matchCallback) for every file found:
- FileDigest ::retreiveDistributionsForDigest
- FileDigest ::retreiveDistributionsForFilename

Summary:

Factor	Evaluation
functionality	useful
modularity	good
interactivity	low

Conclusion: it would be simple to place HTML into another layer and make accessible as a TWikiShellContrib CommandSet

dumpIndexes

loadIndexes()
FileDigest ::dataOutline(), again as HTML

Factor	Evaluation
functionality	useful
modularity	good
interactivity	none

Conclusion: it would be trivial to place HTML into another layer and make accessible as a TWikiShellContrib CommandSet

compareFile

Provides dialog to dig down into a distribution in either lineCountMode or diffMode

Again, as HTML, builds a page to allow navigation to the individual diffs

Factor	Evaluation
functionality	low
modularity	good
interactivity	high

Conclusion: interactive: would need complete rework; not worth it. Perhaps I should go a deeper layer.

diffFiles

Does the actual diffMode compare

Conclusion: a worthy candidate

Required interface

twikishell ext ?? compareFile
twikishell ext ?? list
twikishell ext ?? dump

Implementation plan

Create a TWiki::Plugins::TWikiReleaseTrackerPlugin::Shell class that implements and delegates command line routines to TWikiReleaseTrackerPlugin and its supporting functions.

Also provide a call-anything-mechanism so that non-run subs can be called for testing purposes.

Caveats

Lessons learnt

The process draws attention to where you have initialised stuff. In my code I'd initialised inconsistently: sometimes lower down in the call tree than others. When I then tried to call this from the TWikiShell it meant that I sometimes initialised more than once.
Some intialisation is in the initPlugin class - if the functionality is going to be called externally i.e. from twikishell then non-plugin initialisation needs to be split out into something that can be called from either Plugin/Shell direction.
- Some plugins are going to be doing extensive setup during its loading.
This opens up your code to other programmers - so you can no longer guarantee that parameters will be spelt right or will be present. Caveat emptor!

Points for discussion

The testsuite (TWikiReleaseTrackerPlugin/tests/testPluginTestSuite.pl) does regression testing by calling lines such as:

    saveResult("test1.actualResults", 'indexTopic="TWiki.TRTTestSuite" from="localInstallation" statusFilter="all"');

which is handed off as:

    my $res = TWiki::Plugins::TWikiReleaseTrackerPlugin::handleDiffWiki($testString);

Would users using a shell be willing to type, e.g.

$ diffwiki indexTopic="TWiki.TRTTestSuite" from="localInstallation" statusFilter="all"
$ diffwiki from="distroNone" indexTopic="TWiki.TRTTestSuite" to="distro1" statusFilter="all"

Probably, yes.

Martin tries routing Shell::run_diffwiki to TWiki::Plugins::TWikiReleaseTrackerPlugin::handleDiffWiki