texlive[54373] Master/tlpkg/tlperl/site/lib: Win32::OLE module

commits+siepo at tug.org commits+siepo at tug.org
Tue Mar 17 12:32:46 CET 2020


Revision: 54373
          http://tug.org/svn/texlive?view=revision&revision=54373
Author:   siepo
Date:     2020-03-17 12:32:46 +0100 (Tue, 17 Mar 2020)
Log Message:
-----------
Win32::OLE module removed; no longer needed

Removed Paths:
-------------
    trunk/Master/tlpkg/tlperl/site/lib/OLE.pm
    trunk/Master/tlpkg/tlperl/site/lib/Win32/OLE/
    trunk/Master/tlpkg/tlperl/site/lib/Win32/OLE.pm
    trunk/Master/tlpkg/tlperl/site/lib/auto/Win32/OLE/

Deleted: trunk/Master/tlpkg/tlperl/site/lib/OLE.pm
===================================================================
--- trunk/Master/tlpkg/tlperl/site/lib/OLE.pm	2020-03-17 00:59:37 UTC (rev 54372)
+++ trunk/Master/tlpkg/tlperl/site/lib/OLE.pm	2020-03-17 11:32:46 UTC (rev 54373)
@@ -1,177 +0,0 @@
-# Compatibility layer for applications using the old toplevel OLE.pm.
-# New code should use Win32::OLE
-
-# This file is based on ../lib/OLE.pm from ActiveState build 315.
-
-# Compatibility notes:
-# - "GetObject" -> "GetActiveObject"
-# - "keys %$collection" -> "Win32::OLE::Enum->All($collection)"
-#                       or "in $Collection"
-# - "unnamed" default method retries
-
-########################################################################
-# package Win32;
-########################################################################
-
-*Win32::OLELastError = sub { return OLE->LastError() };
-
-
-########################################################################
-package OLE::Variant;
-########################################################################
-
-use Win32::OLE qw(CP_ACP);
-use Win32::OLE::Variant;
-
-use strict;
-use vars qw($AUTOLOAD @ISA $LCID $CP $Warn $LastError $_NewEnum $_Unique);
- at ISA = qw(Win32::OLE::Variant);
-
-$Warn = 0;
-$LCID = 2 << 10; # LOCALE_SYSTEM_DEFAULT
-$CP = CP_ACP;
-$_NewEnum = 0;
-$_Unique = 0;
-
-sub new {
-    my $self = shift;
-    my $variant = $self->SUPER::new(@_);
-    $OLE::LastError = $Win32::OLE->LastError unless defined $variant;
-    return $variant;
-}
-
-
-########################################################################
-package OLE::Tie;
-########################################################################
-use strict;
-use vars qw(@ISA);
- at ISA = qw(Win32::OLE::Tie);
-
-# !!! It is VERY important that Win32::OLE::Tie::DESTROY gets called. !!!
-# If you subclass DESTROY, don't forget to call $self->SUPER::DESTROY.
-# Otherwise the OLE interfaces will not be released until process termination!
-
-# Retry default method if property doesn't exist
-sub FETCH {
-    my ($self,$key) = @_;
-    return $self->SUPER::Fetch($key, 1);
-}
-
-sub STORE {
-    my ($self,$key,$value) = @_;
-    $self->SUPER::Store($key, $value, 1);
-}
-
-# Enumerate collection members, not object properties
-*FIRSTKEY = *Win32::OLE::Tie::FIRSTENUM;
-*NEXTKEY = *Win32::OLE::Tie::NEXTENUM;
-
-
-########################################################################
-package OLE;
-########################################################################
-use Win32::OLE qw(CP_ACP);
-
-# Use OleInitialize() instead of CoInitializeEx:
-Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE);
-
-use strict;
-
-# Disable overload; unfortunately "no overload" doesn't do it :-(
-# Overloading is no longer enabled by default in Win32::OLE
-#use overload '""'     => sub {overload::StrVal($_[0])},
-#             '0+'     => sub {overload::StrVal($_[0])};
-
-use vars qw($AUTOLOAD @ISA $LCID $CP $Warn $LastError $Tie);
- at ISA = qw(Win32::OLE);
-
-$Warn = 0;
-$LCID = 2 << 10; # LOCALE_SYSTEM_DEFAULT
-$CP = CP_ACP;
-$Tie = 'OLE::Tie';
-
-sub new {
-    my $class = shift;
-    $class = shift if $class eq 'OLE';
-    return OLE->SUPER::new($class);
-}
-
-sub copy {
-    my $class = shift;
-    $class = shift if $class eq 'OLE';
-    return OLE->SUPER::GetActiveObject($class);
-}
-
-sub AUTOLOAD {
-    my $self = shift;
-    my $retval;
-    $AUTOLOAD =~ s/.*:://o;
-
-    Carp::croak("Cannot autoload class method \"$AUTOLOAD\"") 
-      unless ref($self) && UNIVERSAL::isa($self,'OLE');
-
-    local $^H = 0; # !hack alert!
-    unless (defined $self->Dispatch($AUTOLOAD, $retval, @_)) {
-	# Retry default method
-	$self->Dispatch(undef, $retval, $AUTOLOAD, @_);
-    }
-    return $retval;
-}
-
-*CreateObject = \&new;
-*GetObject = \©
-
-# Automation data types.
-
-sub VT_EMPTY {0;}
-sub VT_NULL {1;}
-sub VT_I2 {2;}
-sub VT_I4 {3;}
-sub VT_R4 {4;}
-sub VT_R8 {5;}
-sub VT_CY {6;}
-sub VT_DATE {7;}
-sub VT_BSTR {8;}
-sub VT_DISPATCH {9;}
-sub VT_ERROR {10;}
-sub VT_BOOL {11;}
-sub VT_VARIANT {12;}
-sub VT_UNKNOWN {13;}
-sub VT_I1 {16;}
-sub VT_UI1 {17;}
-sub VT_UI2 {18;}
-sub VT_UI4 {19;}
-sub VT_I8 {20;}
-sub VT_UI8 {21;}
-sub VT_INT {22;}
-sub VT_UINT {23;}
-sub VT_VOID {24;}
-sub VT_HRESULT {25;}
-sub VT_PTR {26;}
-sub VT_SAFEARRAY {27;}
-sub VT_CARRAY {28;}
-sub VT_USERDEFINED {29;}
-sub VT_LPSTR {30;}
-sub VT_LPWSTR {31;}
-sub VT_FILETIME {64;}
-sub VT_BLOB {65;}
-sub VT_STREAM {66;}
-sub VT_STORAGE {67;}
-sub VT_STREAMED_OBJECT {68;}
-sub VT_STORED_OBJECT {69;}
-sub VT_BLOB_OBJECT {70;}
-sub VT_CF {71;}
-sub VT_CLSID {72;}
-
-sub TKIND_ENUM {0;}
-sub TKIND_RECORD {1;}
-sub TKIND_MODULE {2;}
-sub TKIND_INTERFACE {3;}
-sub TKIND_DISPATCH {4;}
-sub TKIND_COCLASS {5;}
-sub TKIND_ALIAS {6;}
-sub TKIND_UNION {7;}
-sub TKIND_MAX {8;}
-
-1;

