Command line parameters and environment variables/ru: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Command line parameters and environment variables/ru

New		Line
1	+	В большинстве (интерактивных) операционных систем [[Program/ru\|программы]] можно запускать через интерфейс командной строки [[Command-line interface\|command line interface]] (CLI), что позволяет предоставлять программе дополнительные данные. Модули [[System unit\|system]] (и [[Object Pascal\|objPas]]) предоставляют базовые [[Function/ru\|функции]] для доступа к данным, предоставленным из командной строки.
2	+
3	+	## Обзор
4	+
5	+	Хотя на этой странице говорится о параметрах командной строки и переменных среды, фактический интерфейс командной строки (CLI) не является обязательным требованием для использования таких данных, а также для использования процедур и терминологии, описанных здесь. Однако, поскольку интерфейс командной строки более осязаем, следующие инструкции в основном относятся к пользовательскому интерфейсу оболочки.
6	+
7	+	### Терминология
8	+
9	+	Option (переключатели)
10	+	Опции - флаги yes/no. Обычно они имеют вид `‑‑dryrun`/`‑‑no‑dryrun` (dryrun включен или отключен соответственно). Опции также называются «переключателями».
11	+
12	+	Parameter (параметр)
13	+	Параметры представляют собой кортежи ключ-значение. В командной строке они выглядят так: `‑‑processors 4`.
14	+
15	+	Argument (аргумент)
16	+	Аргументы — это простые слова. В командной строке они обычно разделяются пробелами (назначают переменную [IFS](https://en.wikipedia.org/wiki/Input_Field_Separators) в некоторых оболочках). В узком смысле, аргументы — это все предоставленные слова, которые не являются ни опциями, ни (частью) параметров. В общем, аргументы — это все слова в командной строке, которые никак не интерпретируются.
17	+
18	+	Environment variable (переменные окружения)
19	+	Переменные окружения относятся к помеченной части хранилища в среде. Это пары имя-значение.
20	+
21	+	Обратите внимание, CLI/OS предоставляет программе только те аргументы, которые она должна получить: например, экранированные символы новой строки, перенаправление файла (каналы или в файл) и присвоение переменных среды не будут перенаправлены в программу.
22	+
23	+	### Основы
24	+
25	+	Поскольку понятия «опция» и «параметры» уже являются своего рода высокоуровневыми, существуют разные стили (короткие опции против длинных опций), и модуль system стремится предоставить базовые средства для работы, все аргументы командной строки просто перечисляютсяить, начиная с нуля. Никакой интерпретации не делается.
26	+
27	+	Функция [`paramStr`](https://www.freepascal.org/docs-html/rtl/system/paramstr.html) возвращает n-й аргумент в командной строке. `ParamStr(0)` пытается вернуть имя и, возможно, полный путь к исполняемому программному файлу.
28	+
29	+	## Параметры командной строки
30	+
31	+	### Основы
32	+
33	+	Программа на Паскале может получить доступ к аргументам командной строки, используя [[Function/ru\|функцию]]`paramStr` в сочетании с [`paramCount`](https://www.freepascal.org/docs-html/rtl/system/paramcount.html). `ParamCount` возвращает количество предоставленных аргументов.
34	+
35	+	``` pascal
36	+	program listArguments(input, output, stdErr);
37	+	{$mode objFPC}
38	+	var
39	+	i: integer;
40	+	begin
41	+	writeLn({$ifDef Darwin}
42	+	// в Mac OS X возвращаемое значение зависит от метода вызова
43	+	'This program was invoked via: ',
44	+	{$else}
45	+	// Turbo Pascal-совместимый paramStr(0) возвращает местоположение
46	+	'This program is/was stored at: ',
47	+	{$endIf}
48	+	paramStr(0));
49	+
50	+	for i := 1 to paramCount() do
51	+	begin
52	+	writeLn(i:2, '. argument: ', paramStr(i));
53	+	end;
54	+	end.
55	+	```
56	+
57	+	Запуск этой программы (на не-Mac OS Ⅹ платформе) может выглядеть следующим образом:
58	+
59	+	```text
60	+	$ ./listArguments foo bar able
61	+	This program is/was stored at: /tmp/listArguments
62	+	1. argument: foo
63	+	2. argument: bar
64	+	3. argument: able
65	+	```
66	+
67	+	Модуль [[RTL]] `system` предоставляет версию `paramStr`, которая возвращает короткие строки [[Shortstring\|shortString]]. Из-за особенностей реализации `shortString` ограничены 255 символами. Однако пользователь может указать более длинные аргументы командной строки.
68	+
69	+	Чтобы получить к ним доступ, модуль [`objPas`](https://www.freepascal.org/docs-html/rtl/objpas/index.html) переопределяет `paramStr`, который вместо этого возвращает строки [[Ansistring\|ansiString]], которые не имеют этого ограничения длины. Модуль `objPas` автоматически включается в режимы компилятора [[Mode ObjFPC\|{$mode objFPC}]] (строка2) и [[Mode Delphi\|{$mode Delphi}]].
70	+
71	+	Распределенная функция `paramStr` пытается быть совместимой с [[Turbo Pascal]]. В TP `paramStr(0)` возвращает местоположение программы. Однако операционная система должна поддерживать это. В частности, в Mac OS Ⅹ значение `paramStr(0)` зависит от метода вызова, от того, как запускается приложение.
72	+
73	+	> Note: Поскольку `paramStr(0)` зависит от функциональности ОС, он не подходит для [[Multiplatform Programming Guide/ru\|кроссплатформенных программ]].
74	+
75	+	> Note: На юниксоидных платформах невозможно точно определить местоположение файла только по строке. Может быть несколько жестких ссылок, указывающих на один и тот же индексный дескриптор, файл мог быть уже удален, части пути к файлу могли измениться, помимо других деталей. По этим причинам `paramStr(0)` на юниксоидных платформах бесполезен.
76	+
77	+	Модуль [`getOpts`](https://www.freepascal.org/docs-html/rtl/getopts/index.html) предоставляет несколько других подпрограмм для вызова программы в соответствии с определенным стилем.
78	+
79	+	### Простота использования
80	+
81	+	Хорошая программа должна выдавать справочное сообщение при вызове с неправильными параметрами и должна следовать общепринятому способу предоставления параметров. Модуль [`custApp`](https://www.freepascal.org/docs-html/fcl/custapp/index.html), поставляемый с FPC, предоставляет класс [`TCustomApplication`](https://www.freepascal.org/docs-html/fcl/custapp/tcustomapplication.html), предоставляющий функции для простой проверки и чтения параметров. Конечно, вы по-прежнему можете получить доступ к параметрам напрямую через `paramStr` и `paramCount`.
82	+
83	+	Каждое приложение [[LCL]] использует это автоматически. Объект Application — это TCustomApplication.
84	+
85	+	Если вы хотите написать не LCL-программу, то создайте в [[Lazarus]] новый проект типа «Консольное приложение». Это создаст файл project1.lpr с некоторыми приятными дополнениями, которые нужны почти всем программам. Перейдите к методу `doRun`.
86	+
87	+	#### Проверка параметра
88	+
89	+	С TCustomApplication вы можете получить доступ к параметрам по имени. Например, ваша программа должна выводить текст справки, когда пользователь задает общий параметр справки -h. -h является коротким вариантом параметра. Длинная форма --help. Чтобы проверить, вызвал ли пользователь программу с помощью -h или --help, вы можете использовать следующий код:
90	+
91	+	```delphi
92	+	if hasOption('h', 'help') then
93	+	begin
94	+	writeHelp;
95	+	halt;
96	+	end;
97	+	```
98	+
99	+	> Note: В LCL-форме вы должны добавить `application.` перед `hasOption`.
100	+
101	+	Например:
102	+
103	+	```delphi
104	+	if application.hasOption('h', 'help') then
105	+	begin
106	+	writeHelp;
107	+	halt;
108	+	end;
109	+	```
110	+
111	+	Если вы хотите поддерживать только короткий вариант, используйте:
112	+
113	+	```delphi
114	+	if hasOption('h', '') then
115	+	```
116	+
117	+	Если вы хотите поддерживать только длинный вариант, используйте:
118	+
119	+	```delphi
120	+	if hasOption('help') then
121	+	```
122	+
123	+	#### Чтение значения параметра
124	+
125	+	Каждому параметру может быть присвоено значение. Например:
126	+
127	+	``` bash
128	+	$ project1 -f filename
129	+	```
130	+
131	+	или в длинной форме:
132	+
133	+	``` bash
134	+	$ project1 --file=filename
135	+	```
136	+
137	+	Чтобы получить `filename`, используйте:
138	+
139	+	```delphi
140	+	writeLn('f=', getOptionValue('f', 'file'));
141	+	```
142	+
143	+	> Note: если вы получаете сообщение об ошибке "`Option at position 1 needs an argument : f.`" (Переключатель в позиции 1 нуждается в аргументе: f), то вы забыли добавить опцию при вызове [`checkOptions`](https://www.freepascal.org/docs-html/fcl/custapp/tcustomapplication.checkoptions.html).
144	+
145	+	#### Проверка параметров на валидность
146	+
147	+	Параметры командной строки представляют собой произвольный текст, поэтому пользователь при вводе может легко допускать ошибки. Отсюда проверка синтаксиса параметров обязательна. Для этого вы можете использовать метод [[doc:fcl/custapp/tcustomapplication.checkoptions.html\|CheckOptions]].
148	+
149	+	Вы можете определить, какие параметры разрешены, какие из них нуждаются в параметре, а в случае синтаксической ошибки вы можете получить сообщение об ошибке, а также неправильные параметры для печати полезных и подробных ошибок.
150	+
151	+	Пример:
152	+
153	+	```delphi
154	+	errorMsg := checkOptions('hf:', 'help file:');
155	+	```
156	+
157	+	Это позволяет передавать короткие переключатели: `‑f value` и `‑h`.\
158	+	Это - передавать длинные переключатели: `‑‑help` или `‑‑file=filename`.\
159	+	А это не позволяет передачу параметра `‑‑help` со значением или `‑‑file` без значения.\
160	+	Пример передачи параметра:
161	+
162	+	``` pascal
163	+	procedure TMainForm.FormShow(Sender: TObject);
164	+	var
165	+	I: Integer;
166	+	Params : TStringList
167	+	LongOpts : array [1..2] of string = ('debug-sync', 'config-dir:');
168	+	begin
169	+	Params := TStringList.Create;
170	+	try
171	+	Application.GetNonOptions('hgo:', LongOpts, Params);
172	+	for I := 0 to Params.Count -1 do
173	+	debugln('Extra Param ' + inttostr(I) + ' is ' + Params[I]); }
174	+	finally
175	+	FreeAndNil(Params);
176	+	end;
177	+	end;
178	+	```
179	+
180	+	Этот пример находит параметры и не смешивает их с переключателями или параметрами командной строки. В этом примере приложение также принимает параметры --debug-sync и --config-dir=somedir, но здесь они не указаны.
181	+
182	+	Обратите внимание, что Application.GetNonOptions() принимает длинные параметры в виде массива, а Application.CheckOptions принимает те же данные, но в виде строки. Немного грустно!
183	+
184	+	## Переменные окружения
185	+
186	+	Модуль [[sysutils\|sysUtils]] определяет три основные функции для получения переменных среды.
187	+
188	+	- [`getEnvironmentVariableCount`](https://www.freepascal.org/docs-html/rtl/sysutils/getenvironmentvariablecount.html) возвращает общее количество переменных среды.
189	+	- [`getEnvironmentString`](https://www.freepascal.org/docs-html/rtl/sysutils/getenvironmentstring.html) возвращает переменную среды по ее индексу
190	+	- [`getEnvironmentVariable`](https://www.freepascal.org/docs-html/rtl/sysutils/getenvironmentvariable.html) возвращает переменную среды по ее ключу
191	+
192	+	Пример:
193	+
194	+	``` pascal
195	+	program environmentVariablesList(input, output, stdErr);
196	+	uses
197	+	sysUtils;
198	+	var
199	+	i: integer;
200	+	begin
201	+	for i := 0 to getEnvironmentVariableCount() - 1 do
202	+	begin
203	+	writeLn(getEnvironmentString(i));
204	+	end;
205	+	end.
206	+	```
207	+
208	+	Также можно загрузить все переменные среды в объект [`TStringList`](https://www.freepascal.org/docs-html/rtl/classes/tstringlist.html) и легко получить доступ к паре имя-значение. Списки строк автоматически учитывают символ-разделитель, который по умолчанию является знаком равенства [[=\|('=')]].
209	+
210	+	```delphi
211	+	program environmentVariablesSorted(input, output, stdErr);
212	+	{$mode objFPC}
213	+	uses
214	+	classes, sysUtils;
215	+	var
216	+	i: integer;
217	+	environmentVariables: tStringList;
218	+	begin
219	+	environmentVariables := tStringList.create();
220	+
221	+	try
222	+	// загружаем все переменные в список строк
223	+	for i := 0 to getEnvironmentVariableCount() - 1 do
224	+	begin
225	+	environmentVariables.append(getEnvironmentString(i));
226	+	end;
227	+
228	+	environmentVariables.sort;
229	+	for i := 0 to environmentVariables.count - 1 do
230	+	begin
231	+	writeLn(environmentVariables.names[i]:20,
232	+	' = ',
233	+	environmentVariables.valueFromIndex[i]);
234	+	end;
235	+	finally
236	+	environmentVariables.free;
237	+	end;
238	+	end.
239	+	```
240	+
241	+	Существует также [[Method\|метод]] `TCustomApplication` для одновременного получения всех переменных среды в виде [[TStringList]]. Тогда схема может выглядеть так:
242	+
243	+	```delphi
244	+	var
245	+	environmentVariables: tStringList;
246	+	begin
247	+	environmentVariables := tStringList.create();
248	+	try
249	+	application.getEnvironmentList(environmentVariables);
250	+	…
251	+	finally
252	+	environmentVariables.free;
253	+	end;
254	+	end;
255	+	```
256	+
257	+	---
258	+	From the Free Pascal wiki, page "Command line parameters and environment variables/ru", as it stood on 2022-05-28 after a change by FTurtle, out of the wiki's dump of 2024-05-26. 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).
259	+	Category: Code/ru

Back to history