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

From Lazarus wiki
Jump to navigationJump to search
Line 1: Line 1:
 
{{Command line parameters and environment variables}}
 
{{Command line parameters and environment variables}}
 +
 
== Overview ==
 
== Overview ==
  
Line 6: Line 7:
 
   fpc -Fudirectory -gh unit1.pas
 
   fpc -Fudirectory -gh unit1.pas
  
−
== Command line parameters - the basics ==
+
== Command line parameters ==
 +
 
 +
=== The basics ===
  
 
A pascal program can access the parameters via ''ParamStr'' and ''ParamCount''. ''ParamStr(0)'' is the program path itself. ''ParamStr(1)'' is the first parameter. ''ParamCount'' is the number of parameters.
 
A pascal program can access the parameters via ''ParamStr'' and ''ParamCount''. ''ParamStr(0)'' is the program path itself. ''ParamStr(1)'' is the first parameter. ''ParamCount'' is the number of parameters.
  
−
<delphi>
+
<delphi>program Project1;
−
program Project1;
 
  
 
{$mode objfpc}{$H+}
 
{$mode objfpc}{$H+}
  
 
var
 
var
−
   i: Integer;
+
   I: Integer;
 
begin
 
begin
−
   writeln('Program: ',ParamStr(0));
+
   WriteLn('Program: ', ParamStr(0));
−
   for i:=1 to ParamCount do
+
   for I := 1 to ParamCount do
−
     writeln('Param ',i,': ',ParamStr(i));
+
     WriteLn('Param ', I, ': ', ParamStr(I));
−
end.
+
end.</DELPHI>
−
</DELPHI>
 
  
 
For example:
 
For example:
Line 29: Line 30:
 
   Param 1: -a
 
   Param 1: -a
  
−
== Command line parameters - comfortable ==
+
=== Comfortable ===
  
 
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.
 
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.
Line 38: Line 39:
 
Go to the DoRun method.  
 
Go to the DoRun method.  
  
−
=== Check for a parameter ===
+
==== 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
 
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
−
<DELPHI>
+
<DELPHI>if HasOption('h', 'help') then begin
−
if HasOption('h','help') then begin
 
 
   WriteHelp;
 
   WriteHelp;
 
   Halt;
 
   Halt;
−
end;
+
end;</DELPHI>
−
</DELPHI>
 
  
 
Note: In an LCL form you must prepend ''Application.'' in front of HasOption. For example:
 
Note: In an LCL form you must prepend ''Application.'' in front of HasOption. For example:
  
−
<DELPHI>
+
<DELPHI>if Application.HasOption('h', 'help') then begin
−
if Application.HasOption('h','help') then begin
 
 
   WriteHelp;
 
   WriteHelp;
 
   Halt;
 
   Halt;
−
end;
+
end;</DELPHI>
−
</DELPHI>
 
  
  
−
<DELPHI>
+
<DELPHI>// If you only want to support the short option use:
−
// If you only want to support the short option use:
+
if HasOption('h', '') then ...
−
if HasOption('h','') then ...
 
  
 
// If you only want to support the long option use:
 
// If you only want to support the long option use:
−
if HasOption('help') then ...
+
if HasOption('help') then ...</DELPHI>
−
</DELPHI>
 
  
−
=== Read the parameter value ===
+
==== Read the parameter value ====
  
 
Each parameter can be given a value. For example:
 
Each parameter can be given a value. For example:
Line 76: Line 71:
 
   project1 --file=filename
 
   project1 --file=filename
  
−
<DELPHI>
+
<DELPHI>WriteLn('f=', GetOptionValue('f', 'file'));</DELPHI>
−
  writeln('f=',GetOptionValue('f','file'));
 
−
</DELPHI>
 
  
 
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.
 
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 ===
+
==== Checking parameters for validity ====
  
 
Command line parameters are free text, so the user can easily do typing errors. Checking the syntax of the parameters is therefore mandatory. You can use the [[doc:fcl/custapp/tcustomapplication.checkoptions.html|CheckOptions]] method for this:
 
Command line parameters are free text, so the user can easily do typing errors. Checking the syntax of the parameters is therefore mandatory. You can use the [[doc:fcl/custapp/tcustomapplication.checkoptions.html|CheckOptions]] method for this:
Line 89: Line 82:
  
 
Examples:
 
Examples:
−
<DELPHI>
+
<DELPHI>ErrorMsg := CheckOptions('hf:', 'help file:');</DELPHI>
−
ErrorMsg:=CheckOptions('hf:','help file:');
 
−
</DELPHI>
 
  
 
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.
 
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.
 +
 +
==Environment variables==
 +
 +
Three basic functions are provided for working with environment variables.
 +
 +
<delphi>function GetEnvironmentVariable(Const EnvVar : String) : String;
 +
function GetEnvironmentVariableCount : Integer;
 +
function GetEnvironmentString(Index : Integer) : String;</delphi>
 +
 +
Example:
 +
 +
<delphi>var
 +
  I: Integer;
 +
begin
 +
  WriteLn('PATH = ' + GetEnvironmentVariable('PATH'));
 +
 +
  WriteLn('All environment variables:');
 +
  for I := 0 to GetEnvironmentVariableCount - 1 do
 +
    WriteLn(GetEnvironmentString(I));
 +
end.</delphi>

Revision as of 08:27, 8 September 2010

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

Overview

When a program is started a user can give command line parameters and setup environment variables. For example the FreePascal compiler gets most of its parameters via command line options: 

 fpc -Fudirectory -gh unit1.pas

Command line parameters

The basics

A pascal program can access the parameters via ParamStr and ParamCount. ParamStr(0) is the program path itself. ParamStr(1) is the first parameter. ParamCount is the number of parameters.

<delphi>program Project1;

{$mode objfpc}{$H+}

var 

 I: Integer;

begin 

 WriteLn('Program: ', ParamStr(0));
 for I := 1 to ParamCount do
   WriteLn('Param ', I, ': ', ParamStr(I));

end.</DELPHI>

For example: 

 $ /tmp/project1 -a
 Program: /tmp/project1
 Param 1: -a

Comfortable

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 <DELPHI>if HasOption('h', 'help') then begin 

 WriteHelp;
 Halt;

end;</DELPHI>

Note: In an LCL form you must prepend Application. in front of HasOption. For example:

<DELPHI>if Application.HasOption('h', 'help') then begin 

 WriteHelp;
 Halt;

end;</DELPHI>


<DELPHI>// 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 ...</DELPHI>

Read the parameter value

Each parameter can be given a value. For example: 

 project1 -f filename

or with the long form: 

 project1 --file=filename

<DELPHI>WriteLn('f=', GetOptionValue('f', 'file'));</DELPHI>

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 do typing 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: <DELPHI>ErrorMsg := CheckOptions('hf:', 'help file:');</DELPHI>

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.

Environment variables

Three basic functions are provided for working with environment variables.

<delphi>function GetEnvironmentVariable(Const EnvVar : String) : String; function GetEnvironmentVariableCount : Integer; function GetEnvironmentString(Index : Integer) : String;</delphi>

Example:

<delphi>var 

 I: Integer;

begin 

 WriteLn('PATH = ' + GetEnvironmentVariable('PATH'));

 WriteLn('All environment variables:');
 for I := 0 to GetEnvironmentVariableCount - 1 do 
   WriteLn(GetEnvironmentString(I));

end.</delphi>

Retrieved from "http://wiki.freepascal.org/index.php?title=Command_line_parameters_and_environment_variables&oldid=44733"