Class 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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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

        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

        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

        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

        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

        public static ExampleCommandLineArgument getCleanArgument​(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

        public 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.
        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

        public 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.
        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

        public 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. 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.