2008-05-30 Vladimir Makarov <vmakarov@redhat.com>
[official-gcc.git] / gcc / ada / g-expect.ads
blob5ec6f99c8dc193190caf149a13635a34bae85d94
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT LIBRARY COMPONENTS --
4 -- --
5 -- G N A T . E X P E C T --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2000-2007, 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 ------------------------------------------------------------------------------
34 -- Currently this package is implemented on all native GNAT ports except
35 -- for VMS. It is not yet implemented for any of the cross-ports (e.g. it
36 -- is not available for VxWorks or LynxOS).
38 -- -----------
39 -- -- Usage --
40 -- -----------
42 -- This package provides a set of subprograms similar to what is available
43 -- with the standard Tcl Expect tool.
45 -- It allows you to easily spawn and communicate with an external process.
46 -- You can send commands or inputs to the process, and compare the output
47 -- with some expected regular expression.
49 -- Usage example:
51 -- Non_Blocking_Spawn
52 -- (Fd, "ftp",
53 -- (1 => new String' ("machine@domain")));
54 -- Timeout := 10000; -- 10 seconds
55 -- Expect (Fd, Result, Regexp_Array'(+"\(user\)", +"\(passwd\)"),
56 -- Timeout);
57 -- case Result is
58 -- when 1 => Send (Fd, "my_name"); -- matched "user"
59 -- when 2 => Send (Fd, "my_passwd"); -- matched "passwd"
60 -- when Expect_Timeout => null; -- timeout
61 -- when others => null;
62 -- end case;
63 -- Close (Fd);
65 -- You can also combine multiple regular expressions together, and get the
66 -- specific string matching a parenthesis pair by doing something like. If you
67 -- expect either "lang=optional ada" or "lang=ada" from the external process,
68 -- you can group the two together, which is more efficient, and simply get the
69 -- name of the language by doing:
71 -- declare
72 -- Matched : Match_Array (0 .. 2);
73 -- begin
74 -- Expect (Fd, Result, "lang=(optional)? ([a-z]+)", Matched);
75 -- Put_Line ("Seen: " &
76 -- Expect_Out (Fd) (Matched (2).First .. Matched (2).Last));
77 -- end;
79 -- Alternatively, you might choose to use a lower-level interface to the
80 -- processes, where you can give your own input and output filters every
81 -- time characters are read from or written to the process.
83 -- procedure My_Filter
84 -- (Descriptor : Process_Descriptor'Class;
85 -- Str : String;
86 -- User_Data : System.Address)
87 -- is
88 -- begin
89 -- Put_Line (Str);
90 -- end;
92 -- Non_Blocking_Spawn
93 -- (Fd, "tail",
94 -- (new String' ("-f"), new String' ("a_file")));
95 -- Add_Filter (Fd, My_Filter'Access, Output);
96 -- Expect (Fd, Result, "", 0); -- wait forever
98 -- The above example should probably be run in a separate task, since it is
99 -- blocking on the call to Expect.
101 -- Both examples can be combined, for instance to systematically print the
102 -- output seen by expect, even though you still want to let Expect do the
103 -- filtering. You can use the Trace_Filter subprogram for such a filter.
105 -- If you want to get the output of a simple command, and ignore any previous
106 -- existing output, it is recommended to do something like:
108 -- Expect (Fd, Result, ".*", Timeout => 0);
109 -- -- Empty the buffer, by matching everything (after checking
110 -- -- if there was any input).
112 -- Send (Fd, "command");
113 -- Expect (Fd, Result, ".."); -- match only on the output of command
115 -- -----------------
116 -- -- Task Safety --
117 -- -----------------
119 -- This package is not task-safe: there should be not concurrent calls to
120 -- the functions defined in this package. In other words, separate tasks
121 -- may not access the facilities of this package without synchronization
122 -- that serializes access.
124 with System;
125 with GNAT.OS_Lib;
126 with GNAT.Regpat;
128 package GNAT.Expect is
130 type Process_Id is new Integer;
131 Invalid_Pid : constant Process_Id := -1;
132 Null_Pid : constant Process_Id := 0;
134 type Filter_Type is (Output, Input, Died);
135 -- The signals that are emitted by the Process_Descriptor upon state
136 -- changed in the child. One can connect to any of this signal through
137 -- the Add_Filter subprograms.
139 -- Output => Every time new characters are read from the process
140 -- associated with Descriptor, the filter is called with
141 -- these new characters in argument.
143 -- Note that output is only generated when the program is
144 -- blocked in a call to Expect.
146 -- Input => Every time new characters are written to the process
147 -- associated with Descriptor, the filter is called with
148 -- these new characters in argument.
149 -- Note that input is only generated by calls to Send.
151 -- Died => The child process has died, or was explicitly killed
153 type Process_Descriptor is tagged private;
154 -- Contains all the components needed to describe a process handled
155 -- in this package, including a process identifier, file descriptors
156 -- associated with the standard input, output and error, and the buffer
157 -- needed to handle the expect calls.
159 type Process_Descriptor_Access is access Process_Descriptor'Class;
161 ------------------------
162 -- Spawning a process --
163 ------------------------
165 procedure Non_Blocking_Spawn
166 (Descriptor : out Process_Descriptor'Class;
167 Command : String;
168 Args : GNAT.OS_Lib.Argument_List;
169 Buffer_Size : Natural := 4096;
170 Err_To_Out : Boolean := False);
171 -- This call spawns a new process and allows sending commands to
172 -- the process and/or automatic parsing of the output.
174 -- The expect buffer associated with that process can contain at most
175 -- Buffer_Size characters. Older characters are simply discarded when
176 -- this buffer is full. Beware that if the buffer is too big, this could
177 -- slow down the Expect calls if not output is matched, since Expect has
178 -- to match all the regexp against all the characters in the buffer.
179 -- If Buffer_Size is 0, there is no limit (i.e. all the characters are kept
180 -- till Expect matches), but this is slower.
182 -- If Err_To_Out is True, then the standard error of the spawned process is
183 -- connected to the standard output. This is the only way to get the
184 -- Except subprograms also match on output on standard error.
186 -- Invalid_Process is raised if the process could not be spawned.
188 procedure Close (Descriptor : in out Process_Descriptor);
189 -- Terminate the process and close the pipes to it. It implicitly
190 -- does the 'wait' command required to clean up the process table.
191 -- This also frees the buffer associated with the process id. Raise
192 -- Invalid_Process if the process id is invalid.
194 procedure Close
195 (Descriptor : in out Process_Descriptor;
196 Status : out Integer);
197 -- Same as above, but also returns the exit status of the process, as set
198 -- for example by the procedure GNAT.OS_Lib.OS_Exit.
200 procedure Send_Signal
201 (Descriptor : Process_Descriptor;
202 Signal : Integer);
203 -- Send a given signal to the process. Raise Invalid_Process if the process
204 -- id is invalid.
206 procedure Interrupt (Descriptor : in out Process_Descriptor);
207 -- Interrupt the process (the equivalent of Ctrl-C on unix and windows)
208 -- and call close if the process dies.
210 function Get_Input_Fd
211 (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
212 -- Return the input file descriptor associated with Descriptor
214 function Get_Output_Fd
215 (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
216 -- Return the output file descriptor associated with Descriptor
218 function Get_Error_Fd
219 (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
220 -- Return the error output file descriptor associated with Descriptor
222 function Get_Pid
223 (Descriptor : Process_Descriptor) return Process_Id;
224 -- Return the process id associated with a given process descriptor
226 function Get_Command_Output
227 (Command : String;
228 Arguments : GNAT.OS_Lib.Argument_List;
229 Input : String;
230 Status : not null access Integer;
231 Err_To_Out : Boolean := False) return String;
232 -- Execute Command with the specified Arguments and Input, and return the
233 -- generated standard output data as a single string. If Err_To_Out is
234 -- True, generated standard error output is included as well. On return,
235 -- Status is set to the command's exit status.
237 --------------------
238 -- Adding filters --
239 --------------------
241 -- This is a rather low-level interface to subprocesses, since basically
242 -- the filtering is left entirely to the user. See the Expect subprograms
243 -- below for higher level functions.
245 type Filter_Function is access
246 procedure
247 (Descriptor : Process_Descriptor'Class;
248 Str : String;
249 User_Data : System.Address := System.Null_Address);
250 -- Function called every time new characters are read from or written
251 -- to the process.
253 -- Str is a string of all these characters.
255 -- User_Data, if specified, is a user specific data that will be passed to
256 -- the filter. Note that no checks are done on this parameter that should
257 -- be used with cautiousness.
259 procedure Add_Filter
260 (Descriptor : in out Process_Descriptor;
261 Filter : Filter_Function;
262 Filter_On : Filter_Type := Output;
263 User_Data : System.Address := System.Null_Address;
264 After : Boolean := False);
265 -- Add a new filter for one of the filter type. This filter will be
266 -- run before all the existing filters, unless After is set True,
267 -- in which case it will be run after existing filters. User_Data
268 -- is passed as is to the filter procedure.
270 procedure Remove_Filter
271 (Descriptor : in out Process_Descriptor;
272 Filter : Filter_Function);
273 -- Remove a filter from the list of filters (whatever the type of the
274 -- filter).
276 procedure Trace_Filter
277 (Descriptor : Process_Descriptor'Class;
278 Str : String;
279 User_Data : System.Address := System.Null_Address);
280 -- Function that can be used a filter and that simply outputs Str on
281 -- Standard_Output. This is mainly used for debugging purposes.
282 -- User_Data is ignored.
284 procedure Lock_Filters (Descriptor : in out Process_Descriptor);
285 -- Temporarily disables all output and input filters. They will be
286 -- reactivated only when Unlock_Filters has been called as many times as
287 -- Lock_Filters;
289 procedure Unlock_Filters (Descriptor : in out Process_Descriptor);
290 -- Unlocks the filters. They are reactivated only if Unlock_Filters
291 -- has been called as many times as Lock_Filters.
293 ------------------
294 -- Sending data --
295 ------------------
297 procedure Send
298 (Descriptor : in out Process_Descriptor;
299 Str : String;
300 Add_LF : Boolean := True;
301 Empty_Buffer : Boolean := False);
302 -- Send a string to the file descriptor.
304 -- The string is not formatted in any way, except if Add_LF is True,
305 -- in which case an ASCII.LF is added at the end, so that Str is
306 -- recognized as a command by the external process.
308 -- If Empty_Buffer is True, any input waiting from the process (or in the
309 -- buffer) is first discarded before the command is sent. The output
310 -- filters are of course called as usual.
312 -----------------------------------------------------------
313 -- Working on the output (single process, simple regexp) --
314 -----------------------------------------------------------
316 type Expect_Match is new Integer;
317 Expect_Full_Buffer : constant Expect_Match := -1;
318 -- If the buffer was full and some characters were discarded
320 Expect_Timeout : constant Expect_Match := -2;
321 -- If not output matching the regexps was found before the timeout
323 function "+" (S : String) return GNAT.OS_Lib.String_Access;
324 -- Allocate some memory for the string. This is merely a convenience
325 -- function to help create the array of regexps in the call to Expect.
327 procedure Expect
328 (Descriptor : in out Process_Descriptor;
329 Result : out Expect_Match;
330 Regexp : String;
331 Timeout : Integer := 10000;
332 Full_Buffer : Boolean := False);
333 -- Wait till a string matching Fd can be read from Fd, and return 1
334 -- if a match was found.
336 -- It consumes all the characters read from Fd until a match found, and
337 -- then sets the return values for the subprograms Expect_Out and
338 -- Expect_Out_Match.
340 -- The empty string "" will never match, and can be used if you only want
341 -- to match after a specific timeout. Beware that if Timeout is -1 at the
342 -- time, the current task will be blocked forever.
344 -- This command times out after Timeout milliseconds (or never if Timeout
345 -- is -1). In that case, Expect_Timeout is returned. The value returned by
346 -- Expect_Out and Expect_Out_Match are meaningless in that case.
348 -- Note that using a timeout of 0ms leads to unpredictable behavior, since
349 -- the result depends on whether the process has already sent some output
350 -- the first time Expect checks, and this depends on the operating system.
352 -- The regular expression must obey the syntax described in GNAT.Regpat.
354 -- If Full_Buffer is True, then Expect will match if the buffer was too
355 -- small and some characters were about to be discarded. In that case,
356 -- Expect_Full_Buffer is returned.
358 procedure Expect
359 (Descriptor : in out Process_Descriptor;
360 Result : out Expect_Match;
361 Regexp : GNAT.Regpat.Pattern_Matcher;
362 Timeout : Integer := 10000;
363 Full_Buffer : Boolean := False);
364 -- Same as the previous one, but with a precompiled regular expression.
365 -- This is more efficient however, especially if you are using this
366 -- expression multiple times, since this package won't need to recompile
367 -- the regexp every time.
369 procedure Expect
370 (Descriptor : in out Process_Descriptor;
371 Result : out Expect_Match;
372 Regexp : String;
373 Matched : out GNAT.Regpat.Match_Array;
374 Timeout : Integer := 10000;
375 Full_Buffer : Boolean := False);
376 -- Same as above, but it is now possible to get the indexes of the
377 -- substrings for the parentheses in the regexp (see the example at the
378 -- top of this package, as well as the documentation in the package
379 -- GNAT.Regpat).
381 -- Matched'First should be 0, and this index will contain the indexes for
382 -- the whole string that was matched. The index 1 will contain the indexes
383 -- for the first parentheses-pair, and so on.
385 ------------
386 -- Expect --
387 ------------
389 procedure Expect
390 (Descriptor : in out Process_Descriptor;
391 Result : out Expect_Match;
392 Regexp : GNAT.Regpat.Pattern_Matcher;
393 Matched : out GNAT.Regpat.Match_Array;
394 Timeout : Integer := 10000;
395 Full_Buffer : Boolean := False);
396 -- Same as above, but with a precompiled regular expression
398 -------------------------------------------------------------
399 -- Working on the output (single process, multiple regexp) --
400 -------------------------------------------------------------
402 type Regexp_Array is array (Positive range <>) of GNAT.OS_Lib.String_Access;
404 type Pattern_Matcher_Access is access all GNAT.Regpat.Pattern_Matcher;
405 type Compiled_Regexp_Array is array (Positive range <>)
406 of Pattern_Matcher_Access;
408 function "+"
409 (P : GNAT.Regpat.Pattern_Matcher)
410 return Pattern_Matcher_Access;
411 -- Allocate some memory for the pattern matcher.
412 -- This is only a convenience function to help create the array of
413 -- compiled regular expressions.
415 procedure Expect
416 (Descriptor : in out Process_Descriptor;
417 Result : out Expect_Match;
418 Regexps : Regexp_Array;
419 Timeout : Integer := 10000;
420 Full_Buffer : Boolean := False);
421 -- Wait till a string matching one of the regular expressions in Regexps
422 -- is found. This function returns the index of the regexp that matched.
423 -- This command is blocking, but will timeout after Timeout milliseconds.
424 -- In that case, Timeout is returned.
426 procedure Expect
427 (Descriptor : in out Process_Descriptor;
428 Result : out Expect_Match;
429 Regexps : Compiled_Regexp_Array;
430 Timeout : Integer := 10000;
431 Full_Buffer : Boolean := False);
432 -- Same as the previous one, but with precompiled regular expressions.
433 -- This can be much faster if you are using them multiple times.
435 procedure Expect
436 (Descriptor : in out Process_Descriptor;
437 Result : out Expect_Match;
438 Regexps : Regexp_Array;
439 Matched : out GNAT.Regpat.Match_Array;
440 Timeout : Integer := 10000;
441 Full_Buffer : Boolean := False);
442 -- Same as above, except that you can also access the parenthesis
443 -- groups inside the matching regular expression.
444 -- The first index in Matched must be 0, or Constraint_Error will be
445 -- raised. The index 0 contains the indexes for the whole string that was
446 -- matched, the index 1 contains the indexes for the first parentheses
447 -- pair, and so on.
449 procedure Expect
450 (Descriptor : in out Process_Descriptor;
451 Result : out Expect_Match;
452 Regexps : Compiled_Regexp_Array;
453 Matched : out GNAT.Regpat.Match_Array;
454 Timeout : Integer := 10000;
455 Full_Buffer : Boolean := False);
456 -- Same as above, but with precompiled regular expressions.
457 -- The first index in Matched must be 0, or Constraint_Error will be
458 -- raised.
460 -------------------------------------------
461 -- Working on the output (multi-process) --
462 -------------------------------------------
464 type Multiprocess_Regexp is record
465 Descriptor : Process_Descriptor_Access;
466 Regexp : Pattern_Matcher_Access;
467 end record;
468 type Multiprocess_Regexp_Array is array (Positive range <>)
469 of Multiprocess_Regexp;
471 procedure Expect
472 (Result : out Expect_Match;
473 Regexps : Multiprocess_Regexp_Array;
474 Matched : out GNAT.Regpat.Match_Array;
475 Timeout : Integer := 10000;
476 Full_Buffer : Boolean := False);
477 -- Same as above, but for multi processes
479 procedure Expect
480 (Result : out Expect_Match;
481 Regexps : Multiprocess_Regexp_Array;
482 Timeout : Integer := 10000;
483 Full_Buffer : Boolean := False);
484 -- Same as the previous one, but for multiple processes.
485 -- This procedure finds the first regexp that match the associated process.
487 ------------------------
488 -- Getting the output --
489 ------------------------
491 procedure Flush
492 (Descriptor : in out Process_Descriptor;
493 Timeout : Integer := 0);
494 -- Discard all output waiting from the process.
496 -- This output is simply discarded, and no filter is called. This output
497 -- will also not be visible by the next call to Expect, nor will any
498 -- output currently buffered.
500 -- Timeout is the delay for which we wait for output to be available from
501 -- the process. If 0, we only get what is immediately available.
503 function Expect_Out (Descriptor : Process_Descriptor) return String;
504 -- Return the string matched by the last Expect call.
506 -- The returned string is in fact the concatenation of all the strings
507 -- read from the file descriptor up to, and including, the characters
508 -- that matched the regular expression.
510 -- For instance, with an input "philosophic", and a regular expression
511 -- "hi" in the call to expect, the strings returned the first and second
512 -- time would be respectively "phi" and "losophi".
514 function Expect_Out_Match (Descriptor : Process_Descriptor) return String;
515 -- Return the string matched by the last Expect call.
517 -- The returned string includes only the character that matched the
518 -- specific regular expression. All the characters that came before are
519 -- simply discarded.
521 -- For instance, with an input "philosophic", and a regular expression
522 -- "hi" in the call to expect, the strings returned the first and second
523 -- time would both be "hi".
525 ----------------
526 -- Exceptions --
527 ----------------
529 Invalid_Process : exception;
530 -- Raised by most subprograms above when the parameter Descriptor is not a
531 -- valid process or is a closed process.
533 Process_Died : exception;
534 -- Raised by all the expect subprograms if Descriptor was originally a
535 -- valid process that died while Expect was executing. It is also raised
536 -- when Expect receives an end-of-file.
538 private
539 type Filter_List_Elem;
540 type Filter_List is access Filter_List_Elem;
541 type Filter_List_Elem is record
542 Filter : Filter_Function;
543 User_Data : System.Address;
544 Filter_On : Filter_Type;
545 Next : Filter_List;
546 end record;
548 type Pipe_Type is record
549 Input, Output : GNAT.OS_Lib.File_Descriptor;
550 end record;
551 -- This type represents a pipe, used to communicate between two processes
553 procedure Set_Up_Communications
554 (Pid : in out Process_Descriptor;
555 Err_To_Out : Boolean;
556 Pipe1 : not null access Pipe_Type;
557 Pipe2 : not null access Pipe_Type;
558 Pipe3 : not null access Pipe_Type);
559 -- Set up all the communication pipes and file descriptors prior to
560 -- spawning the child process.
562 procedure Set_Up_Parent_Communications
563 (Pid : in out Process_Descriptor;
564 Pipe1 : in out Pipe_Type;
565 Pipe2 : in out Pipe_Type;
566 Pipe3 : in out Pipe_Type);
567 -- Finish the set up of the pipes while in the parent process
569 procedure Set_Up_Child_Communications
570 (Pid : in out Process_Descriptor;
571 Pipe1 : in out Pipe_Type;
572 Pipe2 : in out Pipe_Type;
573 Pipe3 : in out Pipe_Type;
574 Cmd : String;
575 Args : System.Address);
576 -- Finish the set up of the pipes while in the child process
577 -- This also spawns the child process (based on Cmd).
578 -- On systems that support fork, this procedure is executed inside the
579 -- newly created process.
581 type Process_Descriptor is tagged record
582 Pid : aliased Process_Id := Invalid_Pid;
583 Input_Fd : GNAT.OS_Lib.File_Descriptor := GNAT.OS_Lib.Invalid_FD;
584 Output_Fd : GNAT.OS_Lib.File_Descriptor := GNAT.OS_Lib.Invalid_FD;
585 Error_Fd : GNAT.OS_Lib.File_Descriptor := GNAT.OS_Lib.Invalid_FD;
586 Filters_Lock : Integer := 0;
588 Filters : Filter_List := null;
590 Buffer : GNAT.OS_Lib.String_Access := null;
591 Buffer_Size : Natural := 0;
592 Buffer_Index : Natural := 0;
594 Last_Match_Start : Natural := 0;
595 Last_Match_End : Natural := 0;
596 end record;
598 -- The following subprogram is provided for use in the body, and also
599 -- possibly in future child units providing extensions to this package.
601 procedure Portable_Execvp
602 (Pid : not null access Process_Id;
603 Cmd : String;
604 Args : System.Address);
605 pragma Import (C, Portable_Execvp, "__gnat_expect_portable_execvp");
606 -- Executes, in a portable way, the command Cmd (full path must be
607 -- specified), with the given Args. Args must be an array of string
608 -- pointers. Note that the first element in Args must be the executable
609 -- name, and the last element must be a null pointer. The returned value
610 -- in Pid is the process ID, or zero if not supported on the platform.
612 end GNAT.Expect;