Difference between revisions of "Command line parameters and environment variables/ru"

From Lazarus wiki
Jump to navigationJump to search
(Category Code->Code/ru)
 
(4 intermediate revisions by one other user not shown)
Line 119: Line 119:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==== Read the parameter value ====
+
==== Чтение значения параметра ====
  
Each parameter can be given a value.
+
Каждому параметру может быть присвоено значение.
For example:
+
Например:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 128: Line 128:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
or in the long form:
+
или в длинной форме:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 134: Line 134:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
In order to retrieve <syntaxhighlight lang="bash" inline>filename</syntaxhighlight> use:
+
Чтобы получить <syntaxhighlight lang="bash" inline>filename</syntaxhighlight>, используйте:
  
 
<syntaxhighlight lang="delphi">
 
<syntaxhighlight lang="delphi">
Line 140: Line 140:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Note: if you get the error message “<syntaxhighlight lang="text" inline>Option at position 1 needs an argument : f.</syntaxhighlight>” then you forgot to add the option in the {{Doc|package=FCL|unit=custapp|identifier=tcustomapplication.checkoptions|text=<syntaxhighlight lang="delphi" inline>checkOptions</syntaxhighlight>}} call.
+
{{Note|если вы получаете сообщение об ошибке "<syntaxhighlight lang="text" inline>Option at position 1 needs an argument : f.</syntaxhighlight>" (Переключатель в позиции 1 нуждается в аргументе: f), то вы забыли добавить опцию при вызове {{Doc|package=FCL|unit=custapp|identifier=tcustomapplication.checkoptions|text=<syntaxhighlight lang="delphi" inline>checkOptions</syntaxhighlight>}}.}}
  
==== Checking parameters for validity ====
+
==== Проверка параметров на валидность ====
  
Command line parameters are free text, so the user can easily type errors.
+
Параметры командной строки представляют собой произвольный текст, поэтому пользователь при вводе может легко допускать ошибки. Отсюда проверка синтаксиса параметров обязательна. Для этого вы можете использовать метод [[doc:fcl/custapp/tcustomapplication.checkoptions.html|CheckOptions]].
Checking the syntax of the parameters is therefore mandatory.
 
You can use the [[doc:fcl/custapp/tcustomapplication.checkoptions.html|CheckOptions]] method for this:
 
  
You can define, what parameters are allowed, which ones ones need a parameter and in case of a syntax error you can get an error message plus the options that were wrong to print helpful and detailed errors.
+
Вы можете определить, какие параметры разрешены, какие из них нуждаются в параметре, а в случае синтаксической ошибки вы можете получить сообщение об ошибке, а также неправильные параметры для печати полезных и подробных ошибок.
  
Examples:
+
Пример:
 
<syntaxhighlight lang="delphi">
 
<syntaxhighlight lang="delphi">
 
errorMsg := checkOptions('hf:', 'help file:');
 
errorMsg := checkOptions('hf:', 'help file:');
 
</syntaxhighlight>
 
</syntaxhighlight>
  
This allows passing short options <syntaxhighlight lang="bash" inline>‑f value</syntaxhighlight> and <syntaxhighlight lang="bash" inline>‑h</syntaxhighlight>.
+
Это позволяет передавать короткие переключатели: <syntaxhighlight lang="bash" inline>‑f value</syntaxhighlight> и <syntaxhighlight lang="bash" inline>‑h</syntaxhighlight>.<br> Это - передавать длинные переключатели: <syntaxhighlight lang="bash" inline>‑‑help</syntaxhighlight> или <syntaxhighlight lang="bash" inline>‑‑file=filename</syntaxhighlight>.<br> А это не позволяет передачу параметра <syntaxhighlight lang="bash" inline>‑‑help</syntaxhighlight> ''со значением'' или <syntaxhighlight lang="bash" inline>‑‑file</syntaxhighlight> ''без значения''.<br>
It allows passing long options <syntaxhighlight lang="bash" inline>‑‑help</syntaxhighlight> or <syntaxhighlight lang="bash" inline>‑‑file=filename</syntaxhighlight>.
 
