Ada Programming/Libraries/Ada.Command Line

is a unit of the Predefined Language Environment since Ada 95.

Introduction
The  package enables the Ada program to access the command line arguments set by the command that invoked the program. It is the Ada version of the C  and   system.

If the environment supports it, it is also possible to set the Ada program's exit status with.

It is important to note, that all the code in this article is compiled and executed on a Slackware Linux system. The compiler used is GNATMAKE GPL 2008 (20080521) and the shell is BASH. This is important because the reference manual clearly states that:

''If the external execution environment supports passing arguments to a program, then Argument_Count returns the number of arguments passed to the program invoking the function. Otherwise, it returns 0. The meaning of “number of arguments” is implementation defined.''

Note the closing sentence: The meaning of “number of arguments” is implementation defined. What this means, is that you cannot trust a given argument string to yield the same result for all environments. is highly dependent on factors such as operating system, shell, and compiler.

Using Ada.Command_Line
The program we'll be using throughout this article doesn't actually do anything, except report the various arguments we've used when invoking the program. The basic program looks like this:

Args IO AdaText_IO CLI AdaCommand_Line IOPut_Line Item "Argument Count:" & CLIArgument_Count Args

When executing the above program with no arguments given, you should get the following output:

Argument Count: 0

Let's quickly go over the program: On lines 1 and 2 we add the  and   packages to the program. On lines 5 and 6 we rename those packages to the shorter  and   and finally on line 8 we output the current argument count. And that is really all that is required to enable access to the command line arguments given to the program.

The full specification of the  package is about as simple as such specifications can be.

We've already encountered the  function in the   program, but lets see what happens when we invoke the   program with some arguments.

Ada.Command_Line.Argument_Count
The specification for  looks like this:

Argument_Count Natural

The basic  program already use the   function, so to see how it works, all we have to do is supply the program with a variety of arguments:

$ ./args --option=value Argument Count: 1 $ ./args --option=value --foo=bar Argument Count: 2 $ ./args --name=Thomas Løcke Argument Count: 2 $ ./args --option="Thomas Løcke" Argument Count: 1 $ ./args /path/to/file with spaces in name Argument Count: 5 $ ./args /path/to/file with spaces in name Argument Count: 1

A pattern should've emerged by now. Of particular interest is the last example: Because the whitespace is escaped, the entire string is treated as one argument. One could easily imagine that another environment might treat such an argument differently and perhaps ignore the backslash. The same holds for the double quotes example ("Thomas Løcke"). Other shells/environments might very well treat "Thomas Løcke" as two separate arguments because of the whitespace. The key thing is to be aware of such details when using.

Ada.Command_Line.Argument
The specification for  looks like this:

Argument Number Positive  String

returns a  argument corresponding to the relative position. Note that  is of type. This means that the valid range of  is. If  is outside this range, a   is raised.

To see how it works, we add 3 more lines to our small  program:

i 1  CLIArgument_Count IOPut_Line Item CLIArgument Number  i

If we run  with the same arguments as given in the   example, we get these results:

$ ./args --option=value Argument Count: 1 1: --option=value $ ./args --option=value --foo=bar Argument Count: 2 1: --option=value 2: --foo=bar $ ./args --name=Thomas Løcke Argument Count: 2 1: --name=Thomas 2: Løcke $ ./args --option="Thomas Løcke" Argument Count: 1 1: --option=Thomas Løcke $ ./args /path/to/file with spaces in name Argument Count: 5 1: /path/to/file 2: with 3: spaces 4: in 5: name $ ./args /path/to/file with spaces in name Argument Count: 1 1: /path/to/file with spaces in name

There are no big surprises here.

If no arguments are given when running the program, you will end up with a  loop:. This is perfectly valid and the result is as expected: The loop is terminated immediately.

Args IO AdaText_IO CLI AdaCommand_Line IOPut_Line Item "Argument Count:" & CLIArgument_Count i 1  CLIArgument_Count IOPut Item i & ": " IOPut_Line Item CLIArgument Number  i  Args

Ada.Command_Line.Command_Name
The specification for  looks like this:

Command_Name String

returns the string command used to invoke the program. As is the case with, this is implementation-defined, so   might return X on system A, Y on system B and null on system C. You cannot rely on this value being the same across all combinations of compilers, shells, and operating systems.

To see how it works, add this line to the  program:

IO.Put_Line (CLI.Command_Name);

If we execute the program, without any arguments, from within GNAT Studio (using Shift+F2), the result will be this:

Argument Count: 0 /home/thomas/wiki_examples/Args/args

Notice how GNAT Studio uses the full path to the  program to invoke it.

If I change directory to, and execute the   program from the commandline, I get this:

$ args Argument Count: 0 args

If I use the common  syntax to execute the program, I get this:

$ ./args Argument Count: 0 ./args

As you can see, in an environment that supports argument passing, the  function returns the exact string used to invoke the program.

Ada.Command_Line.Set_Exit_Status
The specification for  looks like this:

Set_Exit_Status Code Exit_Status

If the environment supports the return of an task completion code,  allows you to set an exit status for the program. If you look at the specification for, you will notice the type   and the two variables   and. These two are defined as 0 and 1, respectively, but it is entirely possible to define your own exit status codes.

To see how that works, add this to the specification of the  program:

More_Than_One_Arg  CLIExit_Status  3

And this to the body of the program:

CLIArgument_Count 0 CLISet_Exit_Status Code CLIFailure CLIArgument_Count 1 CLISet_Exit_Status Code CLISuccess CLISet_Exit_Status Code More_Than_One_Arg

What we do here is set the exit status depending on the number of arguments given to the program. This is what happens when we execute the program with various arguments:

$ ./args Argument Count: 0 $ echo $? 1 $ ./args one Argument Count: 1 $ echo $? 0 $ ./args one two Argument Count: 2 $ echo $? 3

outputs the exit code of the most recently executed program. On the first execution, we get a failure because no arguments are given. On the second execution, we get a success because exactly one argument is given. On the third execution, we get the special exit code 3 because more than one argument is given.

Args AdaText_IO AdaCommand_Line More_Than_One_Arg  CLIExit_Status  3 IOPut_Line Item "Argument Count:" & CLIArgument_Count CLIArgument_Count 0 CLISet_Exit_Status Code CLIFailure CLIArgument_Count 1 CLISet_Exit_Status Code CLISuccess CLISet_Exit_Status Code More_Than_One_Arg Args

Specification
Preelaborate Command_Line Argument_Count Natural Argument Number  Positive  String Command_Name String Exit_Status  implementation_defined  implementation_defined Success  Exit_Status Failure  Exit_Status Set_Exit_Status Code  Exit_Status Import Ada Success Import Ada Failure AdaCommand_Line

Wikibook

 * Ada Programming/Libraries/Ada