Wx::Perl::ProcessStream(3pm)				User Contributed Perl Documentation			      Wx::Perl::ProcessStream(3pm)

NAME

       Wx::Perl::ProcessStream - access IO of external processes via events

VERSION

       Version 0.32

SYNOPSYS

	   use Wx::Perl::ProcessStream qw( :everything );

	   EVT_WXP_PROCESS_STREAM_STDOUT    ( $self, &evt_process_stdout );
	   EVT_WXP_PROCESS_STREAM_STDERR    ( $self, &evt_process_stderr );
	   EVT_WXP_PROCESS_STREAM_EXIT	    ( $self, &evt_process_exit   );
	   EVT_WXP_PROCESS_STREAM_MAXLINES  ( $self, &evt_process_maxlines  );

	   my $proc1 = Wx::Perl::ProcessStream::Process->new('perl -e"print qq($_
) for(@INC);"', 'MyName1', $self);
	   $proc1->Run;

	   my $command = 'executable.exe parm1 parm2 parm3'
	   my $proc2 = Wx::Perl::ProcessStream::Process->new($command, 'MyName2', $self)
						       ->Run;

	   my @args = qw( executable.exe parm1 parm2 parm3 );
	   my $proc3 = Wx::Perl::ProcessStream::Process->new(@args, 'MyName2', $self);
	   $proc3->Run;

	   my $proc4 = Wx::Perl::ProcessStream::Process->new(@args, 'MyName2', $self, 'readline')->Run;

	   my $proc5 = Wx::Perl::ProcessStream::Process->new(@args, 'MyName2', $self);

	   sub evt_process_stdout {
	       my ($self, $event) = @_;
	       $event->Skip(1);
	       my $process = $event->GetProcess;
	       my $line = $event->GetLine;

	       if($line eq 'something we are waiting for') {
		   $process->WriteProcess('a message to stdin');

		   $process->CloseInput() if($finishedwriting);
	       }
	       ............
	       # To Clear Buffer
	       my @buffers = @{ $process->GetStdOutBuffer };

	   }

	   sub evt_process_stderr {
	       my ($self, $event) = @_;
	       $event->Skip(1);
	       my $process = $event->GetProcess;
	       my $line = $event->GetLine;
	       print STDERR qq($line
);
	       # To Clear Buffer
	       my @errors = @{ $process->GetStdErrBuffer };
	   }

	   sub evt_process_exit {
	       my ($self, $event) = @_;
	       $event->Skip(1);
	       my $process = $event->GetProcess;
	       my $line = $event->GetLine;
	       my @buffers = @{ $process->GetStdOutBuffer };
	       my @errors = @{ $process->GetStdErrBuffer };
	       my $exitcode = $process->GetExitCode;
	       ............
	       $process->Destroy;
	   }

	   sub evt_process_maxlines {
	       my ($self, $event) = @_;
	       my $process = $event->GetProcess;

	       ..... bad process

	       $process->Kill;
	   }

