Package com.clumd.projects.java_common_utils.arg_parser

Class Argument<T>

java.lang.Object
com.clumd.projects.java_common_utils.arg_parser.Argument<T>
Type Parameters:
T - The type this Argument's value represents be post parsing.
public class Argument<T> extends Object
This Class represents all the configuration required to parse a single Command Line Argument into a usable output

The Ideal implementation pattern for this is as follows: 
 
 public class YourProgramsArgParser {

      private static final List<Argument<?>> arguments;
      private static final Argument<Void> helpFlag, otherHelpStyleFlags;
      private static final Argument<String> someArgumentWithATypedValue;

      static {
          helpFlag = Argument.<Void>builder()
                 .uniqueId("help flag")
                 .shouldShortCircuit(true)
                 ...
                 .build();
          otherHelpStyleFlags = Argument.<Void>builder()
                 .uniqueId("other flag")
                 ...
                 .build();
          someArgumentWithATypedValue = Argument.<String>builder()
                 .uniqueId("typed arg")
                 ...
                 .build();

          arguments = List.of(helpFlag,
                 otherHelpStyleFlags,
                 someArgumentWithATypedValue);

         argParser = new JavaArgParser();
         argParser.setBoilerplate(...);
      }

      public static ObjectToActionArgsWith getArgs(String[] args) throws UnwrappableThrowable {

          ObjectToActionArgsWith objectToActionArgsWith = new ObjectToActionArgsWith;

          Map<String, Argument<Object>> parsedArguments;
          parsedArguments = argParser.parseFromCLI(arguments, args);

          for (String argID : parsedArguments.keySet()) {
              switch (argID) {
                  case "help flag" -> {
                      System.out.println(argParser.getBoilerplate(arguments));
                      throw new UnwrappableRuntimeException("Instant quit.");
                  }
                  case "other flag" -> otherHelpStyleFlags.getArgumentResult();
                  case "typed arg" -> someArgumentWithATypedValue.getArgumentResult();
                  default ->
                      throw new UnwrappableException("Argument {" + argID + "} configured, but not handled when present.");
              }
          }

          return objectToActionArgsWith;
      }
 }

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Argument.ArgumentBuilder<T>
    Overridden Builder for part of the Lombok process.

  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    attemptValueConversion(String value)
    This method should be called by the implementing CLIArgParser if a value is provided for this Argument.
    static <T> Argument.ArgumentBuilder<T>
    builder()
     
    protected boolean
    canEqual(Object other)
     
    boolean
    equals(Object o)
     
    T
    getArgumentResult()
    If this argument needs a value, then this should be the fully validated and parsed output of that value.
    Function<String,T>
    getConversionFunction()
    This function is used to convert an argument from the CLI string form, into the object the running process needs.
    T
    getDefaultValue()
    This should be used as the default value, if nothing is provided for the conversion function
    String
    getDescription()
    Used to describe the purpose of this Argument and how it should be used.
    Set<String>
    getLongOptions()
    Used to contain all the word alias' to indicate this option
    Set<Character>
    getShortOptions()
    Used to contain all the single character alias' to indicate this option
    String
    getUniqueId()
    Used to index the options, must be unique and supplied by the user.
    Function<T,Boolean>
    getValidationFunction()
    This function can be provided to run a verification step that the argument's value is acceptable.
    int
    hashCode()
     
    boolean
    hasValue()
    Used to indicate if this argument can be followed by a value, defaults to false
    boolean
    isDefaultValueSet()
    Used to track if a default value has been set for this argument to be used if no CLI value is found.
    boolean
    isMandatory()
    Used to indicate if this argument is mandatory and MUST be provided for the utilising code to function.
    void
    setArgumentResult(T argumentResult)
    If this argument needs a value, then this should be the fully validated and parsed output of that value.
    void
    setDefaultValue(T defaultValue)
    This should be used as the default value, if nothing is provided for the conversion function
    void
    setDefaultValueSet(boolean defaultValueSet)
    Used to track if a default value has been set for this argument to be used if no CLI value is found.
    boolean
    shouldShortCircuit()
    Used to tell a parser that if this argument is detected on the CLI at all, it should ALWAYS be returnable to the caller with all present short circuit args.
    String
    toString()
    Overridden to make development cognitively easier by removing the Argument config, and only showing the output for itself.
    final boolean
    validateValue()
    If a value is possible for this CLI Argument, then this method will be called to verify that the argument provided is acceptable by the calling process.
    boolean
    valueIsOptional()
    Used to indicate if the value to this argument can be optional, defaults to false.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • attemptValueConversion

      public final void attemptValueConversion(String value)
      This method should be called by the implementing CLIArgParser if a value is provided for this Argument.
      Parameters:
      value - The CLI Argument's value to be parsed into the desired Java type, or a null if no argument provided

    • validateValue

      public final boolean validateValue()
      If a value is possible for this CLI Argument, then this method will be called to verify that the argument provided is acceptable by the calling process. This works by calling the implementation-provided validationFunction to decide if it is acceptable
      Returns:
      True (default if no function was provided), if the value provided meets the acceptance criteria of the validationFunction, False if it fails validation

    • toString

      public String toString()
      Overridden to make development cognitively easier by removing the Argument config, and only showing the output for itself.
      Overrides:
      toString in class Object
      Returns:
      The string representation of the Argument Result to make scanning in debuggers easier.

    • builder

      public static <T> Argument.ArgumentBuilder<T> builder()

    • getUniqueId

      public String getUniqueId()
      Used to index the options, must be unique and supplied by the user.

    • getShortOptions

      public Set<Character> getShortOptions()
      Used to contain all the single character alias' to indicate this option

    • getLongOptions

      public Set<String> getLongOptions()
      Used to contain all the word alias' to indicate this option

    • isMandatory

      public boolean isMandatory()
      Used to indicate if this argument is mandatory and MUST be provided for the utilising code to function. If you set this value to true, you probably don't want to set a default value.

    • shouldShortCircuit

      public boolean shouldShortCircuit()
      Used to tell a parser that if this argument is detected on the CLI at all, it should ALWAYS be returnable to the caller with all present short circuit args. Ideally ignoring any other constraints, such as isMandatory = true;

    • hasValue

      public boolean hasValue()
      Used to indicate if this argument can be followed by a value, defaults to false

    • valueIsOptional

      public boolean valueIsOptional()
      Used to indicate if the value to this argument can be optional, defaults to false. (e.g. value MUST be provided)

    • getDescription

      public String getDescription()
      Used to describe the purpose of this Argument and how it should be used.

    • getValidationFunction

      public Function<T,Boolean> getValidationFunction()
      This function can be provided to run a verification step that the argument's value is acceptable.

    • getConversionFunction

      public Function<String,T> getConversionFunction()
      This function is used to convert an argument from the CLI string form, into the object the running process needs.

    • isDefaultValueSet

      public boolean isDefaultValueSet()
      Used to track if a default value has been set for this argument to be used if no CLI value is found.

    • getArgumentResult

      public T getArgumentResult()
      If this argument needs a value, then this should be the fully validated and parsed output of that value.

    • getDefaultValue

      public T getDefaultValue()
      This should be used as the default value, if nothing is provided for the conversion function

    • setDefaultValueSet

      public void setDefaultValueSet(boolean defaultValueSet)
      Used to track if a default value has been set for this argument to be used if no CLI value is found.

    • setArgumentResult

      public void setArgumentResult(T argumentResult)
      If this argument needs a value, then this should be the fully validated and parsed output of that value.

    • setDefaultValue

      public void setDefaultValue(T defaultValue)
      This should be used as the default value, if nothing is provided for the conversion function

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • canEqual

      protected boolean canEqual(Object other)

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object