It does not allow <syntaxhighlight lang="bash" inline>‑‑help</syntaxhighlight> with a value, nor <syntaxhighlight lang="bash" inline>‑‑file</syntaxhighlight> without a value.
 
 
 
A Parameter Example:
 
  
 +
Пример передачи параметра:
 
<syntaxhighlight lang="pascal">procedure TMainForm.FormShow(Sender: TObject);
 
<syntaxhighlight lang="pascal">procedure TMainForm.FormShow(Sender: TObject);
 
var
 
var
Line 178: Line 173:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
This example finds parameters and does not mix them with command line switches or options.
+
Этот пример находит параметры и не смешивает их с переключателями или параметрами командной строки. В этом примере приложение также принимает параметры --debug-sync и --config-dir=somedir, но здесь они не указаны.
In this example, the app also accepts the switches --debug-sync and --config-dir=somedir but they are not reported here.
 
  
Note that Application.GetNonOptions() takes the long options as an array but Application.CheckOptions takes the same data but as a string.
+
Обратите внимание, что Application.GetNonOptions() принимает длинные параметры в виде массива, а Application.CheckOptions принимает те же данные, но в виде строки. Немного грустно!
Bit sad!
 
  
== Environment variables ==
+
== Переменные окружения ==
  
The [[sysutils|<syntaxhighlight lang="pascal" inline>sysUtils</syntaxhighlight> unit]] defines three basic functions in order to retrieve environment variables.
+
Модуль [[sysutils|<syntaxhighlight lang="pascal" inline>sysUtils</syntaxhighlight>]] определяет три основные функции для получения переменных среды.
  
* {{Doc|package=RTL|unit=sysutils|identifier=getenvironmentvariablecount|text=<syntaxhighlight lang="pascal" inline>getEnvironmentVariableCount</syntaxhighlight>}} returns the total number of environment variables
+
* {{Doc|package=RTL|unit=sysutils|identifier=getenvironmentvariablecount|text=<syntaxhighlight lang="pascal" inline>getEnvironmentVariableCount</syntaxhighlight>}} возвращает общее количество переменных среды.
* {{Doc|package=RTL|unit=sysutils|identifier=getenvironmentstring|text=<syntaxhighlight lang="pascal" inline>getEnvironmentString</syntaxhighlight>}} returns an environment variable by its index
+
* {{Doc|package=RTL|unit=sysutils|identifier=getenvironmentstring|text=<syntaxhighlight lang="pascal" inline>getEnvironmentString</syntaxhighlight>}} возвращает переменную среды по ее индексу
* {{Doc|package=RTL|unit=sysutils|identifier=getenvironmentvariable|text=<syntaxhighlight lang="pascal" inline>getEnvironmentVariable</syntaxhighlight>}} returns an environment variable by its key
+
* {{Doc|package=RTL|unit=sysutils|identifier=getenvironmentvariable|text=<syntaxhighlight lang="pascal" inline>getEnvironmentVariable</syntaxhighlight>}} возвращает переменную среды по ее ключу
  
Example:
+
Пример:
  
 
<syntaxhighlight lang="pascal" line highlight="3,9">
 
<syntaxhighlight lang="pascal" line highlight="3,9">
Line 208: Line 201:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
It is also possible to load all environment variables to a {{Doc|package=RTL|unit=classes|identifier=tstringlist|text=<syntaxhighlight lang="delphi" inline>tStringList</syntaxhighlight> object}} and access to name-value pair easily.
+
Также можно загрузить все переменные среды в объект {{Doc|package=RTL|unit=classes|identifier=tstringlist|text=<syntaxhighlight lang="delphi" inline>TStringList</syntaxhighlight>}} и легко получить доступ к паре имя-значение. Списки строк автоматически учитывают символ-разделитель, который по умолчанию является знаком равенства [[=|(<syntaxhighlight lang="pascal" inline>'='</syntaxhighlight>)]].
String lists automatically take care of the separator character which is by defaut is an [[=|equal sign (<syntaxhighlight lang="pascal" inline>'='</syntaxhighlight>)]].
 
  
 
