Package org.djutils.cli

Class CliUtil

java.lang.Object
org.djutils.cli.CliUtil
public 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-2019 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

  • Constructor Summary

    Constructors 
    Constructor Description
    CliUtil()  

  • Method Summary

    Modifier and Type Method Description
    static void changeCommandDescription​(Class<?> programClass, String newDescription)
    Change the value of the 'description' property of an already present @Command annotation in a class or superclass of that class.
    static void changeCommandDescription​(Object program, String newDescription)
    Change the value of the 'description' property of an already present @Command annotation in a class or superclass of that class.
    static void changeCommandName​(Class<?> programClass, String newName)
    Change the value of the 'name' property of an already present @Command annotation in a class or superclass of that class.
    static void changeCommandName​(Object program, String newName)
    Change the value of the 'name' property of an already present @Command annotation in a class or superclass of that class.
    static void changeCommandProperty​(Class<?> programClass, String propertyName, Object newValue)
    Change the value of a property of an already present @Command annotation in a class or superclass of that class.
    static void changeCommandProperty​(Object program, String propertyName, Object newValue)
    Change the value of a property of an already present @Command annotation in a class or superclass of that class.
    static void changeCommandVersion​(Class<?> programClass, String newVersion)
    Change the value of the 'version' property of an already present @Command annotation in a class or superclass of that class.
    static void changeCommandVersion​(Object program, String newVersion)
    Change the value of the 'version' property of an already present @Command annotation in a class or superclass of that class.
    static void changeOptionDefault​(Class<?> programClass, String fieldName, String newDefaultValue)
    Change the default value of an already present @Option annotation of the "defaultValue" field in a class or superclass.
    static void changeOptionDefault​(Object program, String fieldName, String newDefaultValue)
    Change the default value of an already present @Option annotation of the "defaultValue" field in a class or superclass.
    static void changeOptionProperty​(Class<?> programClass, String fieldName, String propertyName, Object newValue)
    Change the value of a property of an already present @Option annotation of a field in a class or superclass.
    static void changeOptionProperty​(Object program, String fieldName, String propertyName, Object newValue)
    Change the value of a property of an already present @Option annotation of a field in a class or superclass.
    static void execute​(Object program, String[] args)
    Parse the command line for the program.
    static void execute​(CommandLine commandLine, String[] args)
    Parse the given CommandLine object, that has been generated for a program.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

  • 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 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, IllegalStateException, IllegalArgumentException
      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 - String; 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeOptionProperty

      public static void changeOptionProperty​(Object program, String fieldName, String propertyName, Object newValue) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 - String; 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeOptionDefault

      public static void changeOptionDefault​(Object program, String fieldName, String newDefaultValue) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 - Object; 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeOptionDefault

      public static void changeOptionDefault​(Class<?> programClass, String fieldName, String newDefaultValue) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 - Object; 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeCommandProperty

      public static void changeCommandProperty​(Object program, String propertyName, Object newValue) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      Change the value of a 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
      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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeCommandProperty

      public static void changeCommandProperty​(Class<?> programClass, String propertyName, Object newValue) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      Change the value of a 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
      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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeCommandName

      public static void changeCommandName​(Object program, String newName) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeCommandName

      public static void changeCommandName​(Class<?> programClass, String newName) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeCommandDescription

      public static void changeCommandDescription​(Object program, String newDescription) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeCommandDescription

      public static void changeCommandDescription​(Class<?> programClass, String newDescription) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeCommandVersion

      public static void changeCommandVersion​(Object program, String newVersion) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue

    • changeCommandVersion

      public static void changeCommandVersion​(Class<?> programClass, String newVersion) throws CliException, NoSuchFieldException, IllegalStateException, IllegalArgumentException
      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 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
      IllegalStateException - when the annotation has no member values or access to the member values is denied
      IllegalArgumentException - when the value that is changed is of a different type than the type of the newValue