From b274f34a20f74b13290736e35338d2fe82c6bb0d Mon Sep 17 00:00:00 2001
From: Marijn van Vliet <w.m.vanvliet@gmail.com>
Date: Wed, 5 Sep 2018 03:37:42 +0300
Subject: [PATCH] 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                |  1 +
 CHANGES                |  1 +
 doc/cmd_other.rst      |  3 ++-
 doit/cmd_list.py       | 30 ++++++++++++++++++++++++------
 tests/test_cmd_list.py | 20 ++++++++++++++++++++
 5 files changed, 48 insertions(+), 7 deletions(-)

diff --git a/AUTHORS b/AUTHORS
index 89e6941e..045960bd 100644
--- a/AUTHORS
+++ b/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
diff --git a/CHANGES b/CHANGES
index da0f9849..42ffcbd5 100644
--- a/CHANGES
+++ b/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*)
diff --git a/doc/cmd_other.rst b/doc/cmd_other.rst
index ff8d0691..b9a2a3fd 100644
--- a/doc/cmd_other.rst
+++ b/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
 
diff --git a/doit/cmd_list.py b/doit/cmd_list.py
index 34732311..4652152c 100644
--- a/doit/cmd_list.py
+++ b/doit/cmd_list.py
@@ -55,6 +55,18 @@
     '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"
@@ -62,7 +74,8 @@ class List(DoitCmdBase):
     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
diff --git a/tests/test_cmd_list.py b/tests/test_cmd_list.py
index 6b35eba5..9df69420 100644
--- a/tests/test_cmd_list.py
+++ b/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