Command line parameters and environment variables/ru

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

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

Обзор

Хотя на этой странице говорится о параметрах командной строки и переменных среды, фактический интерфейс командной строки (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) зависит от метода вызова, от того, как запускается приложение.

Примечание: Поскольку paramStr(0) зависит от функциональности ОС, он не подходит для кроссплатформенных программ.

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

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

User friendly

A good program should give a help message when invoked with the wrong parameters and it should follow a common way of giving parameters. The unit custApp that comes with FPC provides the TCustomApplication class, which provides functions to easily check and read parameters. Of course you can still access the parameters directly via paramStr and paramCount.

Every LCL application uses this automatically. The Application object is a TCustomApplication.

If you want to write a non LCL program, then create in Lazarus a new project of type “Console Application”. This will create a project1.lpr with some nice goodies, that almost all programs need. Go to the doRun method.

Check for a parameter

With TCustomApplication you can access parameters by name. For example your program should print a help text when the user gave the common help parameter -h. The -h is a short option. The long form is the --help. To test whether the user called the program with -h or --help you can use:

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

Примечание: In an LCL form you must prepend application. in front of hasOption.

For example:

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

If you only want to support the short option, use:

if hasOption('h', '') then

If you only want to support the long option, use:

if hasOption('help') then

Read the parameter value

Each parameter can be given a value. For example:

$ project1 -f filename

or in the long form:

$ project1 --file=filename

In order to retrieve filename use:

writeLn('f=', getOptionValue('f', 'file'));

Note: if you get the error message “Option at position 1 needs an argument : f.” then you forgot to add the option in the checkOptions call.

Checking parameters for validity

Command line parameters are free text, so the user can easily type errors. Checking the syntax of the parameters is therefore mandatory. You can use the 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:

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

This allows passing short options ‑f value and ‑h. It allows passing long options ‑‑help or ‑‑file=filename. It does not allow ‑‑help with a value, nor ‑‑file without a value.

A Parameter Example:

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;

This example finds parameters and does not mix them with command line switches or options. 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. Bit sad!

Environment variables

The sysUtils unit defines three basic functions in order to retrieve environment variables.

• getEnvironmentVariableCount returns the total number of environment variables
• getEnvironmentString returns an environment variable by its index
• getEnvironmentVariable returns an environment variable by its key

Example:

 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.

It is also possible to load all environment variables to a tStringList object and access to name-value pair easily. String lists automatically take care of the separator character which is by defaut is an equal sign ('=').

 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		// load all variables to string list
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.

There is also a tCustomApplication method available to get all environment variables as a tStringList at once. Then the pattern may look like this:

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