DESCRIPTION

       This module provides the STDOUT, STDERR and exit codes of asynchronously running processes via events.  It may be used for long running or
       blocking processes that provide periodic updates on state via STDOUT. Simple IPC is possible via STDIN.

       Do not use this module simply to collect the output of another process. For that, it is much simpler to do:

	   my ($status, $output) = Wx::ExecuteStdout( 'perl -e"print qq($_
) for(@INC);"' );

   Wx::Perl::ProcessStream::Process
       Methods

       new	   Create a new Wx::Perl::ProcessStream::Process object. You must then use the Run method to execute your command.

		       my $process = Wx::Perl::ProcessStream::Process->new($command, $name, $eventhandler, $readmethod);

		       $command      = command text (and parameters) you wish to run. You may also pass a
				       reference to an array containing the command and parameters.
		       $name	     = an arbitray name for the process.
		       $eventhandler = the Wx EventHandler (Wx:Window) that will handle events for this process.
		       $readmethod   = 'read' or 'readline' (default = 'readline') an optional param. From Wx version
				       0.75 you can specify the method you wish to use to read the output of an
				       external process.
				       The default depends on your Wx version ( 'getc' < 0.75,'readline' >= 0.75)
				       read	  -- uses the Wx::InputStream->READ method to read bytes.
				       readline   -- uses the Wx::InputStream->READLINE method to read bytes
				       getc	  -- alias for read (getc not actually used)

       SetMaxLines Set the maximum number of lines that will be read from a continuous stream before raising a EVT_WXP_PROCESS_STREAM_MAXLINES
		   event. The default is 1000. A continuous stream will cause your application to hang.

		       $process->SetMaxLines(10);

       Run	   Run the process with the parameters passed to new. On success, returns the process object itself.  This allows you to do: my
		   $process = Wx::Perl::ProcessStream->new($command, $name, $self)->Run; Returns undef if the process could not be started.

		       my $process = Wx::Perl::ProcessStream::Process->new($command, $name, $eventhandler, $readmethod);
		       $process->Run;

       CloseInput  Close the STDIN stream of the external process. (Some processes may not close until STDIN is closed.)

		       $process->CloseInput();

       GetAppCloseAction
		   Returns the current process signal that will used on application exit. Either wxpSIGTERM or wxpSIGKILL.  See SetAppCloseAction.

		       my $action = $process->GetAppCloseAction();

       GetExitCode Returns the process exit code. It is undefined until a wxpEVT_PROCESS_STREAM_EXIT event has been received.

		       my $exitcode = $process->GetExitCode();

       GetProcessName
		   Returns the process name as passed to the OpenProcess constructor.

		       my $processname = $process->GetProcessName();

       GetStdErrBuffer
		   This returns a reference to an array containing all the lines sent by the process to stderr.  Calling this clears the process
		   object internal stderr buffer.  (This has no effect on the actual process I/O buffers.)

		       my $arryref = $process->GetStdErrBuffer();

       GetStdOutBuffer
		   This returns a reference to an array containing all the lines sent by the process to stdout.  Calling this clears the process
		   object internal stdout buffer.  (This has no effect on the actual process I/O buffers.)

		       my $arryref = $process->GetStdOutBuffer();

       GetStdErrBufferLineCount
		   This returns the number of lines currently in the stderr buffer.

		       my $count = $process->GetStdErrBufferLineCount();

       GetStdOutBufferLineCount
		   This returns the number of lines currently in the stdout buffer.

		       my $count = $process->GetStdOutBufferLineCount();

       PeekStdErrBuffer
		   This returns a reference to an array containing all the lines sent by the process to stderr.  To retrieve the buffer and clear
		   it, call GetStdErrBuffer instead.

		       my $arryref = $process->PeekStdErrBuffer();

       PeekStdOutBuffer
		   This returns a reference to an array containing all the lines sent by the process to stdout.  To retrieve the buffer and clear
		   it, call GetStdOutBuffer instead.

		       my $arryref = $process->PeekStdOutBuffer();

       GetProcessId
		   Returns the process id assigned by the system.

		       my $processid = $process->GetProcessId();

       GetPid	   Returns the process id assigned by the system.

		       my $processid = $process->GetPid();

       IsAlive	   Check if the process still exists in the system.  Returns 1 if process exists, 0 if process does not exist. If the process has
		   already signalled its exit, the IsAlive method will always return 0. Therefore IsAlive should always return 0 (false) once a
		   EVT_WXP_PROCESS_STREAM_EXIT event has been sent.

		       my $isalive = $process->IsAlive();

       KillProcess Send a SIGKILL signal to the external process.

		       $process->KillProcess();

       SetAppCloseAction
		   When your application exits, any remaining Wx::Perl::ProcessStream::Process objects will be signaled to close.  The default
		   signal is wxpSIGTERM but you can change this to wxpSIGKILL if you are sure this is what you want.

		       $process->SetAppCloseAction( $newaction );

		       $newaction = one of wxpSIGTERM, wxpSIGKILL

       TerminateProcess
		   Send a SIGTERM signal to the external process.

		       $process->TerminateProcess();

       WriteProcess
		   Write to the STDIN of process.

		       $process->WriteProcess( $writedata . "
" );

		       $writedata = The data you wish to write. Remember to add any appropriate line endings your external process may expect.

   Wx::Perl::ProcessStream
       Methods

       OpenProcess Run an external process. DEPRECATED - use Wx::Perl::ProcessStream::Process->new()->Run; If the process is launched
		   successfully, returns a Wx::Perl::ProcessStream::Process object.  If the process could not be launched, returns undef;

		       my $process = Wx::Perl::ProcessStream->OpenProcess($command, $name, $eventhandler, $readmethod);

		       $command      = command text (and parameters) you wish to run. You may also pass a
				       reference to an array containing the command and parameters.
		       $name	     = an arbitray name for the process.
		       $eventhandler = the Wx object that will handle events for this process.
		       $process      = Wx::Perl::ProcessStream::Process object
		       $readmethod   = 'getc' or 'readline' (default = 'readline') an optional param. From Wx version
				       0.75 you can specifiy the method you wish to use to read the output of an
				       external process. The default depends on your Wx version ( 'getc' < 0.75,
				       'readline' >= 0.75)
				       'getc' uses the Wx::InputStream->GetC method to read bytes.
				       'readline', uses the wxPerl implementation of Wx::InputStream->READLINE.

		   If the process could not be started then zero is returned.  You should destroy each process after it has completed. You can do
		   this after receiving the exit event.

       GetDefaultAppCloseAction
		   Returns the default on application close action that will be given to new processes.  When your application exits, any
		   remaining Wx::Perl::ProcessStream::Process objects will be signalled to close.  The default signal is wxpSIGTERM but you can
		   change this to wxpSIGKILL if you are sure this is what you want.  Whenever a mew process is opened, it is given the application
		   close action returned by GetDefaultAppCloseAction.  You can also set the application close action at an individual process
		   level.

		       my $def-action = Wx::Perl::ProcessStream->SetDefaultAppCloseAction();

		       $def-action will be one of wxpSIGTERM or wxpSIGKILL; (default wxpSIGTERM)

       SetDefaultAppCloseAction
		   Sets the default on application close action that will be given to new processes.  See GetDefaultAppCloseAction.

		       Wx::Perl::ProcessStream->SetDefaultAppCloseAction( $newdefaction );

		       $newdefaction = one of wxpSIGTERM or wxpSIGKILL

       SetDefaultMaxLines
		   Sets the default maximum number of lines that will be processed continuously from an individual process. If a process produces
		   a continuous stream of output, this would hang your application. This setting provides a maximum number of lines that will be
		   read from the process streams before control is yielded and the events can be processed.  Additionally, a
		   EVT_WXP_PROCESS_STREAM_MAXLINES event will be sent to the eventhandler.  The setting can also be set on an individual process
		   basis using $process->SetMaxLines

		       Wx::Perl::ProcessStream->SetDefaultMaxLines( $maxlines );

		       the default maxlines number is 1000

       GetPollInterval
		   Get the current polling interval. See SetPollInterval.

		       $milliseconds = Wx::Perl::ProcessStream->GetPollInterval();

       SetPollInterval
		   When all buffers are empty but there are still running external process, the module will pause before polling the processes
		   again for output.  By default, the module waits for 500 milliseconds. You can set the value of this polling intrval with this
		   method.  Internally, a Wx::Timer object is used to handle polling and the value you set here is passed directly to that.  The
		   precision of the intervals is OS dependent.

		       Wx::Perl::ProcessStream->SetPollInterval( $milliseconds );

		       $milliseconds = number of milliseconds to wait when no buffer activity

   Wx::Perl::ProcessStream::ProcessEvent
       A Wx::Perl::ProcessStream::ProcessEvent is sent whenever an external process started with OpenProcess writes to STDOUT, STDERR or when the
       process exits.

       Event Connectors

       EVT_WXP_PROCESS_STREAM_STDOUT
		   Install an event handler for an event of type wxpEVT_PROCESS_STREAM_STDOUT exported on request by this module.  The event
		   subroutine will receive a Wx::Perl::ProcessStream::ProcessEvent for every line written to STDOUT by the external process.

		       EVT_WXP_PROCESS_STREAM_STDOUT( $eventhandler, $codref );

       EVT_WXP_PROCESS_STREAM_STDERR
		   Install an event handler for an event of type wxpEVT_PROCESS_STREAM_STDERR exported on request by this module.  The event
		   subroutine will receive a Wx::Perl::ProcessStream::ProcessEvent for every line written to STDERR by the external process.

		       EVT_WXP_PROCESS_STREAM_STDERR( $eventhandler, $codref );

       EVT_WXP_PROCESS_STREAM_EXIT
		   Install an event handler for an event of type wxpEVT_PROCESS_STREAM_EXIT exported on request by this module.  The event
		   subroutine will receive a Wx::Perl::ProcessStream::ProcessEvent when the external process exits.

		       EVT_WXP_PROCESS_STREAM_EXIT( $eventhandler, $codref );

       EVT_WXP_PROCESS_STREAM_MAXLINES
		   Install an event handler for an event of type wxpEVT_PROCESS_STREAM_MAXLINES exported on request by this module.  The event
		   subroutine will receive a Wx::Perl::ProcessStream::ProcessEvent when the external process produces a continuous stream of lines
		   on stderr and stdout that exceed the max lines set via $process->SetMaxLines or Wx::Perl::ProcessStream->SetDefaultMaxLines.

		       EVT_WXP_PROCESS_STREAM_MAXLINES( $eventhandler, $codref );

       Methods

       GetLine	   For events of type wxpEVT_PROCESS_STREAM_STDOUT and wxpEVT_PROCESS_STREAM_STDERR this will return the line written by the
		   process.

       GetProcess  This returns the process that raised the event. If this is a wxpEVT_PROCESS_STREAM_EXIT event you should destroy the process
		   with $process->Destroy;

COPYRIGHT &; LICENSE
       Copyright (C) 2007-2010 Mark Dootson, all rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

ACKNOWLEDGEMENTS

       Thanks to Johan Vromans for testing and suggesting a better interface.

AUTHOR

       Mark Dootson, "<mdootson at cpan.org>"

SEE ALSO

       The distribution includes examples in the 'example' folder.  From the source root, run

	   perl -Ilib example/psexample.pl

       You can enter commands, execute them and view results.

       You may also wish to consult the wxWidgets manuals for:

       Wx::Process

       Wx::Execute

       Wx::ExecuteArgs

       Wx::ExecuteCommand

       Wx::ExecuteStdout

       Wx::ExecuteStdoutStderr

perl v5.14.2							    2012-03-28					      Wx::Perl::ProcessStream(3pm)