Merge master to 3.x

.github/workflows/php.yml

@@ -0,0 +1,52 @@
+name: Unit-tests
+
+on:
+  push:
+    paths:
+      - '**.php'
+      - 'composer.json'
+      - '**.yml'
+
+jobs:
+  test:
+    name: Test on php ${{ matrix.php}} and ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: true
+      matrix:
+        php: [7.3, 7.4] #
+        os: [ubuntu-latest, macOS-latest] # windows-latest,
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Set ENV vars
+        # https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable
+        run: |
+          echo "RELEASE_TAG=${GITHUB_REF:10}" >> $GITHUB_ENV
+          echo "RELEASE_NAME=$GITHUB_WORKFLOW" >> $GITHUB_ENV
+
+      - name: Display Env
+        run: env
+
+      # usage refer https://github.com/shivammathur/setup-php
+      - name: Setup PHP
+        timeout-minutes: 5
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php}}
+          tools: pecl, php-cs-fixer, phpunit
+          extensions: mbstring, dom, fileinfo, mysql, openssl, igbinary, redis # , swoole-4.4.19 #optional, setup extensions
+          ini-values: post_max_size=56M, short_open_tag=On #optional, setup php.ini configuration
+          coverage: none #optional, setup coverage driver: xdebug, none
+
+      - name: Install dependencies
+        run: composer install --no-progress --no-suggest
+
+      # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
+      # Docs: https://getcomposer.org/doc/articles/scripts.md
+
+      - name: Run unit tests
+        run: php vendor/bin/phpunit

.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Tag-release
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  release:
+    name: Test on php ${{ matrix.php}}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: true
+      matrix:
+        php: [7.3]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Set ENV for github-release
+        # https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable
+        run: |
+          echo "RELEASE_TAG=${GITHUB_REF:10}" >> $GITHUB_ENV
+          echo "RELEASE_NAME=$GITHUB_WORKFLOW" >> $GITHUB_ENV
+
+      # usage refer https://github.com/shivammathur/setup-php
+      - name: Setup PHP
+        timeout-minutes: 5
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php}}
+          tools: pecl, php-cs-fixer, phpunit
+          extensions: mbstring, dom, fileinfo, mysql, openssl # , swoole-4.4.19 #optional, setup extensions
+          ini-values: post_max_size=56M, short_open_tag=On #optional, setup php.ini configuration
+          coverage: none #optional, setup coverage driver: xdebug, none
+
+      - name: Install dependencies # eg: v1.0.3
+        run: |
+          tag1=${GITHUB_REF#refs/*/}
+          echo "release tag: ${tag1}"
+          composer install --no-progress --no-suggest
+
+      # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
+      # Docs: https://getcomposer.org/doc/articles/scripts.md
+
+#      - name: Build phar and send to github assets
+#        run: |
+#          echo $RELEASE_TAG
+#          echo $RELEASE_NAME
+#          php -d phar.readonly=0 bin/kite phar:pack -o kite-${RELEASE_TAG}.phar --no-progress
+#          php kite-${RELEASE_TAG}.phar -V
+
+      # https://github.com/actions/create-release
+      - uses: meeDamian/[email protected]
+        with:
+          gzip: false
+          token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ env.RELEASE_TAG }}
+          name: ${{ env.RELEASE_TAG }}
+#          files: kite-${{ env.RELEASE_TAG }}.phar

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## v4.0.x
+
+> begin at: 2020.08.21
+
+
 ## v3.0.x
 
 > publish at: 2019.01.03

README.md

