-- --
-- S p e c --
-- --
--- --
--- Copyright (C) 2000-2002 Ada Core Technologies, Inc. --
+-- Copyright (C) 2000-2007, AdaCore --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
-- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
-- for more details. You should have received a copy of the GNU General --
-- Public License distributed with GNAT; see file COPYING. If not, write --
--- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
--- MA 02111-1307, USA. --
+-- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
+-- Boston, MA 02110-1301, USA. --
-- --
-- As a special exception, if other files instantiate generics from this --
-- unit, or you link this unit with other files to produce an executable, --
-- however invalidate any other reasons why the executable file might be --
-- covered by the GNU Public License. --
-- --
--- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). --
+-- GNAT was originally developed by the GNAT team at New York University. --
+-- Extensive contributions were provided by Ada Core Technologies Inc. --
-- --
------------------------------------------------------------------------------
-- Currently this package is implemented on all native GNAT ports except
-- for VMS. It is not yet implemented for any of the cross-ports (e.g. it
-- is not available for VxWorks or LynxOS).
---
--- Usage
--- =====
---
+
+-- -----------
+-- -- Usage --
+-- -----------
+
-- This package provides a set of subprograms similar to what is available
-- with the standard Tcl Expect tool.
-- It allows you to easily spawn and communicate with an external process.
-- You can send commands or inputs to the process, and compare the output
-- with some expected regular expression.
---
+
-- Usage example:
---
+
-- Non_Blocking_Spawn
-- (Fd, "ftp",
--- (1 => new String' ("machine@domaine")));
+-- (1 => new String' ("machine@domain")));
-- Timeout := 10000; -- 10 seconds
-- Expect (Fd, Result, Regexp_Array'(+"\(user\)", +"\(passwd\)"),
-- Timeout);
-- when others => null;
-- end case;
-- Close (Fd);
---
+
-- You can also combine multiple regular expressions together, and get the
-- specific string matching a parenthesis pair by doing something like. If you
-- expect either "lang=optional ada" or "lang=ada" from the external process,
-- you can group the two together, which is more efficient, and simply get the
-- name of the language by doing:
---
+
-- declare
--- Matched : Regexp_Array (0 .. 2);
+-- Matched : Match_Array (0 .. 2);
-- begin
-- Expect (Fd, Result, "lang=(optional)? ([a-z]+)", Matched);
-- Put_Line ("Seen: " &
-- Expect_Out (Fd) (Matched (2).First .. Matched (2).Last));
-- end;
---
+
-- Alternatively, you might choose to use a lower-level interface to the
-- processes, where you can give your own input and output filters every
-- time characters are read from or written to the process.
---
+
-- procedure My_Filter
-- (Descriptor : Process_Descriptor'Class;
-- Str : String;
-- begin
-- Put_Line (Str);
-- end;
---
+
-- Non_Blocking_Spawn
-- (Fd, "tail",
-- (new String' ("-f"), new String' ("a_file")));
-- Add_Filter (Fd, My_Filter'Access, Output);
-- Expect (Fd, Result, "", 0); -- wait forever
---
+
-- The above example should probably be run in a separate task, since it is
-- blocking on the call to Expect.
---
+
-- Both examples can be combined, for instance to systematically print the
-- output seen by expect, even though you still want to let Expect do the
-- filtering. You can use the Trace_Filter subprogram for such a filter.
---
+
-- If you want to get the output of a simple command, and ignore any previous
-- existing output, it is recommended to do something like:
---
+
-- Expect (Fd, Result, ".*", Timeout => 0);
-- -- Empty the buffer, by matching everything (after checking
-- -- if there was any input).
---
+
-- Send (Fd, "command");
-- Expect (Fd, Result, ".."); -- match only on the output of command
---
--- Task Safety
--- ===========
---
--- This package is not task-safe. However, you can easily make is task safe
--- by encapsulating the type Process_Descriptor in a protected record.
--- There should not be concurrent calls to Expect.
+
+-- -----------------
+-- -- Task Safety --
+-- -----------------
+
+-- This package is not task-safe: there should be not concurrent calls to
+-- the functions defined in this package. In other words, separate tasks
+-- may not access the facilities of this package without synchronization
+-- that serializes access.
with System;
with GNAT.OS_Lib;
procedure Close (Descriptor : in out Process_Descriptor);
-- Terminate the process and close the pipes to it. It implicitly
-- does the 'wait' command required to clean up the process table.
- -- This also frees the buffer associated with the process id.
+ -- This also frees the buffer associated with the process id. Raise
+ -- Invalid_Process if the process id is invalid.
procedure Close
(Descriptor : in out Process_Descriptor;
Status : out Integer);
- -- Same as above, but also returns the exit status of the process,
- -- as set for example by the procedure GNAT.OS_Lib.OS_Exit.
+ -- Same as above, but also returns the exit status of the process, as set
+ -- for example by the procedure GNAT.OS_Lib.OS_Exit.
procedure Send_Signal
(Descriptor : Process_Descriptor;
Signal : Integer);
- -- Send a given signal to the process.
+ -- Send a given signal to the process. Raise Invalid_Process if the process
+ -- id is invalid.
procedure Interrupt (Descriptor : in out Process_Descriptor);
-- Interrupt the process (the equivalent of Ctrl-C on unix and windows)
-- and call close if the process dies.
function Get_Input_Fd
- (Descriptor : Process_Descriptor)
- return GNAT.OS_Lib.File_Descriptor;
- -- Return the input file descriptor associated with Descriptor.
+ (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
+ -- Return the input file descriptor associated with Descriptor
function Get_Output_Fd
- (Descriptor : Process_Descriptor)
- return GNAT.OS_Lib.File_Descriptor;
- -- Return the output file descriptor associated with Descriptor.
+ (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
+ -- Return the output file descriptor associated with Descriptor
function Get_Error_Fd
- (Descriptor : Process_Descriptor)
- return GNAT.OS_Lib.File_Descriptor;
- -- Return the error output file descriptor associated with Descriptor.
+ (Descriptor : Process_Descriptor) return GNAT.OS_Lib.File_Descriptor;
+ -- Return the error output file descriptor associated with Descriptor
function Get_Pid
- (Descriptor : Process_Descriptor)
- return Process_Id;
- -- Return the process id associated with a given process descriptor.
+ (Descriptor : Process_Descriptor) return Process_Id;
+ -- Return the process id assocated with a given process descriptor
+
+ function Get_Command_Output
+ (Command : String;
+ Arguments : GNAT.OS_Lib.Argument_List;
+ Input : String;
+ Status : not null access Integer;
+ Err_To_Out : Boolean := False) return String;
+ -- Execute Command with the specified Arguments and Input, and return the
+ -- generated standard output data as a single string. If Err_To_Out is
+ -- True, generated standard error output is included as well. On return,
+ -- Status is set to the command's exit status.
--------------------
-- Adding filters --
type Expect_Match is new Integer;
Expect_Full_Buffer : constant Expect_Match := -1;
- -- If the buffer was full and some characters were discarded.
+ -- If the buffer was full and some characters were discarded
Expect_Timeout : constant Expect_Match := -2;
- -- If not output matching the regexps was found before the timeout.
+ -- If not output matching the regexps was found before the timeout
function "+" (S : String) return GNAT.OS_Lib.String_Access;
-- Allocate some memory for the string. This is merely a convenience
- -- convenience function to help create the array of regexps in the
- -- call to Expect.
+ -- function to help create the array of regexps in the call to Expect.
procedure Expect
(Descriptor : in out Process_Descriptor;
Matched : out GNAT.Regpat.Match_Array;
Timeout : Integer := 10000;
Full_Buffer : Boolean := False);
- -- Same as above, but with a precompiled regular expression.
+ -- Same as above, but with a precompiled regular expression
-------------------------------------------------------------
-- Working on the output (single process, multiple regexp) --
type Regexp_Array is array (Positive range <>) of GNAT.OS_Lib.String_Access;
- type Pattern_Matcher_Access is access GNAT.Regpat.Pattern_Matcher;
+ type Pattern_Matcher_Access is access all GNAT.Regpat.Pattern_Matcher;
type Compiled_Regexp_Array is array (Positive range <>)
of Pattern_Matcher_Access;
Matched : out GNAT.Regpat.Match_Array;
Timeout : Integer := 10000;
Full_Buffer : Boolean := False);
- -- Same as above, but for multi processes.
+ -- Same as above, but for multi processes
procedure Expect
(Result : out Expect_Match;
type Pipe_Type is record
Input, Output : GNAT.OS_Lib.File_Descriptor;
end record;
- -- This type represents a pipe, used to communicate between two processes.
+ -- This type represents a pipe, used to communicate between two processes
procedure Set_Up_Communications
(Pid : in out Process_Descriptor;
Err_To_Out : Boolean;
- Pipe1 : access Pipe_Type;
- Pipe2 : access Pipe_Type;
- Pipe3 : access Pipe_Type);
+ Pipe1 : not null access Pipe_Type;
+ Pipe2 : not null access Pipe_Type;
+ Pipe3 : not null access Pipe_Type);
-- Set up all the communication pipes and file descriptors prior to
-- spawning the child process.
-- possibly in future child units providing extensions to this package.
procedure Portable_Execvp
- (Pid : access Process_Id;
+ (Pid : not null access Process_Id;
Cmd : String;
Args : System.Address);
pragma Import (C, Portable_Execvp, "__gnat_expect_portable_execvp");
projects / gcc.git / blobdiff