This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: MRP/Interface, Next: MRP/Introspection, Prev: MRP/BaseClass, Up: Module List defines object interfaces ************************* NAME ==== MRP::Interface - defines object interfaces DESCRIPTION =========== Allows you to specify the interface that an object is expected to implement without implying an inheritance hierachy. SYNOPSIS ======== MRP::Interface->create(Foo => {''=>'My realy usefull interface', # interface description action=>'performs an action', # functions and their descriptions reaction=>'responds to an action', # ... }); MRP::Interface->Foo->implementedBy('Bar'); # register package Bar as implementing interface Foo # Package Bar must have functions 'action' and 'reaction' # or a fatal error is generated. $bar = new Bar; $hoot = new Hoot; MRP::Interface->Foo->implementedBy($bar); # returns true as $bar does implement Foo MRP::Interface->Foo->implementedBy($hoot); # returns false as $hoot doen't implement Foo MRP::Interface->Gee->implementedBy($bar); # fatal error if interface Gee is not defined $int = MRP::Interface->Foo; # gets the interface object for 'Foo' print $int->name(); # prints out 'Foo' %functions = %{$int->functions()}; # %functions now contains Foo's functions and descriptions FUNCTIONS ========= create Creates a new interface. You can create any number of interfaces with a single call. Treats the parameters as a hash, where each key is an interface name, and each value is a hashref. The hasref key/value pairs specify function names and descriptions for those functions. If the function name is " then this is used as the interface description. MRP::Interface->create( interfaceName => { '' => $description_for_interfaceName, func1 => $description_for_func1, func2 => $description_for_func2, ... funcn => $description_for_funcn }, otherInterface => { ..... } ); functions Returns the hash of function names and descriptions used to create the interface. name Returns the name of the interface. implementedBy If the argument is a reference (presumably an object) then return true or false depending on whether the object is of a class that implements the interface. If the argument is a package name (not a reference) then the package is registered as implementing the interface. If the package does not provide all of the required functions then an error is thrown. anything else Any other method is treated as if it where the name of an interface to retrieve. Thus, MRP::Interface->Holly will retrieve the interface named Holly. If Holly does not exist then a fatal error is thrown. So, you can have code like: MRP::Interface->Holly->implementedBy($obj) || die "$obj does not implement interface Holly"; AUTHOR ====== Matthew Pocock mrp@sanger.ac.uk  File: pm.info, Node: MRP/Introspection, Next: MRP/Text, Prev: MRP/Interface, Up: Module List powerful introspection ********************** NAME ==== MRP::Introspection - powerful introspection DESCRIPTION =========== Provides introspection support without you breaking strict. SYNOPSIS ======== These functions perform introspection into a package to avoid you having to tamper with the symbol table directly. They use MAJOR wizardry to make sure that things behave just as you would expect. Use with caution, particularly if you use them to alter variables. Package symbols In a scalar context, these functions return a reference to a hash. In a list context, they return a list of key/value pairs. The keys are all of the items found in the symbol table of a given type. The values are references to these items. Call using something like: $arrayHash = MRP::Interface->_arrays($obj); print "Got ISA ", $arrayHash->{ISA}, "\n"; %arrayHash = MRP::Interface->_functions(MyPackage); print "Found ISA" if exists $arrayHash{'ISA'} _functions _scalars _arrays _hashes Accessing individual symbol table elements These functions all return either a reference to to the item within the package or undef if it doesn't exist. For example, $func = MRP::Interface->_function($thingy, 'printme'); will put a reference to the function 'printme' in $func. If there is no such function within the package that $thingy is blessed into (or the package named by $thingy), then $func will be undef. These functions do not deal with inheritance. They only look in a single package. _function _scalar _array _hash Other functions symTable Returns a hash ref to the symbol table of a package (or the package that an object is blessed into). $symTable = MRP::Introspection->symTable($obj); ISA Returns the @ISA array for a package or object. Returned as an array or a reference to the actual ISA array depending on wantarray. $isaRef = MRP::Introspection->ISA($package); push @$isaRef, $newBaseClass; functionsMatching Returns all of the functions that match a given regex. $sets = MRP::Introspection($package, '^set.*$'); # all the functions in # package $package matching ^set.*$ recursiveFunction MRP::Introspection->recursiveFunction($package, $funcRef); Recursively applies a function throughout an objects inheritance hierachy. Returns a hash or hashref of all of the function return values pre-catonated with the package name. You will have to just try this one out. recursiveInheritance Same as recursiveFunction, but throws away results that could not be reached because they are masked by inheritance. Again, just try it. superAUTOLOAD use: $autref = MRP::Interface->superAutoload($thisPackage, $AUTOLOAD); $autref->(@paramlist); For those stickey moments when you have entered an AUTOLOAD method, but it needs to allow some superclasses AUTOLOAD to do some processing. The method sets $AUTOLOAD in the package that is first reached by inheritance that has an AUTOLOAD method, and returns a reference to that function. You just have to use the reference and pass it the relevant arguments. AUTHOR ====== Matthew Pocock mrp@sanger.ac.uk  File: pm.info, Node: MRP/Text, Next: MSDOS/Attrib, Prev: MRP/Introspection, Up: Module List some text utilities ******************* NAME ==== MRP::Text - some text utilities DESCRIPTION =========== Provides a small number of text manipulating methods that I use all the time. They are invoked as MRP::Text->func. SYNOPSIS ======== print "got ", MRP::Text->pretyArray(@someList), "\n"; Functions ========= pretyArray use: print MRP::Text->pretyArray(qw(pig dog cat)); # prints out (pig, dog, cat) print MRP::Text->pretyArray($arrayRef); # prety-prints the contence of the array ref pretyHash use: print MRP::Text->pretyHash($leader, $hashRef); print MRP::Text->pretyHash($leader, %hash); leader is printed before each key/value pair. AUTHOR ====== Matthew Pocock mrp@sanger.ac.uk  File: pm.info, Node: MSDOS/Attrib, Next: MSDOS/Descript, Prev: MRP/Text, Up: Module List Get or set MS-DOS file attributes ********************************* NAME ==== MSDOS::Attrib - Get or set MS-DOS file attributes SYNOPSIS ======== use MSDOS::Attrib qw(get_attribs set_attribs); $attribs = get_attribs($path); set_attribs($attribs, $path1, $path2, ...); DESCRIPTION =========== MSDOS::Attrib provides access to MS-DOS file attributes. While the read-only attribute can be handled by chmod and stat, the hidden, system, and archive attributes cannot. $attribs = get_attribs($path) Returns the attributes of $path, or the empty string if $path does not exist. Attributes are returned as a five-character string in this format: "RHSAD". Each letter is replaced by an underscore (_) if the file does not have the corresponding attribute. (This is the same format as a 4DOS directory listing.) The attributes are: R The file is read-only (not writable) H The file is hidden (does not appear in directory listings) S The file is a system file (does not appear in directory listings) A The file needs to be archived (it has changed since last backup) D The file is a directory $count = set_attribs($attribs, $path1, [$path2, ...]) Sets the attributes of `$path1', `$path2', etc. You can either specify the complete set of attributes, or add and subtract attributes by using + and -. The case and order of the attributes is not important. For example, '-s+ra' will remove the system attribute and add the read-only and archive attributes. You should not use whitespace between attributes, although underscores are OK. See `get_attribs' for an explanation of the attribute values. You cannot change the directory attribute; if you specify it, it is ignored. Returns the number of files successfully changed. LICENSE ======= This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. AUTHOR ====== Christopher J. Madsen <`chris_madsen@geocities.com'> SEE ALSO ======== The `OS2::ExtAttr' in this node module provides access to extended attributes under OS/2. The *Note Win32/FileSecurity: Win32/FileSecurity, module provides access to Discretionary Access Control Lists under Windows NT.  File: pm.info, Node: MSDOS/Descript, Next: MVS/JESFTP, Prev: MSDOS/Attrib, Up: Module List Manage 4DOS style DESCRIPT.ION files ************************************ NAME ==== MSDOS::Descript - Manage 4DOS style DESCRIPT.ION files SYNOPSIS ======== use MSDOS::Descript; $d = new MSDOS::Descript; print $d->description('foo.txt'); $d->rename('foo.txt', 'bar.txt'); $d->description('baz.txt','This is Baz.txt'); $d->description('frotz.txt', ''); # Remove description for frotz.txt $d->update; DESCRIPTION =========== *MSDOS::Descript* provides access to 4DOS style DESCRIPT.ION files. Remember that changes to the descriptions are not saved unless you call the update or write methods. By default, *MSDOS::Descript* uses relative paths, so if you change the current directory between new and update, you'll be writing to a different file. To avoid this, you can pass an absolute path to new. Methods ------- $d = MSDOS::Descript->new([$filename]) Constructs a new `MSDOS::Descript' object. $filename may be a directory or a 4DOS DESCRIPT.ION format file. If it's a directory, looks for a DESCRIPT.ION file in that directory. If $filename is omitted, it defaults to the current directory. $d->description($file, [$desc]) Gets or sets the description of $file. If `$desc' is omitted, returns the description of $file or undef if it doesn't have one. Otherwise, sets the description of $file to `$desc' and returns the old description. (If `$desc' is the null string or undef, the description is deleted.) $d->rename($old, $new) Transfers the description of `$old' (if any) to `$new'. This does not actually rename the file on disk. $d->read([$file]) Load the descriptions from $file. If $file is omitted, then re-read the original description file. Since new does this automatically, you shouldn't have to call read yourself. $d->read_add($file) Add the descriptions from $file to the current descriptions. $d->write([$file]) Writes the descriptions to $file, or the original description file if $file is omitted. Marks the descriptions as unchanged if writing to the original description file. If the current directory has changed since the descriptions were loaded, and the description file was specified by a relative path (which is the default), you will be writing to a different file. $d->update Saves the descriptions to the original file if any changes have been made. The same warning about the current directory applies (see write). $d->autoupdate([$auto]) Turns on automatic updates for $d if `$auto' is true or omitted. Otherwise, turns automatic updates off. When automatic updates are on, the descriptions are automatically saved when the object is destroyed. *Beware of relative paths!* If the current directory changes before the object is destroyed, you're going to be writing to a different file! I strongly suggest that you use absolute paths if you're going to use `autoupdate'. REQUIREMENTS ============ *MSDOS::Descript* requires the *Tie::CPHash* module (a case-insensitive hash). It also uses *MSDOS::Attrib* to hide DESCRIPT.ION files after it changes them. If you don't have *MSDOS::Attrib*, it will still work, but any DESCRIPT.ION files changed by *MSDOS::Descript* will become visible. Both *Tie::CPHash* and *MSDOS::Attrib* are available from CPAN. BUGS ==== Uses relative paths, so changing the current directory after loading a description file can cause problems. AUTHOR ====== Christopher J. Madsen <`chris_madsen@geocities.com'>  File: pm.info, Node: MVS/JESFTP, Next: MVS/VBFile, Prev: MSDOS/Descript, Up: Module List Perl extension for submitting JCL to MVS systems through FTP. ************************************************************* NAME ==== MVS::JESFTP - Perl extension for submitting JCL to MVS systems through FTP. SYNOPSIS ======== use MVS::JESFTP; $jes = MVS::JESFTP->open($host, $logonid, $password) or die; $jes->submit($job); $aref = $jes->wait_for_results($jobname, $timeout); $jes->get_results($aref); $jes->delete_results($aref); $jes->quit; DESCRIPTION =========== IBM mainframe MVS systems accept job input through the Job Entry Subsystem (JES). This input is in the form of 80-byte *card images* that correspond to the punch cards of ancient times. The new releases of MVS can accept this input via FTP to the MVS *internal reader* (equivalent to the physical card readers of older systems). This module uses the Net::FTP module under the hood to handle the FTP chores. METHODS ======= $jes = MVS::JESFTP->open($host, $logonid, $password); ----------------------------------------------------- This method creates a connection to the MVS system JES. If the connection is made, open returns a reference `$jes' to the JES connection; otherwise open returns `undefined'. open takes three arguments: $host The IP address or DNS name of the MVS system. `$logonid' A valid FTP logon ID for the host. $password A valid FTP password for the host. $jes->submit($job); ------------------- This method submits the jobstream contained in the file `$job'. If the submission is successful, `submit' returns true; otherwise `submit' returns `undefined'. $aref = $jes->wait_for_results($jobname, $timeout); --------------------------------------------------- This method waits for the output of the submitted job to arrive in the JES *hold queue*. `wait_for_results' returns an array reference `$aref' to the a list of output files for the job suitable for input to get_results.(1) `wait_for_results' takes two arguments: `$jobname' The name of the job you presumedly submitted with the `submit' method. $timeout How many seconds to wait for the job output to arrive; defaults to 60. $result = $jes->get_results($aref); ----------------------------------- This method retrieves the output of the submitted job from the JES *hold queue*. get_results returns `undefined' if successful; otherwise it returns a reference to an array of names of the files it could not retrieve. (1) get_results takes one argument: `$aref' An array reference to the a list of output files from the job, such as `wait_for_results' generates. get_results will retreive (via FTP) each output file in turn and store them in the current subdirectory; file names will be preserved. $result = $jes->delete_results($aref); -------------------------------------- This method deletes the output of the submitted job from the JES *hold queue*. `delete_results' returns `true' if successful; otherwise it returns a reference to an array of names of the jobs it could not delete. `delete_results' takes one argument: `$aref' An array reference to the a list of output files from the job, such as `wait_for_results' generates. `delete_results' will delete each job in turn. $jes->quit; ----------- This method closes the connection to JES. It is just the Net::FTP quit method. (1) To use this method, your JCL *JOB* card must specify a *MSGCLASS* that directs its output to the JES *hold queue*. If you don't understand what this means, *don't use this method*, or you will hang your calling program. PREREQUISITES ============= You have to have Net::FTP installed. INSTALLATION ============ tar -xzf MVS-JESFTP-0.01.tar.gz perl Makefile.PL make # # Edit TEST.SEQ to contain your site-specific logonid, # password, account, & node in the appropriate places. # make test make install For Win32 systems, after unarchiving the the package, copy JESFTP.pm to C:\Perl\site\lib\MVS (modifying this path for your installation of Perl). AUTHOR ====== Mike Owens mike.owens@state.nm.us Copyright (c) 2000 Mike Owens. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. SEE ALSO ======== `perl(1)' `Net::FTP'  File: pm.info, Node: MVS/VBFile, Next: Mac/AETE/App, Prev: MVS/JESFTP, Up: Module List Perl extension to read and write variable-length MVS files ********************************************************** NAME ==== MVS::VBFile - Perl extension to read and write variable-length MVS files SYNOPSIS ======== use MVS::VBFile qw(:all); # only vbget is exported by default $next_record = vbget(*FILEHANDLE); @whole_enchilada = vbget(*FILEHANDLE); vbopen(*FILEHANDLE, ">output_file", $blksize); vbput(*FILEHANDLE, $record); vbclose(*FILEHANDLE); $b = vb_blocks_written(*FILEHANDLE); DESCRIPTION =========== This module provides functions to get records from mainframe MVS files in variable blocked (VB) format and to write records in a similar format. FUNCTIONS ========= vbget is exported by default; if you want any other functions, you must ask for them by name. `qw(:all)' exports all functions. vbget *FILEHANDLE The input function, vbget(), works like the angle operator: when called in scalar context, it returns the next record; when in array context, it returns the entire file in a single array. The file must be in "binary" format (no translation of bytes) and include record descriptor words. The file may include block descriptor words but need not. The rationale behind this is as follows. Most files from MVS systems are either fixed-length (record format FB) or variable-length (recfm VB). Perl can read fixed-length mainframe files just as it reads other fixed-length files - open, read a certain number of bytes, close - but variable-length files require some special handling. Since Perl provides open and close, the only function needed is one to get the next record. Read the file as follows: open FILEHANDLE, "..name.."; while (vbget(*FILEHANDLE)) { # Be sure to use '*'!! # process and reality... } # OR do this: @much_in_little = vbget(*FILEHANDLE); # and then process the array (only on small files, of course). close FILEHANDLE; vbopen *FILEHANDLE EXPR [BLKSIZE] Three output functions are provided: vbopen(), vbput(), and vbclose(). These functions allow you to write out records (to tape, most likely) that can later be read by an MVS system. Like vbget(), these functions do not translate any of the data given to them; any translation to EBCDIC (or anything else) must be done before the record is written. vbopen() is similar to Perl's open, but you must pass a typeglob as the first argument (in other words, put a * on the front of it). The third argument is the blksize of the file. The minimum blksize is 9 bytes; the maximum, 256KB (262_144 bytes); the default, 32760. If you wish to use a blksize larger than 32760, make sure that your MVS system will support it. Your output must be blocked; in other words, you cannot write out files with RDW's but no BDW's. You may have more than one filehandle open at a time. vbput *FILEHANDLE RECORD Puts a single logical record to the file. vbclose *FILEHANDLE Closes the file. Be sure to use this function, since it will write a final block that contains any remaining logical records. vb_blocks_written *FILEHANDLE Can be called at any time to find the number of blocks written to the file. This would be most useful after closing the file; the count could, for instance, be used to build an MVS-style tape header. Here's a full example of writing output: vbopen(*VBO, ">$outfile", 32760); foreach $record (@my_array) { vbput(*VBO, $record); } vbclose(*VBO); $b = vb_blocks_written(*VBO); VARIABLE ======== The variable *MVS::VBFile::bdws* applies only to input. It tells the module whether the file to be read contains block descriptor words. The default is 0 (false); set it to 1 or any other true value if the file contains BDW's. RESTRICTIONS ============ For input, both VB (blocked) and V (unblocked) formats are supported. vbget() will not work properly on format VBS (spanned). Since VB is by far the most commonly used format, this should not be a major snag. Output must be blocked (VB); in other words, you cannot write out files with RDW's but no BDW's. MORE ABOUT DESCRIPTOR WORDS =========================== Record descriptor words are 4 bytes that appear at the beginning of each record in a VB file. The first two bytes contain the record length in binary (16 bits, signed, big-endian); the last two are used only by spanned records and are ignored by this module. Block descriptor words, likewise, are 4 bytes that appear at the beginning of each block, having the same format. My experience with FTP from MVS is limited, but it seems that if you transfer a file from an MVS host via FTP including the RDW's, the RDW's will be transferred but the BDW's will not. Most applications do not require BDW's, but if you want them, they can be transferred by converting the VB file to undefined records (recfm=U) under MVS and then transferring the converted file. AUTHOR ====== W. Geoffrey Rommel, GROMMEL@cpan.org, March 1999. Thanks to Bob Shair (bshair@amdocs.com) for suggesting vbput and providing preliminary code.  File: pm.info, Node: Mac/AETE/App, Next: Mac/AETE/Dialect, Prev: MVS/VBFile, Up: Module List reads the Macintosh Apple event dictionary from an application. *************************************************************** NAME ==== Mac::AETE::App - reads the Macintosh Apple event dictionary from an application. SYNOPSIS ======== use Mac::AETE::App; use Mac::AETE::Format::Dictionary; $app = App->new("My Application"); $formatter = Dictionary->new; $app->set_format($formatter); $app->read; $app->write; DESCRIPTION =========== The App module simplifies reading the Apple event dictionary from an application. It will launch the application if necessary to obtain the dictionary. Methods ------- new Example: ($name is the name of the application.) use Mac::AETE::App; use Mac::AETE::Format::Dictionary; $app = App->new($aete_handle, $name); read (Inherited from Mac::AETE::Parser.) Reads the data contained in the AETE resource or handle. Example: $app->read; set_format (Inherited from Mac::AETE::Parser.) Sets the output formatter used during by the 'write' subroutine. Example: $formatter = Dictionary->new; $app->set_format($formatter); copy (Inherited from Mac::AETE::Parser.) Copies all suites from one Parser object into another. Example: $aete2 = Parser->new($aete_handle2, $another_name); $app->copy($aete2); copies the suites from $aete2 into $aete. merge (Inherited from Mac::AETE::Parser.) Merges suites from one Parser object into another. Only the suites that exist in both objects will be replaced. Example: $aete3 = Parser->new($aete_handle2, $another_name); $app->merge($aete3); write (Inherited from Mac::AETE::Parser.) Prints the contents of the AETE or AEUT resource using the current formatter. $app->write; INHERITANCE =========== Inherits from Mac::AETE::Parser. AUTHOR ====== David Schooley <`dcschooley@mediaone.net'>  File: pm.info, Node: Mac/AETE/Dialect, Next: Mac/AETE/Format/Glue, Prev: Mac/AETE/App, Up: Module List reads the Macintosh Apple event dictionary from an Applescript dialect file. ***************************************************************************** NAME ==== Mac::AETE::Dialect - reads the Macintosh Apple event dictionary from an Applescript dialect file. SYNOPSIS ======== use Mac::AETE::App; use Mac::AETE::Dialect; use Mac::AETE::Format::Dictionary; $aeut = Dialect->new(); $aeut->read(); $app = App->new("My Application"); $formatter = Dictionary->new; $app->set_format($formatter); $app->read; $app->merge($aeut); $app->write; DESCRIPTION =========== The data in Dialect objects can be merged into a Parser or App object to make a complete Apple event dictionary. The module will locate the proper AppleScript dialect file in the system folder. See Mac::AETE::Parser and Mac::AETE::App for more details. Methods ------- new Example: use Mac::AETE::Dialect; $app = Dialect->new; read (Inherited from Mac::AETE::Parser.) Reads the data contained in the AETE resource or handle. Example: $app->read; INHERITANCE =========== Inherits from Mac::AETE::Parser. AUTHOR ====== David Schooley <`dcschooley@mediaone.net'>  File: pm.info, Node: Mac/AETE/Format/Glue, Next: Mac/AETE/Parser, Prev: Mac/AETE/Dialect, Up: Module List SYNOPSIS ======== use Mac::Glue; my $obj = new Mac::Glue '__APPNAME__'; DESCRIPTION =========== See `Mac::Glue' for complete documentation on base usage and framework. EOT $self{FINISH} = <new($aete_handle, $name); $formatter = Dictionary->new; $aete->set_format($formatter); $aete->read; $aete->write; DESCRIPTION =========== The Parser module serves as a base class for the Mac::AETE::App and Mac::AETE::Dialect modules. Methods ------- new Example: ($aete_handle is a handle containing a valid AETE resource. $name is the name of the application.) use Mac::AETE::Parser; use Mac::AETE::Format::Dictionary; $aete = Parser->new($aete_handle, $name); read Reads the data contained in the AETE resource or handle. Example: $aete->read; =item set_format Sets the output formatter used during by the 'write' subroutine. Example: $formatter = Dictionary->new; $aete->set_format($formatter); copy Copies all suites from one Parser object into another. Example: $aete2 = Parser->new($aete_handle2, $another_name); $aete->copy($aete2); copies the suites from $aete2 into $aete. merge Merges suites from one Parser object into another. Only the suites that exist in both objects will be replaced. Example: $aete3 = Parser->new($aete_handle2, $another_name); $aete->merge($aete3); write Prints the contents of the AETE or AEUT resource using the current formatter. $aete->write; INHERITANCE =========== Parser does not inherit from any other modules. AUTHOR ====== David Schooley <`dcschooley@mediaone.net'> The data structures are adapted from modifications made to the original aeteconvert script by Chris Nandor.  File: pm.info, Node: Mac/AFDialogs, Next: Mac/Apps/Anarchie, Prev: Mac/AETE/Parser, Up: Module List GUI-Class to create the dialogs for AssistantFrame ************************************************** NAME ==== AFDialogs - GUI-Class to create the dialogs for AssistantFrame SYNOPSIS ======== DESCRIPTION =========== This module implements the dialogs for AssistantFrame. You shouldn't need to access the methods directly without AssistantFrame. HISTORY ======= Starting with version 0.1a this module needs MacPerl 5.1.8r4 minimum. COPYRIGHT ========= Copyright 1998, Georg Bauer This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AVAILABILITY ============ The latest version of this library is likely to be available from: http://www.westfalen.de/hugo/mac/ If there are problems with this library, just drop a note to: Georg_Bauer@muensterland.org =cut  File: pm.info, Node: Mac/Apps/Anarchie, Next: Mac/Apps/Launch, Prev: Mac/AFDialogs, Up: Module List Interface to Anarchie 2.01+ *************************** NAME ==== Mac::Apps::Anarchie - Interface to Anarchie 2.01+ SYNOPSIS ======== use Mac::Apps::Anarchie; $ftp = new Mac::Apps::Anarchie; #see description for the rest DESCRIPTION =========== This is a MacPerl interface to the popular MacOS shareware FTP/archie client, Anarchie. For more info, see the Anarchie documentation. Also required is the Mac::Apps::Launch module, which requires MacPerl 5.1.4r4. NOTE: for some explanations of methods, drop Anarchie on Script Editor, and check the Anarchie docs. Before using, you must autosplit the module. See version notes for 1.4 below. Standard Suite -------------- $ftp->open(ALIAS); $ftp->quit; $ftp->showabout; $ftp->close; $ftp->closeall; $ftp->undo; $ftp->cut; $ftp->copyclip; $ftp->paste; $ftp->clear; $ftp->selectall; Anarchie Suite -------------- NOTE: * denotes compatability with Fetch. Fetch does not use the variables SOCKS, FIRE, BINARY, or TYPE. Fetch implements some of these methods differently than Anarchie. To use Fetch instead of Anarchie for these methods, call the method: $ftp->useagent('FTCh'); There are two forms of each of the following methods: "method" and "methodURL". The methodURL version takes the user name, password, host and path in the URL instead of separately. URLs are usually in the form: ftp://user:password@host.com/path/to/file ftp://user:password@host.com//absolute/path/to/file See Anarchie docs for more info on URLs. Also, the host, username, password, proxy firewall and socks firewall can be preset and then omitted during the method call. This saves a lot of code writing if you are going to make multiple calls to the same host. If a method explicitly names any of those strings, it overrides presets. If username and password are not specified anywhere, FTP is done anonymously. $ftp->host(HOST); $ftp->user(USER); $ftp->pass(PASS); $ftp->fire(FIRE); $ftp->socks(SOCKS); waitreply $ftp->waitreply(BOOLEAN); If you don't want MacPerl to wait for Anarchie to finish what it is doing, then call this with the value 0. You can change it back to 1 if you do want it to wait. The initial setting is 1. fetch * $ftp->fetch(FILENAME [, PATH, BINARY, TYPE, HOST, USER, PASS, FIRE, SOCKS]); $ftp->fetchURL(FILENAME [, URL, BINARY, TYPE, FIRE, SOCKS]); Fetches file and saves to FILENAME on local drive. BINARY is boolean for whether file is binary or ascii. TYPE is the creator code to link file to. NOTE: for Fetch, FILENAME must be an existing directory name, NOT a filename. For Anarchie, FILENAME must be a file if the fetched item is a file or a directory if the fetched item is a directory. Anarchie will create FILENAME on the local drive if it does not exist. store * $ftp->store(FILENAME [, PATH, BINARY, HOST, USER, PASS, FIRE, SOCKS]); $ftp->storeURL(FILENAME [, URL, BINARY, FIRE, SOCKS]); Stores file FIELNAME from local drive to remote location specified. rename * $ftp->rename(NEWNAME [, PATH, HOST, USER, PASS, FIRE, SOCKS]); $ftp->renameURL(NEWNAME [, URL, FIRE, SOCKS]); Renames file NEWNAME to value in PATH or URL. remove * $ftp->remove([PATH, HOST, USER, PASS, FIRE, SOCKS]); $ftp->removeURL([URL, FIRE, SOCKS]); Removes file/directory specified in PATH or URL. mkdir * $ftp->mkdir([PATH, HOST, USER, PASS, FIRE, SOCKS]); $ftp->mkdirURL([URL, FIRE, SOCKS]); Make directory specified in PATH or URL. sendcommand * $ftp->sendcommand([PATH, HOST, USER, PASS, FIRE, SOCKS]); $ftp->sendcommandURL([URL, FIRE, SOCKS]); Send raw FTP command. index * $ftp->index([PATH, HOST, USER, PASS, FIRE, SOCKS]); $ftp->indexURL([URL, FIRE, SOCKS]); Display index listing. SITE INDEX command must be implemented on host. list * $ftp->list(FILENAME, [PATH, HOST, USER, PASS, FIRE, SOCKS]); $ftp->listURL(FILENAME, [URL, FIRE, SOCKS]); List files in a directory, put into file FILENAME. Fetch apparently only lists to the screen, while Anarchie lists to a file. For Fetch, just put any old text in place of FILENAME and it should work just fine. nlist $ftp->nlist(FILENAME, [PATH, HOST, USER, PASS, FIRE, SOCKS]); $ftp->nlistURL(FILENAME, [URL, FIRE, SOCKS]); List names of files in a directory, put into file FILENAME. Anarchie Suite, Part Deux ------------------------- NOTE: These methods are NOT supported at all by Fetch. find $ftp->find(FILENAME [, SERVER, MAX, CASE, REGEX, URL]); Find file containing text FILENAME in Archie SERVER with maximum matches MAX. CASE is boolean (0 or 1) for case sensitive. REGEX is 0, 1 or 2 for denoting that FILENAME is a substring, pattern, or regular expression. macsearch $ftp->macsearch(FILENAME); Find Mac file containing text FILENAME on Ambrosia's Mac server. others $ftp->showtranscript; $ftp->showarchie; $ftp->showget; $ftp->updateserverlist; $ftp->showlog; $ftp->showmacsearch; $ftp->showtips; geturl $ftp->geturl(URL [, FILENAME]); HISTORY ======= v.1.4, January 3, 1998 Basic cleanup. Requires MacPerl 5.1.4r4 or better now. v.1.4, November 3, 1997 Pulled out main functions as autosplit/autoload files. Before using, you must run a script such as the following, in order to AutoSplit the routines: #!perl -w use AutoSplit; $dir = 'HD:MacPerl:site_perl'; autosplit("$dir:Mac:Apps:Anarchie.pm","$dir:auto",0,1,1); This also means that the `Mac::Apps::Anarchie' class is no longer aliased to simply Anarchie. v.1.3, October 15, 1997 Added waitreply method. Fixed error catching. Erorrs still are not descriptive, but now they are reported. :-) v.1.2, October 13, 1997 Get app launching from Mac::Apps::Launch, fixed descriptor disposing. v.1.1 May 4, 1997 Whoops, fixed something I broke in the AEPutParamDesc stuff. v.1.0 May 4, 1997 Finally got around to cleaning it up. Only minor changes. v.0.2 March 20, 1997 First 'public' beta. BUGS ==== regex find Still having problems with the substring/pattern/regex option on `"find"' in this node. I am not sure what the problem is. SEE ALSO ======== Anarchie Home Page http://www.stairways.com/anarchie/index.html AUTHOR ====== Chris Nandor `' http://pudge.net/ Copyright (c) 1998 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Please see the Perl Artistic License. VERSION ======= Version 1.50 (03 January 1998)  File: pm.info, Node: Mac/Apps/Launch, Next: Mac/Apps/MacPGP, Prev: Mac/Apps/Anarchie, Up: Module List MacPerl module to launch applications ************************************* NAME ==== Mac::Apps::Launch - MacPerl module to launch applications SYNOPSIS ======== use Mac::Apps::Launch; my @apps = qw(R*ch Arch MPGP); my $path = "HD:System Folder:Finder"; LaunchApps([@apps], 1) or warn $^E; # launch and switch to front LaunchApps([@apps]) or warn $^E; # launch and don't switch LaunchApps($app, 1) or warn $^E; # launch and switch to front LaunchSpecs($path, 1) or warn $^E; # use path instead of app ID QuitApps(@apps) or warn $^E; # quit all @apps QuitAllApps(@apps) or warn $^E; # quit all except @apps IsRunning('MACS'); # returns boolean for whether # given app ID is running SetFront('MACS') or warn $^E; # set Finder to front Hide('MACS') or warn $^E; # hide Finder Show('Finder', 1) or warn $^E; # show Finder (1 == use name) DESCRIPTION =========== Simply launch or quit applications by their creator ID. The Finder can be quit in this way, though it cannot be launched in this way. This module is used by many other modules. This module as written does not work with MacPerls prior to 5.1.4r4. EXPORT ====== Exports functions `QuitApps', `QuitAllApps', and `LaunchApps', `IsRunning', `LaunchSpecs', `SetFront', Hide, Show. HISTORY ======= v.1.70, June 4, 1999 Cleaned up stuff. Added `SetFront', Show, Hide. Fixed setting of $^E. Improved QuitAllApps to not quit only normal apps by checking `processType' for "APPL". v.1.60, September 28, 1998 Added `LaunchSpecs'. Use this when the app does not have a unique app ID, the app is not really an app (like the Finder), or you have more than one instance of the app, and want to launch a particular one. v.1.50, September 16, 1998 Added `IsRunning'. v.1.40, August 3, 1998 Only launches application if not already open; e.g., won't launch newer version it finds if older version is open. v.1.31, May 18, 1998 Added `AEDisposeDesc' call (D'oh!). Dunno why I forgot this. v.1.3, January 3, 1998 General cleanup, rewrite of method implementation, no longer support versions prior to 5.1.4r4, addition of Quit methods, methods return undef on failure (most recent error in $^E, but could be multiple errors; oh well). AUTHOR ====== Chris Nandor , http://pudge.net/ Copyright (c) 1999 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License, distributed with Perl. VERSION ======= Version 1.70 (June 4, 1999)  File: pm.info, Node: Mac/Apps/MacPGP, Next: Mac/Apps/PBar, Prev: Mac/Apps/Launch, Up: Module List Interface to MacPGP 2.6.3 ************************* NAME ==== Mac::Apps::MacPGP - Interface to MacPGP 2.6.3 SYNOPSIS ======== use Mac::Apps::MacPGP; $object = new Mac::Apps::MacPGP; #see description for the rest DESCRIPTION =========== MacPerl interface to MacPGP 2.6.3. Older versions WILL NOT WORK. The MIT version, MacPGP 2.6.2, does not support nearly the number of AppleEvents as does 2.6.3. For those outside the U.S., you will not be able to download the program; but there are International versions. Perhaps in the future I will add support for those. Many of the functions should work fine for those, actually, but I imagine some will not. MacPerl 5.1.1 (released January 1997) or higher is also required because of bugs in the AppleEvents library in previous versions. Also required is the Mac::Apps::Launch module, however, which requires MacPerl 5.1.4r4 or higher. :) For optional parameters, MacPGP will either use the default or prompt the user. Parameters are required unless noted as optional. Exception: For the `$OUTP' parameter, the MacPGP default is binary but I set it to ASCII in the module, because I rarely use binary PGP files. Boolean parameters take a value of 1 (true) or 0 (false). Filenames should be given the full pathname. To leave an optional parameter empty, give it a value of undef. Optional parameters will either be given the default by MacPGP or MacPGP will prompt the user for a value if necessary. For further explanation of methods and parameters, see your MacPGP 2.6.3 user guide. If something seems seems to not work properly, try doing it directly from MacPGP before assuming it is the fault of MacPGP.pm. :-) USAGE ===== encrypt ------- Encrypt. Returns encrypted text for `$TYPE="ncrd"'. $object->encrypt(TYPE, DOBJ, [RECV|CPAS], PASS, USID, SIGN, READ, OUTP, LATI, WRAP, ALNS, TABX, MDAL, WSRC, COPT); TYPE One of "encr" (encrypt files), "ncrd" (encrypt data), or "cncr" (conventional encryption). DOBJ For `$TYPE="encr"' or `"cncr"', `$DOBJ' is either a filename or a reference to an array of filenames. For `$TYPE="ncrd"', `$DOBJ' is the data to be encrypted. If `$DOBJ' is empty, MacPGP will attempt to encrypt the clipboard instead. RECV Either the name of a recipient or a reference to an array of recipients. (encr and ncrd only) CPAS Password used for conventional encryption. Optional. (cncr only) PASS The password. Optional. USID Name of secret key. Optional. SIGN Sign? One of "sepa" (signature in separate file), "incl", (signature included), "omit" (omitted, don't sign). Optional. READ Input format. One of "macb" (MacBinarize first), "text", (convert text to CRLF), "norm" (do nothing). Optional. OUTP Output format. One of "bina" (8-bit binary), "asci", (ASCII-armored). Optional. LATI Convert text to ISO-Latin1? Boolean. Optional. WRAP Wrap text to this many lines, between 30 and 100. 0=no wrap. Optional. ALNS For armored files, split output into files of this line length. 0=no split. Optional. TABX For wrapped files, expand tabs to this many spaces, from 0 to 9. Optional. MDAL Use "MD5 " or "SHA1" to compute message digest for file. Optional. WSRC Wipe out source file? Boolean. Optional. (encr and cncr only) COPT Self-decrypting? One of "sdf" (self-decrypting) or "sdfb", (self-decrypting and binhexed). Default is neither. Optional. (cncr only) decrypt ------- Decrypt. Returns decrypted text for `$TYPE="dcrd"' and `$DOBJ ne undef'. Returns signatures for `$TYPE="decr"'. $object->decrypt(TYPE, DOBJ, PASS, SCRE, NSIG, APL2, RECV); TYPE One of "decr" (decrypt files), "dcrd" (decrypt data). DOBJ For `$TYPE="decr"', `$DOBJ' is either a filename or a reference to an array of filenames. For `$TYPE="dcrd"', `$DOBJ' is the data to be decrypted. If `$DOBJ' is empty, MacPGP will attempt to decrypt the clipboard instead. To get signatures from "dcrd" event, see `"checksignresult"' in this node. PASS The password. Optional. SCRE Decrypt to screen instead of file? Boolean. Optional. NSIG Do not put up bad signature alerts? Boolean. Optional. APL2 If direct object is a separate sig file, the file the sig applies to. Optional. RECV File to decrypt to. Optional. (decr only) sign ---- Sign. Returns encrypted signed text for `$TYPE="sigd"', returns signature results for `$TYPE="sign"'. $object->sign(TYPE, DOBJ, PASS, USID, SIGN, READ, OUTP, LATI, WRAP, ALNS, TABX, MDAL, STFX); TYPE One of "sign" (sign files), "sigd" (sign data). DOBJ For `$TYPE="sign"', `$DOBJ' is either a filename or a reference to an array of filenames. For `$TYPE="sigd"', `$DOBJ' is the data to be signed. If `$DOBJ' is empty, MacPGP will attempt to sign the clipboard instead. PASS The password. Optional. USID Name of secret key. Optional. SIGN Sign? One of "sepa" (signature in separate file), "incl", (signature included), "omit" (omitted, don't sign). Optional. READ See READ in `"encrypt"' in this node. Optional. OUTP See OUTP in `"encrypt"' in this node. Optional. LATI See LATI in `"encrypt"' in this node. Optional. WRAP See WRAP in `"encrypt"' in this node. Optional. ALNS See ALNS in `"encrypt"' in this node. Optional. TABX See TABX in `"encrypt"' in this node. Optional. MDAL See MDAL in `"encrypt"' in this node. Optional. STFX Set text flag? (Esoteric option for some PGP/MIME implementations.) Boolean. Optional. asciify ------- Asciify a file. $object->asciify(DOBJ, READ, LATI, WRAP, ALNS, TABX); DOBJ Filename or reference to an array of filenames to be asciified. READ See READ in `"encrypt"' in this node. Optional. LATI See LATI in `"encrypt"' in this node. Optional. WRAP See WRAP in `"encrypt"' in this node. Optional. ALNS See ALNS in `"encrypt"' in this node. Optional. TABX See TABX in `"encrypt"' in this node. Optional. execute ------- Execute MacPGP command-line command. $object->execute(DOBJ, PASS, LATI, WRAP, ALNS, TABX, MDAL); DOBJ Command to be executed (i.e., `pgp -kv pudge'). PASS The password. Optional. LATI See LATI in `"encrypt"' in this node. Optional. WRAP See WRAP in `"encrypt"' in this node. Optional. ALNS See ALNS in `"encrypt"' in this node. Optional. TABX See TABX in `"encrypt"' in this node. Optional. MDAL See MDAL in `"encrypt"' in this node. Optional. generate -------- Generate new public/secret key pair. $object->generate(DOBJ, LENG, EBIT); DOBJ User id of new key. LENG Bit length of key. Higher is stronger and slower. Lower is faster and less secure. Can be either a number from 384 to 2048, or one of the following: "casu" (casual, 512), "comm" (commercial, 768), "mili" (military, 1024). Default is casual. Optional. EBIT Number of bits in encryption exponent. Default is 17. Optional. extract ------- Extract (export) a key. $object->extract(DOBJ, RECV, KEYR, OUTP); DOBJ Key id to extract. RECV File to extract key to. File must already exist (for now). See `"create"' in this node. KEYR Filename of keyring to perform operation on. Optional. OUTP Output format. One of "bina" (8-bit binary), "asci", (ASCII-armored). Optional. keyring ------- Miscellaneous keyring functions. $object->keyring(TYPE, DOBJ, KEYR, USID); TYPE addk Add key in file `$DOBJ'. ckey Count keys matching `$DOBJ'. crfy Certify key matching `$DOBJ'. fing Return fingerprint of key matching `$DOBJ'. remv Remove key matching `$DOBJ'. selk Show dialog box, with text `$DOBJ', of keys available in keyring. Returns user id of selected key. DOBJ Varies; see above. KEYR Filename of keyring to perform operation on. Optional. USID Name of secret key to certify with. Optional. (crfy only) create ------ Create temporary scratch file. File with same name, if existing, is erased. $object->create(DOBJ); DOBJ New filename. clip2file --------- Copy Clipboard to file. $object->clip2file(DOBJ); DOBJ Filename of destination file. file2clip --------- Copy file to Clipboard. NOTE: This only works if MacPGP is the front application (see `"switchapp"' in this node). $object->file2clip(DOBJ); DOBJ Filename of source file. checksignresult --------------- Check signature result from previous decrypt data event. See `"decrypt"' in this node. $object->checksignresult; getlasterror ------------ Returns error message from previous MacPGP Apple Event. $object->getlasterror; getversion ---------- Returns MacPGP version. $object->getversion; window ------ Show/hide window. $object->window(DOBJ); DOBJ Either "show" or "hide". logfile ------- Echo PGP messages to a logfile. If logging was active when true sent or no filename is given, returns error. If logging was active. Returns full pathname if successful. $object->logfile(DOBJ, RECV); DOBJ Logging? Boolean. RECV Full pathname of logfile. Existing file of same name erased. Optional. switchapp --------- Set up window handling. Whenever another method is called, MacPGP.pm will use these two variables to determine what app should be in front. Note: when muliple methods are called, this doesn't seem to work great. Oh well. Maybe someone else will fix this for me or have some ideas. Until then, I suggest that if you DO want MacPGP to come to the front and you have sveral methods being called one after the other, that you just set `$object-'switchapp(1)> and don't have it switch back. $object->switchapp(SWITCH, APP); SWITCH Switch to MacPGP when method is called? Boolean. APP Switch to `$APP' after $object is destroyed (i.e., when last reference to $object is made). If left blank and `$SWITCH=1', MacPGP will go to front and stay there. getresults ---------- Returns result of parameter `$DOBJ' from last method call. $object->getresults(DOBJ); DOBJ Name of parameter keyword, one of "---", "result" (synonym for "---", the direct object parameter), "errs" (error string), "errn" (error number), "outp". Optional, defaults to "result". getresultsall ------------- Returns hash of all result parameters from last method call. %results = $object->getresultsall; quitpgp ------- Quit MacPGP app. $object->quitpgp; HISTORY ======= v.1.2, January 3, 1998 Basic cleanup. Requires MacPerl 5.1.4r4 or better now. v.1.1, October 13, 1997 Get app launching from Mac::Apps::Launch, fixed descriptor disposing. v.1.0, February 9, 1997 First full release. * Added a whole slew of scripts and extensions for BBEdit, YA-NewsWatcher, Clipboard, Drag-n-Drop. See MacPGP-scripts.readme for details. * Changed the behavior of switchapp method. Switching to MacPGP only occurs when switchapp method is invoked, and switching back only occurs when object is destroyed. Previously, switching took place before and after each method call. * Fixed bug which required decrypt, encrypt and sign to have a DOBJ value. When one of those methods is performing a function on data (dcrd, ncrd, sigd), MacPGP will use Clipboard if no data is given. * Fixed bug in `_MpgpBBool' routine which would not catch unacceptable input. v.1.0b3, January 15, 1997 Simply switching to .tar.gz for CPAN instead of .sit.hqx. v.1.0b2 January 8, 1997 Fixes problems in earlier release, optimizes, module-izes. * Change name from MacPGP to Mac::Apps::MacPGP. * Rewrote AppleEvent calls using individual `AEPutParamDesc' and `AEBuild' calls. Should be more efficient. Fixes other bugs (like problems with lists and certain characters in TEXT values). * Improved error handling and descriptions. Uses carp for MacPGP errors. * Made file and recipients variables capable of handling either a scalar or a reference to an array. * Added switchapp, getresults, getresultsall, quitpgp methods. See docs above. v.1.0b1, January 3, 1997 First public beta. Nearly fully-functional. BUGS ==== app switching I want to benchmark different ways to switch between applications and use the best one. Stay tuned. If you have ideas, let me know. other versions I am investigating the idea of making this useful with other versions of MacPGP (international versions, and limited capabilities of MacPGP 2.6.2) and the future version of PGP 5.0. stealthify I have one more method group to add, and that is for stealtifying/destealthifying files. This will come along eventually, but it is not a high priority. First I have to figure out how to use it and what it does ... :-) If you have a need/want for it, let me know. SEE ALSO ======== MacPGP 2.6.3 Home Page http://www.math.ohio-state.edu/~fiedorow/PGP/ MacPGP 2.6.3 Documentation Included with the above package, take special note of the PGP User's Guide, MacPGP263_Manual, and MacPGP263_AppleEvents. AUTHOR ====== Chris Nandor `' http://pudge.net/ Copyright (c) 1998 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Please see the Perl Artistic License. VERSION ======= Version 1.20 (03 January 1998)