Style guide - Inputs

[jeffandersen]

Placeholder for discussion about these facets of the style guide.

Talking points

• Select lists
  • With and without "new item" input
• Text input
• Password inputs
• Confirmation (Y/N/abort)
• Args, command option and flag usage

[jeffandersen]

Currently

Select

$ torus link -f
✔ Select organization: jeffandersen
? Select project:
+  Create a new project
   awesome
 ☞ www

Confirmation

$ torus unset ok
You are about to unset "/jeffandersen/awesome/dev-jeffandersen/default/*/*/ok". This cannot be undone.
? Do you wish to continue? [y/n]

[jeffandersen]

I find our pointer character doesn't render the best across all fonts. We should think about replacements for that.

Colorizing the "Create new [object]" entry would provide better separation of outcome.

[ntassone]

@jeffandersen and @jbowes and I discussed the pointer offline and @jbowes followed through! https://github.com/manifoldco/torus-cli/pull/150

[ntassone]

The new object prompt needs to feel more separate imo. The plus doesn't quite get it there. Maybe a place to colorize? Or having the prompt start on create new would show that it can be selected and it is not a label.

[ntassone]

I actually like the way we handle inputs now. It feels very intuitive, dim label with ? to indicate its an input, changing to a ✔ on completion, an ✗ if its input is incorrect.

Password inputs are great right now as well with ●●●● masking.

[ntassone]

@jeffandersen what do you mean by:

Args, command option and flag usage

[jeffandersen]

@ntassone args being torus cmd subcmd [arg] (ie. torus orgs create myorg), command options being torus cmd --command-option [value] and flags being torus cmd --flag (no value).

[ntassone]

@jeffandersen Ah, gotcha, I put my thoughts for those on the main issue: https://github.com/manifoldco/torus-cli/issues/124#issuecomment-266059332

[jbowes]

args being torus cmd subcmd [arg] (ie. torus orgs create myorg), command options being torus cmd --command-option [value] and flags being torus cmd --flag (no value).

argument (or positional argument) is pretty standard for the bare thing on the command line, but the things with one or two -s in front (or heck, even a /!) are called all kinds of things: switches, options, flags, arguments. Sometimes the fact that it takes in its own argument or not changes the name. it's confusing.

I'd like to stick to 3 things:

• commands/subcommands
• arguments: the subject of the command.
• options: stuff with -- that might be:
  • strictly optional (--verbose)
  • sourceable from other locations (env vars, config file)
  • not expressible with vanilla arguments (complex options with deps. avoid these)

regardless of if it has its own argument, we should just call it an option.