replit / clui Goto Github PK

https://www.commonwl.org/v1.1/CommandLineTool.html

First, let me say what a fantastic project this is and it's super easy to use 🙏. Thank you for building and sharing.

I wanted to get your thoughts on how I could extend the @replit/clui-input library to support ordered unnamed arguments before and possibly after named arguments (not as important).

I've tried to read through all the code first and before I began tinkering wanted to check to my thinking - maybe it's already possible and you can point me in the right direction.

At the moment, the input structure is:

COMMAND [SUBCOMMAND] [--KEY [VALUE]]

Where:

• There can be 0 to N subcommands to each (sub)command.
• There can be 0 to N named arguments (--key value) per (sub)command which can be optional and typed.
• Argument value must be preceded by a key.
• Argument value not always required - if flag or
• (Sub)commands and argument options can be resolved at runtime if they are async.

What I'd like to support in my application is:

COMMAND [SUBCOMMAND] [ARG] [--KEY [VALUE]]

The difference being the there is no requirement to identify the key and a free form value is valid for ARG (can be typed and required like named arguments), so it doesn't need to be from an options list.

In theory, this is already achievable if you:

1. Don't provide options to the argument and enter them free-form, but still requires --KEY before.
2. Treat ordered unnamed arguments as subcommands, but this means the values must all be known upfront. If the user wanted to enter COMMAND SUBCOMMAND foo, you would need to know foo in advance. I'd like to allow the user to enter a free form value (string, number, boolean) without specifying the key.
3. Use ordered unnamed arguments after named arguments/the AST is exhausted and manually parse them after receiving an update from the library - loses the clean coupling with specific (sub)commands and forces user to always put named arguments before is a bit awkward when compared to normal CLI.

I imagine you already considered this and it's absence is due to the complexity of handling it, but I figured I'd check anyways.

At the top-level interface, one possible proposal would be to pass a config as such:

  const root: ICommand = {
    commands: {
      user: {
        args: {
          info: {
            type: 'boolean',
          },
          name: {
            type: 'string',
            key: false
          },
        },
      },
    },
  };

Where key: boolean indictes if it requires the --KEY before and if not, it is expected in the order it appears in the config. This however creates the situation of type: boolean + key: false = neither key or value are required.

Therefore, flags could be changed to an explicity property such as argType: 'flag' | 'named' | 'unnamed to combine them all.

Alternatively, it could be it's own property such as orderedArgs (for lack of better name):

  const root: ICommand = {
    commands: {
      user: {
        orderedArgs: {
          nickname: {
            type: 'string',
            required: true
          },
          email: {
          	type: 'string'
          }
        },
        args: {
          info: {
            type: 'boolean',
          },
          name: {
            type: 'string',
          },
        },
      },
    },
  };

From here it's possible the configuration object interfaces used would be almost identical to ICommandArgs except that IArg would not need options. However, since options is already optional, it could use the same interfaces outside the AST and for ASTNodeKind but have a different nodes:

export interface IOrderedArgKeyNode {
  kind: 'ARG_KEY';
  parent: IParamNode;
  token: IToken;
  name: string;
}

export interface IOrderedArgValueNode {
  kind: 'ARG_VALUE';
  parent: IParamNode;
  token: IToken;
}

export interface IOrderedArgNode {
  kind: 'ARG';
  ref: IArg;
  parent: ICmdNode;
  key: IArgKeyNode;
  value?: IArgValueNode;
}

If it would be clearer, interfaces could be more specific outside and inside the AST. For example:

export type ASTNodeKind =
  ...
  | 'ORDERED_ARG'
  | 'ORDERED_ARG_KEY'
  | 'ORDERED_ARG_VALUE'
  ...


export interface IOrderedArgs<D = any> {
  type?: OrderedArgTypeDef;
  required?: true;
  data?: D;
}

....etc

My intuition is taking the simplest path here of just augmenting the current IArg interface by setting a property to identify if its a flag, named or unnamed would be best and then the focus would be on the logic in parser.ts to change the logic for identifying arguments in all 3 styles.

Do you think this is something that is straightforward or would it fundamentally break how you've designed the parsing/AST/options system?

I'd appreciate any input you can provide and will glady create a PR if I can make progress.

I hope this makes, but if not please let me know.

Does clui support OpenAPI spec introspection? Would be nice to have that support.

Sorry for the stupid question, but can I use this to write a command line application and render the suggestions in a terminal emulator?

If so, is there any example of it?