svn commit: r992111 - in /commons/proper/exec/trunk/src: site/apt/commandline.apt test/java/org/apache/commons/exec/CommandLineTest.java

[sg...@apache.org]

Author: sgoeschl
Date: Thu Sep  2 20:41:11 2010
New Revision: 992111

URL: http://svn.apache.org/viewvc?rev=992111&view=rev
Log:
[EXEC-36] Improving the documentation

Added:
    commons/proper/exec/trunk/src/site/apt/commandline.apt
Modified:
    commons/proper/exec/trunk/src/test/java/org/apache/commons/exec/CommandLineTest.java

Added: commons/proper/exec/trunk/src/site/apt/commandline.apt
URL: http://svn.apache.org/viewvc/commons/proper/exec/trunk/src/site/apt/commandline.apt?rev=992111&view=auto
==============================================================================
--- commons/proper/exec/trunk/src/site/apt/commandline.apt (added)
+++ commons/proper/exec/trunk/src/site/apt/commandline.apt Thu Sep  2 20:41:11 2010
@@ -0,0 +1,80 @@
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~  contributor license agreements.  See the NOTICE file distributed with
+~~  this work for additional information regarding copyright ownership.
+~~  The ASF licenses this file to You under the Apache License, Version 2.0
+~~  (the "License"); you may not use this file except in compliance with
+~~  the License.  You may obtain a copy of the License at
+~~
+~~      http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~  Unless required by applicable law or agreed to in writing, software
+~~  distributed under the License is distributed on an "AS IS" BASIS,
+~~  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~  See the License for the specific language governing permissions and
+~~  limitations under the License.
+~~
+~~
+
+ --------
+Apache Commons Exec - Building the command line
+ --------
+ --------
+20 August 2010
+ --------
+
+Building the command line
+
+* Introduction
+
+  You have two ways to create the command line to be executed
+
+    * parsing the entire command line string
+
+    * building the command line incrementally
+
+* General Considerations
+
+  No matter which approach you are using commons-exec does change your command
+  line arguments in the following two cases
+
+    * when the executable contains forward or backward slashes
+
+    * when a command line argument contains an unquoted string 
+
+  The following executable arguments
+
+----------------------------------------
+./bin/vim
+----------------------------------------
+
+  will be translated under Windows to
+
+----------------------------------------
+.\\bin\\vim
+----------------------------------------
+
+* Parsing the command line string
+
+  Parsing the command line string is easy to use but you might run into
+  problems when tackling complex scenarios. Therefore this functionality
+  was deprecated in the {{{http://ant.apache.org/manual/Tasks/exec.html}Ant Exec task}}.
+
+  Let's have a look at few examples you would like to stick to parsing entire command
+  line strings
+
+** Spaces in command line arguments
+
+  Here we would like to invoke a batch file which contains spaces in the path
+
+----------------------------------------
+cmd.exe /C c:\was51\Web Sphere\AppServer\bin\versionInfo.bat
+----------------------------------------
+
+  Due to the space in the file name we have to quote the file name either with
+  single or double quotes otherwise it falls apart into two command line
+  arguments <c:\was51\Web> and <Sphere\AppServer\bin\versionInfo.bat>.
+
+----------------------------------------
+String line = "cmd.exe /C 'c:\\was51\\Web Sphere\\AppServer\\bin\\versionInfo.bat'";
+----------------------------------------

Modified: commons/proper/exec/trunk/src/test/java/org/apache/commons/exec/CommandLineTest.java
URL: http://svn.apache.org/viewvc/commons/proper/exec/trunk/src/test/java/org/apache/commons/exec/CommandLineTest.java?rev=992111&r1=992110&r2=992111&view=diff
==============================================================================
--- commons/proper/exec/trunk/src/test/java/org/apache/commons/exec/CommandLineTest.java (original)
+++ commons/proper/exec/trunk/src/test/java/org/apache/commons/exec/CommandLineTest.java Thu Sep  2 20:41:11 2010
@@ -262,6 +262,21 @@ public class CommandLineTest extends Tes
         assertEquals(args[4], "WITHOUT_HELP_DOC=true");
     }
 
+    /**
+     * Test the following command line
+     *
+     * cmd.exe /C c:\was51\Web Sphere\AppServer\bin\versionInfo.bat
+     */
+    public void testParseRealLifeCommandLine_1() {
+
+        String commandline = "cmd.exe /C \"c:\\was51\\Web Sphere\\AppServer\\bin\\versionInfo.bat\"";
+
+        CommandLine cmdl = CommandLine.parse(commandline);
+        String[] args = cmdl.getArguments();
+        assertEquals("/C", args[0]);
+        assertEquals("\"c:\\was51\\Web Sphere\\AppServer\\bin\\versionInfo.bat\"", args[1]);
+    }
+        
    /**
     * Create a command line with pre-quoted strings to test SANDBOX-192,
     * e.g. "runMemorySud.cmd", "10", "30", "-XX:+UseParallelGC", "\"-XX:ParallelGCThreads=2\""
@@ -477,4 +492,21 @@ public class CommandLineTest extends Tes
         assertEquals("/q:a", args[1]);
         assertEquals("/c:\"install.exe /l \"\"c:\\Documents and Settings\\myusername\\Local Settings\\Temp\\netfx.log\"\" /q\"", args[2] );
     }
+
+    /**
+     * Test the following command line
+     *
+     * C:\CVS_DB\WeightsEngine /f WeightsEngine.mak CFG="WeightsEngine - Win32Release"
+     */
+    public void _testExec36_3() {
+
+        String commandline = "C:\\CVS_DB\\WeightsEngine /f WeightsEngine.mak CFG=\"WeightsEngine - Win32Release\"";
+
+        CommandLine cmdl = CommandLine.parse(commandline);
+        String[] args = cmdl.getArguments();
+        assertEquals("/f", args[0]);
+        assertEquals("WeightsEngine.mak", args[1]);
+        assertEquals("CFG=\"WeightsEngine - Win32Release\"", args[2]);
+    }
+
 }