Radare2: help: distinguish required from optional commands

[ret2libc]

While looking at a help message I want to know immediately whether an argument is required or optional and if it's optional, whether there is a default value for it.

Right now this is not well defined or it is applied in a very inconsistent way.
Examples:

| o [file] 0x4000 rwx       map file at 0x4000
| o+ [file]                 open file in read-write mode
| o: [len]                  open a malloc://[len] copying the bytes from current offset
| fr [[old]] [new]         rename flag (if no new flag current seek one is used)
| fN [[name]] [realname]   set flag real name (if no flag name current seek one is used)
| af ([name]) ([addr])                  analyze functions (start at addr or $$)
Usage: wv[size] [value]   Write value of given size
| afb [addr]                                    list basic blocks of function

As you can see, it is not clear, at least to me. Is [[...]]? Is (...)?
We should be much more consistent in these things, as commands are a very important thing in a CLI.

/cc @karliss @trufae @ITAYC0HEN @xarkes @XVilka @thestr4ng3r

[ret2libc]

My proposal:

• required argument specified with <argument>. For example o+ <file>.
• optional argument specified with [argument]. In case a default value is assumed, list it with =.... For example o <file> [address=0 [rwx-mode]]

WDYT?

[ITAYC0HEN]

I agree with your suggestion

[xarkes]

Me as well.

[karliss]

One case not considered in the proposal above is command groups.
For example what is currently shown as w[1248][+-] and wB[-]. In the first case digit and plus or minus sign is required. In the second case minus sign is optional. I would be fine with using square brackets for the second case.
What about the ~second~ first case?

• w(1248)(+-)
• w([1248])([+-])
• w<1248><+->
• w{1248}{+-}

[XVilka]

Agree with @ret2libc. Regarding command groups I think w{1248}{+-} is better for the required arguments for command groups.

[ret2libc]

I didn't see https://github.com/radareorg/radare2/issues/17337#issuecomment-665145655 . I personally like more w<1248><+-> as < and > already have special meanings within the r2 shell, so they feel somehow less confusing then {..}, considering < can easily be found in command names. However, I don't mind the other options either.