Add help texts and introduce the global 'help' subsubcommand.

AddCommand.py

@@ -86,6 +86,9 @@ class AddCommand(Command.Command):
 
     def execute(self):
         """ Adds a todo item to the list. """
+        if not super(AddCommand, self).execute():
+            return False
+
         if self.text:
             self._preprocess_input_todo()
             self.todo = self.todolist.add(self.text)
@@ -94,3 +97,20 @@ class AddCommand(Command.Command):
             self.out(pretty_print(self.todo, [self.todolist.pp_number()]))
         else:
             self.error(self.usage())
+
+    def usage(self):
+        return """Synopsis: add <text>"""
+
+    def help(self):
+        return """This subcommand automatically adds the creation date to the added item.
+
+<text> may contain:
+
+* Priorities mid-sentence. Example: add "Water flowers (C)"
+
+* Dependencies using before, after and partof tags. They are translated to the
+  corresponding 'id' and 'p' tags. The values of these tags correspond to the
+  todo number (not the dependency number).
+
+  Example: add "Subtask partof:1"
+"""

AppendCommand.py

@@ -27,6 +27,9 @@ class AppendCommand(Command):
         super(AppendCommand, self).__init__(p_args, p_todolist, p_out, p_err, p_prompt=lambda a: None)
 
     def execute(self):
+        if not super(AppendCommand, self).execute():
+            return False
+
         try:
             number = convert_todo_number(self.argument(0))
             text = " ".join(self.args[1:])
@@ -42,3 +45,8 @@ class AppendCommand(Command):
         except TodoList.InvalidTodoException:
             self.error("Invalid todo number given.")
 
+    def usage(self):
+        return """Synopsis: append <number> <text>"""
+
+    def help(self):
+        return """Adds the given <text> to the end of the todo indicated by <number>."""

Command.py

@@ -50,11 +50,14 @@ class Command(object):
 
     def execute(self):
         """
-        Execute the command.
-
-        Returns True when the command succeeded or False on failure.
+        Execute the command. Intercepts the help subsubcommand to show the help
+        text.
         """
-        return False
+        if self.argumentShift("help"):
+            self.error(self.usage() + "\n\n" + self.help())
+            return False
+
+        return True
 
     def argument(self, p_number):
         """ Retrieves a value from the argument list at the given position. """
@@ -77,5 +80,8 @@ class Command(object):
         return False
 
     def usage(self):
-        return "No usage text defined for this command."
+        return "No usage text available for this command."
+
+    def help(self):
+        return "No help text available for this command."
 

DepCommand.py

@@ -99,6 +99,9 @@ class DepCommand(Command):
             self.error(self.usage())
 
     def execute(self):
