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