gcc/ada/g-comlin.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                    G N A T . C O M M A N D _ L I N E                     --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                            $Revision: 1.1 $
  10 --                                                                          --
  11 --            Copyright (C) 1999-2001 Ada Core Technologies, Inc.           --
  12 --                                                                          --
  13 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- As a special exception,  if other files  instantiate  generics from this --
  25 -- unit, or you link  this unit with other files  to produce an executable, --
  26 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  27 -- covered  by the  GNU  General  Public  License.  This exception does not --
  28 -- however invalidate  any other reasons why  the executable file  might be --
  29 -- covered by the  GNU Public License.                                      --
  30 --                                                                          --
  31 -- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com).   --
  32 --                                                                          --
  33 ------------------------------------------------------------------------------
  34
  35 --  High level package for command line parsing
  36
  37 --  This package provides an interface to Ada.Command_Line, to do the
  38 --  parsing of command line arguments. Here is a small usage example:
  39 --
  40 --  begin
  41 --     loop
  42 --        case Getopt ("a b: ad") is  -- Accepts '-a', '-ad', or '-b argument'
  43 --           when ASCII.NUL => exit;
  44 --
  45 --           when 'a' =>
  46 --                 if Full_Switch = "a" then
  47 --                    Put_Line ("Got a");
  48 --                 else
  49 --                    Put_Line ("Got ad");
  50 --                 end if;
  51 --
  52 --           when 'b' =>
  53 --              Put_Line ("Got b + " & Parameter);
  54 --
  55 --           when others =>
  56 --              raise Program_Error;         -- cannot occur!
  57 --        end case;
  58 --     end loop;
  59 --
  60 --     loop
  61 --        declare
  62 --           S : constant String := Get_Argument (Do_Expansion => True);
  63
  64 --        begin
  65 --           exit when S'Length = 0;
  66 --           Put_Line ("Got " & S);
  67 --        end;
  68 --     end loop;
  69 --
  70 --  exception
  71 --     when Invalid_Switch    => Put_Line ("Invalid Switch " & Full_Switch);
  72 --     when Invalid_Parameter => Put_Line ("No parameter for " & Full_Switch);
  73 --  end;
  74 --
  75 --  A more complicated example would involve the use of sections for the
  76 --  switches, as for instance in gnatmake. These sections are separated by
  77 --  special switches, chosen by the programer. Each section act as a
  78 --  command line of its own.
  79 --
  80 --  begin
  81 --     Initialize_Option_Scan ('-', False, "largs bargs cargs");
  82 --     loop
  83 --        --  same loop as above to get switches and arguments
  84 --     end loop;
  85 --
  86 --     Goto_Section ("bargs");
  87 --     loop
  88 --        --  same loop as above to get switches and arguments
  89 --        --  The supports switches in Get_Opt might be different
  90 --     end loop;
  91 --
  92 --     Goto_Section ("cargs");
  93 --     loop
  94 --        --  same loop as above to get switches and arguments
  95 --        --  The supports switches in Get_Opt might be different
  96 --     end loop;
  97 --  end;
  98
  99
 100 with GNAT.Directory_Operations;
 101 with GNAT.Regexp;
 102
 103 package GNAT.Command_Line is
 104
 105    procedure Initialize_Option_Scan
 106      (Switch_Char              : Character := '-';
 107       Stop_At_First_Non_Switch : Boolean := False;
 108       Section_Delimiters       : String := "");
 109    --  This procedure resets the internal state of the package to prepare
 110    --  to rescan the parameters. It need not (but may be) called before the
 111    --  first use of Getopt, but it must be called if you want to start
 112    --  rescanning the command line parameters from the start. The optional
 113    --  parameter Switch_Char can be used to reset the switch character,
 114    --  e.g. to '/' for use in DOS-like systems. The optional parameter
 115    --  Stop_At_First_Non_Switch indicates if Getopt is to look for switches
 116    --  on the whole command line, or if it has to stop as soon as a
 117    --  non-switch argument is found.
 118    --
 119    --  Example:
 120    --
 121    --      Arguments: my_application file1 -c
 122    --
 123    --      if Stop_At_First_Non_Switch is False, then -c will be considered
 124    --      as a switch (returned by getopt), otherwise it will be considered
 125    --      as a normal argument (returned by Get_Argument).
 126    --
 127    --  if SECTION_DELIMITERS is set, then every following subprogram
 128    --  (Getopt and Get_Argument) will only operate within a section, which
 129    --  is delimited by any of these delimiters or the end of the command line.
 130    --
 131    --  Example:
 132    --      Initialize_Option_Scan ("largs bargs cargs");
 133    --
 134    --      Arguments on command line : my_application -c -bargs -d -e -largs -f
 135    --      This line is made of three section, the first one is the default one
 136    --      and includes only the '-c' switch, the second one is between -bargs
 137    --      and -largs and includes '-d -e' and the last one includes '-f'
 138
 139    procedure Goto_Section (Name : String := "");
 140    --  Change the current section. The next Getopt of Get_Argument will
 141    --  start looking at the beginning of the section. An empty name ("")
 142    --  refers to the first section between the program name and the first
 143    --  section delimiter.
 144    --  If the section does not exist, then Invalid_Section is raised.
 145
 146    function Full_Switch return String;
 147    --  Returns the full name of the last switch found (Getopt only returns
 148    --  the first character)
 149
 150    function Getopt (Switches : String) return Character;
 151    --  This function moves to the next switch on the command line (defined
 152    --  as a switch character followed by a character within Switches,
 153    --  casing being significant). The result returned is the first
 154    --  character of the particular switch located. If there are no more
 155    --  switches in the current section, returns ASCII.NUL. The switches
 156    --  need not be separated by spaces (they can be concatenated if they do
 157    --  not require an argument, e.g. -ab is the same as two separate
 158    --  arguments -a -b).
 159    --
 160    --  Switches is a string of all the possible switches, separated by a
 161    --  space. A switch can be followed by one of the following characters :
 162    --
 163    --   ':'  The switch requires a parameter. There can optionally be a space
 164    --        on the command line between the switch and its parameter
 165    --   '!'  The switch requires a parameter, but there can be no space on the
 166    --        command line between the switch and its parameter
 167    --   '?'  The switch may have an optional parameter. There can no space
 168    --        between the switch and its argument
 169    --        ex/ if Switches has the following value : "a? b"
 170    --            The command line can be :
 171    --             -afoo    :  -a switch with 'foo' parameter
 172    --             -a foo   :  -a switch and another element on the
 173    --                           command line 'foo', returned by Get_Argument
 174    --
 175    --     Example: if Switches is "-a: -aO:", you can have the following
 176    --              command lines :
 177    --                -aarg    :  'a' switch with 'arg' parameter
 178    --                -a arg   :  'a' switch with 'arg' parameter
 179    --                -aOarg   :  'aO' switch with 'arg' parameter
 180    --                -aO arg  :  'aO' switch with 'arg' parameter
 181    --
 182    --    Example:
 183    --
 184    --       Getopt ("a b: ac ad?")
 185    --
 186    --         accept either 'a' or 'ac' with no argument,
 187    --         accept 'b' with a required argument
 188    --         accept 'ad' with an optional argument
 189    --
 190    --  If the first item in switches is '*', then Getopt will catch
 191    --  every element on the command line that was not caught by any other
 192    --  switch. The character returned by GetOpt is '*'
 193    --
 194    --    Example
 195    --       Getopt ("* a b")
 196    --       If the command line is '-a -c toto.o -b', GetOpt will return
 197    --       successively 'a', '*', '*' and 'b'. When '*' is returnd,
 198    --       Full_Switch returns the corresponding item on the command line.
 199    --
 200    --
 201    --  When Getopt encounters an invalid switch, it raises the exception
 202    --  Invalid_Switch and sets Full_Switch to return the invalid switch.
 203    --  When Getopt can not find the parameter associated with a switch, it
 204    --  raises Invalid_Parameter, and sets Full_Switch to return the invalid
 205    --  switch character.
 206    --
 207    --  Note: in case of ambiguity, e.g. switches a ab abc, then the longest
 208    --  matching switch is returned.
 209    --
 210    --  Arbitrary characters are allowed for switches, although it is
 211    --  strongly recommanded to use only letters and digits for portability
 212    --  reasons.
 213
 214    function Get_Argument (Do_Expansion : Boolean := False) return String;
 215    --  Returns the next element in the command line which is not a switch.
 216    --  This function should not be called before Getopt has returned
 217    --  ASCII.NUL.
 218    --
 219    --  If Expansion is True, then the parameter on the command
 220    --  line will considered as filename with wild cards, and will be
 221    --  expanded. The matching file names will be returned one at a time.
 222    --  When there are no more arguments on the command line, this function
 223    --  returns an empty string. This is useful in non-Unix systems for
 224    --  obtaining normal expansion of wild card references.
 225
 226    function Parameter return String;
 227    --  Returns parameter associated with the last switch returned by Getopt.
 228    --  If no parameter was associated with the last switch, or no previous
 229    --  call has been made to Get_Argument, raises Invalid_Parameter.
 230    --  If the last switch was associated with an optional argument and this
 231    --  argument was not found on the command line, Parameter returns an empty
 232    --  string
 233
 234    type Expansion_Iterator is limited private;
 235    --  Type used during expansion of file names
 236
 237    procedure Start_Expansion
 238      (Iterator     : out Expansion_Iterator;
 239       Pattern      : String;
 240       Directory    : String := "";
 241       Basic_Regexp : Boolean := True);
 242    --  Initialize an wild card expansion. The next calls to Expansion will
 243    --  return the next file name in Directory which match Pattern (Pattern
 244    --  is a regular expression, using only the Unix shell and DOS syntax if
 245    --  Basic_Regexp is True. When Directory is an empty string, the current
 246    --  directory is searched.
 247
 248    function Expansion (Iterator : Expansion_Iterator) return String;
 249    --  Return the next file in the directory matching the parameters given
 250    --  to Start_Expansion and updates Iterator to point to the next entry.
 251    --  Returns an empty string when there are no more files in the directory.
 252    --  If Expansion is called again after an empty string has been returned,
 253    --  then the exception GNAT.Directory_Operations.Directory_Error is raised.
 254
 255    Invalid_Section : exception;
 256    --  Raised when an invalid section is selected by Goto_Section
 257
 258    Invalid_Switch : exception;
 259    --  Raised when an invalid switch is detected in the command line
 260
 261    Invalid_Parameter : exception;
 262    --  Raised when a parameter is missing, or an attempt is made to obtain
 263    --  a parameter for a switch that does not allow a parameter
 264
 265 private
 266
 267    type Expansion_Iterator is limited record
 268       Dir    : GNAT.Directory_Operations.Dir_Type;
 269       Regexp : GNAT.Regexp.Regexp;
 270    end record;
 271
 272 end GNAT.Command_Line;