<syntaxhighlight lang="delphi" line highlight="4,7,9,15,21,23,26">
 
<syntaxhighlight lang="delphi" line highlight="4,7,9,15,21,23,26">
Line 223: Line 215:
 
 
 
try
 
try
// load all variables to string list
+
// загружаем все переменные в список строк
 
for i := 0 to getEnvironmentVariableCount() - 1 do
 
for i := 0 to getEnvironmentVariableCount() - 1 do
 
begin
 
begin
Line 242: Line 234:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
There is also a <syntaxhighlight lang="delphi" inline>tCustomApplication</syntaxhighlight> [[Method|method]] available to get all environment variables as a [[TStringList|<syntaxhighlight lang="delphi" inline>tStringList</syntaxhighlight>]] at once.
+
Существует также [[Method|метод]] <syntaxhighlight lang="delphi" inline>TCustomApplication</syntaxhighlight> для одновременного получения всех переменных среды в виде [[TStringList|<syntaxhighlight lang="delphi" inline>TStringList</syntaxhighlight>]]. Тогда схема может выглядеть так:
Then the pattern may look like this:
 
  
 
<syntaxhighlight lang="delphi">
 
<syntaxhighlight lang="delphi">
Line 259: Line 250:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
[[Category: Code]]
+
[[Category: Code/ru]]

Latest revision as of 19:54, 28 May 2022

English (en) español (es) suomi (fi) français (fr) русский (ru)

В большинстве (интерактивных) операционных систем программы можно запускать через интерфейс командной строки command line interface (CLI), что позволяет предоставлять программе дополнительные данные. Модули systemobjPas) предоставляют базовые функции для доступа к данным, предоставленным из командной строки.

Обзор

Хотя на этой странице говорится о параметрах командной строки и переменных среды, фактический интерфейс командной строки (CLI) не является обязательным требованием для использования таких данных, а также для использования процедур и терминологии, описанных здесь. Однако, поскольку интерфейс командной строки более осязаем, следующие инструкции в основном относятся к пользовательскому интерфейсу оболочки.

Терминология

Option (переключатели)
Опции - флаги yes/no. Обычно они имеют вид ‑‑dryrun/‑‑no‑dryrun (dryrun включен или отключен соответственно). Опции также называются «переключателями».
Parameter (параметр)
Параметры представляют собой кортежи ключ-значение. В командной строке они выглядят так: ‑‑processors 4.
Argument (аргумент)
Аргументы — это простые слова. В командной строке они обычно разделяются пробелами (назначают переменную IFS в некоторых оболочках). В узком смысле, аргументы — это все предоставленные слова, которые не являются ни опциями, ни (частью) параметров. В общем, аргументы — это все слова в командной строке, которые никак не интерпретируются.
Environment variable (переменные окружения)
Переменные окружения относятся к помеченной части хранилища в среде. Это пары имя-значение.

Обратите внимание, CLI/OS предоставляет программе только те аргументы, которые она должна получить: например, экранированные символы новой строки, перенаправление файла (каналы или в файл) и присвоение переменных среды не будут перенаправлены в программу.

Основы

Поскольку понятия «опция» и «параметры» уже являются своего рода высокоуровневыми, существуют разные стили (короткие опции против длинных опций), и модуль system стремится предоставить базовые средства для работы, все аргументы командной строки просто перечисляютсяить, начиная с нуля. Никакой интерпретации не делается.

Функция paramStr возвращает n-й аргумент в командной строке. ParamStr(0) пытается вернуть имя и, возможно, полный путь к исполняемому программному файлу.

