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-2021 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 Summary

Fields

Modifier and Type	Field	Description
(package private) static Map<String,Object>	overrideMap	The map with overrides for default values and other Option and Program annotation values.

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	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.
static CommandLine.Command	getCommandAnnotation(Class<?> programClass)	Return the @Command annotation of a class or one of its superclasses.
static Class<?>	getCommandAnnotationClass(Class<?> programClass)	Return the @Command annotation of a class or one of its superclasses.
static String[]	getCommandDescription(Class<?> programClass)
static String[]	getCommandDescription(Object program)
static String	getCommandName(Class<?> programClass)
static String	getCommandName(Object program)
static String[]	getCommandVersion(Class<?> programClass)
static String[]	getCommandVersion(Object program)
(package private) static String	makeOverrideKeyCommand(Class<?> programClass, String propertyName)	Make the override key for the Command annotation.
(package private) static String	makeOverrideKeyProperty(Class<?> programClass, String fieldName, String propertyName)	Make the override key for an option property.

Methods inherited from class java.lang.Object

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

Field Detail

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 Detail

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

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