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

@@ -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

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 ------------------------------
 

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 />

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>

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>

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.
+      if (!terminated)
-      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)
       {
-        foundSequence = true;
+        size_t colon;               // Pointer to colon in argument.
-        foreach (id, sequence)
+        std::string from;
-          task.addId (*id);
+        std::string to;
-      }
+        bool global;
+        std::vector <int> sequence;
 
-      // Tags begin with + or - and contain arbitrary text.
+        // The '--' argument shuts off all parsing - everything is an argument.
-      else if (validTag (arg))
+        if (arg == "--")
-      {
+          terminated = true;
-        if (foundSequence)
-          foundSomethingAfterSequence = true;
 
-        if (arg[0] == '+')
+        // An id is the first argument found that contains all digits.
-          task.addTag (arg.substr (1, std::string::npos));
+        else if (lowerCase (command) != "add"  && // "add" doesn't require an ID
-        else if (arg[0] == '-')
+            validSequence (arg, sequence) &&
-          task.addRemoveTag (arg.substr (1, std::string::npos));
+            ! foundSomethingAfterSequence)
-      }
-
-      // 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))
+          foundSequence = true;
-            task.setAttribute (name, value);
+          foreach (id, sequence)
+            task.addId (*id);
         }
 
-        // If it is not a valid attribute, then allow the argument as part of
+        // Tags begin with + or - and contain arbitrary text.
-        // the description.
+        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;
         }
       }
-
+      // terminated, therefore everything subsequently is a description.
-      // 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)

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;