update: update flags help render logic. update readme

Author: inhere

README.md

@@ -16,84 +16,136 @@ Generic PHP command line flags parse library
 composer require toolkit/pflag
 ```
 
-## Flags
+## Flags Usage
 
 Flags - is an cli flags(options&argument) parser and manager.
 
-### Parse CLI Input
+> example codes please see [example/flags-demo.php](example/flags-demo.php)
 
-write the codes to an php file(see [example/flags-demo.php](example/flags-demo.php))
+### Create Flags
 
 ```php
 use Toolkit\PFlag\Flags;
-use Toolkit\PFlag\FlagType;
 
-// run demo:
-// php example/sflags-demo.php --name inhere --age 99 --tag go -t php -t java -f arg0 arr0 arr1
-$flags = $_SERVER['argv'];
-// NOTICE: must shift first element.
-$scriptFile = array_shift($flags);
+require dirname(__DIR__) . '/test/bootstrap.php';
 
 $fs = Flags::new();
+// with some config
 $fs->setScriptFile($scriptFile);
+/** @see Flags::$settings */
+$fs->setSettings([
+    'descNlOnOptLen' => 26
+]);
+```
+
+### Define options
+
+```php
+use Toolkit\PFlag\Flag\Option;
+use Toolkit\PFlag\FlagType;
+use Toolkit\PFlag\Validator\EnumValidator;
 
 // add options
+// - quick add
 $fs->addOpt('age', 'a', 'this is a int option', FlagType::INT);
+
+// - use string rule
 $fs->addOptByRule('name,n', 'string;true;;this is a string option');
+// -- add multi option at once.
 $fs->addOptsByRules([
     'tag,t' => 'strings;no;;array option, allow set multi times',
     'f'     => 'bool;no;;this is an bool option',
 ]);
+// - use array rule
+/** @see Flags::DEFINE_ITEM for array rule */
+$fs->addOptByRule('name-is-very-lang', [
+    'type'   => FlagType::STRING,
+    'desc'   => 'option name is to lang, desc will print on newline',
+    'shorts' => ['d','e','f'],
+    // TIP: add validator limit input value.
+    'validator' => EnumValidator::new(['one', 'two', 'three']),
+]);
+
+// - use Option
+$opt = Option::new('str1', "this is  string option, \ndesc has multi line, \nhaha...");
+$opt->setDefault('defVal');
+$fs->addOption($opt);
+```
+
+### Define Arguments
+
+```php
+use Toolkit\PFlag\Flag\Argument;
+use Toolkit\PFlag\FlagType;
 
 // add arguments
-$fs->addArg('strArg', 'the first arg, is string', 'string', true);
-$fs->addArg('arrArg', 'the second arg, is array', 'strings');
+// - quick add
+$fs->addArg('strArg1', 'the is string arg and is required', 'string', true);
+// - use string rule
+$fs->addArgByRule('intArg2', 'int;no;89;this is a int arg and with default value');
+// - use Argument object
+$arg = Argument::new('arrArg');
+// OR $arg->setType(FlagType::ARRAY);
+$arg->setType(FlagType::STRINGS);
+$arg->setDesc("this is an array arg,\n allow multi value,\n must define at last");
+$fs->addArgument($arg);
+```
+
+### Parse Input
+
+```php
+use Toolkit\PFlag\Flags;
+use Toolkit\PFlag\FlagType;
 
-// call parse
 if (!$fs->parse($flags)) {
+    // on render help
     return;
 }
 
-vdump(
-    $fs->getOpts(),
-    $fs->getArgs()
-);
+vdump($fs->getOpts(), $fs->getArgs());
 ```
 
+**Show help**
+
+```bash
+$ php example/flags-demo.php --help
+```
+
+Output:
+
+![flags-demo](example/images/flags-demo.png)
+
 **Run demo:**
 
 ```bash
-php example/sflags-demo.php --name inhere --age 99 --tag go -t php -t java -f arg0 arr0 arr1
+$ php example/flags-demo.php --name inhere --age 99 --tag go -t php -t java -d one -f arg0 80 arr0 arr1
 ```
 
 Output:
 
 ```text
