de.esprit.common.clp

## Class CommandLineParser

- java.lang.Object
- - de.esprit.common.clp.CommandLineParser

- Direct Known Subclasses:
    ApplicationCommandLineParser

      public abstract class CommandLineParser
      extends java.lang.Object

  This class parses the command line arguments an stores the values for the requested command line options. Note the distinction between 'option' and 'argument'. Lets consider this sample command line:

        java de.esprit.demo.SampleTool -outfile c:/Temp/out.txt -verbose c:/Temp/in.txt

  In this example '-outfile' is a option with an associated argument 'c:/Temp/out.txt' whereas '-verbose' is a boolean option with no associated argument and 'c:/Temp/in.txt' is a pure argument which would be returned by `getArguments()`.
  Whether an option has an associated argument or not depends on how it is requested from the command line:

       String[] restArgs = getArguments();  // returns both file args as a String array
       String outFile = clp.getArgument(0); // returns the first argument 'c:/Temp/out.txt'
       boolean isVerbose = clp.isVerbose(); // in this case returns true (no associated argument).

  Note: Before asking for arguments you must have called `parse()` in order to read all options from the command line.

  The following standard command line options are checked in any case:

  - -help
    prints the help information and exits the VM
  - -logdir C:/Temp
    path name of log-directory, existence in the filesystem is checked
  - -locale de
    sets the default locale according to the given language or country
- -verbose
  Switch on verbose log-level
- -debug
  Switch on debug log-level

