Command line parameters and environment variables/zh CN: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		在大多数（交互式）操作系统中，可以通过[[Command-line interface\|命令行界面]]（CLI）启动[[Program\|程序]]，并允许向程序提供附带的数据。[[System unit\|system]]单元（以及[[Object Pascal\|`objPas`]]）单元提供了一些基本的[[Function\|函数]]，用于访问这些通过命令行给出的数据。
2	2
3		-	~~## Contents~~
4		-
5		-	* 1 概述
6		-	* 1.1 术语
7		-	* 1.2 底层函数
8		-	* 2 命令行参数
9		-	* 2.1 基本用法
10		-	* 2.2 用户友好性
11		-	* 2.2.1 检测某个参数
12		-	* 2.2.2 读取参数值
13		-	* 2.2.3 校验参数
14		-	* 3 环境变量
15		-
16	3		## 概述
17	4
18	5		尽管这里介绍的是“命令行”参数和环境变量，但使用传给程序的数据，以及这里提及的例程和术语，都不需要实际用到命令行界面（CLI）。只是命令行界面更为直观，因此以下内容主要考虑 shell 用户的体验。
19	6
20	7		### 术语
21	8
22		-	~~选项（Option）~~
23		-	~~选项就是“是/否”。通常假定为如下形式~~
	9	+	选项（Option）
24	10
	11	+	选项就是“是/否”。通常假定为如下形式
	12	+
25	13		`‑‑dryrun`/`‑‑no‑dryrun` （分别为启用和禁用 dryrun 选项）。选项也被称为“开关”。
26	14
27		-	~~参数（Parameter）~~
28		-	~~参数是键值元组。在命令行中的形式如下：~~
	15	+	参数（Parameter）
29	16
	17	+	参数是键值元组。在命令行中的形式如下：
	18	+
30	19		`‑‑processors 4`。
31	20
32		-	~~实参（Argument）~~
33		-	实参就是一些简单的单词。在命令行中通常以空格分隔（某些 shell 中可由 IFS 变量定义）。从狭义上讲， _实参_ 指既非选项也不属于参数的所有单词。而从广义上讲，实参是指命令行中未以任何方式解释的所有单词。
	21	+	实参（Argument）
34	22
35		-	~~环境变量（Environment variable）~~
36		-	~~环境变量是指运行环境中打了标签的一块存储空间，都是“名称/值”对。~~
	23	+	实参就是一些简单的单词。在命令行中通常以空格分隔（某些 shell 中可由 IFS 变量定义）。从狭义上讲， _实参_ 指既非选项也不属于参数的所有单词。而从广义上讲，实参是指命令行中未以任何方式解释的所有单词。
	24	+
	25	+	环境变量（Environment variable）
	26	+
	27	+	环境变量是指运行环境中打了标签的一块存储空间，都是“名称/值”对。
