Package com.unboundid.util

Class ExampleCommandLineArgument

java.lang.Object
com.unboundid.util.ExampleCommandLineArgument
All Implemented Interfaces:
Serializable
@ThreadSafety(level=COMPLETELY_THREADSAFE) public final class ExampleCommandLineArgument extends Object implements 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:

  • Method Details

    • getRawForm

      @NotNull public 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 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 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 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 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 String getUnixForm(@NotNull 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 String getWindowsForm(@NotNull 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 List<String> parseExampleCommandLine(@NotNull 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.