Deleted: trunk/Master/tlpkg/tlperl/site/lib/Win32/OLE.pm
===================================================================
--- trunk/Master/tlpkg/tlperl/site/lib/Win32/OLE.pm	2020-03-17 00:59:37 UTC (rev 54372)
+++ trunk/Master/tlpkg/tlperl/site/lib/Win32/OLE.pm	2020-03-17 11:32:46 UTC (rev 54373)
@@ -1,968 +0,0 @@
-# The documentation is at the __END__
-
-package Win32::OLE;
-
-use strict;
-use vars qw($VERSION @ISA @EXPORT @EXPORT_OK @EXPORT_FAIL $AUTOLOAD
-	    $CP $LCID $Warn $LastError $_NewEnum $_Unique);
-
-$VERSION = '0.1712';
-
-use Carp;
-use Exporter;
-use DynaLoader;
- at ISA = qw(Exporter DynaLoader);
-
- at EXPORT = qw();
- at EXPORT_OK = qw(in valof with HRESULT EVENTS OVERLOAD
-                CP_ACP CP_OEMCP CP_MACCP CP_UTF7 CP_UTF8
-		DISPATCH_METHOD DISPATCH_PROPERTYGET
-		DISPATCH_PROPERTYPUT DISPATCH_PROPERTYPUTREF);
- at EXPORT_FAIL = qw(EVENTS OVERLOAD);
-
-sub export_fail {
-    shift;
-    my @unknown;
-    while (@_) {
-	my $symbol = shift;
-	if ($symbol eq 'OVERLOAD') {
-	    eval <<'OVERLOAD';
-	        use overload '""'     => \&valof,
-	                     '0+'     => \&valof,
-	                     fallback => 1;
-OVERLOAD
-	}
-	elsif ($symbol eq 'EVENTS') {
-	    Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE());
-	}
-	else {
-	    push @unknown, $symbol;
-	}
-    }
-    return @unknown;
-}
-
-unless (defined &Dispatch) {
-    # Use regular DynaLoader if XS part is not yet initialized
-    bootstrap Win32::OLE;
-    require Win32::OLE::Lite;
-}
-
-1;
-
-########################################################################
-
-__END__
-
-=head1 NAME
-
-Win32::OLE - OLE Automation extensions
-
-=head1 SYNOPSIS
-
-    $ex = Win32::OLE->new('Excel.Application') or die "oops\n";
-    $ex->Amethod("arg")->Bmethod->{'Property'} = "foo";
-    $ex->Cmethod(undef,undef,$Arg3);
-    $ex->Dmethod($RequiredArg1, {NamedArg1 => $Value1, NamedArg2 => $Value2});
-
-    $wd = Win32::OLE->GetObject("D:\\Data\\Message.doc");
-    $xl = Win32::OLE->GetActiveObject("Excel.Application");
-
-=head1 DESCRIPTION
-
-This module provides an interface to OLE Automation from Perl.
-OLE Automation brings VisualBasic like scripting capabilities and
-offers powerful extensibility and the ability to control many Win32
-applications from Perl scripts.
-
-The Win32::OLE module uses the IDispatch interface exclusively.  It is
-not possible to access a custom OLE interface.  OLE events and OCX's are
-currently not supported.
-
-Actually, that's no longer strictly true.  This module now contains
-B<ALPHA> level support for OLE events.  This is largely untested and the
-specific interface might still change in the future.
-
-=head2 Methods
-
-=over 8
-
-=item Win32::OLE->new(PROGID[, DESTRUCTOR])
-
-The new() class method starts a new instance of an OLE Automation object.
-It returns a reference to this object or C<undef> if the creation failed.
-
-The PROGID argument must be either the OLE I<program id> or the I<class id>
-of the required application.  The optional DESTRUCTOR specifies a DESTROY-like
-method.  This can be either a CODE reference or a string containing an OLE
-method name.  It can be used to cleanly terminate OLE applications in case the
-Perl program dies.
-
-To create an object via DCOM on a remote server you can use an array
-reference in place of PROGID.  The referenced array must contain the
-machine name and the I<program id> or I<class id>.  For example:
-
-	my $obj = Win32::OLE->new(['my.machine.com', 'Program.Id']);
-
-If the PROGID is a I<program id> then Win32::OLE will try to resolve the
-corresponding I<class id> locally.  If the I<program id> is not registered
-locally then the remote registry is queried.  This will only succeed if
-the local process has read access to the remote registry.  The safest
-(and fastest) method is to specify the C<class id> directly.
-
-=item Win32::OLE->EnumAllObjects([CALLBACK])
-
-This class method returns the number Win32::OLE objects currently in
-existence.  It will call the optional CALLBACK function for each of
-these objects:
-
-	$Count = Win32::OLE->EnumAllObjects(sub {
-	    my $Object = shift;
-	    my $Class = Win32::OLE->QueryObjectType($Object);
-	    printf "# Object=%s Class=%s\n", $Object, $Class;
-	});
-
-The EnumAllObjects() method is primarily a debugging tool.  It can be
-used e.g. in an END block to check if all external connections have
-been properly destroyed.
-
-=item Win32::OLE->FreeUnusedLibraries()
-
-The FreeUnusedLibraries() class method unloads all unused OLE
-resources.  These are the libraries of those classes of which all
-existing objects have been destroyed.  The unloading of object
-libraries is really only important for long running processes that
-might instantiate a huge number of B<different> objects over time.
-
-Be aware that objects implemented in Visual Basic have a buggy
-implementation of this functionality: They pretend to be unloadable
-while they are actually still running their cleanup code.  Unloading
-the DLL at that moment typically produces an access violation.  The
-probability for this problem can be reduced by calling the
-SpinMessageLoop() method and sleep()ing for a few seconds.
-
-=item Win32::OLE->GetActiveObject(CLASS[, DESTRUCTOR])
-
-The GetActiveObject() class method returns an OLE reference to a
-running instance of the specified OLE automation server.  It returns
-C<undef> if the server is not currently active.  It will croak if
-the class is not even registered.  The optional DESTRUCTOR method takes
-either a method name or a code reference.  It is executed when the last
-reference to this object goes away.  It is generally considered rude
-to stop applications that you did not start yourself.
-
-=item Win32::OLE->GetObject(MONIKER[, DESTRUCTOR])
-
-The GetObject() class method returns an OLE reference to the specified
-object.  The object is specified by a pathname optionally followed by
-additional item subcomponent separated by exclamation marks '!'.  The
-optional DESTRUCTOR argument has the same semantics as the DESTRUCTOR in
-new() or GetActiveObject().
-
-=item Win32::OLE->Initialize([COINIT])
-
-The Initialize() class method can be used to specify an alternative
-apartment model for the Perl thread.  It must be called B<before> the
-first OLE object is created.  If the C<Win32::OLE::Const> module is
-used then the call to the Initialize() method must be made from a BEGIN
-block before the first C<use> statement for the C<Win32::OLE::Const>
-module.
-
-Valid values for COINIT are:
-
-  Win32::OLE::COINIT_APARTMENTTHREADED  - single threaded
-  Win32::OLE::COINIT_MULTITHREADED      - the default
-  Win32::OLE::COINIT_OLEINITIALIZE      - single threaded, additional OLE stuff
-
-COINIT_OLEINITIALIZE is sometimes needed when an OLE object uses
-additional OLE compound document technologies not available from the
-normal COM subsystem (for example MAPI.Session seems to require it).
-Both COINIT_OLEINITIALIZE and COINIT_APARTMENTTHREADED create a hidden
-top level window and a message queue for the Perl process.  This may
-create problems with other application, because Perl normally doesn't
-process its message queue.  This means programs using synchronous
-communication between applications (such as DDE initiation), may hang
-until Perl makes another OLE method call/property access or terminates.
-This applies to InstallShield setups and many things started to shell
-associations.  Please try to utilize the C<Win32::OLE-E<gt>SpinMessageLoop>
-and C<Win32::OLE-E<gt>Uninitialize> methods if you can not use the default
-COINIT_MULTITHREADED model.
-
-=item OBJECT->Invoke(METHOD[, ARGS])
-
-The Invoke() object method is an alternate way to invoke OLE
-methods.  It is normally equivalent to C<$OBJECT-E<gt>METHOD(@ARGS)>.  This
-function must be used if the METHOD name contains characters not valid
-in a Perl variable name (like foreign language characters).  It can
-also be used to invoke the default method of an object even if the
-default method has not been given a name in the type library.  In this
-case use <undef> or C<''> as the method name.  To invoke an OLE objects
-native Invoke() method (if such a thing exists), please use:
-
-	$Object->Invoke('Invoke', @Args);
-
-=item Win32::OLE->LastError()
-
-The LastError() class method returns the last recorded OLE
-error.  This is a dual value like the C<$!> variable: in a numeric
-context it returns the error number and in a string context it returns
-the error message.  The error number is a signed HRESULT value.  Please
-use the L<HRESULT(ERROR)> function to convert an unsigned hexadecimal
-constant to a signed HRESULT.
-
-The last OLE error is automatically reset by a successful OLE
-call.  The numeric value can also explicitly be set by a call (which will
-discard the string value):
-
-	Win32::OLE->LastError(0);
-
-=item OBJECT->LetProperty(NAME,ARGS,VALUE)
-
-In Win32::OLE property assignment using the hash syntax is equivalent
-to the Visual Basic C<Set> syntax (I<by reference> assignment):
-
-	$Object->{Property} = $OtherObject;
-
-corresponds to this Visual Basic statement:
-
-	Set Object.Property = OtherObject
-
-To get the I<by value> treatment of the Visual Basic C<Let> statement
-
-	Object.Property = OtherObject
-
-you have to use the LetProperty() object method in Perl:
-
-	$Object->LetProperty($Property, $OtherObject);
-
-LetProperty() also supports optional arguments for the property assignment.
-See L<OBJECT->SetProperty(NAME,ARGS,VALUE)> for details.
-
-=item Win32::OLE->MessageLoop()
-
-The MessageLoop() class method will run a standard Windows message
-loop, dispatching messages until the QuitMessageLoop() class method is
-called.  It is used to wait for OLE events.
-
-=item Win32::OLE->Option(OPTION)
-
-The Option() class method can be used to inspect and modify
-L<Module Options>.  The single argument form retrieves the value of
-an option:
-
-	my $CP = Win32::OLE->Option('CP');
-
-A single call can be used to set multiple options simultaneously:
-
-	Win32::OLE->Option(CP => CP_ACP, Warn => 3);
-
-=item Win32::OLE->QueryObjectType(OBJECT)
-
-The QueryObjectType() class method returns a list of the type library
-name and the objects class name.  In a scalar context it returns the
-class name only.  It returns C<undef> when the type information is not
-available.
-
-=item Win32::OLE->QuitMessageLoop()
-
-The QuitMessageLoop() class method posts a (user-level) "Quit" message
-to the current threads message loop.  QuitMessageLoop() is typically
-called from an event handler.  The MessageLoop() class method will
-return when it receives this "Quit" method.
-
-=item OBJECT->SetProperty(NAME,ARGS,VALUE)
-
-The SetProperty() method allows to modify properties with arguments,
-which is not supported by the hash syntax.  The hash form
-
-	$Object->{Property} = $Value;
-
-is equivalent to
-
-	$Object->SetProperty('Property', $Value);
-
-Arguments must be specified between the property name and the new value:
-
-	$Object->SetProperty('Property', @Args, $Value);
-
-It is not possible to use "named argument" syntax with this function
-because the new value must be the last argument to SetProperty().
-
-This method hides any native OLE object method called SetProperty().
-The native method will still be available through the Invoke() method:
-
-	$Object->Invoke('SetProperty', @Args);
-
-=item Win32::OLE->SpinMessageLoop
-
-This class method retrieves all pending messages from the message queue
-and dispatches them to their respective window procedures.  Calling this
-method is only necessary when not using the COINIT_MULTITHREADED model.
-All OLE method calls and property accesses automatically process the
-message queue.
-
-=item Win32::OLE->Uninitialize
-
-The Uninitialize() class method uninitializes the OLE subsystem.  It
-also destroys the hidden top level window created by OLE for single
-threaded apartments.  All OLE objects will become invalid after this call!
-It is possible to call the Initialize() class method again with a different
-apartment model after shutting down OLE with Uninitialize().
-
-=item Win32::OLE->WithEvents(OBJECT[, HANDLER[, INTERFACE]])
-
-This class method enables and disables the firing of events by the
-specified OBJECT.  If no HANDLER is specified, then events are
-disconnected.  For some objects Win32::OLE is not able to
-automatically determine the correct event interface.  In this case the
-INTERFACE argument must contain either the COCLASS name of the OBJECT
-or the name of the event DISPATCH interface.  Please read the L<Events>
-section below for detailed explanation of the Win32::OLE event
-support.
-
-=back
-
-Whenever Perl does not find a method name in the Win32::OLE package it
-is automatically used as the name of an OLE method and this method call
-is dispatched to the OLE server.
-
-There is one special hack built into the module: If a method or property
-name could not be resolved with the OLE object, then the default method
-of the object is called with the method name as its first parameter.  So
-
-	my $Sheet = $Worksheets->Table1;
-or
-	my $Sheet = $Worksheets->{Table1};
-
-is resolved as
-
-	my $Sheet = $Worksheet->Item('Table1');
-
-provided that the $Worksheets object does not have a C<Table1> method
-or property.  This hack has been introduced to call the default method
-of collections which did not name the method in their type library.  The
-recommended way to call the "unnamed" default method is:
-
-	my $Sheet = $Worksheets->Invoke('', 'Table1');
-
-This special hack is disabled under C<use strict 'subs';>.
-
-=head2 Object methods and properties
-
-The object returned by the new() method can be used to invoke
-methods or retrieve properties in the same fashion as described
-in the documentation for the particular OLE class (eg. Microsoft
-Excel documentation describes the object hierarchy along with the
-properties and methods exposed for OLE access).
-
-Optional parameters on method calls can be omitted by using C<undef>
-as a placeholder.  A better way is to use named arguments, as the
-order of optional parameters may change in later versions of the OLE
-server application.  Named parameters can be specified in a reference
-to a hash as the last parameter to a method call.
-
-Properties can be retrieved or set using hash syntax, while methods
-can be invoked with the usual perl method call syntax.  The C<keys>
-and C<each> functions can be used to enumerate an object's properties.
-Beware that a property is not always writable or even readable (sometimes
-raising exceptions when read while being undefined).
-
-If a method or property returns an embedded OLE object, method
-and property access can be chained as shown in the examples below.
-
-=head2 Functions
-
-The following functions are not exported by default.
-
-=over 8
-
-=item HRESULT(ERROR)
-
-The HRESULT() function converts an unsigned number into a signed HRESULT
-error value as used by OLE internally.  This is necessary because Perl
-treats all hexadecimal constants as unsigned.  To check if the last OLE
-function returned "Member not found" (0x80020003) you can write:
-
-	if (Win32::OLE->LastError == HRESULT(0x80020003)) {
-	    # your error recovery here
-	}
-
-=item in(COLLECTION)
-
-If COLLECTION is an OLE collection object then C<in $COLLECTION>
-returns a list of all members of the collection.  This is a shortcut
-for C<Win32::OLE::Enum-E<gt>All($COLLECTION)>.  It is most commonly used in
-a C<foreach> loop:
-
-	foreach my $value (in $collection) {
-	    # do something with $value here
-	}
-
-=item valof(OBJECT)
-
-Normal assignment of Perl OLE objects creates just another reference
-to the OLE object.  The valof() function explictly dereferences the
-object (through the default method) and returns the value of the object.
-
-	my $RefOf = $Object;
-	my $ValOf = valof $Object;
-        $Object->{Value} = $NewValue;
-
-Now $ValOf still contains the old value whereas $RefOf would
-resolve to the $NewValue because it is still a reference to
-$Object.
-
-The valof() function can also be used to convert Win32::OLE::Variant
-objects to Perl values.
-
-=item with(OBJECT, PROPERTYNAME => VALUE, ...)
-
-This function provides a concise way to set the values of multiple
-properties of an object.  It iterates over its arguments doing
-C<$OBJECT-E<gt>{PROPERTYNAME} = $VALUE> on each trailing pair.
-
-=back
-
-=head2 Overloading
-
-The Win32::OLE objects can be overloaded to automatically convert to
-their values whenever they are used in a bool, numeric or string
-context.  This is not enabled by default.  You have to request it
-through the OVERLOAD pseudoexport:
-
-	use Win32::OLE qw(in valof with OVERLOAD);
-
-You can still get the original string representation of an object
-(C<Win32::OLE=0xDEADBEEF>), e.g. for debugging, by using the
-C<overload::StrVal()> method:
-
-	print overload::StrVal($object), "\n";
-
-Please note that C<OVERLOAD> is a global setting.  If any module enables
-Win32::OLE overloading then it's active everywhere.
-
-=head2 Events
-
-The Win32::OLE module now contains B<ALPHA> level event support.  This
-support is only available when Perl is running in a single threaded
-apartment.  This can most easily be assured by using the C<EVENTS>
-pseudo-import:
-
-	use Win32::OLE qw(EVENTS);
-
-which implicitly does something like:
-
-	use Win32::OLE;
-	Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE);
-
-The current interface to OLE events should be considered experimental
-and is subject to change.  It works as expected for normal OLE
-applications, but OLE control events often don't seem to work yet.
-
-Events must be enabled explicitly for an OLE object through the
-Win32::OLE->WithEvents() class method.  The Win32::OLE module uses the
-IProvideClassInfo2 interface to determine the default event source of
-the object.  If this interface is not supported, then the user must
-specify the name of the event source explicitly in the WithEvents()
-method call.  It is also possible to specify the class name of the
-object as the third parameter.  In this case Win32::OLE will try to
-look up the default source interface for this COCLASS.
-
-The HANDLER argument to Win32::OLE->WithEvents() can either be a CODE
-reference or a package name.  In the first case, all events will invoke
-this particular function.  The first two arguments to this function will
-be the OBJECT itself and the name of the event.  The remaining arguments
-will be event specific.
-
-	sub Event {
-	    my ($Obj,$Event, at Args) = @_;
-	    print "Event triggered: '$Event'\n";
-	}
-	Win32::OLE->WithEvents($Obj, \&Event);
-
-Alternatively the HANDLER argument can specify a package name.  When the
-OBJECT fires an event, Win32::OLE will try to find a function of the same
-name as the event in this package.  This function will be called with the
-OBJECT as the first argument followed again by the event specific parameters:
-
-	package MyEvents;
-	sub EventName1 {
-	    my ($Obj, at Args) = @_;
-	    print "EventName1 event triggered\n";
-	}
-
-	package main;
-	Win32::OLE->WithEvents($Obj, 'MyEvents', 'IEventInterface');
-
-If Win32::OLE doesn't find a function with the name of the event then nothing
-happens.
-
-Event parameters passed I<by reference> are handled specially.  They are not
-converted to the corresponding Perl datatype but passed as Win32::OLE::Variant
-objects.  You can assign a new value to these objects with the help of the
-Put() method.  This value will be passed back to the object when the event
-function returns:
-
-	package MyEvents;
-	sub BeforeClose {
-	    my ($self,$Cancel) = @_;
-	    $Cancel->Put(1) unless $MayClose;
-	}
-
-Direct assignment to $Cancel would have no effect on the original value and
-would therefore not command the object to abort the closing action.
-
-=head2 Module Options
-
-The following module options can be accessed and modified with the
-C<Win32::OLE-E<gt>Option> class method.  In earlier versions of the Win32::OLE
-module these options were manipulated directly as class variables.  This
-practice is now deprecated.
-
-=over 8
-
-=item CP
-
-This variable is used to determine the codepage used by all
-translations between Perl strings and Unicode strings used by the OLE
-interface.  The default value is CP_ACP, which is the default ANSI
-codepage.  Other possible values are CP_OEMCP, CP_MACCP, CP_UTF7 and
-CP_UTF8.  These constants are not exported by default.
-
-=item LCID
-
-This variable controls the locale identifier used for all OLE calls.
-It is set to LOCALE_NEUTRAL by default.  Please check the
-L<Win32::OLE::NLS> module for other locale related information.
-
-=item Variant
-
-This options controls how method calls and property accessors return
-values of type VT_CY and VT_DECIMAL are being returned.  By default
-VT_CY values are turned into strings and VT_DECIMAL values into
-floating point numbers.  If the C<Variant> option is enabled, these
-values are returned as Win32::OLE::Variant objects, just like VT_DATE
-and VT_ERROR values.  If the Win32::OLE::Variant module is also
-loaded, then all values should still behave as before in string and in
-numeric context.
-
-The only reason that the C<Variant> behavior is not the default is that
-this is an incompatible change that might break existing programs.
-
-=item Warn
-
-This variable determines the behavior of the Win32::OLE module when
-an error happens.  Valid values are:
-
-	0	Ignore error, return undef
-	1	Carp::carp if $^W is set (-w option)
-	2	always Carp::carp
-	3	Carp::croak
-
-The error number and message (without Carp line/module info) are
-available through the C<Win32::OLE-E<gt>LastError> class method.
-
-Alternatively the Warn option can be set to a CODE reference.  E.g.
-
-    Win32::OLE->Option(Warn => 3);
-
-is equivalent to
-
-    Win32::OLE->Option(Warn => \&Carp::croak);
-
-This can even be used to emulate the VisualBasic C<On Error Goto
-Label> construct:
-
-    Win32::OLE->Option(Warn =>  sub {goto CheckError});
-    # ... your normal OLE code here ...
-
-  CheckError:
-    # ... your error handling code here ...
-
-=item _NewEnum
-
-This option enables additional enumeration support for collection
-objects.  When the C<_NewEnum> option is set, all collections will
-receive one additional property: C<_NewEnum>.  The value of this
-property will be a reference to an array containing all the elements
-of the collection.  This option can be useful when used in conjunction
-with an automatic tree traversal program, like C<Data::Dumper> or an
-object tree browser.  The value of this option should be either 1
-(enabled) or 0 (disabled, default).
-
-    Win32::OLE->Option(_NewEnum => 1);
-    # ...
-    my @sheets = @{$Excel->Worksheets->{_NewEnum}};
-
-In normal application code, this would be better written as:
-
-    use Win32::OLE qw(in);
-    # ...
-    my @sheets = in $Excel->Worksheets;
-
-=item _Unique
-
-The C<_Unique> options guarantees that Win32::OLE will maintain a
-one-to-one mapping between Win32::OLE objects and the native COM/OLE
-objects.  Without this option, you can query the same property twice
-and get two different Win32::OLE objects for the same underlying COM
-object.
-
-Using a unique proxy makes life easier for tree traversal algorithms
-to recognize they already visited a particular node.  This option
-comes at a price: Win32::OLE has to maintain a global hash of all
-outstanding objects and their corresponding proxies.  Identity checks
-on COM objects can also be expensive if the objects reside
-out-of-process or even on a different computer.  Therefore this option
-is off by default unless the program is being run in the debugger.
-
-Unfortunately, this option doesn't always help.  Some programs will
-return new COM objects for even the same property when asked for it
-multiple times (especially for collections).  In this case, there is
-nothing Win32::OLE can do to detect that these objects are in fact
-identical (because they aren't at the COM level).
-
-The C<_Unique> option can be set to either 1 (enabled) or 0 (disabled,
-default).
-
-=back
-
-=head1 EXAMPLES
-
-Here is a simple Microsoft Excel application.
-
-	use Win32::OLE;
-
-	# use existing instance if Excel is already running
-	eval {$ex = Win32::OLE->GetActiveObject('Excel.Application')};
-	die "Excel not installed" if $@;
-	unless (defined $ex) {
-	    $ex = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;})
-		    or die "Oops, cannot start Excel";
-	}
-
-        # get a new workbook
-        $book = $ex->Workbooks->Add;
-
-	# write to a particular cell
-	$sheet = $book->Worksheets(1);
-	$sheet->Cells(1,1)->{Value} = "foo";
-
-        # write a 2 rows by 3 columns range
-        $sheet->Range("A8:C9")->{Value} = [[ undef, 'Xyzzy', 'Plugh' ],
-                                           [ 42,    'Perl',  3.1415  ]];
-
-        # print "XyzzyPerl"
-        $array = $sheet->Range("A8:C9")->{Value};
-	for (@$array) {
-	    for (@$_) {
-		print defined($_) ? "$_|" : "<undef>|";
-	    }
-	    print "\n";
-	}
-
-	# save and exit
-        $book->SaveAs( 'test.xls' );
-	undef $book;
-	undef $ex;
-
-Please note the destructor specified on the Win32::OLE->new method.  It ensures
-that Excel will shutdown properly even if the Perl program dies.  Otherwise
-there could be a process leak if your application dies after having opened
-an OLE instance of Excel.  It is the responsibility of the module user to
-make sure that all OLE objects are cleaned up properly!
-
-Here is an example of using Variant data types.
-
-	use Win32::OLE;
-	use Win32::OLE::Variant;
-	$ex = Win32::OLE->new('Excel.Application', \&OleQuit) or die "oops\n";
-	$ex->{Visible} = 1;
-	$ex->Workbooks->Add;
-	# should generate a warning under -w
-	$ovR8 = Variant(VT_R8, "3 is a good number");
-	$ex->Range("A1")->{Value} = $ovR8;
-	$ex->Range("A2")->{Value} = Variant(VT_DATE, 'Jan 1,1970');
-
-	sub OleQuit {
-	    my $self = shift;
-	    $self->Quit;
-	}
-
-The above will put value "3" in cell A1 rather than the string
-"3 is a good number".  Cell A2 will contain the date.
-
-Similarly, to invoke a method with some binary data, you can
-do the following:
-
-	$obj->Method( Variant(VT_UI1, "foo\000b\001a\002r") );
-
-Here is a wrapper class that basically delegates everything but
-new() and DESTROY().  The wrapper class shown here is another way to
-properly shut down connections if your application is liable to die
-without proper cleanup.  Your own wrappers will probably do something
-more specific to the particular OLE object you may be dealing with,
-like overriding the methods that you may wish to enhance with your
-own.
-
-	package Excel;
-	use Win32::OLE;
-
-	sub new {
-	    my $s = {};
-	    if ($s->{Ex} = Win32::OLE->new('Excel.Application')) {
-		return bless $s, shift;
-	    }
-	    return undef;
-	}
-
-	sub DESTROY {
-	    my $s = shift;
-	    if (exists $s->{Ex}) {
-		print "# closing connection\n";
-		$s->{Ex}->Quit;
-		return undef;
-	    }
-	}
-
-	sub AUTOLOAD {
-	    my $s = shift;
-	    $AUTOLOAD =~ s/^.*:://;
-	    $s->{Ex}->$AUTOLOAD(@_);
-	}
-
-	1;
-
-The above module can be used just like Win32::OLE, except that
-it takes care of closing connections in case of abnormal exits.
-Note that the effect of this specific example can be easier accomplished
-using the optional destructor argument of Win32::OLE::new:
-
-	my $Excel = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;});
-
-Note that the delegation shown in the earlier example is not the same as
-true subclassing with respect to further inheritance of method calls in your
-specialized object.  See L<perlobj>, L<perltoot> and L<perlbot> for details.
-True subclassing (available by setting C<@ISA>) is also feasible,
-as the following example demonstrates:
-
-	#
-	# Add error reporting to Win32::OLE
-	#
-
-	package Win32::OLE::Strict;
-	use Carp;
-	use Win32::OLE;
-
-	use strict qw(vars);
-	use vars qw($AUTOLOAD @ISA);
-	@ISA = qw(Win32::OLE);
-
-	sub AUTOLOAD {
-	    my $obj = shift;
-	    $AUTOLOAD =~ s/^.*:://;
-	    my $meth = $AUTOLOAD;
-	    $AUTOLOAD = "SUPER::" . $AUTOLOAD;
-	    my $retval = $obj->$AUTOLOAD(@_);
-	    unless (defined($retval) || $AUTOLOAD eq 'DESTROY') {
-		my $err = Win32::OLE::LastError();
-		croak(sprintf("$meth returned OLE error 0x%08x",$err))
-		  if $err;
-	    }
-	    return $retval;
-	}
-
-	1;
-
-This package inherits the constructor new() from the Win32::OLE
-package.  It is important to note that you cannot later rebless a
-Win32::OLE object as some information about the package is cached by
-the object.  Always invoke the new() constructor through the right
-package!
-
-Here's how the above class will be used:
-
-	use Win32::OLE::Strict;
-	my $Excel = Win32::OLE::Strict->new('Excel.Application', 'Quit');
-	my $Books = $Excel->Workbooks;
-	$Books->UnknownMethod(42);
-
-In the sample above the call to UnknownMethod() will be caught with
-
-	UnknownMethod returned OLE error 0x80020009 at test.pl line 5
-
-because the Workbooks object inherits the class C<Win32::OLE::Strict> from the
-C<$Excel> object.
-
-=head1 NOTES
-
-=head2 Hints for Microsoft Office automation
-
-=over 8
-
-=item Documentation
-
-The object model for the Office applications is defined in the Visual Basic
-reference guides for the various applications.  These are typically not
-installed by default during the standard installation.  They can be added
-later by rerunning the setup program with the custom install option.
-
-=item Class, Method and Property names
-
-The names have been changed between different versions of Office.  For
-example C<Application> was a method in Office 95 and is a property in
-Office97.  Therefore it will not show up in the list of property names
-C<keys %$object> when querying an Office 95 object.
-
-The class names are not always identical to the method/property names
-producing the object.  E.g. the C<Workbook> method returns an object of
-type C<Workbook> in Office 95 and C<_Workbook> in Office 97.
-
-=item Moniker (GetObject support)
-
-Office applications seem to implement file monikers only.  For example
-it seems to be impossible to retrieve a specific worksheet object through
-C<GetObject("File.XLS!Sheet")>.  Furthermore, in Excel 95 the moniker starts
-a Worksheet object and in Excel 97 it returns a Workbook object.  You can use
-either the Win32::OLE::QueryObjectType class method or the $object->{Version}
-property to write portable code.
-
-=item Enumeration of collection objects
-
-Enumerations seem to be incompletely implemented.  Office 95 application don't
-seem to support neither the Reset() nor the Clone() methods.  The Clone()
-method is still unimplemented in Office 97.  A single walk through the
-collection similar to Visual Basics C<for each> construct does work however.
-
-=item Localization
-
-Starting with Office 97 Microsoft has changed the localized class, method and
-property names back into English.  Note that string, date and currency
-arguments are still subject to locale specific interpretation.  Perl uses the
-system default locale for all OLE transaction whereas Visual Basic uses a
-type library specific locale.  A Visual Basic script would use "R1C1" in string
-arguments to specify relative references.  A Perl script running on a German
-language Windows would have to use "Z1S1".  Set the LCID module option
-to an English locale to write portable scripts.  This variable should
-not be changed after creating the OLE objects; some methods seem to randomly
-fail if the locale is changed on the fly.
-
-=item SaveAs method in Word 97 doesn't work
-
-This is an known bug in Word 97.  Search the MS knowledge base for Word /
-Foxpro incompatibility.  That problem applies to the Perl OLE interface as
-well.  A workaround is to use the WordBasic compatibility object.  It doesn't
-support all the options of the native method though.
-
-    $Word->WordBasic->FileSaveAs($file);
-
-The problem seems to be fixed by applying the Office 97 Service Release 1.
-
-=item Randomly failing method calls
-
-It seems like modifying objects that are not selected/activated is sometimes
-fragile.  Most of these problems go away if the chart/sheet/document is
-selected or activated before being manipulated (just like an interactive
-user would automatically do it).
-
-=back
-
-=head2 Incompatibilities
-
-There are some incompatibilities with the version distributed by Activeware
-(as of build 306).
-
-=over 8
-
-=item 1
-
-The package name has changed from "OLE" to "Win32::OLE".
-
-=item 2
-
-All functions of the form "Win32::OLEFoo" are now "Win32::OLE::Foo",
-though the old names are temporarily accommodated.  Win32::OLECreateObject()
-was changed to Win32::OLE::CreateObject(), and is now called
-Win32::OLE::new() bowing to established convention for naming constructors.
-The old names should be considered deprecated, and will be removed in the
-next version.
-
-=item 3
-
-Package "OLE::Variant" is now "Win32::OLE::Variant".
-
-=item 4
-
-The Variant function is new, and is exported by default.  So are
-all the VT_XXX type constants.
-
-=item 5
-
-The support for collection objects has been moved into the package
-Win32::OLE::Enum.  The C<keys %$object> method is now used to enumerate
-the properties of the object.
-
-=back
-
-=head2 Bugs and Limitations
-
-=over 8
-
-=item *
-
-To invoke a native OLE method with the same name as one of the
-Win32::OLE methods (C<Dispatch>, C<Invoke>, C<SetProperty>, C<DESTROY>,
-etc.), you have to use the C<Invoke> method:
-
-	$Object->Invoke('Dispatch', @AdditionalArgs);
-
-The same is true for names exported by the Exporter or the Dynaloader
-modules, e.g.: C<export>, C<export_to_level>, C<import>,
-C<_push_tags>, C<export_tags>, C<export_ok_tags>, C<export_fail>,
-C<require_version>, C<dl_load_flags>,
-C<croak>, C<bootstrap>, C<dl_findfile>, C<dl_expandspec>,
-C<dl_find_symbol_anywhere>, C<dl_load_file>, C<dl_find_symbol>,
-C<dl_undef_symbols>, C<dl_install_xsub> and C<dl_error>.
-
-=back
-
-=head1 SEE ALSO
-
-The documentation for L<Win32::OLE::Const>, L<Win32::OLE::Enum>,
-L<Win32::OLE::NLS> and L<Win32::OLE::Variant> contains additional
-information about OLE support for Perl on Win32.
-
-=head1 AUTHORS
-
-Originally put together by the kind people at Hip and Activeware.
-
-Gurusamy Sarathy <gsar at cpan.org> subsequently fixed several
-major bugs, memory leaks, and reliability problems, along with some
-redesign of the code.
-
-Jan Dubois <jand at activestate.com> pitched in with yet more massive redesign,
-added support for named parameters, and other significant enhancements.
-He's been hacking on it ever since.
-
-Please send questions about problems with this module to the
-Perl-Win32-Users mailinglist at ActiveState.com.  The mailinglist charter
-requests that you put an [OLE] tag somewhere on the subject line (for OLE
-related questions only, of course).
-
-=head1 COPYRIGHT
-
-    (c) 1995 Microsoft Corporation. All rights reserved.
-    Developed by ActiveWare Internet Corp., now known as
-    ActiveState Tool Corp., http://www.ActiveState.com
-
-    Other modifications Copyright (c) 1997-2006 by Gurusamy Sarathy
-    <gsar at cpan.org> and Jan Dubois <jand at activestate.com>
-
-    You may distribute under the terms of either the GNU General Public
-    License or the Artistic License, as specified in the README file.
-
-=head1 VERSION
-
-Version 0.1712	  14 May 2014
-
-=cut



More information about the tex-live-commits mailing list.