Add option --sort to 'list' command (#267)

* Add option --sort to 'list' command

The --sort option controls the order in which the tasks are listed.
Currently, two options are supported:

name: sort the tasks by name (the default)
definition: lists the tasks in the order in which they are defined

* Remove redundant test. Add --sort parameter to docs.

AUTHORS

@@ -24,3 +24,4 @@
  * Simon Mutch - https://github.com/smutch
  * Michael Milton - https://github.com/tmiguelt
  * Mike Pagel - https://github.com/moltob
+ * Marijn van Vliet - https://github.com/wmvanvliet

CHANGES

@@ -16,6 +16,7 @@ Changes
  - Fix #113: `tools.config_changed` deals with nested dictionaries.
              Using json instead of repr.
  - Fix #261: help organize command options in sections, and improve formatting.
+ - Fix #267: `doit list` now has a `--sort` parameter to determine the order in which the tasks are listed.
 
 
 0.31.1 (*2018-03-18*)

doc/cmd_other.rst

@@ -34,7 +34,8 @@ list
 ------
 
 *list* is used to show all tasks available in a *dodo* file.
-Tasks are listed in alphabetical order, not by order of execution.
+Tasks are listed in alphabetical order by default, but *--sort=definition* can
+be speficied to sort them in the order in which they appear in the `dodo` file.
 
 .. code-block:: console
 

doit/cmd_list.py

@@ -55,14 +55,27 @@
     'help': "display entries with template"
     }
 
+opt_sort = {
+    'name': 'sort',
+    'short': '',
+    'long': 'sort',
+    'type': str,
+    'choices': [('name', 'sort by task name'),
+                ('definition', 'list tasks in the order they were defined')],
+    'default': 'name',
+    'help': ("choose the manner in which the task list is sorted. "
+             "[default: %(default)s]")
+    }
+
 
 class List(DoitCmdBase):
     doc_purpose = "list tasks from dodo file"
     doc_usage = "[TASK ...]"
     doc_description = None
 
     cmd_options = (opt_listall, opt_list_quiet, opt_list_status,
-                   opt_list_private, opt_list_dependencies, opt_template)
+                   opt_list_private, opt_list_dependencies, opt_template,
+                   opt_sort)
 
 
     STATUS_MAP = {'ignore': 'I', 'up-to-date': 'U', 'run': 'R', 'error': 'E'}
@@ -113,10 +126,9 @@ def _list_all(self, include_subtasks):
         return print_list
 
 
-    def _execute(self, subtasks=False, quiet=True, status=False,
-                 private=False, list_deps=False, template=None, pos_args=None):
-        """List task generators, in the order they were defined.
-        """
+    def _execute(self, subtasks=False, quiet=True, status=False, private=False,
+                 list_deps=False, template=None, sort='name', pos_args=None):
+        """List task generators"""
         filter_tasks = pos_args
         # dict of all tasks
         tasks = dict([(t.name, t) for t in self.task_list])
@@ -144,7 +156,13 @@ def _execute(self, subtasks=False, quiet=True, status=False,
                 template = '{status} ' + template
         template += '\n'
 
+        # sort list of tasks
+        if sort == 'name':
+            print_list = sorted(print_list)
+        elif sort == 'definition':
+            pass  # task list is already sorted in order of definition
+
         # print list of tasks
-        for task in sorted(print_list):
+        for task in print_list:
             self._print_task(template, task, status, list_deps, tasks)
         return 0

tests/test_cmd_list.py

@@ -163,3 +163,23 @@ def test_unicode_name(self, dep_manager):
         cmd_list._execute()
         got = [line.strip() for line in output.getvalue().split('\n') if line]
         assert 't做' == got[0]
+
+    def testSortByName(self):
+        # by default, the task list should be ordered by name
+        task_list = list(tasks_sample())
+        output = StringIO()
+        cmd_list = CmdFactory(List, outstream=output, task_list=task_list)
+        cmd_list._execute()
+        got = [line.strip() for line in output.getvalue().split('\n') if line]
+        expected = ['g1', 't1', 't2', 't3']
+        assert expected == got
+
+    def testSortByDefinition(self):
+        # test sorting task list by order of definition
+        task_list = list(tasks_sample())
+        output = StringIO()
+        cmd_list = CmdFactory(List, outstream=output, task_list=task_list)
+        cmd_list._execute(sort='definition')
+        got = [line.strip() for line in output.getvalue().split('\n') if line]
+        expected = ['t1', 't2', 'g1', 't3']
+        assert expected == got