egehurturk/EasyCLI

Command Line Argument Parser for Java

               

EasyCLI

A command line argument parser utility for Java
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About the Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About the Project

EasyCli is a light-weight command line argument parser for Java.

Built With

• Java

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

You need to have Java and Maven installed on your local machine.

Installation

These steps will install EasyCli on your local machine:

1. Clone this repository:

$ git clone https://github.com/egehurturk/EasyCLI.git

2. Install the project (pom.xml) into local maven repository.
   • This step will install the JAR and pom.xml files to ~/.m2/repository/

$ cd EasyCLI
$ ./mvnw package
$ mvn install

3. Add the following dependency to your Maven generated project:

<dependencies>
  <!-- Add this snippet under <dependencies> in pom.xml -->
    <dependency>
       <groupId>com.easycli</groupId>
       <artifactId>EasyCLI</artifactId>
       <version>1.0</version>
    </dependency>
</dependencies>

4. Use the API!

Usage

You can create command line arguments and flags with EasyCli API:

Arg

Arg directory = Arg.with()
          .longOptionName("directory")
          .shortOptionName("d")
          .argName("project_dir")
          .description("Maven generated project path")
          .required()
          .alias("dir")
          .build();

• longOptionName(String): sets the long name, i.e., the name that will be visible with -- prefix. For instance, if you set it as directory, then it will be accessed with --directory.
• shortOptionName(String): sets the short name, i.e., the name that will be visible with - prefix. For instance, if you set is as d, then it will be accessed with -d.
• argName(String): sets the argument name that will be displayed in the help message.
• description(String): sets the description for the argument and will be displayed in the help message.
• required(): marks the Arg as required. The opposite method is optional(), which marks the Arg as optional.
• alias(String): gives an alias value for the argument. This value is used to retrieve the value of an Arg.
• build(): builds the Arg

The code above will create an Arg. An Arg in a command line is a special parameter that has a value. For instance:

$ ./executable --directory /dev/null

Here, the --directory is defined as an Arg, which has a value after the flag.

Flag

Flag version = Flag.with()
          .longOptionName("version")
          .shortOptionName("v")
          .description("Get the latest version")
          .optional()
          .alias("version")
          .build();

• longOptionName(String): sets the long name, i.e., the name that will be visible with -- prefix. For instance, if you set it as version, then it will be accessed with --version.
• shortOptionName(String): sets the short name, i.e., the name that will be visible with - prefix. For instance, if you set is as v, then it will be accessed with -v.
• description(String): sets the description for the argument and will be displayed in the help message.
• optional(): marks the Flag as required. The opposite method is required(), which marks the Flag as optional.
• alias(String): gives an alias value for the argument.
• build(): builds the Flag

The code above will create a Flag. A Flag is a command line parameter that does not have a value. For instance,

./executable --version

Here, the --version is defined as a Flag, which does not have a value and is an indicator.

CmdOptions

CmdOptions is a class that stores Args and Flags. You can create a new CmdOptions with either:

CmdOptions options = new CmdOptions(arg1, flag1, /*...*/);

or

CmdOptions options = new CmdOptions();
options.add(arg1);
options.add(flag1);
//...

EasyCli

This class is the main class that provides methods to check and retrieve command line arguments. You can create a new EasyCli with:

 EasyCli cli = new EasyCli(args, options);

• args is the argument array. This must be the parameter of the main method: public static void main(String[] args)
• options is the CmdOptions class that stores Args and Flags

EasyCli class provides a method to check if all required Args and Flags exist in the args array. This method is matchAllArgs and returns a boolean:

boolean success = cli.matchAllArgs();

• A typical usage of this method is to print the help message when required parameters do not exist in the array:

   if (!cli.matchAllArgs()) {
      EasyCli.Synopsis helper = cli.new Synopsis("<exec_name>");
      helper.print();
  }

You can check if a parameter (an Arg or a Flag) exists with the has(String) method. The method accepts the alias value set for the particular parameter:

boolean versionExists = cli.has("version");

• Here, the "version" is the alias name

You can get Arg values with the get(String) method. The method accepts the alias value set for an Arg:

String dirValue = cli.get("dir");

• If a Flag alias is given, then the method throws IllegalArgumentException
• If the Arg with the given alias is not found, the return value will be null.
  • You can combine has(String) and get(String):

    if (cli.has("dir")) 
        String dir = cli.get("dir");

    • This will prevent dir from being null.

EasyCli.Synopsis

This class provides a method to print the synopsis of the given CmdOptions object. You can instantiate this class with:

EasyCli.Synopsis synopsis = cli.new Synopsis("<executable>");

• "<executable>" is the name of the executable you are running.

You can print the help message with the print() method:

synopsis.print();

This will produce an output like:

Usage: <executable> -d|--dir <project_dir> [-v|--version] [-h|--help]
	-d|--directory <project_dir>              Maven generated project
	-v|--version                              Get the latest version
	-h|--help                                 Print this message

• [] indicates that the value is optional.
• | is a separator for mutually exclusive items; choose one
• <> is a placeholder for which you must supply a value

The recommended way to use EasyCli is like this:

EasyCli cli = new EasyCli(args, options /* CmdOptions object */);
if (!cli.matchAllArgs()) {
    EasyCli.Synopsis help = cli.new Synopsis("<exec_name>");
    help.print();
    System.exit(1);
}
String dirVal = cli.get("dir");
//...

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Your Name - @egehurturk - ege.hurturk@gmail.com

Project Link: https://github.com/egehurturk/EasyCli