1-- Copyright (c) 1990 Regents of the University of California.
2-- All rights reserved.
3--
4--    The primary authors of ayacc were David Taback and Deepak Tolani.
5--    Enhancements were made by Ronald J. Schmalz.
6--
7--    Send requests for ayacc information to ayacc-info@ics.uci.edu
8--    Send bug reports for ayacc to ayacc-bugs@ics.uci.edu
9--
10-- Redistribution and use in source and binary forms are permitted
11-- provided that the above copyright notice and this paragraph are
12-- duplicated in all such forms and that any documentation,
13-- advertising materials, and other materials related to such
14-- distribution and use acknowledge that the software was developed
15-- by the University of California, Irvine.  The name of the
16-- University may not be used to endorse or promote products derived
17-- from this software without specific prior written permission.
18-- THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
19-- IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
20-- WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
21
22-- Module       : command_line_interface_.ada
23-- Component of : common_library
24-- Version      : 1.2
25-- Date         : 11/21/86  16:03:08
26-- SCCS File    : disk21~/rschm/hasee/sccs/common_library/sccs/sxcommand_line_interface_.ada
27
28with String_Lists;  use String_Lists;
29with String_pkg;    use String_pkg;
30
31--------------------------------------------------------------------
32
33Package command_line_interface is
34--| Provides primitives for getting at the command line arguments.
35
36--| Overview
37--| This package provides a universal and portable interface to
38--| the arguments typed on a command line when a program is invoked.
39--| Each command line argument is either a Word (sequence of non-blank
40--| characters) or a quoted string, with embedded quotes doubled.
41--|
42--| Both named and positional arguments may be given on the command
43--| line.  However, once a named parameter is used, all the subseqent
44--| parameters on the command line must be named parameters.  For example,
45--| the commands
46--|-
47--|     compile  abc pqr xyz library => plib
48--|     compile  abc,pqr,unit=>xyz,library=>plib
49--|+
50--| have one named argument and three positional arguments.  This
51--| package separates the named parameters from the positional
52--| parameters, ignores spaces around the "bound to" (=>) symbol, and
53--| allows parameters to be separated by either spaces or commas,
54--| so these command lines are indistinguishable.
55--|
56--| At program elaboration time, the command line string is automatically
57--| obtained from the host operating system and parsed into
58--| individual arguments.  The following operations may then be used:
59--|-
60--| Named_arg_count()		Returns number of named arguments entered
61--| Positional_arg_count()	Returns number of positional arguments
62--| Positional_arg_value(N)	Returns the Nth positional argument
63--| Named_arg_value(Name, Dflt)	Returns value of a named argument
64--| Arguments()			Returns the entire command line
65--|+
66
67----------------------------------------------------------------
68
69max_args: constant := 255;
70--| Maximum number of command line arguments (arbitrary).
71
72subtype Argument_count is integer range 0..max_args;
73--| For number of arguments
74subtype Argument_index is Argument_count range 1..Argument_count'last;
75--| Used to number the command line arguments.
76
77no_arg: exception;
78  --| Raised when request made for nonexistent argument
79
80missing_positional_arg: exception;
81  --| Raised when command line is missing positional argument (A,,B)
82
83invalid_named_association: exception;
84  --| Raised when command line is missing named argument value (output=> ,A,B)
85
86unreferenced_named_arg: exception;
87  --| Raised when not all named parameters have been retrieved
88
89invalid_parameter_order: exception;
90  --| Raised when a positional parameter occurs after a named parameter
91  --  in the command line
92
93--Invalid_Aggregate : exception;
94  --| Raised when an aggregate does not begin and end with parentheses
95  --  in Parse_Aggregate.
96
97Unbalanced_Parentheses : exception;
98  --| Raised when the number of left paren's does not match the number
99  --| of right paren's.
100
101Invalid_Parameter : exception;
102  --| Raised when the conversion of a string to a parameter type is not
103  --| possible.
104
105----------------------------------------------------------------
106
107procedure Initialize (Tool_Name : in String);
108  --| Initializes command_line_interface
109  --| N/A: modifies, errors, raises
110
111---------------------------------------------------------------------
112
113function Named_arg_count	--| Return number of named arguments
114  return Argument_count;
115--| N/A: modifies, errors, raises
116
117
118function Positional_arg_count	--| Return number of positional arguments
119  return Argument_count;
120--| N/A: modifies, errors, raises
121
122
123----------------------------------------------------------------
124
125function Positional_arg_value(	--| Return an argument value
126  N: Argument_index	        --| Position of desired argument
127  ) return string;              --| Raises: no_arg
128
129--| Effects: Return the Nth argument.  If there is no argument at
130--| position N, no_arg is raised.
131
132--| N/A: modifies, errors
133
134
135function Positional_arg_value(	    --| Return an argument value
136  N: Argument_index	            --| Position of desired argument
137  ) return String_type;             --| Raises: no_arg
138
139--| Effects: Return the Nth argument.  If there is no argument at
140--| position N, no_arg is raised.
141
142--| N/A: modifies, errors
143
144--------------------------------------------------------------------
145
146function Named_arg_value(--| Return a named argument value
147  Name: string;
148  Default: string
149  ) return string;
150
151--| Effects: Return the value associated with Name on the command
152--| line.  If there was none, return Default.
153
154--| N/A: modifies, errors
155
156function Named_arg_value(--| Return a named argument value
157  Name: string;
158  Default: string
159  ) return String_Type;
160
161--| Effects: Return the value associated with Name on the command
162--| line.  If there was none, return Default.
163
164--| N/A: modifies, errors
165
166
167function Named_arg_value(--| Return a named argument value
168  Name: string;
169  Default: String_type
170  ) return String_type;
171
172--| Effects: Return the value associated with Name on the command
173--| line.  If there was none, return Default.
174
175--| N/A: modifies, errors
176
177----------------------------------------------------------------
178
179function Arguments	--| Return the entire argument string
180  return string;
181--| Effects: Return the entire command line, except for the name
182--| of the command itself.
183
184--| N/A: modifies, errors, raises
185
186----------------------------------------------------------------
187
188  function Parse_Aggregate (Aggregate_Text : in String_Type)
189                                                return String_Lists.List;
190
191  function Parse_Aggregate (Aggregate_Text : in String)
192                                                return String_Lists.List;
193  --| Effects: Returns components of Aggregate_Text as a String_List.
194  --| Raises : Invalid_Aggregate
195
196----------------------------------------------------------------
197
198  generic
199    type Parameter_Type is (<>);
200    Type_Name : in String;
201  function Convert (Parameter_Text : in String) return Parameter_Type;
202  --| Raises: Invalid_Parameter
203
204----------------------------------------------------------------
205
206procedure Finalize ;    --| Raises: unrecognized parameters
207
208--| Effects: If not all named parameters have been retrieved
209--| unrecognized parameters is raised.
210--| N/A: modifies, errors
211
212end command_line_interface;
213
214----------------------------------------------------------------
215