de.caff.util.args

## Interface Switch

- All Superinterfaces:
    SwitchOrArgument
  All Known Implementing Classes:
    AbstractMultipleSwitch, AbstractSwitch, SimpleOnOffSwitch, SimpleOnSwitch, SimpleSwitch, StringArgMultipleSwitch, StringArgSwitch

      public interface Switch
      extends SwitchOrArgument

  A basic command line switch.

  A switch can appear in a short one-character form like `-k` or a long form like `--kill-all-idiots`. Long forms can have an argument directly append separated by an equals-sign (`=`), or as next command line argument. Short forms only accept the latter.

  Since:
    January 27, 2019
  Author:
    Rammi

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default boolean` | `consumeArgument(java.lang.String arg)` Read further arguments from the command line.
    `void` | `found(char shortSwitch)` This switch appears in the command line in the given short form.
    `void` | `found(java.lang.String longSwitch)` This switch appears in the command line in the given long form.
    `java.util.Collection<java.lang.String>` | `getLongForms()` Get the long forms influencing this switch.
    `java.util.Collection<java.lang.Character>` | `getShortForms()` Get the short one character forms influencing this switch.
    `default boolean` | `isOptional()` Is this an optional switch?
    `default boolean` | `isSwitch()` Is this a switch?
    `default boolean` | `needsArguments()` Does this switch require arguments?

    - ### Methods inherited from interface de.caff.util.args.SwitchOrArgument

      `getAppearance, getDescription, isVarLength`

- - ### Method Detail

    - #### isSwitch

          default boolean isSwitch()

      Description copied from interface: `SwitchOrArgument`
      Is this a switch?
      Specified by:
        `isSwitch` in interface `SwitchOrArgument`
      Returns:
        `true`: this is a switch and can be casted to `Switch`, `false`: this is a argument and can be casted to `Argument`

    - #### getShortForms

          @NotNull
          java.util.Collection<java.lang.Character> getShortForms()

      Get the short one character forms influencing this switch.

      If the command line switch is `-k`, this method should return a singleton collection with the character `k`.

      Returns:
        short one character forms, may be empty

    - #### getLongForms

          @NotNull
          java.util.Collection<java.lang.String> getLongForms()

      Get the long forms influencing this switch.

      The return strings must not include the `--` prefix, and have to consist of characters, digits and the minus sign (`-`.

      So if the command line switch is `--kill-all-idiots`, this method should return a singleton collection with the string `kill-all-idiots`.

      Returns:
        long switches. may be empty

    - #### isOptional

          default boolean isOptional()

      Is this an optional switch? Non-optional switches have to appear on the command line. The default implementation returns `true`.
      Specified by:
        `isOptional` in interface `SwitchOrArgument`
      Returns:
        `true`: if this switch is optional
        `false`: if this switch is required

    - #### found

          void found(char shortSwitch)

      This switch appears in the command line in the given short form.
      Parameters:
        `shortSwitch` - short form in which this switch appeared

    - #### found

          void found(@NotNull
                     java.lang.String longSwitch)

      This switch appears in the command line in the given long form.
      Parameters:
        `longSwitch` - long form

    - #### needsArguments

          default boolean needsArguments()

      Does this switch require arguments? Only if it requires arguments, the `consumeArgument(String)` method will be called. The default implementation returns `false`, so always both this method and the `consumeArgument(String)` method need to be overridden.
      Returns:
        `true` if this switch requires arguments
        `false` if this switch does not require arguments
      See Also:
        `consumeArgument(String)`

    - #### consumeArgument

          default boolean consumeArgument(@NotNull
                                          java.lang.String arg)

      Read further arguments from the command line.
      Specified by:
        `consumeArgument` in interface `SwitchOrArgument`
      Parameters:
        `arg` - argument
      Returns:
        if more arguments may be consumed
      See Also:
        `needsArguments()`