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

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

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

Summary:

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

dumpIndexes

1. loadIndexes()
2. FileDigest::dataOutline(), again as HTML

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

compareFile

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

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

diffFiles

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"');

    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

Timeline

• Don't hold your breath!

-- MartinCleaver - 22 Oct 2004