This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: End, Next: English, Prev: Emotion, Up: Module List generalized END {}. ******************* NAME ==== End - generalized END {}. SYNOPSIS ======== use End; { my $foo = end {print "Leaving the block\n"}; ... last; # prints "Leaving the block\n". ... } DESCRIPTION =========== The module End exports a single subroutine end, which allows you to set up some code that is run whenever the current block is exited, regardless whether that is due to a return, next, last, redo, exit, die, goto or just reaching the end of the block. To be more precise, end returns an object, that will execute the code when the object is destroyed; that is, when the variable assigned to goes out of scope. If the variable is lexical to the current block, the code will be executed when leaving the block. One can force premature execution of the code by undefining the variable assigned to, or assigning another value to the variable. end only takes one argument, a code reference. If one wishes the code reference to take arguments, wrapping the code reference in a closure suffices. BUGS ==== Due to a bug in Perl 5.6.0 (and perhaps before), anonymous subroutines that are not a closure will not go out of scope, not even on program termination. That is why end wraps the code fragment in a closure. There is a second bug in Perl 5.6.0 (and perhaps before) why this is necessary. If the code fragment isn't wrapped in another code reference, the original subroutine will be blessed in the package, making that ref on that code no longer returns the right value. REVISION HISTORY ================ $Log: End.pm,v $ Revision 1.2 2000/05/31 20:25:33 abigail Added the license paragraph in the POD section. Revision 1.1 2000/05/31 19:35:01 abigail Initial revision AUTHOR ====== This package was written by Abigail, *abigail@delanet.com*. COPYRIGHT & LICENSE =================== This program is copyright 2000 by Abigail. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  File: pm.info, Node: English, Next: English/Reference, Prev: End, Up: Module List use nice English (or awk) names for ugly punctuation variables ************************************************************** NAME ==== English - use nice English (or awk) names for ugly punctuation variables SYNOPSIS ======== use English; ... if ($ERRNO =~ /denied/) { ... } DESCRIPTION =========== This module provides aliases for the built-in variables whose names no one seems to like to read. Variables with side-effects which get triggered just by accessing them (like $0) will still be affected. For those variables that have an *awk* version, both long and short English alternatives are provided. For example, the $/ variable can be referred to either $RS or $INPUT_RECORD_SEPARATOR if you are using the English module. See *Note Perlvar: (perl.info)perlvar, for a complete list of these. BUGS ==== This module provokes sizeable inefficiencies for regular expressions, due to unfortunate implementation details. If performance matters, consider avoiding English.  File: pm.info, Node: English/Reference, Next: Env, Prev: English, Up: Module List use words to dereference things ******************************* NAME ==== English::Reference - use words to dereference things SYNOPSIS ======== use English::Reference; or use English::Reference qw(deref); ... print SCALAR \"Hello World"; DESCRIPTION =========== Provides the ability to use: ARRAY $arrayref CODE $coderef GLOB $globref HASH $hashref SCALAR $scalaref en lieu of @$arrayref &$coderef *$globref %$hashref $$scalaref or @{$arrayref} &{$coderef} *{$globref} %{$hashref} ${$scalaref} As an added bonus, there is a function deref; not exported by default; which you can use to dereference a reference of any type. CAVEATS ======= You cannot do ARRAY{$arrayref} etc. This is not too bad seeing as the whole point of this module is to reduce the amount of punctuation you use. AUTHORS ======= Jerrad Pierce , Jeff Pinyan , Casey R. Tweten SEE ALSO ======== English(3).  File: pm.info, Node: Env, Next: Env/Array, Prev: English/Reference, Up: Module List perl module that imports environment variables as scalars or arrays ******************************************************************* NAME ==== Env - perl module that imports environment variables as scalars or arrays SYNOPSIS ======== use Env; use Env qw(PATH HOME TERM); use Env qw($SHELL @LD_LIBRARY_PATH); DESCRIPTION =========== Perl maintains environment variables in a special hash named %ENV. For when this access method is inconvenient, the Perl module Env allows environment variables to be treated as scalar or array variables. The `Env::import()' function ties environment variables with suitable names to global Perl variables with the same names. By default it ties all existing environment variables (`keys %ENV') to scalars. If the import function receives arguments, it takes them to be a list of variables to tie; it's okay if they don't yet exist. The scalar type prefix '$' is inferred for any element of this list not prefixed by '$' or '@'. Arrays are implemented in terms of split and join, using `$Config::Config{path_sep}' as the delimiter. After an environment variable is tied, merely use it like a normal variable. You may access its value @path = split(/:/, $PATH); print join("\n", @LD_LIBRARY_PATH), "\n"; or modify it $PATH .= ":."; push @LD_LIBRARY_PATH, $dir; however you'd like. Bear in mind, however, that each access to a tied array variable requires splitting the environment variable's string anew. The code: use Env qw(@PATH); push @PATH, '.'; is equivalent to: use Env qw(PATH); $PATH .= ":."; except that if `$ENV{PATH}' started out empty, the second approach leaves it with the (odd) value "`:.'", but the first approach leaves it with ".". To remove a tied environment variable from the environment, assign it the undefined value undef $PATH; undef @LD_LIBRARY_PATH; LIMITATIONS =========== On VMS systems, arrays tied to environment variables are read-only. Attempting to change anything will cause a warning. AUTHOR ====== Chip Salzenberg <`chip@fin.uucp'> and Gregor N. Purdy <`gregor@focusresearch.com'>  File: pm.info, Node: Env/Array, Next: Env/Path, Prev: Env, Up: Module List Perl module that "imports" environment variables as arrays ********************************************************** NAME ==== Env::Array - Perl module that "imports" environment variables as arrays SYNOPSIS ======== With explicit delimiters: use Env::Array qw(PATH :); use Env::Array qw(@MANPATH :); With inferred delimiters: use Env::Array qw(@LD_LIBRARY_PATH); DESCRIPTION =========== The `Env::Array' Perl module allows environment variables to be treated as Perl array variables, analogous to the way the Env module allows them to be treated as scalar variables. The Env::Array::import() function requires pairs of environment variable names and delimiter strings to be presented in the use statement. If just one argument is given, then `$Config::Config{path_sep}' is taken as the delimiter. `Env::Array' allows the variable name to have the '`@'' array type prefix, if desired. The variable being tied must otherwise begin with a letter. Unlike Env, `Env::Array' does nothing if the use list is empty. After an environment variable is tied, just use it like an ordinary array. Bear in mind, however, that each access to the variable requires splitting the string anew. The code: use Env::Array qw(@PATH); push @PATH, '.'; is equivalent to: use Env qw(PATH); $PATH .= ":."; except that the `Env::Array' approach does the right thing for both Unix-like operating systems and for Win32. Also, if `$ENV{PATH}' was the empty string, the Env approach leaves it with the (odd) value "`:.'", but the `Env::Array' approach leaves it with ".". `Env::Array' requires Perl 5.005 or later for proper operation due to its use of tied arrays. SEE ALSO ======== The Env Perl module. AUTHOR ====== Gregor N. Purdy <`gregor@focusresearch.com'> COPYRIGHT ========= Copyright (C) 1999-2000 Gregor N. Purdy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Env/Path, Next: Envy/Load, Prev: Env/Array, Up: Module List Advanced operations on path variables ************************************* NAME ==== Env::Path - Advanced operations on path variables SYNOPSIS ======== use Env::Path; # basic usage my $manpath = Env::Path->MANPATH; $manpath->Append('/opt/samba/man'); for ($manpath->List) { print $_, "\n" }; # similar to above using the "implicit object" shorthand Env::Path->MANPATH; MANPATH->Append('/opt/samba/man'); for (MANPATH->List) { print $_, "\n" }; # one-shot use Env::Path->PATH->Append('/usr/sbin'); # change instances of /usr/local/bin to an architecture-specific dir Env::Path->PATH->Replace('/usr/local/bin', "/usr/local/$ENV{PLATFORM}/bin"); # more complex use (different names for same semantics) my $libpath; if ($^O =~ /aix/) { $libpath = Env::Path->LIBPATH; } else { $libpath = Env::Path->LD_LIBRARY_PATH; } $libpath->Assign(qw(/usr/lib /usr/openwin/lib)); $libpath->Prepend('/usr/ucblib') unless $libpath->Has('/usr/ucblib'); $libpath->InsertAfter('/usr/ucblib', '/xx/yy/zz'); $libpath->Uniqify; $libpath->DeleteNonexistent; $libpath->Remove('/usr/local/lib'); print $libpath->Name, ":"; for ($libpath->List) { print " $_" }; print "\n"; # simplest usage: bless all existing EV's as Env::Path objects use Env::Path ':all'; my @cats = PATH->Whence('cat*'); print "@cats\n"; DESCRIPTION =========== Env::Path presents an object-oriented interface to *path variables*, defined as that subclass of *environment variables* which name an ordered list of filesystem elements separated by a platform-standard separator (typically ':' on UNIX and ';' on Windows). Of course, core Perl constructs such $ENV{PATH} .= ":/usr/local/bin"; will suffice for most uses. Env::Path is for the others; cases where you need to insert or remove interior path entries, strip redundancies, operate on a pathvar without having to know whether the current platform uses ":" or ";", operate on a pathvar which may have a different name on different platforms, etc. This OO interface is slightly unusual in that the environment variable is itself the object and the constructor is Env::Path->AUTOLOAD(); thus Env::Path->MANPATH; would bless $ENV{MANPATH} into its package. `$ENV{MANPATH}' is otherwise unmodified with the exception of possible autovivification. The only attribute the new object has is its pre-existing value. Also, while the object reference may be assigned and used in the normal style my $path = Env::Path->CLASSPATH; $path->Append('/opt/foo/classes.jar'); a shorthand is also available: Env::Path->CLASSPATH; CLASSPATH->Append('/opt/foo/classes.jar'); I.e. the name of the path variable may be used as a proxy for its object reference. This may be done at 'use' time too: use Env::Path qw(PATH CLASSPATH); # or qw(:all) to bless all EV's CLASSPATH->Append('/opt/foo/classes.jar'); CLASS METHODS ------------- * The constructor may have any name; it's assumed to name a *path variable* as defined above. Returns the object reference. * PathSeparator Returns or sets the platform-specific path separator character, by default : on open platforms and *;* on monopolistic ones. INSTANCE METHODS ---------------- Unless otherwise indicated these methods return the object reference, allowing method calls to be strung together. All methods which take lists join them together using the value of `Env::Path->PathSeparator'. * Name Returns the name of the pathvar. * Has Returns true iff the specified entry is present in the pathvar. * Assign Takes a list and sets the pathvar to that value, separated by the current PathSeparator. * List Returns the current path in list format. * Prepend For each entry in the supplied list, removes it from the pathvar if present and prepends it, thus ensuring that it's present exactly once and at the front. * Append Analogous to Prepend. * InsertBefore Takes a and a list, inserts the list just before the first instance of the . If *dirname* is not found, works just like *Prepend*. As with *Prepend*, duplicates of the supplied entries are removed. * InsertAfter Analogous to *InsertBefore* * Remove Removes the specified entries from the path. * Replace Takes a /pattern/ and a list. Traverses the path and replaces all entries which match the pattern with the concatenated list entries. * DeleteNonexistent Removes from the path all entries which do not exist as filesystem entities. * Uniqify Removes redundant entries (the 2nd through nth instances of each entry). * Whence Takes a pattern and returns an ordered list of all filenames found along the path which match it and are executable. * Shell Returns a string suitable for passing to a shell which would set and export the pathvar to its current value within the shell context. NOTES ===== * No provision is made for path variables which are not also environment variables, a situation which is technically possible but quite rare. * Except where necessary no assumption is made that path entries should be directories, because pathvars like CLASSPATH may contain "virtual dirs" such as zip/jar files. For instance the *DeleteNonexistent* method does not remove entries which are files. In Perl terms the test applied is -e, not -d. * The shorthand notation for pathvar FOO is implemented by hacking *@FOO::ISA*, so there's a slight risk of namespace collision if your code also creates packages with all-upper-case names. No packages are created unless the shorthand notation is employed. WORKS ON ======== UNIX and Windows. AUTHOR ====== David Boyce COPYRIGHT ========= Copyright (c) 2000 David Boyce. All rights reserved. This Perl program is free software; you may redistribute and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), perlobj(1), Env::Array(3)  File: pm.info, Node: Envy/Load, Next: Errno, Prev: Env/Path, Up: Module List Load Envy Files *************** NAME ==== Envy::Load - Load Envy Files SYNOPSIS ======== use Envy::Load qw(dev objstore); { my $env = Envy::Load->new(); $env->load(qw(prod testdb)); # %ENV restored when $env goes out of scope } DESCRIPTION =========== Similar to `envy load ...`.  File: pm.info, Node: Errno, Next: Error, Prev: Envy/Load, Up: Module List System errno constants ********************** NAME ==== Errno - System errno constants SYNOPSIS ======== use Errno qw(EINTR EIO :POSIX); DESCRIPTION =========== Errno defines and conditionally exports all the error constants defined in your system `errno.h' include file. It has a single export tag, `:POSIX', which will export all POSIX defined error numbers. Errno also makes `%!' magic such that each element of `%!' has a non-zero value only if $! is set to that value. For example: use Errno; unless (open(FH, "/fangorn/spouse")) { if ($!{ENOENT}) { warn "Get a wife!\n"; } else { warn "This path is barred: $!"; } } If a specified constant `EFOO' does not exist on the system, `$!{EFOO}' returns "". You may use `exists $!{EFOO}' to check whether the constant is available on the system. CAVEATS ======= Importing a particular constant may not be very portable, because the import will fail on platforms that do not have that constant. A more portable way to set $! to a valid value is to use: if (exists &Errno::EFOO) { $! = &Errno::EFOO; } AUTHOR ====== Graham Barr COPYRIGHT ========= Copyright (c) 1997-8 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Error, Next: Error/Unhandled, Prev: Errno, Up: Module List Error/exception handling in an OO-ish way ***************************************** NAME ==== Error - Error/exception handling in an OO-ish way SYNOPSIS ======== use Error qw(:try); throw Error::Simple( "A simple error"); sub xyz { ... record Error::Simple("A simple error") and return; } unlink($file) or throw Error::Simple("$file: $!",$!); try { do_some_stuff(); die "error!" if $condition; throw Error::Simple -text => "Oops!" if $other_condition; } catch Error::IO with { my $E = shift; print STDERR "File ", $E->{'-file'}, " had a problem\n"; } except { my $E = shift; my $general_handler=sub {send_message $E->{-description}}; return { UserException1 => $general_handler, UserException2 => $general_handler }; } otherwise { print STDERR "Well I don't know what to say\n"; } finally { close_the_garage_door_already(); # Should be reliable }; # Don't forget the trailing ; or you might be surprised DESCRIPTION =========== The Error package provides two interfaces. Firstly Error provides a procedural interface to exception handling. Secondly Error is a base class for errors/exceptions that can either be thrown, for subsequent catch, or can simply be recorded. Errors in the class Error should not be thrown directly, but the user should throw errors from a sub-class of Error. PROCEDURAL INTERFACE ==================== Error exports subroutines to perform exception handling. These will be exported if the `:try' tag is used in the use line. try BLOCK CLAUSES try is the main subroutine called by the user. All other subroutines exported are clauses to the try subroutine. The BLOCK will be evaluated and, if no error is throw, try will return the result of the block. `CLAUSES' are the subroutines below, which describe what to do in the event of an error being thrown within BLOCK. catch CLASS with BLOCK This clauses will cause all errors that satisfy `$err->isa(CLASS)' to be caught and handled by evaluating BLOCK. BLOCK will be passed two arguments. The first will be the error being thrown. The second is a reference to a scalar variable. If this variable is set by the catch block then, on return from the catch block, try will continue processing as if the catch block was never found. To propagate the error the catch block may call `$err->throw' If the scalar reference by the second argument is not set, and the error is not thrown. Then the current try block will return with the result from the catch block. except BLOCK When try is looking for a handler, if an except clause is found BLOCK is evaluated. The return value from this block should be a HASHREF or a list of key-value pairs, where the keys are class names and the values are CODE references for the handler of errors of that type. otherwise BLOCK Catch any error by executing the code in BLOCK When evaluated BLOCK will be passed one argument, which will be the error being processed. Only one otherwise block may be specified per try block finally BLOCK Execute the code in BLOCK either after the code in the try block has successfully completed, or if the try block throws an error then BLOCK will be executed after the handler has completed. If the handler throws an error then the error will be caught, the finally block will be executed and the error will be re-thrown. Only one finally block may be specified per try block CLASS INTERFACE =============== CONSTRUCTORS ------------ The Error object is implemented as a HASH. This HASH is initialized with the arguments that are passed to it's constructor. The elements that are used by, or are retrievable by the Error class are listed below, other classes may add to these. -file -line -text -value -object If `-file' or `-line' are not specified in the constructor arguments then these will be initialized with the file name and line number where the constructor was called from. If the error is associated with an object then the object should be passed as the `-object' argument. This will allow the Error package to associate the error with the object. The Error package remembers the last error created, and also the last error associated with a package. This could either be the last error created by a sub in that package, or the last error which passed an object blessed into that package as the `-object' argument. throw ( [ ARGS ] ) Create a new Error object and throw an error, which will be caught by a surrounding try block, if there is one. Otherwise it will cause the program to exit. throw may also be called on an existing error to re-throw it. with ( [ ARGS ] ) Create a new Error object and returns it. This is defined for syntactic sugar, eg die with Some::Error ( ... ); record ( [ ARGS ] ) Create a new Error object and returns it. This is defined for syntactic sugar, eg record Some::Error ( ... ) and return; STATIC METHODS -------------- prior ( [ PACKAGE ] ) Return the last error created, or the last error associated with PACKAGE OBJECT METHODS -------------- stacktrace If the variable `$Error::Debug' was non-zero when the error was created, then stacktrace returns a string created by calling `Carp::longmess'. If the variable was zero the stacktrace returns the text of the error appended with the filename and line number of where the error was created, providing the text does not end with a newline. object The object this error was associated with file The file where the constructor of this error was called from line The line where the constructor of this error was called from text The text of the error OVERLOAD METHODS ---------------- stringify A method that converts the object into a string. This method may simply return the same as the text method, or it may append more information. For example the file name and line number. By default this method returns the `-text' argument that was passed to the constructor, or the string `"Died"' if none was given. value A method that will return a value that can be associated with the error. For example if an error was created due to the failure of a system call, then this may return the numeric value of $! at the time. By default this method returns the `-value' argument that was passed to the constructor. PRE-DEFINED ERROR CLASSES ========================= Error::Simple This class can be used to hold simple error strings and values. It's constructor takes two arguments. The first is a text value, the second is a numeric value. These values are what will be returned by the overload methods. If the text value ends with `at file line 1' as $@ strings do, then this infomation will be used to set the `-file' and `-line' arguments of the error object. This class is used internally if an eval'd block die's with an error that is a plain string. KNOWN BUGS ========== None, but that does not mean there are not any. AUTHORS ======= Graham Barr The code that inspired me to write this was originally written by Peter Seibel and adapted by Jesse Glick .  File: pm.info, Node: Error/Unhandled, Next: Event, Prev: Error, Up: Module List a Module for letting Errors do their own handling ************************************************* NAME ==== Error::Unhandled - a Module for letting Errors do their own handling SYNOPSIS ======== use Error qw(:try); use Error::Unhandled; try { &foo; } otherwise { my $E = shift; print "I caught:\n".$E->stringify."\n\n"; }; &foo; sub foo { throw Error::Unhandled(unhandled => sub {print "No one handled this.\n"; exit}); } DESCRIPTION =========== While doing ASP programming, I wanted to use an object oriented exception handling system. Graham Barr pointed me at `Error.pm', which handled almost everything I needed. It was missing, however, a way for exceptions to define their own default error handling behavior. This can be very useful when ASP programming - someone using your object can decide to implement their own error handling routines, but if they don't the user will at least get a semi-informative message in their browser. After trying several different approaches, I ended up with a subclass of Error titled `Error::Unhandled'. The *only* difference in behavior between `Error::Unhandled' and Error is what happens when throw is called. The implementation of throw in `Error::Unhandled' uses caller to search the call stack, looking for `Error::subs::try'. If it finds one, it throws the exception as per normal behavior. If it doesn't find one, it calls `$self->unhandled'. Before doing that, however, it checks to see if the element `unhandled' is defined in its hash. If it is and it is a reference to a subroutine, it calls that instead. Note that if the element `unhandled' is present and is not a reference to a subroutine, throw will not call `$self->unhandled'. Finally, after all of that returns, throw will throw the exception as per normal behavior. If you don't want it to throw the exception, call exit or die within your `unhandled' subroutine. It is, of course, also possible (and recommended in many situations) to sub class `Error::Unhandled' and provide a class-defined implementation of `unhandled'. Also note that both the instance-defined and class-defined `unhandled' methods receive `$self' as their first parameter. Installation instructions ------------------------- This module requires Error, available from CPAN. AUTHOR ====== Toby Everett, teverett@alascom.att.com  File: pm.info, Node: Event, Next: Event/MakeMaker, Prev: Error/Unhandled, Up: Module List Event loop processing ********************* NAME ==== Event - Event loop processing WARNING ======= *THIS IS EXPERIMENTAL CODE AND IS LIKELY TO CHANGE A CONSIDERABLE AMOUNT* *BEFORE IT IS RELEASED FOR GENERAL USE.* SYNOPSIS ======== use Event; # initialize application Event->Loop; # and some callback will call Event->exit; DESCRIPTION =========== EVENT TYPES =========== idle Event->idle( \&idle ); Call `&idle' when the loop is idle. atexit $e = Event->atexit( \&cleanup ) Call `&cleanup' when the event loop is about to exit. If after registering an atexit handler it is not required, the the `cancel' method can be called on $e. watchvar $e = Event->watchvar( -variable => \$var, -async => 0, -callback => \&watcher, ); Call `&watcher' when `$var' is changed. If `-async' is *true* then `&watcher' will be called immediately, otherwise the call to `&watcher' will be pushed onto the event queue. When called `&watcher' will be passed $e as the first argument, `&watcher' may the call the `cancel' method to stop any future changes to `$var' creating events. timer $e = Event->timer( -after => 10, -at => time + 10, -interval => 2, -callback => \&timeout ); Call `&timeout' either after a given delay or at a given time (-after and -at are mutually exclusive). Then optionally call `&timeout' at given intervals. When called `&timeout' will be passed $e as the first argument, and the time that the event was triggered as the second argument. `&timeout' may the call the `cancel' method on $e to stop any future timer events, or if `-interval' was not given and `-after' was then `&timeout' may call the `again' method on $e which will cause the event to re-occur, the time at which the event will re-occur is the value given by `-after' added to the time the event was triggered. Due to lags in the event loop calling the callback, this time may already be in the past, in which case the event will be queued immediately io $e = Event->io( -handle => $sock, -events => POLLREAD, -callback => \&ready ); Call `&ready' when $sock has data to be read. `-event' can take any combination of the constants that are accepted by IO::Poll. When called `&ready' is passed $e as the first argument, $handle as the second argument and the events that happened as the third argument. `&ready' may call the `cancel' method on $e to stop any future event handling on $handle signal $e = Event->signal( -signal => 'INT', -callback => \&interrupt ); Call `&interrupt' when an `INT' signal is received. `-signal' accepts any signal name except `CHLD', see below. When called `&interrupt' will be passed $e as the first argument and the name of the signal as the second. `&interrupt' amy call the `cancel' method on $e to stop any future events being caught. process $e = Event->process( -pid => $pid, -callback => \&reap ); Call `&reap' when the child process with pid `$pid' exits. If `$pid' is not given then `&reap' will be called for any process that does not have it's own event handler. When called `&reap' will be passed $e as the first parameter, the process id of the child as the second and the exit status of the child as the third. `&reap' may call the `cancel' method on $e to stop future process events, this is only of use on event handlers where `-pid' is not specified. FUTURE ENHANCEMENTS =================== # generate an event when we can successfully run an op $e = Event->semaphore( -semaphore => $sem, -op => $op, -callback => \&gotit ); # generate an event when the msg queue is/is not empty $e = Event->msg( -msg => $msg, -callback => \&doit ); =head1 AUTHOR Graham Barr <`gbarr@pobox.com'> COPYRIGHT ========= Copyright (c) 1997 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Event/MakeMaker, Next: Event/Stats, Prev: Event, Up: Module List MakeMaker glue for the C-level Event API **************************************** NAME ==== Event::MakeMaker - MakeMaker glue for the C-level Event API SYNOPSIS ======== This is an advanced feature of Event. DESCRIPTION =========== For optimal performance, hook into Event at the C-level. You'll need to make changes to your Makefile.PL and add code to your `xs' / c file(s). WARNING ======= When you hook in at the C-level you get a *huge* performance gain, but you also reduce the chances that your code will work unmodified with newer versions of `perl' or Event. This may or may not be a problem. Just be aware, and set your expectations accordingly. HOW TO ====== Makefile.PL ----------- use Event::MakeMaker qw(event_args); # ... set up %args ... WriteMakefile(event_args(%args)); XS -- #include "EventAPI.h" BOOT: I_EVENT_API("YourModule"); API (v21) --------- struct EventAPI { I32 Ver; /* EVENTS */ void (*queue )(pe_event *ev); void (*start )(pe_watcher *ev, int repeat); void (*now )(pe_watcher *ev); void (*stop )(pe_watcher *ev, int cancel_events); void (*cancel )(pe_watcher *ev); void (*suspend )(pe_watcher *ev); void (*resume )(pe_watcher *ev); /* All constructors optionally take a stash and template. Either or both can be NULL. The template should not be a reference. */ pe_idle *(*new_idle )(HV*, SV*); pe_timer *(*new_timer )(HV*, SV*); pe_io *(*new_io )(HV*, SV*); pe_var *(*new_var )(HV*, SV*); pe_signal *(*new_signal)(HV*, SV*); /* TIMEABLE */ void (*tstart)(pe_timeable *); void (*tstop)(pe_timeable *); /* HOOKS */ pe_qcallback *(*add_hook)(char *which, void *cb, void *ext_data); void (*cancel_hook)(pe_qcallback *qcb); /* STATS */ void (*install_stats)(pe_event_stats_vtbl *esvtbl); void (*collect_stats)(int yes); pe_ring *AllWatchers; /* TYPEMAP */ SV *(*watcher_2sv)(pe_watcher *wa); void *(*sv_2watcher)(SV *sv); SV *(*event_2sv)(pe_event *ev); void *(*sv_2event)(SV *sv); }; EXAMPLE ------- static pe_io *X11_ev=0; static void x_server_dispatch(void *ext_data) { ... } if (!X11_ev) { X11_ev = GEventAPI->new_io(0,0); X11_ev->poll = PE_R; sv_setpv(X11_ev->base.desc, "X::Server"); X11_ev->base.callback = (void*) x_server_dispatch; X11_ev->base.ext_data = ; X11_ev->base.prio = PE_PRIO_NORMAL; } X11_ev->fd = x_fd; GEventAPI->resume((pe_event*) X11_ev); GEventAPI->start((pe_event*) X11_ev, 0); BUT I NEED A NEW TYPE OF WATCHER FOR MY INTERGALACTIC INFEROMETER ----------------------------------------------------------------- I'd prefer not to export the entire Event.h apparatus in favor of minimizing interdependencies. If you really, really need to create a new type of watcher send your problem analysis to the mailing list!  File: pm.info, Node: Event/Stats, Next: Event/tcpsession, Prev: Event/MakeMaker, Up: Module List Event loop statistics ********************* NAME ==== Event::Stats - Event loop statistics SYNOPSIS ======== XXX DESCRIPTION =========== Instrument the Event module in order to gather statistics. API === collect($yes) Determines whether statistics are collected. Arithmetically adds $yes to the usage count. Stats are enabled while the usage count is positive. $round_sec = round_seconds($sec) Statistics are not collected in one second intervals. This function converts a *desired* time interval into an *available* time interval. Units are in seconds. $elapse = total_time($sec) Due to long-running callbacks, measurement intervals may take longer than expected. This function returns the actual clock-time for a given measurement interval. ($rans, $dies, $elapse) = idle_time($sec) ($runs, $dies, $elapse) = $watcher->stats($sec) Return statistics for the last $sec seconds of operation. Three numbers are returned: the number of times the callback has been invoked, the number of uncaught exceptions and the number of seconds spent within the callback. Also see `NetServer::ProcessTop' in this node. enforce_max_callback_time($yes) Useful for debugging. XXX SUPPORT ======= Please direct your insights and complaints to the perl-loop@perl.org mailing list! COPYRIGHT ========= Copyright © 1999, 2000 Joshua Nathaniel Pritikin. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Event/tcpsession, Next: Exception/Class, Prev: Event/Stats, Up: Module List reliable bidirectional RPC session layer **************************************** NAME ==== Event::tcpsession - reliable bidirectional RPC session layer SYNOPSIS ======== my $api = [ { name => 'my_rpc', req => 'nN', # network short, network long reply => '', # no translator for reply code => sub { 'returned to caller' } # server-side code }, ... ]; Event->tcpsession(fd => $socket, api => $api); DESCRIPTION =========== Automatic client-side recovery. Embedded NULLs are OK. What are the arbitrary limits? SUPPORT ======= If you have insights or complaints then please subscribe to the mailing list! Send email to: majordomo@perl.org The body of your message should read: subscribe perl-loop This list is archived at http://www.xray.mpe.mpg.de/mailing-lists/perl-loop/ Thanks! COPYRIGHT ========= Copyright © 1999 Joshua Nathaniel Pritikin. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Exception/Class, Next: Exception/Cxx, Prev: Event/tcpsession, Up: Module List A module that allows you to declare real exception classes in Perl ****************************************************************** NAME ==== Exception::Class - A module that allows you to declare real exception classes in Perl SYNOPSIS ======== use Exception::Class ( 'MyException', 'AnotherException' => { isa => 'MyException' }, 'YetAnotherException' => { isa => 'AnotherException', description => 'These exceptions are related to IPC' } ); eval { MyException->throw( error => 'I feel funny.'; }; print $@->error, "\n"; MyException->trace(1); eval { MyException->throw( error => 'I feel funnier.'; }; print $@->error, "\n", $@->trace->as_string, "\n"; print join ' ', $@->euid, $@->egid, $@->uid, $@->gid, $@->pid, $@->time; # catch if ($@->isa('MyException')) { do_something(); } elsif ($@->isa('FooException')) { go_foo_yourself(); } else { $@->rethrow; } DESCRIPTION =========== Exception::Class allows you to declare exceptions in your modules in a manner similar to how exceptions are declared in Java. It features a simple interface allowing programmers to 'declare' exception classes at compile time. It also has a base exception class, Exception::Class::Base, that can be used for classes stored in files (aka modules ;) ) that are subclasses. It is designed to make structured exception handling simpler and better by encouraging people to use hierarchies of exceptions in their applications. NOTE: This module does not implement any try/catch syntax. Please see the `OTHER EXCEPTION MODULES (try' in this node for more information on how to get this syntax. DECLARING EXCEPTION CLASSES =========================== The 'use Exception::Class' syntax lets you automagically create the relevant Exception::Class::Base subclasses. You can also create subclasses via the traditional means of external modules loaded via 'use'. These two methods may be combined. The syntax for the magic declarations is as follows: 'MANDATORY CLASS NAME' => \%optional_hashref The hashref may contain two options: * isa This is the class's parent class. If this isn't provided then the class name is $Exception::Class::BASE_EXC_CLASS is assumed to be the parent (see below). This parameter lets you create arbitrarily deep class hierarchies. This can be any other Exception::Class::Base subclass in your declaration _or_ a subclass loaded from a module. To change the default exception class you will need to change the value of $Exception::Class::BASE_EXC_CLASS _before_ calling import. To do this simply do something like this: BEGIN { $Exception::Class::BASE_EXC_CLASS = 'SomeExceptionClass'; } If anyone can come up with a more elegant way to do this please let me know. CAVEAT: If you want to automagically subclass a Exception::Class::Base class loaded from a file, then you _must_ compile the class (via use or require or some other magic) _before_ you do 'use Exception::Class' or you'll get a compile time error. This may change with the advent of Perl 5.6's CHECK blocks, which could allow even more crazy automagicalness (which may or may not be a good thing). * description Each exception class has a description method that returns a fixed string. This should describe the exception _class_ (as opposed to the particular exception being thrown). This is useful for debugging if you start catching exceptions you weren't expecting (particularly if someone forgot to document them) and you don't understand the error messages. The Exception::Class magic attempts to detect circular class hierarchies and will die if it finds one. It also detects missing links in a chain so if you declare Bar to be a subclass of Foo and never declare Foo then it will also die. My tests indicate that this is functioning properly but this functionality is still somewhat experimental. Exception::Class::Base CLASS METHODS ==================================== * do_trace($true_or_false) Each Exception::Class::Base subclass can be set individually to make a Devel::StackTrace object when an exception is thrown. The default is to not make a trace. Calling this method with a value changes this behavior. It always returns the current value (after any change is applied). * throw( error => $error_message ) This method creates a new Exception::Class::Base object with the given error message. If no error message is given, $! is used. It then die's with this object as its argument. * new( error => $error_message ) Returns a new Exception::Class::Base object with the given error message. If no error message is given, $! is used. * description Returns the description for the given Exception::Class::Base subclass. The Exception::Class::Base class's description is 'Generic exception' (this may change in the future). This is also an object method. Exception::Class::Base OBJECT METHODS ===================================== * rethrow Simply dies with the object as its sole argument. It's just syntactic sugar. This does not change any of the object's attribute values. However, it will cause caller to report the die as coming from within the Exception::Class::Base class rather than where rethrow was called. * error Returns the error message associated with the exception. * pid Returns the pid at the time the exception was thrown. * uid Returns the real user id at the time the exception was thrown. * gid Returns the real group id at the time the exception was thrown. * euid Returns the effective user id at the time the exception was thrown. * egid Returns the effective group id at the time the exception was thrown. * time Returns the time in seconds since the epoch at the time the exception was thrown. * package Returns the package from which the exception was thrown. * file Returns the file within which the exception was thrown. * line Returns the line where the exception was thrown. * trace Returns the trace object associated with the Exception::Class::Base if do_trace was true at the time it was created or undef. * as_string Returns a string form of the error message (something like what you'd expect from die). If there is a trace available then it also returns this in string form (like Carp::confess). OVERLOADING =========== The Exception::Class::Base object is overloaded so that stringification produces a normal error message. It just calls the as_string method described above. This means that you can just `print $@' after an eval and not worry about whether or not its an actual object. It also means an application or module could do this: $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); }; and this would probably not break anything (unless someone was expecting a different type of exception object from die). USAGE RECOMMENDATION ==================== If you're creating a complex system that throws lots of different types of exceptions consider putting all the exception declarations in one place. For an app called Foo you might make a Foo::Exceptions module and use that in all your code. This module could just contain the code to make Exception::Class do its automagic class creation. This allows you to more easily see what exceptions you have and makes it easier to keep track of them all (as opposed to looking at the top of 10-20 different files). It's also ever so slightly faster as the Class::Exception->import method doesn't get called over and over again (though a given class is only ever made once). You may want to create a real module to subclass Exception::Class::Base as well, particularly if you want your exceptions to have more methods. Read the `DECLARING EXCEPTION CLASSES' in this node for more details. OTHER EXCEPTION MODULES (try/catch syntax) ========================================== If you are interested in adding try/catch/finally syntactic sugar to your code then I recommend you check out Graham Barr's Error module, which implements this syntax. It also includes its own base exception class, Error::Simple, but you should be able to use Exception::Class::Base along with his try/catch routines transparently. If you encounter any issues in getting these two to work together, please let me know (and maybe Graham as well) and I will fix this. AUTHOR ====== Dave Rolsky, SEE ALSO ======== Devel::StackTrace  File: pm.info, Node: Exception/Cxx, Next: Expect, Prev: Exception/Class, Up: Module List Switch to ANSI C++ exceptions ***************************** NAME ==== Exception::Cxx - Switch to ANSI C++ exceptions SYNOPSIS ======== use Exception::Cxx; DESCRIPTION =========== This module arranges for perl to use ANSI C++ exceptions (instead of setjmp/longjmp). The reason you might want this is for integration with 3rd party libraries that use C++ exceptions and cannot switch back to longjmp. BUGS ==== sigsetjmp saves more state than catch {}. In C++, sigprocmask & `priocntl' are not saved or restored. C++ exceptions will not work with the CC perl compiler backend. IMO, this is a bug in the backend. CONTACT ======= If you have suggestions or more hints files, please contact me at bitset@mindspring.com. Thanks! AUTHOR ====== Copyright © 1997-1999 Joshua Nathaniel Pritikin. All rights reserved. This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)  File: pm.info, Node: Expect, Next: Expect_FAQ, Prev: Exception/Cxx, Up: Module List Expect for Perl, Version 1.11 ***************************** NAME ==== Expect.pm - Expect for Perl, Version 1.11 SYNOPSIS use Expect; ======================= Expect.pm is built to either spawn a process or take an existing filehandle and interact with it such that normally interactive tasks can be done without operator assistance. This concept makes more sense if you are already familiar with the versatile Tcl version of Expect. The (current) public functions that make up Expect.pm are: Expect->exp_init(\*FILEHANDLE) Expect->spawn($command, @parameters) Expect::interconnect(@objects_to_be_read_from) Expect::test_handles($timeout, @objects_to_test) Expect::version($version_requested | undef); $object->clear_accum() $object->debug($debug_level) $object->exp_internal(0 | 1 | undef) $object->exp_stty(@stty_modes)# See the IO::Stty docs $object->expect($timeout, @match_patterns) $object->exp_before(); $object->exp_match(); $object->exp_after(); $object->exp_matchlist(); $object->exp_match_number(); $object->exp_error(); $object->exp_command(); $object->exp_exitstatus(); $object->exp_pty_handle(); $object->restart_timeout_upon_receive(0 | 1); $object->interact($other_object, $escape_sequence) $object->log_group(0 | 1 | undef) $object->log_user(0 | 1 | undef) $object->log_file("filename" | $filehandle | undef) $object->manual_stty(0 | 1 | undef) $object->match_max($max_buffersize or undef) $object->exp_pid(); $object->send_slow($delay, @strings_to_send) $object->set_group(@listen_group_objects | undef) $object->set_seq($sequence,\&function,\@parameters); There are several configurable package variables that affect the behavior of Expect. They are: $Expect::Debug; $Expect::Exp_Internal; $Expect::Log_Group; $Expect::Log_Stdout; $Expect::Manual_Stty; $Expect::Multiline_Matching; DESCRIPTION =========== The Expect module is a successor of Comm.pl and a descendent of Chat.pl. It more closely ressembles the Tcl Expect language than its predecessors. It does not contain any of the networking code found in Comm.pl. I suspect this would be obsolete anyway given the advent of IO::Socket and external tools such as netcat. Expect.pm is an attempt to have more of a switch() & case: feeling to make decision processing more fluid. Three separate types of debugging have been implemented to make code production easier. It is now possible to interconnect multiple file handles (and processes) much like Tcl's expect. An attempt was made to enable all the features of Tcl's expect without forcing Tcl on the victim programmer :-) . USAGE ===== * Initializes $new_handle_object for use with other Expect functions. It must be passed a *_reference_* to FILEHANDLE if you want it to work properly. IO::File objects are preferable. Returns a reference to the newly created object. * Expect->spawn($command, @parameters) Forks and execs $command. returns a reference to the newly created process object. Returns undef if the fork was unsuccessful or the object could not be created. * Expect::interconnect(@objects); Read from @objects and print to their @listen_groups until an escape sequence is matched from one of @objects and the associated function returns 0 or undef. The special escape sequence 'EOF' is matched when an object's handle returns an end of file. Note that it is not necessary to include objects that only accept data in @objects since the escape sequence is _read_ from an object. Further note that the listen_group for a write-only object is always empty. Why would you want to have objects listening to STDOUT (for example)? By default every member of @objects _as well as every member of its listen group_ will be set to 'raw -echo' for the duration of interconnection. Setting $object->manual_stty() will stop this behavior per object. The original tty settings will be restored as interconnect exits. * Expect::test_handles(@objects) Given a set of objects determines which objects' handles have data ready to be read. *Returns an array* who's members are positions in @objects that have ready handles. Returns undef if there are no such handles ready. * Expect::version($version_requested or undef); Returns current version of Expect. As of .99 earlier versions are not supported. Too many things were changed to make versioning possible. * $object->clear_accum() Clear the contents of the accumulator for $object. This gets rid of any residual contents of a handle after expect() or send_slow() such that the next expect() call will only see new data from $object. The contents of the accumulator are returned. * $object->debug(0 | 1 | 2 | 3 | undef) Sets debug level for $object. 1 refers to general debugging information, 2 refers to verbose debugging and 0 refers to no debugging. If you call debug() with no parameters it will return the current debugging level. When the object is created the debugging level will match that $Expect::Debug, normally 0. The '3' setting is new with 1.05, and adds the additional functionality of having the _full_ accumulated buffer printed every time data is read from an Expect object. This was implemented by request. I recommend against using this unless you think you need it as it can create quite a quantity of output under some circumstances.. * $object->exp_internal(1 | 0) Sets/unsets 'exp_internal' debugging. This is similar in nature to its Tcl counterpart. It is extremely valuable when debugging expect() sequences. When the object is created the exp_internal setting will match the value of $Expect::Exp_Internal, normally 0. Returns the current setting if called without parameters. It is highly recommended that you make use of the debugging features lest you have angry code. * $object->expect_stty($mode) Sets the tty mode for $object's associated terminal to $mode. Typical values are 'sane', 'raw', and 'raw -echo'. This should be used in conjunction with manual_stty(). See the docs for IO::Stty to see what values make sense here. * $object->expect($timeout, @match_patterns) or, more like Tcl/Expect, expect($timeout, '-i', [ $obj1, $obj2, ... ], [ $re_pattern, sub { ...; exp_continue; }, @subparms, ], [ 'eof', sub { ... } ], [ 'timeout', sub { ... }, \$subparm1 ], '-i', [ $objn, ...], '-ex', $exact_pattern, sub { ... }, $exact_pattern, sub { ...; exp_continue_timeout; }, '-re', $re_pattern, sub { ... }, '-i', \@object_list, @pattern_list, ...); *Simple interface:* Given $timeout in seconds Expect will wait for $object's handle to produce one of the match_patterns. Due to o/s limitations $timeout should be a round number. If $timeout is 0 Expect will check one time to see if $object's handle contains any of the match_patterns. If $timeout is undef Expect will wait forever for a pattern to match. If called in a scalar context, expect() will return the position of the matched pattern within $match_patterns, or undef if no pattern was matched. This is a position starting from 1, so if you want to know which of an array of @matched_patterns matched you should subtract one from the return value. If called in an array context expect() will return ($matched_pattern_position, $error, $successfully_matching_string, $before_match, and $after_match). $matched_pattern_position will contain the value that would have been returned if expect() had been called in a scalar context. $error is the error that occurred that caused expect() to return. $error will contain a number followed by a string equivalent expressing the nature of the error. Possible values are undef, indicating no error, '1:TIMEOUT' indicating that $timeout seconds had elapsed without a match, '2:EOF' indicating an eof was read from $object, '3: spawn id($fileno) died' indicating that the process exited before matching and '4:$!' indicating whatever error was set in $ERRNO during the last read on $object's handle. All handles indicated by set_group plus STDOUT will have all data to come out of $object printed to them during expect() if log_group and log_stdout are set. Changed from older versions is the regular expression handling. By default now all strings passed to expect() are treated as literals. To match a regular expression pass '-re' as a parameter in front of the pattern you want to match as a regexp. Example: $object->expect(15, 'match me exactly','-re','match\s+me\s+exactly'); This change makes it possible to match literals and regular expressions in the same expect() call. Also new is multiline matching. ^ will now match the beginning of lines. Unfortunately, because perl doesn't use $/ in determining where lines break using $ to find the end of a line frequently doesn't work. This is because your terminal is returning "\r\n" at the end of every line. One way to check for a pattern at the end of a line would be to use \r?$ instead of $. Example: Spawning telnet to a host, you might look for the escape character. telnet would return to you "\r\nEscape character is '^]'.\r\n". To find this you might use $match='^Escape char.*\.\r?$'; $telnet->expect(10,'-re',$match); *New more TCL-like interface (added by RGiersig@cpan.org):* It's now possible to expect on more than one connection at a time by specifying '-i' (see the TCL expect manpage) and a ref to an array containing Expect objects. Furthermore, patterns can now be specified as array refs containing [$regexp, sub { ...}, @optional_subprams] . When the pattern matches, the subroutine is called with parameters ($matched_expect_obj, @optional_subparms). The subroutine can return the symbol `exp_continue' to continue the expect matching with timeout starting anew or return the symbol `exp_continue_timeout' for continuing expect without resetting the timeout count. `expect' is now exported by default. [I did my best to assure backward compatibility with the old-style call interface, but hey, I'm JAPH... - Roland] * $object->exp_before(); exp_before() returns the 'before' part of the last expect() call. If the last expect() call didn't match anything, exp_before() will return the entire output of the object accumulated before the expect() call finished. * $object->exp_after(); exp_after() returns the 'after' part of the last expect() call. If the last expect() call didn't match anything, exp_after() will return undef(). exp_match() returns the string matched by the last expect() call, undef if no string was matched. * $object->exp_match_number(); exp_match_number() returns the number of the pattern matched by the last expect() call. Keep in mind that the first pattern in a list of patterns is 1, not 0. Returns undef if no pattern was matched. * $object->exp_matchlist(); exp_matchlist() returns a list of matched substrings from the brackets () inside the regexp that last matched. ($object->exp_matchlist)[0] thus corresponds to $1, ($object->exp_matchlist)[1] to $2, etc. * $object->exp_error(); exp_error() returns the error generated by the last expect() call if no pattern was matched. It is typically useful to examine the value returned by exp_before() to find out what the output of the object was in determining why it didn't match any of the patterns. * $object->exp_command(); exp_command() returns the string that was used to spawn the command. Helpful for debugging and for reused patternmatch subroutines. * $object->exp_exitstatus() Returns the exit status of $object (if it already exited). * $object->exp_pty_handle() Returns a string representation of the attached pty, for example: `spawn id(5)' (pty has fileno 5), `handle id(7)' (pty was initialized from fileno 7) or `STDIN'. Useful for debugging. * $object->restart_timeout_upon_receive(0 | 1) If this is set to 1, the expect timeout is retriggered whenever something is received from the spawned command. This allows to perform some aliveness testing and still expect for patterns. $exp->restart_timeout_upon_receive(1); $exp->expect($timeout, [ timeout => \&report_timeout ], [ qr/pattern/ => \&handle_pattern], ); Now the timeout isn't triggered if the command produces any kind of output, i.e. is still alive, but you can act upon patterns in the output. * $object->interact( `\*FILEHANDLE, $escape_sequence') interact() is essentially a macro for calling interconnect() for connecting 2 processes together. \*FILEHANDLE defaults to \*STDIN and $escape_sequence defaults to undef. Interaction ceases when $escape_sequence is read from *FILEHANDLE*, not $object. $object's listen group will consist solely of \*FILEHANDLE for the duration of the interaction. \*FILEHANDLE will not be echoed on STDOUT. * $object->log_group(0 | 1 | undef) Set/unset logging of $object to its 'listen group'. If set all objects in the listen group will have output from $object printed to them during $object->expect(), $object->send_slow(), and `Expect::interconnect($object , ...)'. Default value is on. During creation of $object the setting will match the value of $Expect::Log_Group, normally 1. * $object->log_user(0 | 1 | undef) Set/unset logging of object's handle to STDOUT. This corresponds to Tcl's log_user variable. Returns current setting if called without parameters. Default setting is off for initialized handles. When a process object is created (not a filehandle initialized with exp_init) the log_stdout setting will match the value of $Expect::Log_Stdout variable, normally 1. If/when you initialize STDIN it is usually associated with a tty which will by default echo to STDOUT anyway, so be careful or you will have multiple echoes. * $object->log_file("filename" | $filehandle | undef) Log session to a file. All characters send to or received from the spawned process are written to the file. Normally appends to the logfile, but you can pass an additional mode of "w" to truncate the file upon open(): $object->log_file("filename", "w"); Returns the logfilehandle. If called with an undef value, stops logging and closes logfile: $object->log_file(undef); If called without argument, returns the logfilehandle: $fh = $object->log_file(); * $object->set_seq($sequence, \&function, \@function_parameters) During Expect->interconnect() if $sequence is read from $object &function will be executed with parameters @function_parameters. It is *_highly recommended_* that the escape sequence be a single character since the likelihood is great that the sequence will be broken into to separate reads from the $object's handle, making it impossible to strip $sequence from getting printed to $object's listen group. \&function should be something like 'main::control_w_function' and @function_parameters should be an array defined by the caller, passed by reference to set_seq(). Your function should return a non-zero value if execution of interconnect() is to resume after the function returns, zero or undefined if interconnect() should return after your function returns. The special sequence 'EOF' matches the end of file being reached by $object. See interconnect() for details. * $object->set_group(@listener_objects) @listener_objects is the list of objects that should have their handles printed to by $object when Expect::interconnect, $object->expect() or $object->send_slow() are called. Calling w/out parameters will return the current list of the listener objects. * $object->manual_stty(0 | 1 | undef) Sets/unsets whether or not Expect should make reasonable guesses as to when and how to set tty parameters for $object. Will match $Expect::Manual_Stty value (normally 0) when $object is created. If called without parameters manual_stty() will return the current manual_stty setting. * $object->match_max($maximum_buffer_length | undef) Set the maximum accumulator size for object. This is useful if you think that the accumulator will grow out of hand during expect() calls. Since the buffer will be matched by every match_pattern it may get slow if the buffer gets too large. Returns current value if called without parameters. Not defined by default. * $object->exp_pid() Return pid of $object, if one exists. Initialized filehandles will not have pids (of course). * $object->send_slow($delay, @strings); print each character from each string of @strings one at a time with $delay seconds before each character. This is handy for devices such as modems that can be annoying if you send them data too fast. After each character $object will be checked to determine whether or not it has any new data ready and if so update the accumulator for future expect() calls and print the output to STDOUT and @listen_group if log_stdout and log_group are appropriately set. Configurable Package Variables: ------------------------------- $Expect::Debug; Defaults to 0. Newly created objects have a $object->debug() value of $Expect::Debug. See $object->debug(); $Expect::Exp_Internal; Defaults to 0. Newly created objects have a $object->exp_internal() value of $Expect::Exp_Internal. See $object->exp_internal(). $Expect::Log_Group; Defaults to 1. Newly created objects have a $object->log_group() value of $Expect::Log_Group. See $object->log_group(). $Expect::Log_Stdout; Defaults to 1 for spawned commands, 0 for file handles attached with exp_init(). Newly created objects have a $object->log_stdout() value of $Expect::Log_Stdout. See $object->log_stdout(). $Expect::Manual_Stty; Defaults to 0. Newly created objects have a $object->manual_stty() value of $Expect::Manual_Stty. See $object->manual_stty(). $Expect::Multiline_Matching; Defaults to 1. Affects whether or not expect() uses the /m flag for doing regular expression matching. If set to 1 /m is used. This makes a difference when you are trying to match ^ and $. If you have this on you can match lines in the middle of a page of output using ^ and $ instead of it matching the beginning and end of the entire expression. I think this is handy. CONTRIBUTIONS ============= Lee Eakin has ported the kibitz script from Tcl/Expect to Perl/Expect. You can find it in the examples/ subdir. Thanks Lee! SEE ALSO ======== *Note Expect_FAQ: Expect_FAQ, HOMEPAGE ======== http://sourceforge.net/projects/expectperl/ AUTHORS ======= (c) 1997 Austin Schutz expect() interface & functionality enhancements (c) 1999 Roland Giersig. This module now is maintained by Roland Giersig LICENSE ======= This module can be used under the same terms as Perl.