@@ -1,13 +1,15 @@
-# PHP console
+# PHP Console
 
 [![License](https://img.shields.io/packagist/l/inhere/console.svg?style=flat-square)](LICENSE)
-[![Php Version](https://img.shields.io/badge/php-%3E=7.1.0-brightgreen.svg?maxAge=2592000)](https://packagist.org/packages/inhere/console)
+[![Php Version](https://img.shields.io/badge/php-%3E=7.2.0-brightgreen.svg?maxAge=2592000)](https://packagist.org/packages/inhere/console)
 [![Latest Stable Version](http://img.shields.io/packagist/v/inhere/console.svg)](https://packagist.org/packages/inhere/console)
+[![Github Actions Status](https://github.com/inhere/php-console/workflows/Unit-tests/badge.svg)](https://github.com/inhere/php-console/actions)
 
 A simple, full-featured php command line application library. 
+
 Provide console parameter parsing, command run, color style output, user information interaction, and special format information display.
 
-> **[中文README](./README_cn.md)**
+> **[中文README](./README.zh-CN.md)**
 
 ## Command line preview
 
@@ -19,15 +21,17 @@ Provide console parameter parsing, command run, color style output, user informa
 
 - Command line application, `controller`, `command` parsing run on the command line
 - Support for setting aliases for commands. A command can have multiple aliases. Support command display/hide, enable/disable
-- Full-featured command line option parameter parsing (named parameters, short options, long options...). `input`, `output` of the command line, management, use
+- Full-featured command line option parameter parsing (named parameters, short options `-s`, long options `--long`). 
+- The `input`, `output` of the command line, management, use
 - Command method comments are automatically parsed as help information (by default, `@usage` `@arguments` `@options` `@example`)
 - Support for outputting message texts of multiple color styles (`info`, `comment`, `success`, `warning`, `danger`, `error` ... )
 - Commonly used special format information display (`section`, `panel`, `padding`, `helpPanel`, `table`, `tree`, `title`, `list`, `multiList`)
 - Rich dynamic information display (`pending/loading`, `pointing`, `spinner`, `counterTxt`, `dynamicText`, `progressTxt`, `progressBar`)
 - Common user information interaction support (`select`, `multiSelect`, `confirm`, `ask/question`, `askPassword/askHiddenInput`)
-- Support for predefined parameter definitions like `symfony/console` (giving parameter values ​​by position, recommended when strict parameter restrictions are required)
+- Support for predefined parameter definitions like `symfony/console` (giving parameter values by position, recommended when strict parameter restrictions are required)
 - The color output is `windows` `linux` `mac` compatible. Environments that do not support color will automatically remove the relevant CODE.
 - Quickly generate auto-completion scripts for the current application in the `bash/zsh` environment
+- NEW: Support start an interactive shell for run application
 
 ### Built-in tools
 
@@ -40,7 +44,7 @@ Provide console parameter parsing, command run, color style output, user informa
 
 > All features, effects; can be run in the example code `phps/app` in `examples/`. Basically covers all the features and can be tested directly
 
-## Quick installation
+## Installation
 
 ```bash
 composer require inhere/console

README_cn.md → README.zh-CN.md

@@ -1,8 +1,9 @@
-# php 命令行应用库
+# PHP Console
 
 [![License](https://img.shields.io/packagist/l/inhere/console.svg?style=flat-square)](LICENSE)
-[![Php Version](https://img.shields.io/badge/php-%3E=7.1.0-brightgreen.svg?maxAge=2592000)](https://packagist.org/packages/inhere/console)
+[![Php Version](https://img.shields.io/badge/php-%3E=7.2.0-brightgreen.svg?maxAge=2592000)](https://packagist.org/packages/inhere/console)
 [![Latest Stable Version](http://img.shields.io/packagist/v/inhere/console.svg)](https://packagist.org/packages/inhere/console)
+[![Github Actions Status](https://github.com/inhere/php-console/workflows/Unit-tests/badge.svg)](https://github.com/inhere/php-console/actions)
 
 简洁、功能全面的php命令行应用库。提供控制台参数解析, 命令运行，颜色风格输出, 用户信息交互, 特殊格式信息显示。
 
@@ -18,7 +19,8 @@
 
 - 命令行应用, 命令行的 `controller`, `command` 解析运行 
 - 支持给命令设置别名,一个命令可以有多个别名。支持命令的显示/隐藏，启用/禁用
-- 功能全面的命令行的选项参数解析(命名参数，短选项，长选项 ...)。命令行的 `input`, `output` 管理、使用
+- 功能全面的命令行的选项参数解析(命名参数，短选项 `-s`，长选项 `--long`)
+- 命令行下的 输入`input`, 输出 `output` 管理、使用
 - 命令方法注释自动解析为帮助信息（默认提取 `@usage` `@arguments` `@options` `@example` 等信息）
 - 支持输出多种颜色风格的消息文本(`info`, `comment`, `success`, `warning`, `danger`, `error` ... )
 - 常用的特殊格式信息显示(`section`, `panel`, `padding`, `helpPanel`, `table`, `tree`, `title`, `list`, `multiList`)

TODO.md

@@ -0,0 +1,5 @@
+# TODO
+
+- [x] Add more events supports
+- [ ] Add nested command supports
+- [ ] Simpler bash command completion support

composer.json

@@ -22,13 +22,13 @@
     }
   ],
   "require": {
-    "php": ">7.1.0",
+    "php": ">7.2.0",
     "toolkit/cli-utils": "~1.0",
     "toolkit/stdlib": "~1.0",
     "toolkit/sys-utils": "~1.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "^7.5"
+    "phpunit/phpunit": "~9.1"
   },
   "autoload": {
     "psr-4": {

examples/Controller/HomeController.php

@@ -19,6 +19,7 @@
 /**
  * default command controller. there are some command usage examples(1)
  * Class HomeController
+ *
  * @package Inhere\Console\Examples\Controller
  */
 class HomeController extends Controller
@@ -34,14 +35,15 @@ protected static function commandAliases(): array
     {
         return [
             // now, 'home:i' is equals to 'home:index'
-            'i'   => 'index',
-            'prg' => 'progress',
-            'pgb' => 'progressBar',
-            'l'   => 'list',
-            'af'  => 'artFont',
-            'ml'  => 'multiList',
-            'sl'  => 'splitLine',
-            'dt'  => 'dynamicText',
+            'i'      => 'index',
+            'prg'    => 'progress',
+            'pgb'    => 'progressBar',
+            'l'      => 'list',
+            'af'     => 'artFont',
+            'ml'     => 'multiList',
+            'sl'     => 'splitLine',
+            'dt'     => 'dynamicText',
+            'defArg' => ['da', 'defarg'],
         ];
     }
 
@@ -50,6 +52,10 @@ protected function init(): void
         parent::init();
 
         $this->addCommentsVar('internalFonts', implode(',', ArtFont::getInternalFonts()));
+
+        $this->setCommandMeta('defArg', [
+            'desc' => 'the command args and opts config use defined configure, it like symfony console, please see defArgConfigure()',
+        ]);
     }
 
     /**
@@ -75,6 +81,7 @@ protected function afterExecute(): void
     /**
      * this is a command's description message
      * the second line text
+     *
      * @usage {command} [arg ...] [--opt ...]
      * @arguments
      *  arg1        argument description 1
@@ -102,27 +109,27 @@ public function disabledCommand(): void
 
     /**
      * command `defArgCommand` config
+     *
      * @throws LogicException
      */
     protected function defArgConfigure(): void
     {
         $this->createDefinition()
-            ->setDescription('the command arg/opt config use defined configure, it like symfony console: argument define by position')
+            // ->setDescription('the command args and opts config use defined configure, it like symfony console, please see defArgConfigure()')
             ->addArgument('name', Input::ARG_REQUIRED, "description for the argument 'name'")
             ->addOption('yes', 'y', Input::OPT_BOOLEAN, "description for the option 'yes'")
             ->addOption('opt1', null, Input::OPT_REQUIRED, "description for the option 'opt1'");
     }
 
-    /**
-     * the command arg/opt config use defined configure, it like symfony console: argument define by position
-     */
+    // desc set at $this->commandMetas.
     public function defArgCommand(): void
     {
         $this->output->dump($this->input->getArgs(), $this->input->getOpts(), $this->input->getBoolOpt('y'));
     }
 
     /**
      * a command for test throw exception
+     *
      * @throws RuntimeException
      */
     public function exCommand(): void
@@ -177,6 +184,7 @@ public function colorCheckCommand(): void
 
     /**
      * output art font text
+     *
      * @options
      *  --font    Set the art font name(allow: {internalFonts}).
      *  --italic  Set the art font type is italic.
@@ -201,9 +209,10 @@ public function artFontCommand(): int
 
     /**
      * dynamic notice message show: counterTxt. It is like progress txt, but no max value.
+     *
+     * @return int
      * @example
      *  {script} {command}
-     * @return int
      */
     public function counterCommand(): int
     {
@@ -289,16 +298,19 @@ public function dynamicTextCommand(): void
 
     /**
      * a progress bar example show, by Show::progressBar()
+     *
      * @options
      *  --type      the progress type, allow: bar,txt. <cyan>txt</cyan>
      *  --done-char the done show char. <info>=</info>
      *  --wait-char the waiting show char. <info>-</info>
      *  --sign-char the sign char show. <info>></info>
+     *
+     * @param Input $input
+     *
+     * @return int
      * @example
      *  {script} {command}
      *  {script} {command} --done-char '#' --wait-char ' '
-     * @param Input $input
-     * @return int
      */
     public function progressCommand($input): int
     {
@@ -329,6 +341,7 @@ public function progressCommand($input): int
 
     /**
      * a progress bar example show, by class ProgressBar
+     *
      * @throws LogicException
      */
     public function progressBarCommand(): void
@@ -470,6 +483,7 @@ public function paddingCommand(): void
 
     /**
      * a example for use arguments on command
+     *
      * @usage home:useArg [arg1=val1 arg2=arg2] [options]
      * @example
      *  home:useArg status=2 name=john arg0 -s=test --page=23 -d -rf --debug --test=false -a v1 --ab -c -g --cd val -h '' -i stat=online
@@ -509,6 +523,7 @@ public function envCommand(): void
     /**
      * This is a demo for download a file to local
      * @usage {command} url=url saveTo=[saveAs] type=[bar|text]
+     *
      * @example {command} url=https://github.com/inhere/php-console/archive/master.zip type=bar
      */
     public function downCommand(): int