new cli syntax

[perrygeo]

As discussed in #5, We ditched the idea of click command options (--saturation, etc) because they are unordered. As an alternative, we developed a little domain specific language where each additional argument was an operation to applied in order.

e.g. this would apply gamma to red and green then a saturation to the whole image

rio color in.tif out.tif "gamma r,g 1.05" "saturation 125"

This works until you start passing around the the operations as shell variables. You quickly get into quote escape and delimeter hell. Consider this

$ color_formula="\"gamma r,g 1.05\" \"saturation 125\""
$ set -x
$ echo $color_formula
+ echo '"gamma' r,g '1.05"' '"saturation' '125"'

Ugh. broken by spaces. It gets even nastier when you try to read operations from files or sed streams.

In short, our DSL has issues.

❓ Potential Solutions:

• Use a different delimiter: gamma_r,g_1.05 saturation_125 a bit yicky but functional. By using _ and avoiding the space, we avoid the need to use quotes. And we could make it compatible with the existing language.
• Use something that would be an entire departure
  • a single quoted series of S-expressions: "(gamma r,g 1.05) (saturation 125)"
  • override click.Command.parse_args to keep ordered options: --gamma r,g 1.05 --saturation 125
  • unquoted DSL: gamma r,g 1.05 saturation 125

/cc @sgillies @celoyd

[perrygeo]

soliciting some advice over at pallets/click#567

[celoyd]

What about commas?

rio color in.tif out.tif gamma rg 1.05, saturation 125

Con: It makes color selectors less readable, and it means that long-form selectors like red,green have to go. It’s also not particularly standard syntax.

Pro: it’s easy to type, and it expresses the idea of sequence clearly.

[perrygeo]

So I've gone ahead with the "unquoted DSL" route with optional commas to separate the operations.

These are equivalent commands. Commas are effectively treated like an empty string, use them if they make it more clear but they have no syntactic meaning.

$ rio color in.tif out.tif gamma rgb 0.95 sigmoidal rgb 35 0.13
$ rio color in.tif out.tif gamma rgb 0.95, sigmoidal rgb 35 0.13

PR coming soon.