Package org.djutils.cli

Class CliUtil

java.lang.Object
org.djutils.cli.CliUtil
public final class CliUtil extends Object
CliUtil offers a helper method to display --help and --version without starting the program. The method is used as follows: 
 public static void main(final String[] args) throws Exception
 {
     Program program = new Program(); // initialize the Checkable class with the @Option information
     CliUtil.execute(program, args); // register Unit converters, parse the command line, catch --help, --version and error
     // do rest of what the main method should do
 }
When the program is Checkable, the check() method is called after the arguments have been parsed. Here, further checks on the arguments (i.e., range checks) can be carried out. Potentially, check() can also provide other initialization of the program to be executed, but this can better be provided by other methods in main() . Make sure that expensive initialization is not carried out in the constructor of the program class that is given to the execute method. Alternatively, move the command line options to a separate class, e.g. called Options and initialize that class rather than the real program class. The real program can then take the values of the program from the Options class. An example: 
 public class Program
 {
     @Command(description = "Test program for CLI", name = "Program", mixinStandardHelpOptions = true, version = "1.0")
     public static class Options implements Checkable
     {
         @Option(names = {"-p", "--port"}, description = "Internet port to use", defaultValue = "80")
         private int port;
 
         public int getPort()
         {
             return this.port;
         }
 
         @Override
         public void check() throws Exception
         {
             if (this.port <= 0 || this.port > 65535)
                 throw new Exception("Port should be between 1 and 65535");
         }
     }
 
     public Program()
     {
         // initialization for the program; avoid really starting things
     }
 
     public static void main(final String[] args)
     {
         Options options = new Options();
         CliUtil.execute(options, args);
         System.out.println("port = " + options.getPort());
         // you can now call methods on the program, e.g. for real initialization using the CLI parameters in options
     }
 }

