com.unboundid.util

Class ExampleCommandLineArgument

java.lang.Object

com.unboundid.util.ExampleCommandLineArgument

All Implemented Interfaces:

java.io.Serializable

@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class ExampleCommandLineArgument
extends java.lang.Object
implements java.io.Serializable

This class provides access to a form of a command-line argument that is safe to use in a shell. It includes both forms for both Unix (bash shell specifically) and Windows, since there are differences between the two platforms. Quoting of arguments is performed with the following goals:

• The same form should be used for both Unix and Windows whenever possible.
• If the same form cannot be used for both platforms, then make it as easy as possible to convert the form to the other platform.
• If neither platform requires quoting of an argument, then it is not quoted.

To that end, here is the approach that we've taken:

• Characters in the output are never escaped with the \ character because Windows does not understand \ used to escape.
• On Unix, double-quotes are used to quote whenever possible since Windows does not treat single quotes specially.
• If a String needs to be quoted on either platform, then it is quoted on both. If it needs to be quoted with single-quotes on Unix, then it will be quoted with double quotes on Windows.
• On Unix, single-quote presents a problem if it's included in a string that needs to be singled-quoted, for instance one that includes the $ or ! characters. In this case, we have to wrap it in double-quotes outside of the single-quotes. For instance, Server's! would end up as 'Server'"'"'s!'.
• On Windows, double-quotes present a problem. They have to be escaped using two double-quotes inside of a double-quoted string. For instance "Quoted" ends up as """Quoted""".

All of the forms can be unambiguously parsed using the parseExampleCommandLine(java.lang.String) method regardless of the platform. This method can be used when needing to parse a command line that was generated by this class outside of a shell environment, e.g. if the full command line was read from a file. Special characters that are escaped include |, &, ;, (, ), !, ", ', *, ?, $, and `.

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
static ExampleCommandLineArgument	getCleanArgument(java.lang.String argument) Return a clean form of the specified argument that can be used directly on the command line.
java.lang.String	getLocalForm() Return the form of the argument that is safe to use in the command line shell of the current operating system platform.
java.lang.String	getRawForm() Return the original, unquoted raw form of the argument.
java.lang.String	getUnixForm() Return the form of the argument that is safe to use in a Unix command line shell.
static java.lang.String	getUnixForm(java.lang.String argument) Return a clean form of the specified argument that can be used directly on a Unix command line.
java.lang.String	getWindowsForm() Return the form of the argument that is safe to use in a Windows command line shell.
static java.lang.String	getWindowsForm(java.lang.String argument) Return a clean form of the specified argument that can be used directly on a Windows command line.
static java.util.List<java.lang.String>	parseExampleCommandLine(java.lang.String exampleCommandLine) Return a list of raw parameters that were parsed from the specified String.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getRawForm

@NotNull
public java.lang.String getRawForm()

Return the original, unquoted raw form of the argument. This is what was passed into the getCleanArgument(java.lang.String) method.

Returns:

The original, unquoted form of the argument.

getUnixForm

@NotNull
public java.lang.String getUnixForm()

Return the form of the argument that is safe to use in a Unix command line shell.

Returns:

The form of the argument that is safe to use in a Unix command line shell.

getWindowsForm

@NotNull
public java.lang.String getWindowsForm()

Return the form of the argument that is safe to use in a Windows command line shell.

Returns:

The form of the argument that is safe to use in a Windows command line shell.

getLocalForm

@NotNull
public java.lang.String getLocalForm()

Return the form of the argument that is safe to use in the command line shell of the current operating system platform.

Returns:

The form of the argument that is safe to use in a command line shell of the current operating system platform.

getCleanArgument

@NotNull
public static ExampleCommandLineArgument getCleanArgument(@NotNull
                                                                   java.lang.String argument)

Return a clean form of the specified argument that can be used directly on the command line.

Parameters:

argument - The raw argument to convert into a clean form that can be used directly on the command line.

Returns:

The ExampleCommandLineArgument for the specified argument.

getUnixForm

@NotNull
public static java.lang.String getUnixForm(@NotNull
                                                    java.lang.String argument)

Return a clean form of the specified argument that can be used directly on a Unix command line.

Parameters:

argument - The raw argument to convert into a clean form that can be used directly on the Unix command line.

Returns:

A form of the specified argument that is clean for us on a Unix command line.

getWindowsForm

@NotNull
public static java.lang.String getWindowsForm(@NotNull
                                                       java.lang.String argument)

Return a clean form of the specified argument that can be used directly on a Windows command line.

Parameters:

argument - The raw argument to convert into a clean form that can be used directly on the Windows command line.

Returns:

A form of the specified argument that is clean for us on a Windows command line.

parseExampleCommandLine

@NotNull
public static java.util.List<java.lang.String> parseExampleCommandLine(@NotNull
                                                                                java.lang.String exampleCommandLine)

Return a list of raw parameters that were parsed from the specified String. This can be used to undo the quoting that was done by getCleanArgument(java.lang.String). It perfectly handles any String that was passed into this method, but it won't behave exactly as any single shell behaves because they aren't consistent. For instance, it will never treat \\ as an escape character.

Parameters:

exampleCommandLine - The command line to parse.

Returns:

A list of raw arguments that were parsed from the specified example usage command line.