Author:
  Rainer Buesch

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Version` | `espritVersion`
    `protected CommandLineOption` | `optDebug`
    `protected CommandLineOption` | `optDemo`
    `protected CommandLineOption` | `optHelp`
    `protected CommandLineOption` | `optLocale`
    `protected OptionLogDir` | `optLogDir`
    `protected CommandLineOption` | `optLogToFile`
    `protected CommandLineOption` | `optNoConsole`
    `protected CommandLineOption` | `optTest`
    `protected CommandLineOption` | `optVerbose`
    `protected CommandLineOption` | `optVersion`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommandLineParser(java.lang.Class mainClass, java.lang.String... args)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `<O extends CommandLineOption> O` | `addOption(CommandLineOption option)` Adds a new option always to the top of already existing options.
    `<O extends CommandLineOption> O` | `addOption(int positionIndex, CommandLineOption option)`
    `protected Version` | `addSoftwareVersion(Version version)`
    `protected void` | `checkDependencies()` Is called after all options have been parsed.
    `java.lang.String` | `createHelpText(boolean isPrintAll)`
    `java.lang.String` | `createHelpText(java.lang.Exception e)` Creates the exception trace message as well as the help-text
    `protected java.lang.String` | `createOptionList()`
    `protected java.lang.String` | `createSyntaxLine()`
    `protected void` | `ensureParsed()`
    `<T extends CommandLineOption> T` | `fetchDefinedOptionFor(java.lang.String arg)`
    `<T extends CommandLineOption> T` | `findDefinedOptionFor(java.lang.String arg)`
    `java.lang.String` | `getArgument(int index)`
    `int` | `getArgumentCount()`
    `java.lang.String[]` | `getArguments()`
    `Version` | `getCustomVersion()` Returns the last version added, which is the version of the customers application.
    `Version` | `getEspritVersion()` Returns either the current `Version` of the esprit software.
    `java.io.File` | `getLogDir()`
    `protected java.lang.Class` | `getMainClass()`
    `java.util.List<Version>` | `getSoftwareVersions()` Returns the software versions this application builds on.
    `LogLevel` | `getStartLogLevel()` Evaluates the -debug or -verbose option and returns the according `LogLevel` constant.
    `protected void` | `handleParsingError(java.lang.Exception error)`
    `boolean` | `hasArguments()`
    `boolean` | `isDebug()`
    `boolean` | `isDemoMode()`
    `boolean` | `isExitAfterParsing()`
    `boolean` | `isLogToFile()`
    `boolean` | `isNoConsoleLog()`
    `protected boolean` | `isParsed()` Tells whether `parse()` yet has been called.
    `boolean` | `isTestMode()`
    `boolean` | `isVerbose()`
    `void` | `parse()` Parses the command line and fill all options with values.
    `void` | `removeOption(CommandLineOption option)` Removes the given option.
    `void` | `removeOption(java.lang.String option)` Removes the given option by name.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### espritVersion

          protected Version espritVersion

    - #### optVersion

          protected final CommandLineOption optVersion

    - #### optHelp

          protected final CommandLineOption optHelp

    - #### optDebug

          protected final CommandLineOption optDebug

    - #### optVerbose

          protected final CommandLineOption optVerbose

    - #### optTest

          protected final CommandLineOption optTest

    - #### optDemo

          protected final CommandLineOption optDemo

    - #### optNoConsole

          protected final CommandLineOption optNoConsole

    - #### optLogToFile

          protected final CommandLineOption optLogToFile

    - #### optLocale

          protected final CommandLineOption optLocale

    - #### optLogDir

          protected final OptionLogDir optLogDir

  - ### Constructor Detail

    - #### CommandLineParser

          public CommandLineParser(java.lang.Class mainClass,
                           java.lang.String... args)

  - ### Method Detail

    - #### getMainClass

          protected final java.lang.Class getMainClass()

    - #### addSoftwareVersion

          protected final Version addSoftwareVersion(Version version)

    - #### getEspritVersion

          public final Version getEspritVersion()

      Returns either the current `Version` of the esprit software.

    - #### getCustomVersion

          public final Version getCustomVersion()

      Returns the last version added, which is the version of the customers application.

    - #### getSoftwareVersions

          public final java.util.List<Version> getSoftwareVersions()

      Returns the software versions this application builds on.

    - #### addOption

          public final <O extends CommandLineOption> O addOption(CommandLineOption option)

      Adds a new option always to the top of already existing options. Thus the last option added appears first in the help text list.

    - #### addOption

          public final <O extends CommandLineOption> O addOption(int positionIndex,
                                                  CommandLineOption option)

    - #### removeOption

          public final void removeOption(java.lang.String option)

      Removes the given option by name.

    - #### removeOption

          public final void removeOption(CommandLineOption option)

      Removes the given option.

    - #### getArguments

          public final java.lang.String[] getArguments()

    - #### getArgument

          public final java.lang.String getArgument(int index)

    - #### hasArguments

          public final boolean hasArguments()

    - #### getArgumentCount

          public final int getArgumentCount()

    - #### createHelpText

          public java.lang.String createHelpText(boolean isPrintAll)

    - #### createSyntaxLine

          protected java.lang.String createSyntaxLine()

    - #### createOptionList

          protected java.lang.String createOptionList()

    - #### parse

          public void parse()

      Parses the command line and fill all options with values. Parsing is done in several phases:
      - look for all options found in the command line and parse their value
      - for options defined but not found in the command line the default value is parsed
      - check validity of each option
      - check inter option dependencies
      - check for options provided but not defined
      - check for missing mandatory options
      If a parsing error occurs the error is printed to the console and the VM exits.

    - #### handleParsingError

          protected void handleParsingError(java.lang.Exception error)
                                     throws CommandLineParsingException

      Throws:
        `CommandLineParsingException`

    - #### isExitAfterParsing

          public boolean isExitAfterParsing()

    - #### ensureParsed

          protected final void ensureParsed()

    - #### isParsed

          protected final boolean isParsed()

      Tells whether `parse()` yet has been called. Note that it needs to be called before accessing any options.

    - #### createHelpText

          public java.lang.String createHelpText(java.lang.Exception e)

      Creates the exception trace message as well as the help-text

    - #### checkDependencies

          protected void checkDependencies()
                                    throws java.lang.Exception

      Is called after all options have been parsed. Maybe overridden to implement any inter-option dependency checking.
      Throws:
        `java.lang.Exception`

    - #### fetchDefinedOptionFor

          public final <T extends CommandLineOption> T fetchDefinedOptionFor(java.lang.String arg)

    - #### findDefinedOptionFor

          public final <T extends CommandLineOption> T findDefinedOptionFor(java.lang.String arg)

    - #### getLogDir

          public final java.io.File getLogDir()

    - #### isLogToFile

          public final boolean isLogToFile()

    - #### isTestMode

          public final boolean isTestMode()

    - #### isDemoMode

          public final boolean isDemoMode()

    - #### isNoConsoleLog

          public final boolean isNoConsoleLog()

    - #### isDebug

          public final boolean isDebug()

    - #### isVerbose

          public final boolean isVerbose()

    - #### getStartLogLevel

          public final LogLevel getStartLogLevel()

      Evaluates the -debug or -verbose option and returns the according `LogLevel` constant. Returns null if none of these options were specified in the command-line.

Copyright © 2014 EsprIT-Systems. All Rights Reserved.