From c223d38872d54c8bac9e8835b17e7e20b87526f6 Mon Sep 17 00:00:00 2001
From: Paul Beckingham <paul@beckingham.net>
Date: Sun, 24 May 2009 22:32:36 -0400
Subject: [PATCH] Enhancement - Supports '--' on the command line

- Using '--' on the command line separates the left hand side, where
  task is free to interpret arguments in the usual way, and the right
  hand side, which is then assumed to be part of the task description,
  and is not interpreted by task.
---
 AUTHORS            |   8 ++-
 ChangeLog          |   2 +
 html/advanced.html |  12 ++++
 html/faq.html      |  18 ++++++
 html/task.html     |   2 +
 src/parse.cpp      | 154 +++++++++++++++++++++++++--------------------
 src/task.cpp       |   2 +
 7 files changed, 128 insertions(+), 70 deletions(-)

diff --git a/AUTHORS b/AUTHORS
index 06795c1c6..55267243a 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,6 +1,12 @@
 Principal Author:
   Paul Beckingham
 
+Package Maintainer & Contributing Author:
+  Federico Hernandez
+
+Designer:
+  David J Patrick
+
 Contributing Authors:
   Damian Glenny
   Andy Lester
@@ -10,9 +16,7 @@ Contributing Authors:
   Benjamin Tegarden
   Chris Pride
   Richard Querin
-  Federico Hernandez
   T. Charles Yun
-  David J Patrick
   P.C. Shyamshankar
   Johan Friis
   Steven de Brouwer
diff --git a/ChangeLog b/ChangeLog
index 754e3f5aa..4292528be 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -8,6 +8,8 @@
  + Fixed documentation errors (thanks to Thomas@BIC).
  + The 'weekstart' configuration variable now controls the 'calendar'
    command (thanks to Federico Hernandez).
+ + Supports '--' argument to indicate that all subsequence arguments are
+   part of the description, despite what they otherwise might mean.
 
 ------ old releases ------------------------------
 
diff --git a/html/advanced.html b/html/advanced.html
index 9f2a538ce..07ad69021 100644
--- a/html/advanced.html
+++ b/html/advanced.html
@@ -485,6 +485,18 @@ on_white    on_bright_white</code></pre>
                   Note also that this capability does depend on whether your terminal
                   program can display these colors.
                 </p>
+
+                <strong>% task add project:Home -- pri:H +tag /from/to/</strong>
+                <p>
+                  The -- argument can be used to tell task to stop interpreting
+                  the command line arguments.  In the example above, a new task
+                  is added for the project 'Home', then the -- argument appears,
+                  and therefore all remaining arguments are part of the
+                  description.  In this case, the description is "pri:H +tag
+                  /from/to/".  This is one way to override task's interpretation
+                  of the command line.  The other way is to put the entire
+                  description in quotes.
+                </p>
               </div>
 
               <br />
diff --git a/html/faq.html b/html/faq.html
index fa65a0e56..b1c7950fa 100644
--- a/html/faq.html
+++ b/html/faq.html
@@ -175,6 +175,24 @@
                 </p>
                 <hr>
 
+                <p>
+                  <b>
+                    Q: How do I use '+word' in a task description, and prevent it
+                       from being interpreted as a tag?
+                  </b>
+                  <br />
+                  A: There are several ways to do this.  The simplest is to use
+                     the '--' argument in the command line, and task will assume
+                     that everything afterwards is part of the description.  For
+                     example:
+                     <pre><code>% task add -- +tag</code></pre>
+                     Allows the task description to be "+tag".  If you use the
+                     command:
+                     <pre><code>% task &lt;id&gt; edit</code></pre>
+                     Then you are free to put (almost) anything in the description
+                     field without task interpreting it.
+                </p>
+                <hr>
 <!--
                 <p>
                   <b>
diff --git a/html/task.html b/html/task.html
index 041b55575..bf2e340fb 100644
--- a/html/task.html
+++ b/html/task.html
@@ -138,6 +138,8 @@
                   <li>Fixed documentation errors (thanks to Thomas@BIC).
                   <li>The 'weekstart' configuration variable now controls the 'calendar'
                       command (thanks to Federico Hernandez).
+                  <li>Supports '--' argument to indicate that all subsequence arguments are
+                      part of the description, despite what they otherwise might mean.
                 </ul>
 
                 <p>