-array(4) {
+array(6) {
+  ["str1"]=> string(6) "defVal"
   ["name"]=> string(6) "inhere"
   ["age"]=> int(99)
   ["tag"]=> array(3) {
     [0]=> string(2) "go"
     [1]=> string(3) "php"
     [2]=> string(4) "java"
   }
+  ["name-is-very-lang"]=> string(3) "one"
   ["f"]=> bool(true)
 }
-array(2) {
+array(3) {
   [0]=> string(4) "arg0"
-  [1]=> array(2) {
+  [1]=> int(80)
+  [2]=> array(2) {
     [0]=> string(4) "arr0"
     [1]=> string(4) "arr1"
   }
 }
 ```
 
-**Show help**
-
-```bash
-$ php example/flags-demo.php --help
-```
-
 ## SFlags
 
 SFlags - is an simple flags(options&argument) parser and manager.
@@ -263,7 +315,7 @@ $rules = [
 
 **For options**
 
-- option allow set alias/shorts
+- option allow set shorts
 
 > TIP: name `long,s` - first is the option name. remaining is short names.
 
@@ -274,21 +326,22 @@ $rules = [
 
 **Definition item**
 
-The const `SFlags::DEFINE_ITEM`:
+The const `Flags::DEFINE_ITEM`:
 
 ```php
-    public const DEFINE_ITEM = [
-        'name'      => '',
-        'desc'      => '',
-        'type'      => FlagType::STRING,
-        // 'index'    => 0, // only for argument
-        'required'  => false,
-        'default'   => null,
-        'shorts'    => [], // only for option
-        // value validator
-        'validator' => null,
-        // 'category' => null
-    ];
+public const DEFINE_ITEM = [
+    'name'      => '',
+    'desc'      => '',
+    'type'      => FlagType::STRING,
+    'showType'  => '', // use for show help
+    // 'index'    => 0, // only for argument
+    'required'  => false,
+    'default'   => null,
+    'shorts'    => [], // only for option
+    // value validator
+    'validator' => null,
+    // 'category' => null
+];
 ```
 
 ## Unit tests

example/flag-demo.php

@@ -0,0 +1,77 @@
+<?php declare(strict_types=1);
+
+/**
+ * This file is part of toolkit/pflag.
+ *
+ * @link     https://github.com/php-toolkit
+ * @author   https://github.com/inhere
+ * @license  MIT
+ */
+
+use Toolkit\PFlag\Flag\Argument;
+use Toolkit\PFlag\Flag\Option;
+use Toolkit\PFlag\Flags;
+use Toolkit\PFlag\FlagType;
+use Toolkit\PFlag\Validator\EnumValidator;
+
+require dirname(__DIR__) . '/test/bootstrap.php';
+
+// run demo:
+// php example/flag-demo.php -h
+// php example/sflags-demo.php --name inhere --age 99 --tag go -t php -t java -f arg0 arr0 arr1
+$flags = $_SERVER['argv'];
+// NOTICE: must shift first element.
+$scriptFile = array_shift($flags);
+
+$fs = Flags::new();
+$fs->setScriptFile($scriptFile);
+/** @see Flags::$settings */
+$fs->setSettings([
+    'descNlOnOptLen' => 26
+]);
+
+// add options
+// - quick add
+$fs->addOpt('age', 'a', 'this is a int option', FlagType::INT);
+
+// - use string rule
+$fs->addOptByRule('name,n', 'string;true;;this is a string option');
+// -- add multi option at once.
+$fs->addOptsByRules([
+    'tag,t' => 'strings;no;;array option, allow set multi times',
+    'f'     => 'bool;no;;this is an bool option',
+]);
+// - use array rule
+/** @see Flags::DEFINE_ITEM for array rule */
+$fs->addOptByRule('name-is-very-lang', [
+    'type'   => FlagType::STRING,
+    'desc'   => 'option name is to lang, desc will print on newline',
+    'shorts' => ['d','e'],
+    // TIP: add validator limit input value.
+    'validator' => EnumValidator::new(['one', 'two', 'three']),
+]);
+
+// - use Option
+$opt = Option::new('str1', "this is string option, \ndesc has multi line, \nhaha...");
+$opt->setDefault('defVal');
+$fs->addOption($opt);
+
+// add arguments
+// - quick add
+$fs->addArg('strArg1', 'the is string arg and is required', 'string', true);
+// - use string rule
+$fs->addArgByRule('intArg2', 'int;no;89;this is a int arg and with default value');
+// - use Argument object
+$arg = Argument::new('arrArg');
+// OR $arg->setType(FlagType::ARRAY);
+$arg->setType(FlagType::STRINGS);
+$arg->setDesc("this is an array arg,\n allow multi value,\n must define at last");
+$fs->addArgument($arg);
+
+// edump($fs);
+if (!$fs->parse($flags)) {
+    // on render help
+    return;
+}
+
+vdump($fs->getOpts(), $fs->getArgs());