phpgt / cli Goto Github PK

Within run, $arguments->contains("something") will return false if another argument has been checked first, because something will be the value of the other argument.

Named arguments --like-this or short versions like -l should only be accepted if they are defined. I just tried using a cli script with an incorrectly named argument and it just ignored it... easy mistake to make, but it would have been nice to have been recognised by the system. An error message like Invalid argument supplied: "--something" would have been nice.

When a command outputs something, it needs to be grouped into its own output stream.

Each stream can be provided a different colour, after #4 is implemented. For non-coloured terminals, the name of the command that is being output can be shown along with a timestamp before the message.

For example, two long-running processes "time" and "status" that make output every few seconds:

[time] 2020-04-05 17:25:53
The time is twenty five minutes past five.

[status] 2020-04-05 17:25:59
OK

[time] 2020-04-05 17:26:03
The time is twenty six minutes past five.

[status]  2020-04-05 17:26:10
OK

This will avoid unknown streams being passed by accident.

Not 100% sure how this will work, but it is common to be able to pass in multiple arguments of the same name.

For example: myapp mycommand --thing=123 --thing=456 --thing=789

This should prevent command chaining if the arguments aren't matching.

When setting a new parameter on a command, if the long/short option has already been used, throw an exception.

This would be nice to see when reading data from the cli.

Dependabot needs to be tamed, as per PhpGt/WebEngine#568

Inspired from snap install on Ubuntu.

The bottom line of the terminal is used to display text progress and percent progress in a minimal way.

As the status changes of the long-running process (for example, each package name as is being installed by Composer), the text is updated, but also the background/text colours are inverted to show a progress bar.

A nice solution in a single line on the Cli.

The setDefaultCommand function is used to allow calling a command that's registered on the Application without calling the command, which is useful for applications that only have one command.

However, the function was designed with one particular use-case in mind: a command that takes only Parameters and not NamedParameters. With NamedParameters, this functionality is impossible to use.

If the setDefaultCommand function was renamed to forceCommand, this would tell the Application that the provided command should always be run.

Would be extra useful to have #15 implemented for this too.

--version is handled by the Application, but needs some work integrating with composer and reading through the composer.json.

Currently, the method of checking the version number is by looking the Composer's installed.json and finding a "bin" match, returning that version number. There is probably a better way.

All of the initialisation is currently made in the constructor. Add abstract get functions to the base Command class to enforce the following:

• getName():string
• getParameters():???

Not only does this force the developer to implement all required parts of a Command, but there are plans to add logic to the abstract Command constructor, and I personally prefer not to have to chain parent constructor calls.

For example, in the repository PHP.Gt/Cron the help output message looks like this:

PHP.Gt Cron

Available commands:
 • run	Start a long-running process to execute each job when it is due
 • validate	Check the syntax of your crontab file and that the jobs exist

It should be possible to make tabs line up automatically in certain "table" outputs.

If a parameter is given an example value, it should be shown in the --help output. It's currently being shown, but it doesn't make sense where it's being output.

Example of what's currently happeneing:

$ myscript --help
Usage: mycommand exampleNamedParameter [--startFrom|-s 12345]

  -s, --startFrom      (Optional) Provide an ID to start from

Maybe just an "e.g." would make more sense.

When listing out the named parameters, use uppercase example usage, for example:

Error: Not enough arguments passed. Passed: 0 required: 1.
Usage: create PROJECT_NAME [--blueprint|-b BLUEPRINT_NAME]

currently PROJECT_NAME is shown as name.

Currently all arguments have to be pre-specified in order to be able to use them. This is useful for passing user data into the application.

When an output stream emits the same message more than once, it would be extremely useful to "stack" the stream.

Issue #5 defines the feature of having one or more output streams. After this is implemented, a follow-on feature is to stack similar messages.

If the same message is output from the same script, rather than outputting it again, mark it with the number of repetitions instead.

[time] 2020-04-05 17:25:53
The time is twenty five minutes past five.

[time] 2020-04-05 17:26:03
The time is twenty six minutes past five.

[status]  2020-04-05 17:26:10 (7)
OK

Unix style parameters (single letters) can be chained together, but currently this is not possible in PHP.Gt/Cli

Example

tar --create --gzip --file myarchive.tar.gz
# equal to:
tar -c -z -f myarchive.tar.gz
# equal to:
tar -czf myarchive.tar.gz

Colour the output in a consistent manner.

output("some text", Colour::GREEN); // single green message, resets afterwards
setOutputColour(Colour::RED); // set default colour to reset to
resetOutputColour(); // reset to default colour

Must not use the word Colour because of the American/British spelling.

app help is a nice way to get help about the available commands, but getting a command's parameters wrong is currently the only way to see the example usage for each command.

app help commandName is a good solution for this. Possibly needs to have "Type app help commandName for help with a specific command" added to the bottom of the help message.

Allow setting an exit status code in the application logic to be exited with in the exit function, called after run has completed.

Automatically concatenate getAll with spaces.

Return type of Gt\Cli\Argument\ArgumentList::rewind() should either be compatible with Iterator::rewind(): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /home/g105b/Code/Persomic/website/vendor/phpgt/cli/src/Argument/ArgumentList.php on line 145

The default command is automatically set to help but some commands would be nice to call via just the application's name.

Parameters should still be passed through, but obviously named parameters would not work like this.

It would be useful to refactor and enhance the output from just simple writeLine usage.

Idea:

$section = new OutputSection("The title of this section:");
$section->writeLine("Some text that will be indented", Colour::GREEN);

Oh, but Americans will hate the word Colour, so something else should be used.

Should the argument order matter?

Currently, looking at PHP.Gt/Sync, this command fails:

sync --pattern * --symlink path/to/source path/to/dest

but this command succeeds:

sync path/to/source path/to/dest --pattern * --symlink

Shouldn't they both be synonymous?

The term "require" is used throughout to mean something that must be set, but the first argument of the Parameter's constructor means whether this particular parameter takes a value, or whether it is value-less.

Many unix programs accept --help as an argument. phpgt/cli uses "help" as a command name, but it would help discoverability of functionality to users if --help worked too, especially for applications with a default command other than help, thanks to #23.