命令行参数设计

1. 目的

众多通用的小功能，制作为一个小工具，然后通过命令行来进行交互，使用非常的简便。本规范是为了统一命令行参数的设计，使得大家在制作或使用命令行工具时，能够更加有共享，进行会更加方便。

2. 适用范围

所有命令行工具参数的设计。

3. 基本原则

• 普适性，不同的操作系统，不同的编程语言，不同规模的工具都适用。

• 最大共识，设计原则采用业界最流行的方式。

• 实用性，不死板追求形式，追求实际使用的方便。

4. 基本规则

4.1. 语法规则

• <>表示必选参数

• []表示可选参数。

• -表示短参数标识

• –表示长参数标识

• |表示或

4.2. 风格规则

1. 默认在未输入命令行参数时，显示工具的基本用法。

第一行显示工具名及版本号，并一句话概括其主要用途。

第二行介绍其用法的语法形式，参见4.1.的语法规则。

第三行"Options"项。

第四行介绍具体选项的作用。

第五行”Example”选项。

第六行举例用法，至少1个示例用法。

第七行，退出码，根据实际情况描述。

如果有其他注意项，可以在后面补充。

描述默认统一使用英文，特殊情况可以使用中文。

YSTime V1.1.3，obtain the current timestamp.
Usage：YSTime <-b|a> 
Options:
  -b|t   -b indicates beijing time zone,-t indicates tokyo time zone.
  -h     Display help information.
Example:
  YSTime -t 1
Exit Code，0 for success, other values for failure.

2. 命令行参数较少时，使用短参数方式。

'-'指示短参数，如果短参数后有值，以空格分隔。

    YSCopy V1.0.1, copy folder and files to destination.
    Usage：YSCopy [option] <-s src> <-d dst>
    Options:
      -r        Recursively operate on subdirectories.
      -s src    src is a source path.
      -d dst    dst is a destination path.
      -h        Display help information.
    Example:
       YSCopy -s e:\work -d f:\mywork
       YSCopy -r -s e:\work -d f:\mywork
    Exit Code，0 for success, other values for failure.
    If path contains spaces, please add double quotes.

3. 命令行参数较多时，使用长参数方式。

"–"表示长参数。命令行参数比较多时，短参数可能不够用，因此需要长参数。长参数后的值以=分隔。

    YSB2E V2.0.1, convert bat to exe.
    Usage: YSB2E [option] <--input=bat_path> <--output=exe_path>
    Options:
       --encrypt         Convert with encrpt.
       --password=pw     pw indicates the password for open.Password enclosed in double quotes.
       --input=bat_path  bat_path indicates the bat path input.
       --output=exe_path exe_path indicates the exe path for output.
        --help           Display help information.
    Example:
       YSB2E --password="123" --imput=e:\make.bat --output="e:\mike home\work\make.exe"
    Exit Code，0 for success, other values for failure.
    If path contains spaces, please add double quotes.

4. 混合

短参数更方便，但是短参数确实不够用，全改用长参数又有点麻烦，此时可以两种混用。一般情况建议统一风格，更容易理解。

    YSCopy V1.0.1, copy folder and files to destination.
    Usage：YSCopy [option] <-s src> <-d dst> [--password=pw]
    Options:
      -r             Recursively operate on subdirectories.
      -s src         src is a source path.
      -d dst         dst is a destination path.
      --password=pw  pw is the password for encrypt.
      -h             Display help information.
    Example:
       YSCopy -s e:\work -d f:\mywork
       YSCopy -r -s e:\work -d f:\mywork --password=123456
    Exit Code，0 for success, other values for failure.
    If path contains spaces, please add double quotes.

5. 大型命令行工具

一些大型的，功能非常多的命令行功能，例如Python中的pip包管理工具。其在长参数之前，还添加一层命令行，每个命令项下有单独的命令行参数。

    YSTool V2.0.2, Common Utilities.
    Usage: YSTool command [option] [arg]
    Commands:
      clean      clean the buffer.
      verify     verify the result.
      update     update the argument.
    Options:
      --where    Output project home information.
      --venv     Output virtualenv information.
      -h --help  Display help information
    Example:
       YSTool clean
       YSTool verify --where=c:\dir
    Exit Code，0 for success, other values for failure.
    If path contains spaces, please add double quotes.

6. 其他

有些时间，命令行参数很少，可能就不需要短参数标识了。

    YSMD5 V1.0.1, obtain the MD5 value of a specified file.
    Usage: YSMD5 <file_name>
    Options:
      file_name is the specified file path. MD5 value will be displayed on the terminal. 
    Exit Code，0 for success, other values for failure.
    If path contains spaces, please add double quotes.
    ```