Параметры командной строки

Основы

Программа на Паскале может получить доступ к аргументам командной строки, используя функциюparamStr в сочетании с paramCount. ParamCount возвращает количество предоставленных аргументов.

program listArguments(input, output, stdErr);
{$mode objFPC}
var
	i: integer;
begin
	writeLn({$ifDef Darwin}
			// в Mac OS X возвращаемое значение зависит от метода вызова
			'This program was invoked via: ',
		{$else}
			// Turbo Pascal-совместимый paramStr(0) возвращает местоположение
			'This program is/was stored at: ',
		{$endIf}
		paramStr(0));
	
	for i := 1 to paramCount() do
	begin
		writeLn(i:2, '. argument: ', paramStr(i));
	end;
end.

Запуск этой программы (на не-Mac OS Ⅹ платформе) может выглядеть следующим образом:

$ ./listArguments foo bar able
This program is/was stored at: /tmp/listArguments
 1. argument: foo
 2. argument: bar
 3. argument: able

Модуль RTL system предоставляет версию paramStr, которая возвращает короткие строки shortString. Из-за особенностей реализации shortString ограничены 255 символами. Однако пользователь может указать более длинные аргументы командной строки.

Чтобы получить к ним доступ, модуль objPas переопределяет paramStr, который вместо этого возвращает строки ansiString, которые не имеют этого ограничения длины. Модуль objPas автоматически включается в режимы компилятора {$mode objFPC} (строка2) и {$mode Delphi}.

Распределенная функция paramStr пытается быть совместимой с Turbo Pascal. В TP paramStr(0) возвращает местоположение программы. Однако операционная система должна поддерживать это. В частности, в Mac OS Ⅹ значение paramStr(0) зависит от метода вызова, от того, как запускается приложение.

Light bulb  Примечание: Поскольку paramStr(0) зависит от функциональности ОС, он не подходит для кроссплатформенных программ.
Light bulb  Примечание: На юниксоидных платформах невозможно точно определить местоположение файла только по строке. Может быть несколько жестких ссылок, указывающих на один и тот же индексный дескриптор, файл мог быть уже удален, части пути к файлу могли измениться, помимо других деталей. По этим причинам paramStr(0) на юниксоидных платформах бесполезен.

Модуль getOpts предоставляет несколько других подпрограмм для вызова программы в соответствии с определенным стилем.

Простота использования

Хорошая программа должна выдавать справочное сообщение при вызове с неправильными параметрами и должна следовать общепринятому способу предоставления параметров. Модуль custApp, поставляемый с FPC, предоставляет класс TCustomApplication, предоставляющий функции для простой проверки и чтения параметров. Конечно, вы по-прежнему можете получить доступ к параметрам напрямую через paramStr и paramCount.

Каждое приложение LCL использует это автоматически. Объект Application — это TCustomApplication.

Если вы хотите написать не LCL-программу, то создайте в Lazarus новый проект типа «Консольное приложение». Это создаст файл project1.lpr с некоторыми приятными дополнениями, которые нужны почти всем программам. Перейдите к методу doRun.

Проверка параметра

С TCustomApplication вы можете получить доступ к параметрам по имени. Например, ваша программа должна выводить текст справки, когда пользователь задает общий параметр справки -h. -h является коротким вариантом параметра. Длинная форма --help. Чтобы проверить, вызвал ли пользователь программу с помощью -h или --help, вы можете использовать следующий код:

if hasOption('h', 'help') then
begin
	writeHelp;
	halt;
end;
Light bulb  Примечание: В LCL-форме вы должны добавить application. перед hasOption.

Например:

if application.hasOption('h', 'help') then
begin
	writeHelp;
	halt;
end;

Если вы хотите поддерживать только короткий вариант, используйте:

if hasOption('h', '') then

Если вы хотите поддерживать только длинный вариант, используйте:

