Mistral CLI spec for specifying action inputs

mistral_cli_spec.md

I was looking into fixing bug: https://bugs.launchpad.net/mistral/+bug/1401039. My idea was to use shlex to parse the string. This actually would work for anything that is supplied in the linux shell syntax. Problem is this craps out when we want to support complex data structures such as arrays and dicts as arguments. I did not think we supported a syntax to take in complex data structures in a one line format. Consider for example:

      task7:
        for-each:
          vm_info: $.vms
        workflow: wf2 is_true=true object_list=[1, null, "str"]
        on-complete:
          - task9
          - task10

Specifically

wf2 is_true=true object_list=[1, null, "str"]

shlex will not handle this correctly because object_list is an array. Same problem with dict.

There are 3 potential options here:

Option 1

1. Provide a spec for specifying lists and dicts like so: list_arg=1,2,3 and dict_arg=h1:h2,h3:h4,h5:h6

shlex will handle this fine but there needs to be a code that converts the argument values to appropriate data types based on schema. (ActionSpec should have a parameter schema probably in jsonschema). This is doable.

wf2 is_true=true object_list="1,null,"str""

Option 2

2. Allow JSON strings to be used as arguments so we can json.loads them (if it fails, use them as simple string). For example, with this approach, the line becomes

wf2 is_true=true object_list="[1, null, "str"]"

This would pretty much resemble http://stackoverflow.com/questions/7625786/type-dict-in-argparse-add-argument

Option 3

3. Keep the spec as such and try to parse it. I have no idea how we can do this reliably. We need a more rigorous lexer. This syntax doesn't translate well when we want to build a CLI. Linux shells cannot support this syntax natively. This means people would have to use shlex syntax and a translation needs to happen in CLI layer. This will lead to inconsistency. CLI uses some syntax and the action input line in workflow definition will use another. We should try and avoid this.

Option 4

4. Completely drop support for this fancy one line syntax in workflow. This is probably the least desired option.

Looking the options, I personally prefer option 2 even though we need to JSON stringify complex types. With some documentation, we can tell people why we went with this approach. People will also grok because they are already familiar with CLI limitations in linux.