如何看懂命令/函数描述

如何看懂命令/函数描述 --命令/函数描述规则

1.前言

在学习新的编程语言的时候,往往需要了解新的函数.在看官方给定描述函数的文档时,通常都是这样的:

在网上查看其用法的时候,往往看到的是例子和文字性的讲解,对于用法描述的不是很全面.
所以这就要求我们有自己看懂函数描述的能力
对于这部分的内容,网上的资料很少.以下的内容来自一个英文网页,我简要的翻译一下

2.基本规则

基本规则由一个 Command Syntax Reference Table描述

记号	意义
BOLD(黑体字)	黑体字的内容必须一字不差的输入
ltalic(斜体)	斜体字的内同需要自己提供(参数),但是输入的时候不要输入斜体!
空格	空格也必须被严格的输入
[中括号内的文字]	中括号内的文字代表其是可选的,如果不选,不要输入中括号
括号外的文字	括号外的文字时必不可少的,在很多命令中,唯一在括号外的文字就时命令名称自己
{大括号内的文字}	大括号内的文字也是可选的,但只能选择一个
|竖线	竖线用于区分括号里的不同元素
…省略号	省略号代表其前面的内容可以无限次的重复

2021.6.10补充:双减号(dash)和单减号的区别

这里的dash就是键盘上的 - 字符,在命令的选项里经常有这个.
这里讨论 - 和 -- 的区别

A single hyphen can be followed by multiple single-character flags. A
double hyphen prefixes a single, multicharacter option.

意思就是单个 - 后面接的是命令的首字母, --后是命令的完整字符
比如说 ls -a 和 ls --all 是一样的

除此之外, - 符号还可以用于命令的拼接
也就是说 command -abcd 等于 command -a -b -c -d
举个例子 ls --all 和 ls -all
第一个命令,就是 ls 加上 all 选项,它等同于 ls -a

列出来是这样的
第二个命令和第一个完全不一样,它等同于 ls -a -l -l

列出来是这样的,等同于 ls -a -l -l (两个-l估计只识别一个)

3.实例

Vol Command

(vol 是什么…赶紧查一下)
vol命令:显示出当前或者指定磁盘的卷标及序列号.

其形式为 vol [drive/:]

1.vol是黑体字,所以必须严格的准确输入
2.vol后面有一个空格,这个空格也是必须的
3.中括号意味着其是可选的,如果想让命令完成预期的功能,就要为其赋值
4.这个:(冒号)也是黑体的,所以这个冒号也是要输入的!!
以下展示几种情况:
1.合法情况1

2.不合法情况1(没有冒号:)

3.合法情况2

Shutdown Command

命令描述 :
shutdown [/i | /l | /s | /r | /g | /a | /p | /h | /e] [/f] [/m \computername] [/t xxx] [/d [p:|u:]xx:yy] [/c “comment”]
这是一个很复杂的命令,但基本的原理还是一样的
1./i, /l, /s, /r, /g, /a, /p, /h, or /e.这几个都是可选的,注意到这写都是黑体字,所以必须严格输入(包括这个斜杠/)
2. [/d [p:|u:] xx:yy],这代表可选中的可选

以下展示几种情况
1.不合法情况(/r 和 /s不可以同时用)

2.不合法情况2

解释:p:0:0仅在/d选项可用时可用
3.合法情况

Net Use Command

由于这个命令过于复杂,所以只截取一部分
net use [{devicename | *}] [\\computername\sharename [{password | *}]] [/persistent:{yes | no}] [/savecred] [/delete]
更急上述的规则,只看几种情况就行
1.不合法情况1

解释:[{devicename | *}] 意味着这两个只能选一个,e:和*冲突

2.不合法情况2

解释:这里我们选用了/persistent选项,但是没有从大阔号里选择yes/no

4.实践

学习完之后,可以分析一个正在学习的语法(psql)

有些时候是没有分黑体和斜体的,不过也不太影响
这里写的很清晰了,只要中括号括起来的都是可选的选项
但是看命令的时候最好还是去官方文档哪里看,网上的命令有些时候会 不全 甚至 有错误

5.结语

如果能看网上的描述和例子学会一条命令可以称之为 知其然 的话,
那么也许看懂命令描述形式才能称之为知其 所以然.
我认为,计算机的一大重要特点在于 规范化 和 无歧义 ,命令的语法也因该如此,想要系统的了解命令语法的构成和形式,明白 描述命令的语法 是至关重要的.

鉴于作者水平有限,如有错误,欢迎指出