ENH: New --list option which lists all plugins and exits

fsl/add_module/ui.py

@@ -29,7 +29,8 @@ from   fsl.add_module.messages        import (info,
                                               warning,
                                               error,
                                               prompt,
-                                              EMPHASIS)
+                                              EMPHASIS,
+                                              UNDERLINE)
 
 
 def downloadPluginManifest(url : Union[str, pathlib.Path]) -> Manifest:
@@ -51,6 +52,35 @@ def downloadPluginManifest(url : Union[str, pathlib.Path]) -> Manifest:
     return manifest
 
 
+def listPlugins(manifest : Manifest, verbose : bool = False):
+    """Prints a list of all available plugins.
+
+    :arg manifest: :class:`.Manifest` object describing all available plugins.
+    :arg verbose:  If true, more information is printed.
+    """
+    important('Modules available for download:', EMPHASIS)
+
+    categories = manifest.categories
+
+    for category in categories:
+        info(f'Category: {category}', UNDERLINE)
+        plugins = manifest.getCategory(category)
+
+        for plugin in plugins:
+            info(f'{plugin.name:25s}', EMPHASIS, indent=2)
+
+            if plugin.description is not None:
+                info(plugin.description, indent=4, wrap=True)
+
+            if verbose:
+                for item in ('url', 'destination', 'checksum'):
+                    value = getattr(plugin, item)
+                    item  = f'{item}:'
+                    if value in (None, ''):
+                        value = 'N/A'
+                    info(f'{item:12s} {value}', indent=4)
+
+
 def createArchiveDir(archiveDir : Union[str, pathlib.Path]):
     """Creates the directory used to store/cache downloaded plugin archive
     files.

fsl/scripts/fsl_add_module.py

@@ -5,7 +5,7 @@
 # Author: Paul McCarthy <pauldmccarthy@gmail.com>
 #
 """The ``fsl_add_module`` script is used for downloading and installing FSL
-"plugins" - archive files (e.g. ``.tar.gz`` ``.zip``, etc.).
+"modules"/"plugins" - archive files (e.g. ``.tar.gz`` ``.zip``, etc.).
 
 Normal execution of this script is as follows:
 
@@ -77,6 +77,19 @@ When called in one of the above forms, ``fsl_add_module`` will:
     plugin.
 
  4. Download and install each plugin.
+
+
+::
+
+    fsl_add_module -l
+    fsl_add_module -l -m <manifest_url>
+
+When called in one of the above forms, ``fsl_add_module`` will:
+
+ 1. Download a manifest file from the default :data:`MANIFEST_URL`, or
+    ``<manifest_url>`` if specified
+
+ 2. Print a list of all available plugins and exit.
 """
 
 
@@ -97,7 +110,7 @@ from   fsl.add_module.messages        import (info,
                                               UNDERLINE)
 
 
-MANIFEST_URL = 'http://fsl.fmrib.ox.ac.uk/fslcourse/downloads/manifest.txt'
+MANIFEST_URL = 'http://fsl.fmrib.ox.ac.uk/fsldownloads/manifest.txt'
 """Location of the official FSL plugin manifest file, downloaded if an
 alternate manifest file is not specified.
 """
@@ -114,33 +127,39 @@ def parseArgs(argv : List[str]) -> argparse.Namespace:
 
     helps = {
         'version'     : 'Print version and exit.',
-        'plugin'      : 'Name or URL of FSL plugin to download.',
-        'manifest'    : 'URL to plugin manifest file.',
+        'verbose'     : 'Output more information.',
+        'list'        : 'Print all available modules and exit. All other '
+                        'options, apart from --manifest, are ignored.',
+        'module'      : 'Name or URL of FSL module to download.',
+        'manifest'    : 'URL to module manifest file.',
         'archiveDir'  : 'Directory to cache downloaded files in.',
-        'category'    : 'Only display available plugins from the specified '
-                        'category. Ignored if plugins are explicitly '
+        'category'    : 'Only display available modules from the specified '
+                        'category. Ignored if modules are explicitly '
                         'specified on the command-line.',
-        'destination' : 'Destination directory to install plugin files. If '
-                        'used once, applies to all plugins. Otherwise, must '
-                        'be specified for each plugin that is specified on '
+        'destination' : 'Destination directory to install module files. If '
+                        'used once, applies to all modules. Otherwise, must '
+                        'be specified for each module that is specified on '
                         'the command-line. If not provided, you will be '
                         'prompted to select the destination directory for '
-                        'each plugin.',
+                        'each module.',
         'force'       : 'If used, you will not be asked any questions, and '
                         'all default settings will be applied. Can only be '
-                        'used when the plugins you wish to have installed '
+                        'used when the modules you wish to have installed '
                         'are specified on the command-line. '
     }
 
     parser = argparse.ArgumentParser(
         'fsl_add_module',
-        usage='fsl_add_module [options] [plugins]',
-        description='Download and install FSL plugins')
+        usage='fsl_add_module [options] [modules]',
+        description='Download and install FSL modules')
     parser.add_argument(
         '-V', '--version', action='version', help=helps['version'],
         version='%(prog)s {}'.format(__VERSION__))
     parser.add_argument(
-        'plugin', nargs='*', help=helps['plugin'])
+        '-v', '--verbose', action='store_true', help=helps['verbose'])
+    parser.add_argument(
+        '-l', '--list', action='store_true', dest='listPlugins',
+        help=helps['list'])
     parser.add_argument(
         '-m', '--manifest', default=MANIFEST_URL, help=helps['manifest'])
     parser.add_argument(
@@ -151,6 +170,7 @@ def parseArgs(argv : List[str]) -> argparse.Namespace:
         '-d', '--destination', action='append', help=helps['destination'])
     parser.add_argument(
         '-f', '--force', action='store_true', help=helps['force'])
+    parser.add_argument('module', nargs='*', help=helps['module'])
 
     args = parser.parse_args(argv)
 
@@ -158,11 +178,11 @@ def parseArgs(argv : List[str]) -> argparse.Namespace:
         args.archiveDir = op.abspath(args.archiveDir)
 
     if args.destination is not None:
-        if len(args.destination) not in (1, len(args.plugin)):
+        if len(args.destination) not in (1, len(args.module)):
             parser.error('The --destination option must either be specified '
                          'exactly once, or once for every requested module.')
 
-    if args.force and len(args.plugin) == 0:
+    if args.force and len(args.module) == 0:
         parser.error('The --force option may only be used when you specify '
                      'which module to install on the command line.')
 
@@ -187,7 +207,7 @@ def loadManifest(args : argparse.Namespace) -> Tuple[plgman.Manifest,
     """
 
     manifest = ui.downloadPluginManifest(args.manifest)
-    plugins  = list(args.plugin)
+    plugins  = list(args.module)
 
     # assume that any plugins that were specified
     # on the command line, and which are not in
@@ -321,13 +341,17 @@ def main(argv=None):
 
     try:
 
-        manifest, plugins = loadManifest( args)
-        plugins           = selectPlugins(args, manifest, plugins)
+        manifest, plugins = loadManifest(args)
+
+        if args.listPlugins:
+            ui.listPlugins(manifest, args.verbose)
 
-        if len(plugins) > 0:
-            ui.createArchiveDir(args.archiveDir)
-            download(           args, plugins)
-            install(            args, plugins)
+        else:
+            plugins = selectPlugins(args, manifest, plugins)
+            if len(plugins) > 0:
+                ui.createArchiveDir(args.archiveDir)
+                download(           args, plugins)
+                install(            args, plugins)
 
     except Exception as e:
         error(str(e))