ENH: Provide unix-sytle command line parsing

Add System_Parse_CommandForUnix to the KWSys System interface as a
utility to parse a unix-style command line.  Move the existing
implementation out of ProcessUNIX.  Add a flags argument reserved for
future use in providing additional behavior.

1 files changed, 23 insertions, 0 deletions

diff --git a/Source/kwsys/System.h.in b/Source/kwsys/System.h.in
index f96c74e..842ebbd 100644
--- a/Source/kwsys/System.h.in
+++ b/Source/kwsys/System.h.in
@@ -25,6 +25,7 @@
 # define kwsysEXPORT @KWSYS_NAMESPACE@_EXPORT
 #endif
 #if !@KWSYS_NAMESPACE@_NAME_IS_KWSYS
+# define kwsysSystem_Parse_CommandForUnix             kwsys_ns(System_Parse_CommandForUnix)
 # define kwsysSystem_Shell_GetArgumentForWindows      kwsys_ns(System_Shell_GetArgumentForWindows)
 # define kwsysSystem_Shell_GetArgumentForUnix         kwsys_ns(System_Shell_GetArgumentForUnix)
 # define kwsysSystem_Shell_GetArgumentSizeForWindows  kwsys_ns(System_Shell_GetArgumentSizeForWindows)
@@ -113,6 +114,27 @@ enum kwsysSystem_Shell_Flag_e
   kwsysSystem_Shell_Flag_AllowMakeVariables = (1<<5)
 };
 
+/**
+ * Parse a unix-style command line string into separate arguments.
+ *
+ * On success, returns a pointer to an array of pointers to individual
+ * argument strings.  Each string is null-terminated and the last
+ * entry in the array is a NULL pointer (just like argv).  It is the
+ * caller's responsibility to free() the strings and the array of
+ * pointers to them.
+ *
+ * On failure, returns NULL.  Failure occurs only on invalid flags or
+ * when memory cannot be allocated; never due to content of the input
+ * string.  Missing close-quotes are treated as if the necessary
+ * closing quote appears.
+ *
+ * By default single- and double-quoted arguments are supported, and
+ * any character may be escaped by a backslash.  The flags argument is
+ * reserved for future use, and must be zero (or the call will fail).
+ */
+kwsysEXPORT char** kwsysSystem_Parse_CommandForUnix(const char* command,
+                                                    int flags);
+
 #if defined(__cplusplus)
 } /* extern "C" */
 #endif
@@ -123,6 +145,7 @@ enum kwsysSystem_Shell_Flag_e
 # undef kwsys_ns
 # undef kwsysEXPORT
 # if !defined(KWSYS_NAMESPACE) && !@KWSYS_NAMESPACE@_NAME_IS_KWSYS
+#  undef kwsysSystem_Parse_CommandForUnix
 #  undef kwsysSystem_Shell_GetArgumentForWindows
 #  undef kwsysSystem_Shell_GetArgumentForUnix
 #  undef kwsysSystem_Shell_GetArgumentSizeForWindows