if hasOption('help') then

Чтение значения параметра

Каждому параметру может быть присвоено значение. Например:

$ project1 -f filename

или в длинной форме:

$ project1 --file=filename

Чтобы получить filename, используйте:

writeLn('f=', getOptionValue('f', 'file'));
Light bulb  Примечание: если вы получаете сообщение об ошибке "Option at position 1 needs an argument : f." (Переключатель в позиции 1 нуждается в аргументе: f), то вы забыли добавить опцию при вызове checkOptions.

Проверка параметров на валидность

Параметры командной строки представляют собой произвольный текст, поэтому пользователь при вводе может легко допускать ошибки. Отсюда проверка синтаксиса параметров обязательна. Для этого вы можете использовать метод CheckOptions.

Вы можете определить, какие параметры разрешены, какие из них нуждаются в параметре, а в случае синтаксической ошибки вы можете получить сообщение об ошибке, а также неправильные параметры для печати полезных и подробных ошибок.

Пример:

errorMsg := checkOptions('hf:', 'help file:');

Это позволяет передавать короткие переключатели: ‑f value и ‑h.
Это - передавать длинные переключатели: ‑‑help или ‑‑file=filename.
А это не позволяет передачу параметра ‑‑help со значением или ‑‑file без значения.

Пример передачи параметра:

procedure TMainForm.FormShow(Sender: TObject);
var
    I: Integer;
    Params : TStringList
    LongOpts : array [1..2] of string = ('debug-sync', 'config-dir:');
begin
    Params := TStringList.Create;
    try
        Application.GetNonOptions('hgo:', LongOpts, Params);
        for I := 0 to Params.Count -1 do
            debugln('Extra Param ' + inttostr(I) + ' is ' + Params[I]);  }
    finally
        FreeAndNil(Params);
    end;
end;

Этот пример находит параметры и не смешивает их с переключателями или параметрами командной строки. В этом примере приложение также принимает параметры --debug-sync и --config-dir=somedir, но здесь они не указаны.

Обратите внимание, что Application.GetNonOptions() принимает длинные параметры в виде массива, а Application.CheckOptions принимает те же данные, но в виде строки. Немного грустно!

Переменные окружения

Модуль sysUtils определяет три основные функции для получения переменных среды.

Пример:

 1program environmentVariablesList(input, output, stdErr);
 2uses
 3	sysUtils;
 4var
 5	i: integer;
 6begin
 7	for i := 0 to getEnvironmentVariableCount() - 1 do
 8	begin
 9		writeLn(getEnvironmentString(i));
10	end;
11end.

Также можно загрузить все переменные среды в объект TStringList и легко получить доступ к паре имя-значение. Списки строк автоматически учитывают символ-разделитель, который по умолчанию является знаком равенства ('=').

 1program environmentVariablesSorted(input, output, stdErr);
 2{$mode objFPC}
 3uses
 4	classes, sysUtils;
 5var
 6	i: integer;
 7	environmentVariables: tStringList;
 8begin
 9	environmentVariables := tStringList.create();
10	
11	try
12		// загружаем все переменные в список строк
13		for i := 0 to getEnvironmentVariableCount() - 1 do
14		begin
15			environmentVariables.append(getEnvironmentString(i));
16		end;
17		
18		environmentVariables.sort;
19		for i := 0 to environmentVariables.count - 1 do
20		begin
21			writeLn(environmentVariables.names[i]:20,
22				' = ',
23				environmentVariables.valueFromIndex[i]);
24		end;
25	finally
26		environmentVariables.free;
27	end;
28end.

Существует также метод TCustomApplication для одновременного получения всех переменных среды в виде TStringList. Тогда схема может выглядеть так:

var
	environmentVariables: tStringList;
begin
	environmentVariables := tStringList.create();
	try
		application.getEnvironmentList(environmentVariables);
		
	finally 
		environmentVariables.free;
	end;
end;