Document command syntax

[fgrazi]

Discussed in #838

^{Originally posted by fgrazi August 1, 2023}
I would like to use this Spring library, but I am getting a lot of trouble
on the command syntax.

I am confused with the syntax of the command. How does the parser recognize
arguments from options:

• What is the difference between a positional parameter and an option?
• Shall options precede positional parameters?
• How to make parameters and/or options mandatory?
• How to quote parameters and options? How to escape quotes?

Those are fundamental questions to whoever is trying to use the library.
I tried to use it but, since those principles are not clear, I get results that look weird and inconsistent. Here are some examples.

  @ShellMethod(key = "test")
  public String test(String arg1, String arg2, @ShellOption String opt1, @ShellOption String opt2) {
   return MessageFormat.format("arg1: {0}, arg2: {1}, opt1: {2}, opt2: {3}",
     arg1, arg2, opt1, opt2);
  }

And some trials:

  test arg1 arg2 opt1 opt2 => arg1, arg2: arg2, opt1: opt1, opt2: opt2

Despite @ShellOption everything here seems to be parsed as positional
and options are captured as parameters.

If I try the options as positional I get an error:

  shell:>test --opt2 opt2 --opt1 opt1 arg1 arg2
  Missing mandatory option '--arg2'
  Missing mandatory option '--arg1'

But not if the options follow the arguments:

  test arg1 arg2 --opt2 opt2 --opt1 opt1 => arg1: arg1, arg2: arg2, opt1: opt1, opt2: opt2

OK, but if I ask for help I read that all arguments are mandatory and also there is no distinction between arguments and options:

  shell:>help test
  NAME
      test - 
   
  SYNOPSIS
      test [--arg1 String] [--arg2 String] [--opt1 String] [--opt2 String] --help 
   
  OPTIONS
      --arg1 String
      [Mandatory]
   
      --arg2 String
      [Mandatory]
   
      --opt1 String
      [Mandatory]
   
      --opt2 String
      [Mandatory]
   
      --help or -h 
      help for test
      [Optional]

I only get a error if I specify no arguments and options:

     shell:>test
     Missing mandatory option '--arg2'
     Missing mandatory option '--arg1'
     Missing mandatory option '--opt1'
     Missing mandatory option '--opt2'

Quoting arguments is also confused (as I have already reported).

Is there some link where the command line syntax is clearly explained?

[fmbenhassine]

In Spring Shell 4, we have a new section that documents the command syntax with all parsing rules: https://docs.spring.io/spring-shell/reference/4.0-SNAPSHOT/commands/syntax.html