| blob | 5df3e73d43b34813a135a88577ced8cc6c4cb6ce |
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 -- $Revision: 1.8 $
10 -- --
11 -- Copyright (C) 2000-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 ------------------------------------------------------------------------------
35 -- Currently this package is implemented on all native GNAT ports except
36 -- for VMS. It is not yet implemented for any of the cross-ports (e.g. it
37 -- is not available for VxWorks or LynxOS).
38 --
39 -- Usage
40 -- =====
41 --
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.
48 --
49 -- Usage example:
50 --
51 -- Non_Blocking_Spawn (Fd, "ftp machine@domaine");
52 -- Timeout := 10000; -- 10 seconds
53 -- Expect (Fd, Result, Regexp_Array'(+"\(user\)", +"\(passwd\)"),
54 -- Timeout);
55 -- case Result is
56 -- when 1 => Send (Fd, "my_name"); -- matched "user"
57 -- when 2 => Send (Fd, "my_passwd"); -- matched "passwd"
58 -- when Expect_Timeout => null; -- timeout
59 -- when others => null;
60 -- end case;
61 -- Close (Fd);
62 --
63 -- You can also combine multiple regular expressions together, and get the
64 -- specific string matching a parenthesis pair by doing something like. If you
65 -- expect either "lang=optional ada" or "lang=ada" from the external process,
66 -- you can group the two together, which is more efficient, and simply get the
67 -- name of the language by doing:
68 --
69 -- declare
70 -- Matched : Regexp_Array (0 .. 2);
71 -- begin
72 -- Expect (Fd, Result, "lang=(optional)? ([a-z]+)", Matched);
73 -- Put_Line ("Seen: " &
74 -- Expect_Out (Fd) (Matched (2).First .. Matched (2).Last));
75 -- end;
76 --
77 -- Alternatively, you might choose to use a lower-level interface to the
78 -- processes, where you can give your own input and output filters every
79 -- time characters are read from or written to the process.
80 --
81 -- procedure My_Filter (Descriptor : Process_Descriptor; Str : String) is
82 -- begin
83 -- Put_Line (Str);
84 -- end;
85 --
86 -- Fd := Non_Blocking_Spawn ("tail -f a_file");
87 -- Add_Filter (Fd, My_Filter'Access, Output);
88 -- Expect (Fd, Result, "", 0); -- wait forever
89 --
90 -- The above example should probably be run in a separate task, since it is
91 -- blocking on the call to Expect.
92 --
93 -- Both examples can be combined, for instance to systematically print the
94 -- output seen by expect, even though you still want to let Expect do the
95 -- filtering. You can use the Trace_Filter subprogram for such a filter.
96 --
97 -- If you want to get the output of a simple command, and ignore any previous
98 -- existing output, it is recommended to do something like:
99 --
100 -- Expect (Fd, Result, ".*", Timeout => 0);
101 -- -- empty the buffer, by matching everything (after checking
102 -- -- if there was any input).
103 -- Send (Fd, "command");
104 -- Expect (Fd, Result, ".."); -- match only on the output of command
105 --
106 -- Task Safety
107 -- ===========
108 --
109 -- This package is not task-safe. However, you can easily make is task safe
110 -- by encapsulating the type Process_Descriptor in a protected record.
111 -- There should not be concurrent calls to Expect.
124 -- The signals that are emitted by the Process_Descriptor upon state
125 -- changed in the child. One can connect to any of this signal through
126 -- the Add_Filter subprograms.
127 --
128 -- Output => Every time new characters are read from the process
129 -- associated with Descriptor, the filter is called with
130 -- these new characters in argument.
131 --
132 -- Note that output is only generated when the program is
133 -- blocked in a call to Expect.
134 --
135 -- Input => Every time new characters are written to the process
136 -- associated with Descriptor, the filter is called with
137 -- these new characters in argument.
138 -- Note that input is only generated by calls to Send.
139 --
140 -- Died => The child process has died, or was explicitly killed
143 -- Contains all the components needed to describe a process handled
144 -- in this package, including a process identifier, file descriptors
145 -- associated with the standard input, output and error, and the buffer
146 -- needed to handle the expect calls.
150 ------------------------
151 -- Spawning a process --
152 ------------------------
154 procedure Non_Blocking_Spawn
160 -- This call spawns a new process and allows sending commands to
161 -- the process and/or automatic parsing of the output.
162 --
163 -- The expect buffer associated with that process can contain at most
164 -- Buffer_Size characters. Older characters are simply discarded when
165 -- this buffer is full. Beware that if the buffer is too big, this could
166 -- slow down the Expect calls if not output is matched, since Expect has
167 -- to match all the regexp against all the characters in the buffer.
168 -- If Buffer_Size is 0, there is no limit (ie all the characters are kept
169 -- till Expect matches), but this is slower.
170 --
171 -- If Err_To_Out is True, then the standard error of the spawned process is
172 -- connected to the standard output. This is the only way to get the
173 -- Except subprograms also match on output on standard error.
174 --
175 -- Invalid_Process is raised if the process could not be spawned.
178 -- Terminate the process and close the pipes to it. It implicitly
179 -- does the 'wait' command required to clean up the process table.
180 -- This also frees the buffer associated with the process id.
182 procedure Send_Signal
185 -- Send a given signal to the process.
188 -- Interrupt the process (the equivalent of Ctrl-C on unix and windows)
189 -- and call close if the process dies.
191 function Get_Input_Fd
194 -- Return the input file descriptor associated with Descriptor.
196 function Get_Output_Fd
199 -- Return the output file descriptor associated with Descriptor.
201 function Get_Error_Fd
204 -- Return the error output file descriptor associated with Descriptor.
206 function Get_Pid
209 -- Return the process id assocated with a given process descriptor.
211 --------------------
212 -- Adding filters --
213 --------------------
215 -- This is a rather low-level interface to subprocesses, since basically
216 -- the filtering is left entirely to the user. See the Expect subprograms
217 -- below for higher level functions.
220 procedure
224 -- Function called every time new characters are read from or written
225 -- to the process.
226 --
227 -- Str is a string of all these characters.
228 --
229 -- User_Data, if specified, is a user specific data that will be passed to
230 -- the filter. Note that no checks are done on this parameter that should
231 -- be used with cautiousness.
233 procedure Add_Filter
239 -- Add a new filter for one of the filter type. This filter will be
240 -- run before all the existing filters, unless After is set True,
241 -- in which case it will be run after existing filters. User_Data
242 -- is passed as is to the filter procedure.
244 procedure Remove_Filter
247 -- Remove a filter from the list of filters (whatever the type of the
248 -- filter).
250 procedure Trace_Filter
254 -- Function that can be used a filter and that simply outputs Str on
255 -- Standard_Output. This is mainly used for debugging purposes.
256 -- User_Data is ignored.
259 -- Temporarily disables all output and input filters. They will be
260 -- reactivated only when Unlock_Filters has been called as many times as
261 -- Lock_Filters;
264 -- Unlocks the filters. They are reactivated only if Unlock_Filters
265 -- has been called as many times as Lock_Filters.
267 ------------------
268 -- Sending data --
269 ------------------
271 procedure Send
276 -- Send a string to the file descriptor.
277 --
278 -- The string is not formatted in any way, except if Add_LF is True,
279 -- in which case an ASCII.LF is added at the end, so that Str is
280 -- recognized as a command by the external process.
281 --
282 -- If Empty_Buffer is True, any input waiting from the process (or in the
283 -- buffer) is first discarded before the command is sent. The output
284 -- filters are of course called as usual.
286 -----------------------------------------------------------
287 -- Working on the output (single process, simple regexp) --
288 -----------------------------------------------------------
292 -- If the buffer was full and some characters were discarded.
295 -- If not output matching the regexps was found before the timeout.
298 -- Allocate some memory for the string. This is merely a convenience
299 -- convenience function to help create the array of regexps in the
300 -- call to Expect.
302 procedure Expect
308 -- Wait till a string matching Fd can be read from Fd, and return 1
309 -- if a match was found.
310 --
311 -- It consumes all the characters read from Fd until a match found, and
312 -- then sets the return values for the subprograms Expect_Out and
313 -- Expect_Out_Match.
314 --
315 -- The empty string "" will never match, and can be used if you only want
316 -- to match after a specific timeout. Beware that if Timeout is -1 at the
317 -- time, the current task will be blocked forever.
318 --
319 -- This command times out after Timeout milliseconds (or never if Timeout
320 -- is -1). In that case, Expect_Timeout is returned. The value returned by
321 -- Expect_Out and Expect_Out_Match are meaningless in that case.
322 --
323 -- Note that using a timeout of 0ms leads to unpredictable behavior, since
324 -- the result depends on whether the process has already sent some output
325 -- the first time Expect checks, and this depends on the operating system.
326 --
327 -- The regular expression must obey the syntax described in GNAT.Regpat.
328 --
329 -- If Full_Buffer is True, then Expect will match if the buffer was too
330 -- small and some characters were about to be discarded. In that case,
331 -- Expect_Full_Buffer is returned.
333 procedure Expect
339 -- Same as the previous one, but with a precompiled regular expression.
340 -- This is more efficient however, especially if you are using this
341 -- expression multiple times, since this package won't need to recompile
342 -- the regexp every time.
344 procedure Expect
351 -- Same as above, but it is now possible to get the indexes of the
352 -- substrings for the parentheses in the regexp (see the example at the
353 -- top of this package, as well as the documentation in the package
354 -- GNAT.Regpat).
355 --
356 -- Matched'First should be 0, and this index will contain the indexes for
357 -- the whole string that was matched. The index 1 will contain the indexes
358 -- for the first parentheses-pair, and so on.
360 ------------
361 -- Expect --
362 ------------
364 procedure Expect
371 -- Same as above, but with a precompiled regular expression.
373 -------------------------------------------------------------
374 -- Working on the output (single process, multiple regexp) --
375 -------------------------------------------------------------
386 -- Allocate some memory for the pattern matcher.
387 -- This is only a convenience function to help create the array of
388 -- compiled regular expressoins.
390 procedure Expect
396 -- Wait till a string matching one of the regular expressions in Regexps
397 -- is found. This function returns the index of the regexp that matched.
398 -- This command is blocking, but will timeout after Timeout milliseconds.
399 -- In that case, Timeout is returned.
401 procedure Expect
407 -- Same as the previous one, but with precompiled regular expressions.
408 -- This can be much faster if you are using them multiple times.
410 procedure Expect
417 -- Same as above, except that you can also access the parenthesis
418 -- groups inside the matching regular expression.
419 -- The first index in Matched must be 0, or Constraint_Error will be
420 -- raised. The index 0 contains the indexes for the whole string that was
421 -- matched, the index 1 contains the indexes for the first parentheses
422 -- pair, and so on.
424 procedure Expect
431 -- Same as above, but with precompiled regular expressions.
432 -- The first index in Matched must be 0, or Constraint_Error will be
433 -- raised.
435 -------------------------------------------
436 -- Working on the output (multi-process) --
437 -------------------------------------------
446 procedure Expect
452 -- Same as above, but for multi processes.
454 procedure Expect
459 -- Same as the previous one, but for multiple processes.
460 -- This procedure finds the first regexp that match the associated process.
462 ------------------------
463 -- Getting the output --
464 ------------------------
466 procedure Flush
469 -- Discard all output waiting from the process.
470 --
471 -- This output is simply discarded, and no filter is called. This output
472 -- will also not be visible by the next call to Expect, nor will any
473 -- output currently buffered.
474 --
475 -- Timeout is the delay for which we wait for output to be available from
476 -- the process. If 0, we only get what is immediately available.
479 -- Return the string matched by the last Expect call.
480 --
481 -- The returned string is in fact the concatenation of all the strings
482 -- read from the file descriptor up to, and including, the characters
483 -- that matched the regular expression.
484 --
485 -- For instance, with an input "philosophic", and a regular expression
486 -- "hi" in the call to expect, the strings returned the first and second
487 -- time would be respectively "phi" and "losophi".
490 -- Return the string matched by the last Expect call.
491 --
492 -- The returned string includes only the character that matched the
493 -- specific regular expression. All the characters that came before are
494 -- simply discarded.
495 --
496 -- For instance, with an input "philosophic", and a regular expression
497 -- "hi" in the call to expect, the strings returned the first and second
498 -- time would both be "hi".
500 ----------------
501 -- Exceptions --
502 ----------------
505 -- Raised by most subprograms above when the parameter Descriptor is not a
506 -- valid process or is a closed process.
509 -- Raised by all the expect subprograms if Descriptor was originally a
510 -- valid process that died while Expect was executing. It is also raised
511 -- when Expect receives an end-of-file.
513 ------------------------
514 -- Internal functions --
515 ------------------------
517 -- The following subprograms are provided so that it is easy to write
518 -- extensions to this package. However, clients should not use these
519 -- routines directly.
522 -- Executes, in a portable way, the command Cmd (full path must be
523 -- specified), with the given Args. Note that the first element in Args
524 -- must be the executable name, and the last element must be a null
525 -- pointer
527 private
540 -- This type represents a pipe, used to communicate between two processes.
542 procedure Set_Up_Communications
548 -- Set up all the communication pipes and file descriptors prior to
549 -- spawning the child process.
551 procedure Set_Up_Parent_Communications
556 -- Finish the set up of the pipes while in the parent process
558 procedure Set_Up_Child_Communications
565 -- Finish the set up of the pipes while in the child process
566 -- This also spawns the child process (based on Cmd).
567 -- On systems that support fork, this procedure is executed inside the
568 -- newly created process.