Merge pull request #104 from wflynny/alias-desc

Allows aliases with descriptions.

Alias can be defined as currently supported and as subsections of the `[[alias]]` section of `conf.py` of the form:
```
[[[alias-name]]]
command = alias-command-definition
description = alias-description
```

Note that aliases defined this way must be placed at the end of the [[alias]] section or they will gobble up aliases defined in the current format. This is a limitation of `ConfigObj` sectioning.

pubs/config/spec.py

@@ -88,6 +88,13 @@ active = force_list(default=list('alias'))
 # shell commands can also be defined, by prefixing them with a bang `!`, e.g:
 # count = !pubs list -k | wc -l
 
+# aliases can also be defined with descriptions using the following configobj
+# subsectioning.  NOTE: any aliases defined this way should come after all other
+# aliases, otherwise simple aliases will be ignored.
+# [[[count]]]
+# command = !pubs list -k | wc -l
+# description = lists number of pubs in repo
+
 [internal]
 # The version of this configuration file. Do not edit.
 version = string(min=5, default='{}')

pubs/plugs/alias/alias.py

@@ -8,26 +8,30 @@ from ...pubs_cmd import execute
 
 class Alias(object):
 
-    def __init__(self, name, definition):
+    def __init__(self, name, definition, description=None):
         self.name = name
         self.definition = definition
+        if not description:
+            self.description = "user alias for `%s`"%definition
+        else:
+            self.description = description
 
     def parser(self, parser):
         self.parser = parser
-        p = parser.add_parser(self.name, help='user defined command')
+        p = parser.add_parser(self.name, help=self.description)
         p.add_argument('arguments', nargs='*',
-            help="arguments to be passed to the user defined command")
+            help="arguments to be passed to %s"%self.name)
         return p
 
     def command(self, conf, args):
         raise NotImplementedError
 
     @classmethod
-    def create_alias(cls, name, definition):
+    def create_alias(cls, name, definition, description=None):
         if len(definition) > 0 and definition[0] == '!':
-            return ShellAlias(name, definition[1:])
+            return ShellAlias(name, definition[1:], description)
         else:
-            return CommandAlias(name, definition)
+            return CommandAlias(name, definition, description)
 
 
 class CommandAlias(Alias):
@@ -64,8 +68,16 @@ class AliasPlugin(PapersPlugin):
     def __init__(self, conf):
         self.aliases = []
         if 'alias' in conf['plugins']:
-            for name, definition in conf['plugins']['alias'].items():
+            for name, entry in conf['plugins']['alias'].items():
-                self.aliases.append(Alias.create_alias(name, definition))
+                if isinstance(entry, dict):
+                    definition = entry.get('command')
+                    description = entry.get('description', None)
+                else:
+                    definition = entry
+                    description = None
+
+                alias = Alias.create_alias(name, definition, description)
+                self.aliases.append(alias)
 
     def update_parser(self, subparsers, conf):
         """Add subcommand to the provided subparser"""

tests/test_plug_alias.py

@@ -93,3 +93,57 @@ class AliasPluginTestCase(unittest.TestCase):
                                          'count': '!pubs list -k | wc -l'}
         self.plugin = AliasPlugin(self.conf)
         self.assertEqual(len(self.plugin.aliases), 2)
+
+    def testAliasPluginNestedDefinitionType(self):
+        self.conf['plugins']['alias'] = {'print': {'description': 'print this',
+                                                   'command': 'open -w lpppp'}}
+        self.plugin = AliasPlugin(self.conf)
+        self.assertEqual(len(self.plugin.aliases), 1)
+        self.assertEqual(type(self.plugin.aliases[0]), CommandAlias)
+        self.assertEqual(self.plugin.aliases[0].name, 'print')
+        self.assertEqual(self.plugin.aliases[0].description, 'print this')
+        self.assertEqual(self.plugin.aliases[0].definition, 'open -w lpppp')
+
+    def testAliasPluginNestedDefinitionNoDescription(self):
+        self.conf['plugins']['alias'] = {'print': {'command': 'open -w lpppp'}}
+        self.plugin = AliasPlugin(self.conf)
+        self.assertEqual(len(self.plugin.aliases), 1)
+        self.assertEqual(type(self.plugin.aliases[0]), CommandAlias)
+        self.assertEqual(self.plugin.aliases[0].name, 'print')
+        self.assertEqual(self.plugin.aliases[0].description,
+                         'user alias for `open -w lpppp`')
+        self.assertEqual(self.plugin.aliases[0].definition, 'open -w lpppp')
+
+    def testAliasPluginMixedDefinitionTypes(self):
+        self.conf['plugins']['alias'] = {'print': {'description': 'print this',
+                                                   'command': 'open -w lpppp'},
+                                         'count': '!pubs list -k | wc -l'}
+        self.plugin = AliasPlugin(self.conf)
+        self.plugin.aliases = sorted(self.plugin.aliases, key=lambda a: a.name)
+
+        self.assertEqual(len(self.plugin.aliases), 2)
+        self.assertEqual(type(self.plugin.aliases[1]), CommandAlias)
+        self.assertEqual(type(self.plugin.aliases[0]), ShellAlias)
+
+        self.assertEqual(self.plugin.aliases[0].name, 'count')
+        self.assertEqual(self.plugin.aliases[0].description,
+                         'user alias for `pubs list -k | wc -l`')
+        self.assertEqual(self.plugin.aliases[0].definition,
+                         'pubs list -k | wc -l')
+
+        self.assertEqual(self.plugin.aliases[1].name, 'print')
+        self.assertEqual(self.plugin.aliases[1].description, 'print this')
+        self.assertEqual(self.plugin.aliases[1].definition, 'open -w lpppp')
+
+    def testAliasPluginWrongDefinitionOrder(self):
+        self.conf['plugins']['alias'] = {'print': {'description': 'print this',
+                                                   'command': 'open -w lpppp',
+                                         'count': '!pubs list -k | wc -l'}}
+        self.plugin = AliasPlugin(self.conf)
+
+        self.assertEqual(len(self.plugin.aliases), 1)
+        self.assertEqual(type(self.plugin.aliases[0]), CommandAlias)
+
+        self.assertEqual(self.plugin.aliases[0].name, 'print')
+        self.assertEqual(self.plugin.aliases[0].description, 'print this')
+        self.assertEqual(self.plugin.aliases[0].definition, 'open -w lpppp')