diff --git a/src/parse.cpp b/src/parse.cpp
index b4e40aa34..18816e860 100644
--- a/src/parse.cpp
+++ b/src/parse.cpp
@@ -478,6 +478,7 @@ void parse (
 {
   command = "";
 
+  bool terminated = false;
   bool foundSequence = false;
   bool foundSomethingAfterSequence = false;
 
@@ -490,87 +491,104 @@ void parse (
     // specified rc file.
     if (arg.substr (0, 3) != "rc:")
     {
-      size_t colon;               // Pointer to colon in argument.
-      std::string from;
-      std::string to;
-      bool global;
-      std::vector <int> sequence;
-
-      // An id is the first argument found that contains all digits.
-      if (lowerCase (command) != "add"  && // "add" doesn't require an ID
-          validSequence (arg, sequence) &&
-          ! foundSomethingAfterSequence)
+      if (!terminated)
       {
-        foundSequence = true;
-        foreach (id, sequence)
-          task.addId (*id);
-      }
+        size_t colon;               // Pointer to colon in argument.
+        std::string from;
+        std::string to;
+        bool global;
+        std::vector <int> sequence;
 
-      // Tags begin with + or - and contain arbitrary text.
-      else if (validTag (arg))
-      {
-        if (foundSequence)
-          foundSomethingAfterSequence = true;
+        // The '--' argument shuts off all parsing - everything is an argument.
+        if (arg == "--")
+          terminated = true;
 
-        if (arg[0] == '+')
-          task.addTag (arg.substr (1, std::string::npos));
-        else if (arg[0] == '-')
-          task.addRemoveTag (arg.substr (1, std::string::npos));
-      }
-
-      // Attributes contain a constant string followed by a colon, followed by a
-      // value.
-      else if ((colon = arg.find (":")) != std::string::npos)
-      {
-        if (foundSequence)
-          foundSomethingAfterSequence = true;
-
-        std::string name  = lowerCase (arg.substr (0, colon));
-        std::string value = arg.substr (colon + 1, std::string::npos);
-
-        if (validAttribute (name, value, conf))
+        // An id is the first argument found that contains all digits.
+        else if (lowerCase (command) != "add"  && // "add" doesn't require an ID
+            validSequence (arg, sequence) &&
+            ! foundSomethingAfterSequence)
         {
-          if (name != "recur" || validDuration (value))
-            task.setAttribute (name, value);
+          foundSequence = true;
+          foreach (id, sequence)
+            task.addId (*id);
         }
 
-        // If it is not a valid attribute, then allow the argument as part of
-        // the description.
+        // Tags begin with + or - and contain arbitrary text.
+        else if (validTag (arg))
+        {
+          if (foundSequence)
+            foundSomethingAfterSequence = true;
+
+          if (arg[0] == '+')
+            task.addTag (arg.substr (1, std::string::npos));
+          else if (arg[0] == '-')
+            task.addRemoveTag (arg.substr (1, std::string::npos));
+        }
+
+        // Attributes contain a constant string followed by a colon, followed by a
+        // value.
+        else if ((colon = arg.find (":")) != std::string::npos)
+        {
+          if (foundSequence)
+            foundSomethingAfterSequence = true;
+
+          std::string name  = lowerCase (arg.substr (0, colon));
+          std::string value = arg.substr (colon + 1, std::string::npos);
+
+          if (validAttribute (name, value, conf))
+          {
+            if (name != "recur" || validDuration (value))
+              task.setAttribute (name, value);
+          }
+
+          // If it is not a valid attribute, then allow the argument as part of
+          // the description.
+          else
+          {
+            if (descCandidate.length ())
+              descCandidate += " ";
+            descCandidate += arg;
+          }
+        }
+
+        // Substitution of description text.
+        else if (validSubstitution (arg, from, to, global))
+        {
+          if (foundSequence)
+            foundSomethingAfterSequence = true;
+
+          task.setSubstitution (from, to, global);
+        }
+
+        // Command.
+        else if (command == "")
+        {
+          if (foundSequence)
+            foundSomethingAfterSequence = true;
+
+          std::string l = lowerCase (arg);
+          if (isCommand (l) && validCommand (l))
+            command = l;
+          else
+          {
+            if (descCandidate.length ())
+              descCandidate += " ";
+            descCandidate += arg;
+          }
+        }
+
+        // Anything else is just considered description.
         else
         {
+          if (foundSequence)
+            foundSomethingAfterSequence = true;
+
           if (descCandidate.length ())
             descCandidate += " ";
           descCandidate += arg;
         }
       }
-
-      // Substitution of description text.
-      else if (validSubstitution (arg, from, to, global))
-      {
-        if (foundSequence)
-          foundSomethingAfterSequence = true;
-
-        task.setSubstitution (from, to, global);
-      }
-
-      // Command.
-      else if (command == "")
-      {
-        if (foundSequence)
-          foundSomethingAfterSequence = true;
-
-        std::string l = lowerCase (arg);
-        if (isCommand (l) && validCommand (l))
-          command = l;
-        else
-        {
-          if (descCandidate.length ())
-            descCandidate += " ";
-          descCandidate += arg;
-        }
-      }
-
-      // Anything else is just considered description.
+      // terminated, therefore everything subsequently is a description.
       else
       {
         if (foundSequence)
diff --git a/src/task.cpp b/src/task.cpp
index 57526180a..5034e0607 100644
--- a/src/task.cpp
+++ b/src/task.cpp
@@ -272,6 +272,8 @@ static std::string longUsage (Config& conf)
       << "  task add \"quoted ' quote\""                                      << "\n"
       << "  task add escaped \\' quote"                                       << "\n"
       <<                                                                         "\n"
+      << "The argument -- tells task to treat all other args as description." << "\n"
+      <<                                                                         "\n"
       << "Many characters have special meaning to the shell, including:"      << "\n"
       << "  $ ! ' \" ( ) ; \\ ` * ? { } [ ] < > | & % # ~"                    << "\n"
       << std::endl;