Copyright (c) 2019-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information www.simulation.tudelft.nl. The source code and binary code of this software is proprietary information of Delft University of Technology.
Author:
Alexander Verbraeck

  • Field Details

    • overrideMap

      static Map<String,Object> overrideMap
      The map with overrides for default values and other Option and Program annotation values. values in the map are:
      • className%fieldName%propertyName for the @Option annotation for field fieldName within the class named className, and the annotation property propertyName. An example of the propertyName is "defaultValue"
      • className%propertyName for the @Command annotation for the annotation property with propertyName in the named class. Examples of the propertyName are "name", "version", and "description"

  • Method Details

    • execute

      public static void execute(Object program, String[] args)
      Parse the command line for the program. Register Unit converters, parse the command line, catch --help, --version and errors. If the program implements the Checkable interface, it calls the "check" method of the class that can take care of further checks of the CLI arguments. Potentially, check() can also provide other initialization of the program to be executed, but this can better be provided by other methods in main(). The method will exit on requesting help or version information, or when the arguments are not complete or not correct.
      Parameters:
      program - Object; the potentially checkable program with the @Option information
      args - String[]; the arguments from the command line

    • execute

      public static void execute(CommandLine commandLine, String[] args)
      Parse the given CommandLine object, that has been generated for a program. Register Unit converters, parse the command line, catch --help, --version, --locale, and errors. If the program implements the Checkable interface, it calls the "check" method of the class that can take care of further checks of the CLI arguments. Potentially, check() can also provide other initialization of the program to be executed, but this can better be provided by other methods in main(). The method will exit on requesting help or version information, or when the arguments are not complete or not correct.
      Parameters:
      commandLine - CommandLine; the CommandLine object for the program with the @Option information
      args - String[]; the arguments from the command line

    • changeOptionProperty

      public static void changeOptionProperty(Class<?> programClass, String fieldName, String propertyName, Object newValue) throws CliException, NoSuchFieldException
      Change the value of a property of an already present @Option annotation of a field in a class or superclass.
      Parameters:
      programClass - Class<?>; the class of the program for which the options should be changed
      fieldName - String; the field for which the defaultValue in @Option should be changed
      propertyName - String; the name of the property to change the value of
      newValue - Object; the new value of the property
      Throws:
      CliException - when the field cannot be found, or when the @Option annotation is not present in the field
      NoSuchFieldException - when the field with the name does not exist in the program object

    • changeOptionProperty

      public static void changeOptionProperty(Object program, String fieldName, String propertyName, Object newValue) throws CliException, NoSuchFieldException
      Change the value of a property of an already present @Option annotation of a field in a class or superclass.
      Parameters:
      program - Object; the program for which the options should be changed
      fieldName - String; the field for which the defaultValue in @Option should be changed
      propertyName - String; the name of the property to change the value of
      newValue - Object; the new value of the property
      Throws:
      CliException - when the field cannot be found, or when the @Option annotation is not present in the field
      NoSuchFieldException - when the field with the name does not exist in the program object

    • changeOptionDefault

      public static void changeOptionDefault(Object program, String fieldName, String newDefaultValue) throws CliException, NoSuchFieldException
      Change the default value of an already present @Option annotation of the "defaultValue" field in a class or superclass.
      Parameters:
      program - Object; the program for which the options should be changed
      fieldName - String; the field for which the defaultValue in @Option should be changed
      newDefaultValue - String; the new value of the defaultValue
      Throws:
      CliException - when the field cannot be found, or when the @Option annotation is not present in the field
      NoSuchFieldException - when the field with the name does not exist in the program object

    • changeOptionDefault

      public static void changeOptionDefault(Class<?> programClass, String fieldName, String newDefaultValue) throws CliException, NoSuchFieldException
      Change the default value of an already present @Option annotation of the "defaultValue" field in a class or superclass.
      Parameters:
      programClass - Class<?>; the class of the program for which the options should be changed
      fieldName - String; the field for which the defaultValue in @Option should be changed
      newDefaultValue - String; the new value of the defaultValue
      Throws:
      CliException - when the field cannot be found, or when the @Option annotation is not present in the field
      NoSuchFieldException - when the field with the name does not exist in the program object

    • changeCommandName

      public static void changeCommandName(Object program, String newName) throws CliException
      Change the value of the 'name' property of an already present @Command annotation in a class or superclass of that class.
      Parameters:
      program - Object; the program for which the cli property should be changed
      newName - String; the new value of the name
      Throws:
      CliException - when the class is not annotated with @Command

    • changeCommandName

      public static void changeCommandName(Class<?> programClass, String newName) throws CliException
      Change the value of the 'name' property of an already present @Command annotation in a class or superclass of that class.
      Parameters:
      programClass - Class<?>; the class of the program for which the options should be changed
      newName - String; the new value of the name
      Throws:
      CliException - when the class is not annotated with @Command

    • changeCommandDescription

      public static void changeCommandDescription(Object program, String newDescription) throws CliException
      Change the value of the 'description' property of an already present @Command annotation in a class or superclass of that class.
      Parameters:
      program - Object; the program for which the cli property should be changed
      newDescription - String; the new value of the description
      Throws:
      CliException - when the class is not annotated with @Command

    • changeCommandDescription

      public static void changeCommandDescription(Class<?> programClass, String newDescription) throws CliException
      Change the value of the 'description' property of an already present @Command annotation in a class or superclass of that class.
      Parameters:
      programClass - Class<?>; the class of the program for which the options should be changed
      newDescription - String; the new value of the description
      Throws:
      CliException - when the class is not annotated with @Command

    • changeCommandVersion

      public static void changeCommandVersion(Object program, String newVersion) throws CliException
      Change the value of the 'version' property of an already present @Command annotation in a class or superclass of that class.
      Parameters:
      program - Object; the program for which the cli property should be changed
      newVersion - String; the new value of the version
      Throws:
      CliException - when the class is not annotated with @Command

    • changeCommandVersion

      public static void changeCommandVersion(Class<?> programClass, String newVersion) throws CliException
      Change the value of the 'version' property of an already present @Command annotation in a class or superclass of that class.
      Parameters:
      programClass - Class<?>; the class of the program for which the options should be changed
      newVersion - String; the new value of the version
      Throws:
      CliException - when the class is not annotated with @Command

    • getCommandAnnotation

      public static CommandLine.Command getCommandAnnotation(Class<?> programClass) throws CliException
      Return the @Command annotation of a class or one of its superclasses.
      Parameters:
      programClass - Class<?>; the class of the program for which the annotation should be retrieved
      Returns:
      Command; the @Command annotation of the class or one of its superclasses
      Throws:
      CliException - when the class or one of its superclasses is not annotated with @Command

    • getCommandAnnotationClass

      public static Class<?> getCommandAnnotationClass(Class<?> programClass) throws CliException
      Return the @Command annotation of a class or one of its superclasses.
      Parameters:
      programClass - Class<?>; the class of the program for which the annotation should be retrieved
      Returns:
      Class<?>; the class or superclass in which the @Command annotation was found
      Throws:
      CliException - when the class or one of its superclasses is not annotated with @Command

    • getCommandVersion

      public static String[] getCommandVersion(Class<?> programClass) throws CliException
      Parameters:
      programClass - Class<?>; the class for which to retrieve the version. The class should be annotated with @Command
      Returns:
      String[] the version string
      Throws:
      CliException - when the class is not annotated with @Command

    • getCommandVersion

      public static String[] getCommandVersion(Object program) throws CliException
      Parameters:
      program - Object; the program for which to retrieve the version. The program's class should be annotated with @Command
      Returns:
      String[] the version string
      Throws:
      CliException - when the class is not annotated with @Command

    • getCommandName

      public static String getCommandName(Class<?> programClass) throws CliException
      Parameters:
      programClass - Class<?>; the class for which to retrieve the program name. The class should be annotated with @Command
      Returns:
      String the name string
      Throws:
      CliException - when the class is not annotated with @Command

    • getCommandName

      public static String getCommandName(Object program) throws CliException
      Parameters:
      program - Object; the program for which to retrieve the program name. The program's class should be annotated with @Command
      Returns:
      String the name string
      Throws:
      CliException - when the class is not annotated with @Command

    • getCommandDescription

      public static String[] getCommandDescription(Class<?> programClass) throws CliException
      Parameters:
      programClass - Class<?>; the class for which to retrieve the description. The class should be annotated with @Command
      Returns:
      String[] the description string
      Throws:
      CliException - when the class is not annotated with @Command

    • getCommandDescription

      public static String[] getCommandDescription(Object program) throws CliException
      Parameters:
      program - Object; the program for which to retrieve the description. The program's class should be annotated with @Command
      Returns:
      String[] the description string
      Throws:
      CliException - when the class is not annotated with @Command

    • makeOverrideKeyProperty

      static String makeOverrideKeyProperty(Class<?> programClass, String fieldName, String propertyName)
      Make the override key for an option property.
      Parameters:
      programClass - Class<?>; the class of the program for which the options should be changed
      fieldName - String; the field for which the defaultValue in @Option should be changed
      propertyName - String; the name of the property to change the value of
      Returns:
      String; the override key for an option property

    • makeOverrideKeyCommand

      static String makeOverrideKeyCommand(Class<?> programClass, String propertyName)
      Make the override key for the Command annotation.
      Parameters:
      programClass - Class<?>; the class of the program for which the options should be changed
      propertyName - String; the name of the annotation property to change the value of
      Returns:
      String; the override key for an option property