ENH: Teach separate_arguments() to parse commands

This adds UNIX_COMMAND and WINDOWS_COMMAND modes to the command.
These modes parse unix- and windows-style command lines.

1 files changed, 17 insertions, 1 deletions

diff --git a/Source/cmSeparateArgumentsCommand.h b/Source/cmSeparateArgumentsCommand.h
index 827f7f2..c31d10e 100644
--- a/Source/cmSeparateArgumentsCommand.h
+++ b/Source/cmSeparateArgumentsCommand.h
@@ -58,7 +58,7 @@ public:
   virtual const char* GetTerseDocumentation() 
     {
     return 
-      "Split space separated arguments into a semi-colon separated list.";
+      "Parse space-separated arguments into a semicolon-separated list.";
     }
   
   /**
@@ -67,6 +67,22 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
+      "  separate_arguments(<var> <UNIX|WINDOWS>_COMMAND \"<args>\")\n"
+      "Parses a unix- or windows-style command-line string \"<args>\" and "
+      "stores a semicolon-separated list of the arguments in <var>.  "
+      "The entire command line must be given in one \"<args>\" argument."
+      "\n"
+      "The UNIX_COMMAND mode separates arguments by unquoted whitespace.  "
+      "It recognizes both single-quote and double-quote pairs.  "
+      "A backslash escapes the next literal character (\\\" is \"); "
+      "there are no special escapes (\\n is just n)."
+      "\n"
+      "The WINDOWS_COMMAND mode parses a windows command-line using the "
+      "same syntax the runtime library uses to construct argv at startup.  "
+      "It separates arguments by whitespace that is not double-quoted.  "
+      "Backslashes are literal unless they precede double-quotes.  "
+      "See the MSDN article \"Parsing C Command-Line Arguments\" for details."
+      "\n"
       "  separate_arguments(VARIABLE)\n"
       "Convert the value of VARIABLE to a semi-colon separated list.  "
       "All spaces are replaced with ';'.  This helps with generating "