+        if not super(DepCommand, self).execute():
+            return False
+
         dispatch = {
             'add':   self._handle_add,
             'rm':    self._handle_rm,
@@ -113,3 +116,15 @@ class DepCommand(Command):
         else:
             self.error(self.usage())
 
+    def usage(self):
+        return """Synopsis:
+  dep <add|rm> <NUMBER> [to] <NUMBER>
+  dep ls <NUMBER> to
+  dep ls to <NUMBER>
+  dep clean"""
+
+    def help(self):
+        return """* add: Adds a dependency.
+* rm (alias: del): Removes a dependency.
+* ls: Lists all dependencies to or from a certain todo.
+* clean (alias: gc): Removes redundant id or p tags."""

DoCommand.py

@@ -56,6 +56,9 @@ class DoCommand(Command):
             self.out(pretty_print(new_todo, [self.todolist.pp_number()]))
 
     def execute(self):
+        if not super(DoCommand, self).execute():
+            return False
+
         if not self.number:
             self.error(self.usage())
         elif self.todo and not self.todo.is_completed():
@@ -67,3 +70,13 @@ class DoCommand(Command):
             self.error("Invalid todo number given.")
         else:
             self.error("Todo has already been completed.")
+
+    def usage(self):
+        return """Synopsis: do <NUMBER>"""
+
+    def help(self):
+        return """ Marks the todo with given number as complete. In case the todo has subitems,
+they may optionally be completed too.
+
+In case the completed todo is recurring, a new todo will be added to the list,
+while the given todo item is marked as complete."""

ListCommand.py

@@ -27,6 +27,9 @@ class ListCommand(Command.Command):
         super(ListCommand, self).__init__(p_args, p_todolist, p_out, p_err, p_prompt)
 
     def execute(self):
+        if not super(ListCommand, self).execute():
+            return False
+
         show_all = self.argumentShift("-x")
 
         sorter = Sorter.Sorter(Config.SORT_STRING)
@@ -36,3 +39,19 @@ class ListCommand(Command.Command):
             filters.append(Filter.GrepFilter(self.argument(0)))
 
         self.out(self.todolist.view(sorter, filters).pretty_print())
+
+    def usage(self):
+        return """Synopsis: ls [-x] [expression]
+
+Use "ls help" for more info."""
+
+    def help(self):
+        return """Lists all relevant todos. A todo is relevant when:
+
+* has not been completed yet;
+* the start date (if present) has passed;
+* there are no subitems that need to be completed.
+
+When an expression is given, only the todos matching that expression are shown.
+
+-x : Show all todos (i.e. do not filter on dependencies or relevance)."""

ListContextCommand.py

@@ -24,5 +24,14 @@ class ListContextCommand(Command.Command):
         super(ListContextCommand, self).__init__(p_args, p_todolist, p_out, p_err, p_prompt)
 
     def execute(self):
+        if not super(ListContextCommand, self).execute():
+            return False
+
         for context in sorted(self.todolist.contexts(), key=str.lower):
             self.out(context)
+
+    def usage(self):
+      return """Synopsis: lscon"""
+
+    def help(self):
+      return """Lists all contexts in the todo list."""

ListProjectCommand.py

@@ -24,5 +24,14 @@ class ListProjectCommand(Command.Command):
         super(ListProjectCommand, self).__init__(p_args, p_todolist, p_out, p_err, p_prompt)
 
     def execute(self):
+        if not super(ListProjectCommand, self).execute():
+            return False
+
         for project in sorted(self.todolist.projects(), key=str.lower):
             self.out(project)
+
+    def usage(self):
+      return """Synopsis: lscon"""
+
+    def help(self):
+      return """Lists all projects in the todo list."""

PriorityCommand.py

@@ -27,6 +27,9 @@ class PriorityCommand(Command):
         super(PriorityCommand, self).__init__(p_args, p_todolist, p_out, p_err, p_prompt)
 
     def execute(self):
+        if not super(PriorityCommand, self).execute():
+            return False
+
         number = None
         priority = None
         try:
@@ -53,3 +56,9 @@ class PriorityCommand(Command):
                 self.error( "Invalid todo number given.")
             else:
                 self.error(self.usage())
+
+    def usage(self):
+        return """Synopsis: pri <NUMBER> <PRIORITY>"""
+
+    def help(self):
+        return """Sets the priority of todo the given number to the given priority."""

test/AddCommandTest.py

@@ -177,3 +177,10 @@ class AddCommandTest(CommandTest.CommandTest):
 
         self.assertEquals(self.output, "")
         self.assertEquals(self.errors, command.usage() + "\n")
+
+    def test_help(self):
+        command = AddCommand.AddCommand(["help"], self.todolist, self.out, self.error)
+        command.execute()
+
+        self.assertEquals(self.output, "")
+        self.assertEquals(self.errors, command.usage() + "\n\n" + command.help() + "\n")

test/AppendCommandTest.py

@@ -71,3 +71,10 @@ class AppendCommandTest(CommandTest.CommandTest):
 
         self.assertEqual(self.output, "")
         self.assertEqual(self.errors, command.usage() + "\n")
+
+    def test_help(self):
+        command = AppendCommand.AppendCommand(["help"], self.todolist, self.out, self.error)
+        command.execute()
+
+        self.assertEquals(self.output, "")
+        self.assertEquals(self.errors, command.usage() + "\n\n" + command.help() + "\n")

test/DepCommandTest.py

@@ -202,3 +202,9 @@ class DepCommandTest(CommandTest.CommandTest):
         self.assertEqual(self.errors, command.usage() + "\n")
         self.assertFalse(self.todolist.is_dirty())
 
+    def test_help(self):
+        command = DepCommand.DepCommand(["help"], self.todolist, self.out, self.error)
+        command.execute()
+
+        self.assertEquals(self.output, "")
+        self.assertEquals(self.errors, command.usage() + "\n\n" + command.help() + "\n")

test/DoCommandTest.py

@@ -128,3 +128,10 @@ class DoCommandTest(CommandTest.CommandTest):
         self.assertFalse(self.todolist.is_dirty())
         self.assertFalse(self.output)
         self.assertEquals(self.errors, command.usage() + "\n")
+
+    def test_help(self):
+        command = DoCommand.DoCommand(["help"], self.todolist, self.out, self.error)
+        command.execute()
+
+        self.assertEquals(self.output, "")
+        self.assertEquals(self.errors, command.usage() + "\n\n" + command.help() + "\n")

test/ListCommandTest.py

@@ -61,3 +61,10 @@ class ListCommandTest(CommandTest.CommandTest):
         self.assertFalse(self.todolist.is_dirty())
         self.assertEquals(self.output, "")
         self.assertEquals(self.errors, "")
+
+    def test_help(self):
+        command = ListCommand.ListCommand(["help"], self.todolist, self.out, self.error)
+        command.execute()
+
+        self.assertEquals(self.output, "")
+        self.assertEquals(self.errors, command.usage() + "\n\n" + command.help() + "\n")

test/ListContextCommandTest.py

@@ -34,3 +34,10 @@ class ListContextCommandTest(CommandTest.CommandTest):
 
         self.assertEquals(self.output,"Context1\nContext2\n")
         self.assertFalse(self.errors)
+
+    def test_help(self):
+        command = ListContextCommand.ListContextCommand(["help"], None, self.out, self.error)
+        command.execute()
+
+        self.assertEquals(self.output, "")
+        self.assertEquals(self.errors, command.usage() + "\n\n" + command.help() + "\n")

test/ListProjectCommandTest.py

@@ -34,3 +34,10 @@ class ListProjectCommandTest(CommandTest.CommandTest):
 
         self.assertEquals(self.output,"Project1\nProject2\n")
         self.assertFalse(self.errors)
+
+    def test_help(self):
+        command = ListProjectCommand.ListProjectCommand(["help"], None, self.out, self.error)
+        command.execute()
+
+        self.assertEquals(self.output, "")
+        self.assertEquals(self.errors, command.usage() + "\n\n" + command.help() + "\n")

test/PriorityCommandTest.py

@@ -82,3 +82,10 @@ class PriorityCommandTest(CommandTest.CommandTest):
         self.assertFalse(self.todolist.is_dirty())
         self.assertFalse(self.output)
         self.assertEquals(self.errors, command.usage() + "\n")
+
+    def test_help(self):
+        command = PriorityCommand.PriorityCommand(["help"], self.todolist, self.out, self.error)
+        command.execute()
+
+        self.assertEquals(self.output, "")
+        self.assertEquals(self.errors, command.usage() + "\n\n" + command.help() + "\n")