37	28
38	29		请注意，命令行界面操作系统向程序传递的参数会先进行处理：比如转义后的换行符、文件重定向（管道或重定向文件）、对环境变量的赋值，都不会传给程序。
39	30
40	31		### 底层函数
41	32
42	33		“选项”和“参数”的概念抽象程度已经较高，且存在不同的风格（如短选项和长选项），而 system 单元的目标是提供较为 _底层_ 的工作方式，因此只把全部命令行参数视为从零开始的枚举类型，未做任何解释处理。
43	34
44	35		函数 [`paramStr`](<https://www.freepascal.org/docs-html/rtl/system/paramstr.html>) 用于返回第 n 个命令行参数。 `ParamStr(0)` 尝试返回可执行程序文件名，以及完整路径。
45	36
46	37		## 命令行参数
47	38
48	39		### 基本用法
49	40
50	41		Pascal 程序可以将 `paramStr` [[Function\|函数]] 和 [`paramCount`](<https://www.freepascal.org/docs-html/rtl/system/paramcount.html>) 结合起来，以便访问命令行参数。
51	42
52	43		`ParamCount` 将返回给出的参数个数。
53	44		```
54	45		program listArguments(input, output, stdErr);
55	46		{$mode objFPC}
56	47		var
57	48		i: integer;
58	49		begin
59	50		writeLn({$ifDef Darwin}
60	51		// Mac OS X 中的返回值依赖于调用方法
61	52		'This program was invoked via: ',
62	53		{$else}
63	54		// 兼容 Turbo Pascal 的 paramStr(0) 返回程序所在位置
64	55		'This program is/was stored at: ',
65	56		{$endIf}
66	57		paramStr(0));
67	58
68	59		for i := 1 to paramCount() do
69	60		begin
70	61		writeLn(i:2, '. argument: ', paramStr(i));
71	62		end;
72	63		end.
73	64		```
74	65
75	66		在非 Mac OS X 系统中，上述程序的运行结果可能如下：
76	67		```
77	68		$ ./listArguments foo bar able
78	69		This program is/was stored at: /tmp/listArguments
79	70		1. argument: foo
80	71		2. argument: bar
81	72		3. argument: able
82	73		```
83	74
84	75		RTL 的 system 单元提供了一个 `paramStr`，返回的是[[Shortstring\|`shortString`]] 类型的字符串。`shortString` 类型的实现方式限制了其长度在255个字符以内。但是用户可能会给出长度超限的命令行参数。为了访问全部命令行参数，[`objPas` 单元](<https://www.freepascal.org/docs-html/rtl/objpas/index.html>) 重新定义了 `paramStr`，返回类型换成了 [[Ansistring\|`ansiString`]]，这样长度就不受限了。在 [[Mode ObjFPC\|`{$mode objFPC}`]]（第2行）和 [[Mode Delphi\|`{$mode Delphi}`]] 编译模式下，会自动包含 `objPas` 单元。
85	76
86	77		提供 `paramStr` 函数是为了与 Turbo Pascal 保持兼容。在 Turbo Pascal 中，`paramStr(0)` 返回程序的所在位置。但这需要操作系统的支持。尤其值得注意的是，在 Mac OS X 系统中，`paramStr(0)` 的返回值取决于调用方法，即应用程序的启动方式。
87	78
88	79		![Light bulb](https://upload.wikimedia.org/wikipedia/commons/d/d8/Nuvola_apps_ktip.png) Note: 由于 `paramStr(0)` 依赖于操作系统的支持，所以并不适用于 [[Multiplatform Programming Guide\|跨平台应用]]。
89	80
90	81		![Light bulb](https://upload.wikimedia.org/wikipedia/commons/d/d8/Nuvola_apps_ktip.png) Note: 在类 Unix 系统中，只用字符串不可能确定文件的位置。可能有多个硬链接指向同一个i节点，文件可能已删除，文件路径可能已有部分改动，以及其他细节问题。
91	82
92	83		因此，在类 Unix 系统中 `paramStr(0)` 无效。
93	84
94	85		[`getOpts` 单元](<https://www.freepascal.org/docs-html/rtl/getopts/index.html>)提供了其他一些函数，在以特定格式调用程序时可用于解析命令行参数。
95	86
96	87		### 用户友好性
97	88
98	89		设计良好的程序在收到错误参数时应能给出帮助信息，并且应该遵循一种通用的参数传递方式。 FPC 的 [unit `custApp`](<https://www.freepascal.org/docs-html/fcl/custapp/index.html>) 单元提供了一个 [`TCustomApplication`](<https://www.freepascal.org/docs-html/fcl/custapp/tcustomapplication.html>) 类，可用于轻松检查和读取命令行参数。当然，用 `paramStr` 和 `paramCount` 直接访问也没问题。
99	90
100	91		[[LCL]] 应用程序都会自动使用 TCustomApplication。Application 对象就是 TCustomApplication 的实例。
101	92
102	93		若要编写非 LCL 程序，那么先在 [[Lazarus]] 中新建“控制台应用程序”类型的项目。这会创建一个包含某些实用功能的 project1.lpr，这些功能几乎所有程序都需要用到。接下来，请定位到 `doRun` 方法。
103	94
104	95		#### 检测某个参数
105	96
106	97		TCustomApplication 可以通过名称访问命令行参数。比如用户给出通用的求助参数 _-h_ 时，程序应该打印出一条帮助文字。 _-h_ 是个短选项。长选项则为 _\--help_ 。若要测试用户在调用程序时是否带有 _-h_ 或 _\--help_ 参数，可以使用如下代码：
107	98		```
108	99		if hasOption('h', 'help') then
109	100		begin
110	101		writeHelp;
111	102		halt;
112	103		end;
113	104		```
114	105
115	106		![Light bulb](https://upload.wikimedia.org/wikipedia/commons/d/d8/Nuvola_apps_ktip.png) Note: 在 LCL 窗体中，必须在 `hasOption` 前面加上 `application.`。
116	107
117	108		例如：
118	109		```
119	110		if application.hasOption('h', 'help') then
120	111		begin
121	112		writeHelp;
122	113		halt;
123	114		end;
124	115		```
125	116
126	117		如果只支持短选项，请用以下代码：
127	118		```
128	119		if hasOption('h', '') then
129	120		```
130	121
131	122		若只支持长选项，则用：
132	123		```
133	124		if hasOption('help') then
134	125		```
135	126
136	127		#### 读取参数值
137	128
138	129		每个命令行参数可以给定一个值。例如：
139	130		```
140	131		$ project1 -f filename
141	132		```
142	133
143	134		或者长格式：
144	135		```
145	136		$ project1 --file=filename
146	137		```
147	138
148	139		读取 `filename` ：
149	140		```
150	141		writeLn('f=', getOptionValue('f', 'file'));
151	142		```
152	143
153	144		注意：如果报错“`Option at position 1 needs an argument : f.`”，则是在调用
154	145		```
155	146		[checkOptions](<https://www.freepascal.org/docs-html/fcl/custapp/tcustomapplication.checkoptions.html>) 时忘记加入该选项了。
156	147		```
157	148
158	149		#### 校验参数
159	150
160	151		命令行参数就是一条内容随意的文本，因此用户输入很容易出错。因此，必须对命令行参数作语法检查。用 [CheckOptions](<http://lazarus-ccr.sourceforge.net/docs/fcl/custapp/tcustomapplication.checkoptions.html> "doc:fcl/custapp/tcustomapplication.checkoptions.html") 方法即可完成检查。
161	152
162	153		可定义允许哪些参数及哪些参数需要有值，在发生语法错误时可获取错误消息和出错的选项，以便打印出帮助信息和错误细节。
163	154
164	155		示例：
165	156		```
166	157		errorMsg := checkOptions('hf:', 'help file:');
167	158		```
168	159
169	160		上述代码允许传递短选项 `‑f value` 和 `‑h`，还允许 `‑‑help` 或 `‑‑file=filename`。但不允许 `‑‑help` 带有值，也不允许 `‑‑file` 没有值。
170	161
171	162		参数示例：
172	163		```
173	164		procedure TMainForm.FormShow(Sender: TObject);
174	165		var
175	166		I: Integer;
176	167		Params : TStringList
177	168		LongOpts : array [1..2] of string = ('debug-sync', 'config-dir:');
178	169		begin
179	170		Params := TStringList.Create;
180	171		try
181	172		Application.GetNonOptions('hgo:', LongOpts, Params);
182	173		for I := 0 to Params.Count -1 do
183	174		debugln('Extra Param ' + inttostr(I) + ' is ' + Params[I]); }
184	175		finally
185	176		FreeAndNil(Params);
186	177		end;
187	178		end;
188	179		```
189	180
190	181		以上例程会查找参数，且不会和命令行开关或选项混淆。应用程序还接受 --debug-sync 和 --config-dir=somedir 开关，只是没有打印出来。
191	182
192	183		请注意，Application.GetNonOptions() 方法以数组类型的长选项为参数，而 Application.CheckOptions 方法的参数数据相同却只认字符串。有点遗憾！
193	184
194	185		## 环境变量
195	186
196	187		[[sysutils\|`sysUtils`]] 单元定义了3个读取环境变量的基本函数。
197	188
198	189		* [`getEnvironmentVariableCount`](<https://www.freepascal.org/docs-html/rtl/sysutils/getenvironmentvariablecount.html>) 返回全部环境变量的数量。
199	190		* [`getEnvironmentString`](<https://www.freepascal.org/docs-html/rtl/sysutils/getenvironmentstring.html>) 按索引编号返回某个环境变量。
200	191		* [`getEnvironmentVariable`](<https://www.freepascal.org/docs-html/rtl/sysutils/getenvironmentvariable.html>) 按键值返回某个环境变量。
201	192
202	193		示例：
203	194		```
204	195		program environmentVariablesList(input, output, stdErr);
205	196		uses
206	197		sysUtils;
207	198		var
208	199		i: integer;
209	200		begin
210	201		for i := 0 to getEnvironmentVariableCount() - 1 do
211	202		begin
212	203		writeLn(getEnvironmentString(i));
213	204		end;
214	205		end.
215	206		```
216	207
217	208		另外还有一种可能的方式，就是将所有环境变量载入 [`tStringList`](<https://www.freepascal.org/docs-html/rtl/classes/tstringlist.html>)对象，以便访问键值对。字符串列表会自动处理分隔符，默认为[[=\|等号 (`'='`)]]。
218	209		```
219	210		program environmentVariablesSorted(input, output, stdErr);
220	211		{$mode objFPC}
221	212		uses
222	213		classes, sysUtils;
223	214		var
224	215		i: integer;
225	216		environmentVariables: tStringList;
226	217		begin
227	218		environmentVariables := tStringList.create();
228	219
229	220		try
230	221		// load all variables to string list
231	222		for i := 0 to getEnvironmentVariableCount() - 1 do
232	223		begin
233	224		environmentVariables.append(getEnvironmentString(i));
234	225		end;
235	226
236	227		environmentVariables.sort;
237	228		for i := 0 to environmentVariables.count - 1 do
238	229		begin
239	230		writeLn(environmentVariables.names[i]:20,
240	231		' = ',
241	232		environmentVariables.valueFromIndex[i]);
242	233		end;
243	234		finally
244	235		environmentVariables.free;
245	236		end;
246	237		end.
247	238		```
248	239
249	240		还可以采用 `tCustomApplication` 的 [[Method\|方法]]，可一次性将全部环境变量读取为一个[[TStringList\|`tStringList`]]。大致如下所示：
250	241		```
251	242		var
252	243		environmentVariables: tStringList;
253	244		begin
254	245		environmentVariables := tStringList.create();
255	246		try
256	247		application.getEnvironmentList(environmentVariables);
257	248		…
258	249		finally
259	250		environmentVariables.free;
260	251		end;
261	252		end;
262	253		```
263	254		*[IFS]: internal field separator
264	255
265	256		---
266	257		From the Free Pascal wiki, page "Command line parameters and environment variables/zh CN", as the Internet Archive kept it on 2025-01-13, last changed on 2024-12-09. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history