[jira] [Comment Edited] (CLI-298) Define CLI options via configuration file

["Richard (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/CLI-298?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16953190#comment-16953190 ] 

Richard edited comment on CLI-298 at 10/16/19 9:02 PM:
-------------------------------------------------------

Thanks Emmanuel,

Global option OPTION_TYPE is checked for re-definition; not sure that standard option.[name] types are or global HELP_* options are; if they're not, I'll update the tests tomorrow to cater for catching these exceptions.

WRT example of options, if you start with the javadoc for CommandLineConfiguration, it's all linked from there. But, for brevity, here goes:

Step 0: We're going to create a CLI configuration that supports -f/--file (file to write to), -t/--text (text to write to file) and -o/--overwrite --(overwrite file). In addition, we want the CLI configuration to deal with help printing for us.

Step 1: Create your CLI configuration in a file named opt.config:

```
HELP_OPTION_NAME=showHelp
 HELP_COMMAND_NAME=writeData
 HELP_COMMAND_HEADER=Write the specified text to the specified file. If the \
 options contain spaces or special characters, supply the arguments in \
 double quotes.
 HELP_COMMAND_FOOTER=Copyleft Foo, Bar & Baz International.
 option.outfile.opts=f/file
 option.outfile.hasArg=true
 option.outfile.argName=file
 option.outfile.description=File to write to.

 option.textToWrite.opts=t/text
 option.textToWrite.hasArg=true
 option.textToWrite.argName=text
 option.textToWrite.description=Text to write to the file.

 option.writeover.opts=o/overwrite
 option.writeover.hasArg=false
 option.writeover.description=If set, write over the existing file; \
      otherwise, append to the file.

 option.showHelp.opts=h/help
 option.showHelp.hasArg=false
 option.showHelp.description=Print this help then quit.
```

Step 2: Create an option listener:

```
public class MyOptionListener implements OptionListener

```
public class MyOptionListener implements OptionListener
{
    public File outFile;

    public String text;

    public boolean overwrite;

    @Override
    public void option(final String option, final Object value)
    {
        if ("help".equals(option))
        {
            System.exit(0);
        }
        else if ("file".equals(option))
        {
            outFile = new File(value.toString());
        }
        else if ("text".equals(option))
        {
            text = value.toString();
        }
        else if ("overwrite".equals(option))
        {
            overwrite = true;
        }
     }
}
```

Step 3: Call the API from a call to static void main(String[] args) - this example illustrates a pre-defined class named Application that has a call to write(File, String, boolean), but that's not really important - at this point we've processed all the arguments and can do what we like with them:

```
 MyAppListener listener = new MyAppListener();
 InputStream is = new FileInputStream(new File("opt.config"));
 CommandLineConfiguration cliConfig = new CommandLineConfiguration();
 cliConfig.addOptionListener(listener);
 // args[] from the public static void main(String[] args) call:
 cliConfig.process(is, args);
 Application application = new Application();
 if (listener.file != null && listener.text != null)
 {
     application.write(listener.file, listener.text, listener.overwrite);
 }
 else
 {
     System.err.println("File and text must be supplied.");
     System.exit(1);
 }
```

 


was (Author: zendawg):
Thanks Emmanuel,

Global option OPTION_TYPE is checked for re-definition; not sure that standard option.[name] types are or global HELP_* options are; if they're not, I'll update the tests tomorrow to cater for catching these exceptions.

WRT example of options, if you start with the javadoc for CommandLineConfiguration, it's all linked from there. But, for brevity, here goes:

Step 0: We're going to create a CLI configuration that supports \-f/\-\-file (file to write to), \-t/\-\-text (text to write to file) and \-o/\-\-overwrite --(overwrite file). In addition, we want the CLI configuration to deal with help printing for us.

Step 1: Create your CLI configuration in a file named opt.config:

{{HELP_OPTION_NAME=showHelp}}
{{ HELP_COMMAND_NAME=writeData}}
{{ HELP_COMMAND_HEADER=Write the specified text to the specified file. If the \}}
{{     options contain spaces or special characters, supply the arguments in \}}
{{     }}{{ double quotes.}}
{{ HELP_COMMAND_FOOTER=Copyleft Foo, Bar & Baz International.}}{{option.outfile.opts=f/file}}
{{ option.outfile.hasArg=true}}
{{ option.outfile.argName=file}}
{{ option.outfile.description=File to write to.}}{{option.textToWrite.opts=t/text}}
{{ option.textToWrite.hasArg=true}}
{{ option.textToWrite.argName=text}}
{{ option.textToWrite.description=Text to write to the file.}}{{option.writeover.opts=o/overwrite}}
{{}}{{option.writeover.description=If set, write over the existing file; \}}
{{     }}{{otherwise, append to the file.}}{{option.showHelp.opts=h/help}}
{{ option.showHelp.hasArg=false}}
{{ option.showHelp.description=Print this help then quit.}}

Step 2: Create an option listener:

{{public class MyOptionListener implements OptionListener}}

{{{}}

{{    public File outFile;}}

{{    }}{{public String text;}}

{{    }}{{public boolean overwrite;}}

{{    }}{{@Override}}

{{    }}{{public void option(final String option, final Object value)}}
{{    }}{{{}}
{{    }}{{ if ("help".equals(option))}}
{{    }}{{}}{{{}}

{{        // Global HELP_* options at this point already printed so we quit here and exit gracefully}}
{{    }}{{    }}{{ System.exit(0);}}
{{    }}{{ }}}
{{    }}{{ else if ("file".equals(option))}}
{{    }}{{ {}}
{{    }}{{    }}{{ outFile = new File(value.toString());}}
{{    }}{{ }}}
{{    }}{{ else if ("text".equals(option))}}
{{    }}{{{}}
{{    }}{{    }}{{ text = value.toString();}}
{{    }}{{ }}}
{{    }}{{ else if ("overwrite".equals(option))}}
{{    }}{{ {}}
{{    }}{{    }}{{overwrite = true;}}
{{    }}{{ }}}
{{ }}}

Step 3: Call the API from a call to static void main(String[] args) - this example illustrates a pre-defined class named Application that has a call to write(File, String, boolean), but that's not really important - at this point we've processed all the arguments and can do what we like with them:

{{ MyOptionListener listener = new MyOptionListener(); }}

{{InputStream is = new FileInputStream(new File("opt.config")); }}

{{CommandLineConfiguration cliConfig = new CommandLineConfiguration();}}

{{ cliConfig.addOptionListener(listener); }}

{{// args[] from the public static void main(String[] args) call: }}

{{cliConfig.process(is, "UTF-8"args); }}

{{Application application = new Application(); }}

{{if (listener.file != null && listener.text != null) }}

{{}}

{{{}}

{{    }}{{application.write(listener.file, listener.text, listener.overwrite); }}

{{} }}

{{else}}

{{{}}

{{    System.err.println("File and text must be supplied.");
     System.exit(1);}}

{{}}}

 

> Define CLI options via configuration file
> -----------------------------------------
>
>                 Key: CLI-298
>                 URL: https://issues.apache.org/jira/browse/CLI-298
>             Project: Commons CLI
>          Issue Type: Improvement
>          Components: Options definition
>    Affects Versions: 1.5, Nightly Builds
>            Reporter: Richard
>            Priority: Minor
>              Labels: newbie, pull-request-available, ready-to-commit
>   Original Estimate: 336h
>  Remaining Estimate: 336h
>
> Create a configuration that enables users to define CLI options via a configuration file. Such configuration would normally pre-defined and bundled inside the executable jar running the application. This would reduce the amount of code required to define command line options and introduce the ability to do a lot of the checking a user does (such as converting values to integers, files, checking if integers are above/below a certain amount, checking that files or directories do/don't exist etc.) For security purposes, at compile time calculate an MD5 for the application, if this doesn't match at runtime warn of corrupted file exception. Also add I18N since this will be driven via the user experience for exception messages.
> So far I've catered for basic options that utilise strings.
> Code already started with a pull request at [https://github.com/zendawg/commons-cli] underneath the branch named "cli-configuration".
> Apologies in advance, never contributed to Apache SWF before.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)