This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Getopt/Tiny, Next: Getopt/constant, Prev: Getopt/Tabular, Up: Module List yet another command line argument parsing module ************************************************ NAME ==== Getopt::Tiny - yet another command line argument parsing module SYNOPSIS ======== use Getopt::Tiny; my $arg = 'default value'; my @list; my %hash; my $flag; my %set; # begin usage info my (%flags) = ( 'argx' => \$arg, # set a parameter 'listx' => \@list, # fill in a list 'hashx' => \%hash, # set key/value pairs ); my (%switches) = ( 'flagx' => \$flag, # on or off } # end usage info getopt(\@ARGV, \%flags, \%switches); Getopt::Tiny::usage(__FILE__, \%flags, \%switches); or use Getopt::Tiny; %flags = ... %switches = ... getopt() Getopt::Tiny::usage(); DESCRIPTION =========== Getopt::Tiny is yet another argument parsing module. The results of the argument parsing are stored by using references that were provided to getopt(). Usage information is automatically generated. Getopt::Tiny expects all arguments to be switches - no trailing list of files. Getopt::Tiny can either call an existing usage() function or it can use it's own builtin one. It trys to use the existing one by default. If that fails, it will use its own. It figures out how to describe things by reading the file where call to getopt() originated. In the file where getopt is called, the following two lines must appear exactly as written here: # begin usage info # end usage info Between these two lines, lines that match the pattern of: 'someflag' => ... # a description will be noticed and used to document each flag individually. The usage() function of Getopt::Tiny can be called on it's own. It can either have it's arguments given to it explicitly or it can default them like getopt(). If a usage function is provided, it will be called with one parameter: the argument that didn't parse. ARGUMENT TYPES ============== There are four types of arguments that Getopt::Tiny supports. switches Switches are either on or off. In the example in the synopsis, the variable $flag will be respectively set to 1 or 0 if `-flagx' or `-noflagx' appears in the argument list . parameter Parameters have values. In the example above, the $arg variable will be set to whatever follows `-argx' in the argument list. list List flags can have multiple values. If present, they will have at least one value. In the example above, if the argument list containted `qw(-listx a b c -listx -d e -argx foo)', the array @list would end up with a value of `qw(a b c -d e)'. hash Hashes have multiple key-value pairs. If present they will have at least one value. In the exmaple above, if the argument list containted `qw(-hashx a=b c=d -hashx -e=f -argx bar)', the hash %hash would end up with a value of `(a => b, c => d, -e => f)'. DEFAULT PARAMETERS ================== If no arguments are given to getopt() then it assumes that the argument list to parse is `\@ARGV' and that the flags and switch references are `\%::flags' and `\%::switches' respectively. Likewise, if no arguments are given to usage() then it assumes that filename to look for information in is `(caller(0))[1]' and that the flags and switches are as above. COPYRIGHT ========= Copyright (C) 1998, David Muir Sharnoff. All rights reserved. License hearby granted for anyone to use this module at their own risk. Please feed useful changes back to muir@idiom.com.  File: pm.info, Node: Getopt/constant, Next: Gettext, Prev: Getopt/Tiny, Up: Module List set constants from command line options *************************************** NAME ==== Getopt::constant - set constants from command line options SYNOPSIS ======== # Assuming @ARGV is: ('-foo=9,8,7', '-bar', 'wakawaka.txt') use Getopt::constant ( ':prefix' => 'C_', 'foo' => [3,5], 'bar' => 0, ':usage' => "Usage: thingamabob -foo=one,two,three : fooey on these items -bar : enable barriness ", ); # @ARGV is now 'wakawaka.txt', and you've now got # a constant C_foo with value (9,8,7) # and a constant C_bar with value 1 DESCRIPTION =========== Other command-line options processing modules (like Getopt::Std) parse command-line arguments (from @ARGV) and set either variables or hash entries based on them. This module, however, parses command-line arguments into constants which are put into the current package. You provide default values for each constant in the list that you pass in the "use Getopt::constant (...);" statement. Values can be a scalar (in which case you will get a scalar constant) or an arrayref (in which case you will get a list constant). OPTIONS ======= ":prefix" => STRING, Constants are named by putting the value of the ":prefix" option (which can be empty-string) before the option name. For an example, read the SYNOPSIS section above. Default is empty-string, "". A common useful value you should consider is `"C_"'. You should not use a value, like "*" or "-" or "1" that can't begin a legal Perl symbol name. ":permissive" => BOOL, Normally, if Getopt::constant is parsing the options in @ARGV and finds an unknown item, this causes a fatal error. For example, if your call to `use Getopt::constant (...)' didn't mention a 'foo' => some_value, then when Getopt::constant gets to parsing "-foo=1", it would exit with a message to STDERR, as determined by the value of the ":usage" parameter. However, if the ":permissive" parameter is set to a true value, then unknown items are simply ignored. The default value is 0. ":usage" => VALUE, When Getopt::constant hits a command-line switch that attempts to set an option that's not in its list of known options, this is considered a fatal error, unless the ":permissive" option has been set to true (in which case it is simply ignored). What happens in the case of a fatal error is controlled by the ":usage" parameter's value: If it's a string, then on STDERR we print "Unknown options: ", and the list of the unknown options, and a newline and then the string value of the ":usage" parameter (which should presumably be something explaining what the valid parameters are, and what they mean); and then the program exits. If it's undef (which is the default value), then on STDERR we print "Unknown options: ", and the list of the unknown options and a newline, and then on the next line, the list of all permitted options; and then the program exits. If it's a code ref, then the code ref is called with three options: a reference to the array of unknown options found, a reference to the array of options allowed, and a reference to the hash consisting of the elements passed in the '`use Getopt::constant (...)';' statement. For example, if you said: use Getopt::constant ( ':prefix' => 'C_', 'foo' => [3,5], 'bar' => 0, ':usage' => sub {...}, ); and there's a "-baz" in @ARGV, then the specified sub will be called as $thatsub->( ['baz'], ['foo','bar'], { ':prefix' => 'C_', 'foo' => [3,5], 'bar' => 0, ':usage' => sub {...}, } ); and then once that sub returns, the program exits. ":retain" => BOOL, This controls whether (1) or not (0) parsed options are removed from @ARGV. Default is 0 - to remove parsed items from @ARGV. If you want to parse the options in @ARGV first with Getopt::constant and then with something like Getopt::Std, you should consider: ":retain" => 1, ":retain" => 1, (Although note that this is only a partial solution: consider an argument list of `qw(-foo 13 -bar)' which you want to be parsed by Getopt::constant and then by Getopt::Long. Getopt::Long will parse it as you expect, but Getopt::constant has a more restricted view of switch parsing and will stop parsing at "13".) ":*whatever*" => any_value, Assignments to parameters beginning with ":", other than the ones mentioned above, have no effect. "option_name" => [ ...list elements... ] Specifies a default list value for that option. The option name should be a legal Perl symbol name (e.g., "thing_1", "Thing_1", and "THING_1" are all okay - "thing 1", "thing-1", "1thing" are not.) "option_name" => value Specifies a default scalar value for that option. The option name should be a legal Perl symbol name. SWITCH PARSING ============== As Getopt::constant parses thru the items in @ARGV, it expects @ARGV to start with some number of switches; it stops parsing when it hits the first non-switch item. A switch consists of one of the following syntaxes: -foo or -foo This sets option "foo" to 1 if it's to be a scalar constant (as it usually is), or sets "foo" to [1] if it's to be a list constant. (Which it is, is determined by whether you said "foo => VALUE" or "foo => [...]" in your parameters to "use Getopt::constant (...)"). -foo=VALUE or -foo=VALUE This sets option "foo" to VALUE if it's to be a scalar constant (as it usually is); or if it's to be a list constant, then it's set to: split(",", VALUE, -1) Note that VALUE may be empty-string. I.e., "-foo=", is a legal switch which sets foo to empty-string, or empty-list if foo is to be a list constant. - (That's two hyphens in a row, not one.) This signals the end of the parameter list. Note that switches of the form: % progname.pl -foo VALUE are not recognized; you need to express that as one of: % progname.pl -foo=VALUE % progname.pl --foo=VALUE SEE ALSO ======== *Note Constant: constant,, *Note Getopt/Long: Getopt/Long,, *Note Getopt/Std: Getopt/Std, WHY? ==== Consider this: use Getopt::constant ('DEBUG' => 0); ... print "Starting doing things...\n" if DEBUG; ... foreach $thing (@many_things) { print " About to do things with $thing\n" if DEBUG > 1; ... } ... DEBUG and printf "Done doing things at %s after %s sec.\n", scalar(localtime), time - $^T; What's the point of doing this, as opposed to using Getopt::Std to set a `$DEBUG' that we'd use everywhere where we have a DEBUG above? Well, every time an expression consisting of a variable, or involving a variable (like "`$DEBUG > 1'") is encountered, it has to be evaluated. That means that in every iteration of the loop, the expression "`$DEBUG > 1'" would have to be evaluated anew, since Perl has no assurance that `$DEBUG''s value can't have changed since the last iteration. But, with constants, or expressions involving constants, Perl evaluates them only once, at compile time. So if Perl knows that the constant DEBUG has the value 2, then the expression print " About to do things with $thing\n" if DEBUG > 1; turns into: print " About to do things with $thing\n"; as Perl compiles it. But more importantly, if Perl knows DEBUG is 0 (or anything such that "DEBUG > 1" is false) then the above statement is actually removed from the in-memory compiled version of the program, before it is actually run. Incidentally, you can, with some doing, use any other Getopt library to make constants, using something like: #...Assuming an @ARGV of qw( -D4 -x9 stuff )... use strict; my %opts; BEGIN { # constants need to be made at compile time! %opts = ( 'D' => 0, 'y' => 'nope', 'x' => 3 ); # default values use Getopt::Std (); Getopt::Std::getopt('Dxy', \%opts); require constant; # Now make constants from whatever we want: constant->import('D', $opts{'D'}); constant->import('C_y', $opts{'y'}); } print "ARGV is @ARGV\n"; printf "D is %s, C_y is %s, and opts-x is %s\n", D, C_y, $opts{'x'}; That prints: ARGV is stuff D is 4, C_y is nope, opts-x is 9 That's obviously a bit circuitous, but it's quite doable. COPYRIGHT AND DISCLAIMER ======================== Copyright (c) 2001 Sean M. Burke. All rights reserved. This library 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. AUTHOR ====== Sean M. Burke, sburke@cpan.org  File: pm.info, Node: Gettext, Next: Glade/PerlGenerate, Prev: Getopt/constant, Up: Module List Perl extension for emulating gettext-related API. ************************************************* NAME ==== Gettext - Perl extension for emulating gettext-related API. SYNOPSIS ======== use Gettext; DESCRIPTION =========== Gettext.pm emulates the gettext library routines in Perl, although it calls the external utility program gettext to actually read .mo files. man gettext on Solaris has pretty good documentation. The steps to use this module are: * install the gnu gettext package if necessary (not needed on Solaris or Red Hat) * set TEXTDOMAINDIR, LANGUAGE, LANG, and LC_* if needed in your env. * use xgettext on your script that contains gettext calles to make the .po (portable message object) file, run msgfmt to make the .mo (message object) file, and move the .mo file to where you want it, normally $TEXTDOMAINDIR/lang/LC_MESSAGES. * call setlocale before calling these functions. use Gettext; my $gt = new Gettext; $gt->textdomain('domainname'); $gt->bindtextdomain('domainname', 'dirname'); $gt->gettext('msgid'); $gt->dgettext('domainname', 'msgid'); $gt->dcgettext('domainname', 'msgid', 'category (locale)'); SAMPLE ====== use strict; use diagnostics; use POSIX 'locale_h'; use locale; use Gettext; setlocale(LC_CTYPE, 'es_ES'); my $gt = new Gettext(); $gt->bindtextdomain("messages", "/root/work"); print $gt->gettext("flower"),"\n"; print $gt->gettext("yellow"),"\n"; print $gt->dgettext("messages", "flower"),"\n"; print $gt->dgettext("messages", "yellow"),"\n"; print $gt->dcgettext("messages", "flower", "fr_FR"),"\n"; print $gt->dcgettext("messages", "yellow", "fr_FR"),"\n"; print $gt->textdomain(),"\n"; print $gt->textdomain(''),"\n"; Tested on Solaris 2.6 and Red Hat Linux 6.0 AUTHOR ====== James Briggs, james@rf.net SEE ALSO ======== perldoc perllocale TO DO ===== Gettext.pm calls the external gettext utility program, but someday should have an internal routine to directory read .mo files.  File: pm.info, Node: Glade/PerlGenerate, Next: GnuPG, Prev: Gettext, Up: Module List Generate Perl source from a Glade XML project file. *************************************************** NAME ==== Glade::PerlGenerate - Generate Perl source from a Glade XML project file. SYNOPSIS ======== The simplest way to run Glade::PerlGenerate is to use the supplied script 'glade2perl' that is also called by Glade when you hit the 'Build' button. glade2perl Project.glade Otherwise you can control every aspect of the source generation by calling the same methods that glade2perl calls: use Glade::PerlGenerate; Glade::PerlGenerate->options( 'author' => 'Dermot Musgrove ', 'description' => "This is an example of the Glade-Perl source code generator", 'verbose' => 2, 'indent' => ' ', 'tabwidth' => 4, 'diag_wrap' => 0, 'write_source' => 'True', 'dont_show_UI' => 'True', 'autoflush' => 'True', 'use_modules' => 'Example::BusForm_mySUBS', 'log_file' => 'Test.log', ); Then to generate the UI defined in a file Glade::PerlGenerate->Form_from_Glade_File( 'glade_filename'=> "Example/BusForm.glade" ); OR if you want to generate the UI directly from an XML string Glade::PerlGenerate->Form_from_XML( 'xml' => $xml_string, 'use_modules' => ['Example::Project_mySUBS'] ); DESCRIPTION =========== Glade::PerlGenerate reads a definition from a Glade file (or a string) using XML::Parser, converts it into a hash of hashes and works its way through this to show the UI using Gtk-Perl bindings. The module can also optionally generate Perl source code to show the UI and handle the signals. Any signal handlers that are specified in the project file but not visible at Generate time will be hijacked to show a 'missing_handler' message_box and a stub for it will be defined in the the UI class for dynamic AUTOLOAD()ing. The stub will simply show a message_box to prove that the handler has been called and you can write your own with the same name in another module. You then quote this module to the next Generate run and Glade::PerlGenerate will use these handlers and not define stubs. USER OPTIONS ============ These options can be specified using the Glade::PerlGenerate->options() method or with the same name in the options XML files. Boolean values can be specified as True|true|Yes|yes|1 or False|false|No|no|0|"|undef Project options --------------- author The author's name to appear in generated sources. Backslash-escape any @ signs so that they are passed through perl strings correctly. The default is synthesised from some of the values returned by Perl's gethostbyname "localhost" e.g. 'Dermot Musgrove options() although it is logged in the project_options file user_options - Default is ~/.glade2perl.xml File name containing options for all projects in this user. This option is only meaningful when set by Glade::PerlGenerate->options() although it is logged in the project_options file project_options - Default means don't read or save a file Filename of project options to read and save. This option is only meaningful when set by Glade::PerlGenerate->options() although it is logged in the project_options file glade_encoding - default 'ISO-8859-1' Character encoding of Glade file eg 'ISO-8859-1' glade2perl_encoding - default is glade_encoding option Character encoding of glade2perl.xml options files. This option is only meaningful when set by Glade::PerlGenerate->options() although it is saved in the file itself. eg 'ISO-8859-1' From the Glade file ------------------- name Name to use for the generated packages. Any spaces, dots or minuses will be removed from the name as these are not valid in perl package names. source_directory - Directory to contain the generated sources pixmaps_directory - Directory to search for pixmaps The UI ------ dont_show_UI - default is to show the UI and wait for user action Bool - whether to show the UI during the Build. glade2perl sets this to 0 so that the UI is not shown. logo - default 'Logo.xpm' Use the specified logo in about boxes or if any pixmap is missing my_perl_gtk - Default is to use Gtk-Perl's version number Version number of my Gtk-Perl module. This overrides the number reported by Gtk::Perl so that CVS fixes can be used. '0.6123' I have CPAN version 0.6123 '19991001' I have the gnome.org CVS version of 'gnome-perl' that I downloaded on Oct 1st 1999 my_gnome_libs - Default is to use gnome-libs version no Version number of my gnome-libs. This overrides the number reported by `gnome-libs-config -version` so that CVS fixes can be used. '1.0.58' I have the released version 1.0.58 of 'gnome-libs' '19991001' I have the gnome.org CVS version of 'gnome-libs' that I downloaded on Oct 1st 1999 Source code options ------------------- indent - default is 4 spaces Indent to use for 'nested' source code e.g. ' ' (2 spaces) tabwidth - default is 8 Number of spaces to replace with a tab in generated source code e.g. 4 write_source - default is no source Where to write the source code. glade2perl sets this to 1. 'STDOUT' Write sources to STDOUT but there will be nothing to run later 'File.pm' Write sources to File.pm They will not run from here and you must cut-paste them True - write the sources to standard files. undef Don't write source code hierarchy - default means don't generate any hierarchy ...widget... generates a widget hierarchy eg $hier->{'vbox2'}{'table1'}... ...class... generates a class hierarchy eg $hier->{'GtkVBox'}{'vbox2'}{'GtkTable'}{'table1'}... ...both... both widget and class hierarchies generated e.g. 'widget_hierarchy' style - default AUTOLOAD AUTOLOAD - OO class implements missing signal handlers with an AUTOLOAD sub Libglade - generate libglade code and signal handlers split - generates each class in its own .pm file. source_LANG - default $ENV{'LANG'} Which language do we want the source to be documented in? e.g. 'pt_BR' Diagnostics options ------------------- verbose - default is 2 Level of verbosity of diagnostics 0 - Quiet/no diagnostics (glade2perl uses this) 1 - Main project messages and errors only 2 - also warnings 4 - also project options and more diagnostics 6 - also source code as it is generated 8 - also lookups and conversions 10 - everything (more than you want?) diag_wrap - default is 0 (no breaks) Maximum diagnostics message line length (approximate) 0 - no breaks (not easy to read on 80 column displays). 80 - should display comfortably on 80 column display 132 - Wrap diagnostics so that lines are about 132 characters long log_file - Default is to use STDOUT Write diagnostics and errors to filename if verbose > 0 glade2perl can set this to /path/to/glade/file.glade2perl.log e.g. '/home/dermot/Devel/Test/Project1.glade2perl.log' autoflush - default is False (write at end of block) Bool - whether to autoflush the file output. This is really to force errors to be shown by my editor's shellout in the case of a failure. benchmark - default means don't add time to the diagnostic messages Bool - True will cause the time to prefix all diagnostics messages diag_LANG - default $ENV{'LANG'} Which language do we want the diagnostic messages in? e.g. 'de' Run History - for internal use only ----------------------------------- start_time Time that this run started options_set - default 'DEFAULT' Who set the options last. glade_proto This is where Glade::PerlGenerate stores the Glade proto glade2perl_version Version of Glade::PerlGenerate that wrote this file. glade2perl_logo - default 'glade2perl_logo.xpm' Name of the Glade::PerlGenerate logo pixmap used. EXAMPLE OPTIONS FILES ===================== This is a typical project_options file ~/Devel/Glade-Perl/Example/Reference/Existing/Reference.glade2perl.xml -------------------------------------------------------------------------------------------------------------- 1 1 1 A reference form containing all possible Gtk and Gnome widgets 1 ISO-8859-1 0.53 NONE Existing/Reference.glade2perl.log Glade/Build Source Existing/Reference.glade2perl.xml Sat Apr 8 15:29:12 BST 2000 8 Existing::Reference_mySUBS /home/dermot/.glade2perl.xml 0.53 This what I have in my user_options file ~/.glade2perl.xml ----------------------------------------------------------- Dermot Musgrove en 0 en 4 1 This what I have in my site_options file /etc/glade2perl.xml ------------------------------------------------------------- # This library is released under the same conditions as Perl, that # is, either of the following: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 1, or (at your option) any # later version. # # b) the Artistic License. # # If you use this library in a commercial enterprise, you are invited, # but not required, to pay what you feel is a reasonable fee to cpan.org # at http://www.perl.org or contact donors\@perlmongers.org for details. # 20000301 ERRORS and WARNINGS =================== The module will report several errors or warnings that warn of problems with the Glade file or other unexpected occurences. These are to help me cater for new widgets or widget properties and not because Glade creates inconsistent project files but they do point out errors in hand-edited XML. FILES GENERATED =============== projectUI.pm A perl class/module (projectUI.pm) that contains a class for each toplevel window/dialog, each with a standard method (new) that will construct the UI. projectSIGS.pm A perl class/module (projectSIGS.pm) that contains a class for each toplevel window/dialog, with skeleton signal handlers for any that were missing at build time. If the 'split' style is used, the typical filename will be projectSIGS_class .pm (one file per class). project.pm A perl class/module (project.pm) that is a copy of projectSIGS.pm for you to edit to become your "App". You can generate the UI again and again without changing any of your signal handlers as it is only written the first time through (if missing). If you add signal definitions to your Glade project, skeletons for the handlers will be generated in the projectSIGS.pm file and you can cut-and-paste them from there into the relevant class in the project.pm "App" module. If the 'split' style is used, the typical filename will be project_class .pm (one file per class). Subproject.pm A perl class/module (Subproject.pm) that subclasses project.pm that you can edit to subclass your "App". You can generate the UI again and again without changing any of your signal handlers as it is only written the first time through (if missing). projectLIBGLADE.pm An optional perl class/module (projectLIBGLADE.pm) that initialises the Libglade bindings and has skeleton signal handlers that you can edit to form your "App". You can generate the UI again and again without changing any of your signal handlers as it is only written the first time through (if missing). SEE ALSO ======== Documentation that came with the module is in Directory 'Documentation' in files README, Changelog, FAQ, TODO, NEWS, ROADMAP etc. The test file for 'make test' is test.pl which is runnable and has examples of user options. A Perl script to generate source code from the Glade 'Build' button or menuitem is in file 'Example/glade2perl'. You can also call this script from the command line. A module that subclasses the test example is in file Example/SubBus.pm. This module will use (inherit or subclass) the generated perl classes and also use the supplied signal handlers module (Example/BusForm_mySUBS.pm)  File: pm.info, Node: GnuPG, Next: GnuPG/Fingerprint, Prev: Glade/PerlGenerate, Up: Module List Perl module interface to the GNU Privacy Guard. *********************************************** NAME ==== GnuPG - Perl module interface to the GNU Privacy Guard. SYNOPSIS ======== use GnuPG qw( :algo ); my $gpg = new GnuPG(); $gpg->encrypt( plaintext => "file.txt", output => "file.gpg", armor => 1, sign => 1, passphrase => $secret ); $gpg->decrypt( ciphertext => "file.gpg", output => "file.txt" ); $gpg->clearsign( plaintext => "file.txt", output => "file.txt.asc", passphrase => $secret, armor => 1, ); $gpg->verify( signature => "file.txt.asc", file => "file.txt" ); $gpg->gen_key( name => "Joe Blow", comment => "My GnuPG key", passphrase => $secret, ); DESCRIPTION =========== GnuPG is a perl interface to the GNU Privacy Guard. It uses the shared memory coprocess interface that gpg provides for its wrappers. It tries its best to map the interactive interface of the gpg to a more programmatic model. API OVERVIEW ============ The API is accessed through methods on a GnuPG object which is a wrapper around the *gpg* program. All methods takes their argument using named parameters, and errors are returned by throwing an exception (using croak). If you wan't to catch errors you will have to use eval. There is also a tied file handle interface which you may find more convenient for encryption and decryption. See GnuPG::Tie(3) for details. CONSTRUCTOR =========== new ( [params] ) ---------------- You create a new GnuPG wrapper object by invoking its new method. (How original !). The module will try to finds the *gpg* program in your path and will croak if it can't find it. Here are the parameters that it accepts : gnupg_path Path to the *gpg* program. options Path to the options file for *gpg*. If not specified, it will use the default one (usually `~/.gnupg/options'). homedir Path to the *gpg* home directory. This is the directory that contains the default options file, the public and private key rings as well as the trust database. trace If this variable is set to true, *gpg* debugging output will be sent to stderr. Example: my $gpg = new GnuPG(); METHODS ======= gen_key( [params] ) ------------------- This methods is used to create a new gpg key pair. The methods croaks if there is an error. It is a good idea to press random keys on the keyboard while running this methods because it consumes a lot of entropy from the computer. Here are the parameters it accepts : Ex: $gpg-> algo This is the algorithm use to create the key. Can be ELGAMAL, DSA_ELGAMAL or DSA. It defaults to DSA_ELGAMAL. To import those constant in your name space, use the :algo tag. size The size of the public key. Defaults to 1024. Cannot be less than 768 bits, and keys longer than 2048 are also discouraged. (You *DO* know that your monitor may be leaking sensitive informations ;-). valid How long the key is valid. Defaults to 0 or never expire. name This is the only mandatory argument. This is the name that will used to construct the user id. email Optional email portion of the user id. comment Optional comment portion of the user id. passphrase The passphrase that will be used to encrypt the private key. Optional but strongly recommended. Example: $gpg->gen_key( algo => DSA_ELGAMAL, size => 1024, name => "My name" ); import_keys( [params] ) ----------------------- Import keys into the GnuPG private or public keyring. The method croaks if it encounters an error. It returns the number of keys imported. Parameters : keys Only parameter and mandatory. It can either be a filename or a reference to an array containing a list of files that will be imported. Example: $gpg->import_keys( keys => [ qw( key.pub key.sec ) ] ); export_keys( [params] ) ----------------------- Exports keys from the GnuPG keyrings. The method croaks if it encounters an error. Parameters : keys Optional argument that restricts the keys that will be exported. Can either be a user id or a reference to an array of userid that specifies the keys to be exported. If left unspecified, all keys will be exported. secret If this argument is to true, the secret keys rather than the public ones will be exported. all If this argument is set to true, all keys (even those that aren't OpenPGP compliant) will be exported. output This argument specifies where the keys will be exported. Can be either a file name or a reference to a file handle. If not specified, the keys will be exported to stdout. armor Set this parameter to true, if you want the exported keys to be ASCII armored. Example: $gpg->export_keys( armor => 1, output => "keyring.pub" ); encrypt( [params] ) ------------------- This method is used to encrypt a message, either using assymetric or symmetric cryptography. The methods croaks if an error is encountered. Parameters: plaintext This argument specifies what to encrypt. It can be either a filename or a reference to a file handle. If left unspecified, STDIN will be encrypted. output This optional argument specifies where the ciphertext will be output. It can be either a file name or a reference to a file handle. If left unspecified, the ciphertext will be sent to STDOUT. armor If this parameter is set to true, the ciphertext will be ASCII armored. symmetric If this parameter is set to true, symmetric cryptography will be used to encrypt the message. You will need to provide a passphrase parameter. recipient If not using symmetric cryptography, you will have to provide this parameter. It should contains the userid of the intended recipient of the message. It will be used to look up the key to use to encrypt the message. sign If this parameter is set to true, the message will also be signed. You will probably have to use the passphrase parameter to unlock the private key used to sign message. This option is incompatible with the symmetric one. local-user This parameter is used to specified the private key that will be used to sign the message. If left unspecified, the default user will be used. This option only makes sense when using the sign option. passphrase This parameter contains either the secret passphrase for the symmetric algorithm or the passphrase that should be used to decrypt the private key. Example: $gpg->encrypt( plaintext => file.txt, output => "file.gpg", sign => 1, passphrase => $secret ); sign( [params] ) ---------------- This method is used create a signature for a file or stream of data. This method croaks on errors. Parameters : plaintext This argument specifies what to sign. It can be either a filename or a reference to a file handle. If left unspecified, the data read on STDIN will be signed. output This optional argument specifies where the signature will be output. It can be either a file name or a reference to a file handle. If left unspecified, the signature will be sent to STDOUT. armor If this parameter is set to true, the signature will be ASCII armored. passphrase This parameter contains the secret that should be used to decrypt the private key. local-user This parameter is used to specified the private key that will be used to make the signature . If left unspecified, the default user will be used. detach-sign If set to true, a digest of the data will be signed rather than the whole file. Example: $gpg->sign( plaintext => "file.txt", output => "file.txt.asc", armor => 1, ); clearsign( [params] ) --------------------- This methods clearsign a message. The output will contains the original message with a signature appended. It takes the same parameters as the sign method. verify( [params] ) ------------------ This method verifies a signature against the signed message. The methods croaks if the signature is invalid or an error is encountered. If the signature is valid, it returns an hash with the signature parameters. Here are the method's parameters : signature If the message and the signature are in the same file (i.e. a clearsigned message), this parameter can be either a file name or a reference to a file handle. If the signature doesn't follows the message, than it must be the name of the file that contains the signature. file This is a file name or a reference to an array of file names that contains the signed data. When the signature is valid, here are the elements of the hash that is returned by the method : sigid The signature id. This can be used to protect against replay attack. date The data at which the signature has been made. timestamp The epoch timestamp of the signature. keyid The key id used to make the signature. user The userid of the signer. fingerprint The fingerprint of the signature. trust The trust value of the public key of the signer. Those are values that can be imported in your namespace with the :trust tag. They are (TRUST_UNDEFINED, TRUST_NEVER, TRUST_MARGINAL, TRUST_FULLY, TRUST_ULTIMATE). Example : my $sig = $gpg->verify( signature => "file.txt.asc", file => "file.txt" ); decrypt( [params] ) ------------------- This method decrypts an encrypted message. It croaks, if there is an error while decrypting the message. If the message was signed, this method also verifies the signature. If decryption is sucessful, the method either returns the valid signature parameters if present, or true. Method parameters : ciphertext This optional parameter contains either the name of the file containing the ciphertext or a reference to a file handle containing the ciphertext. If not present, STDIN will be decrypted. output This optional parameter determines where the plaintext will be stored. It can be either a file name or a reference to a file handle. If left unspecified, the plaintext will be sent to STDOUT. symmetric This should be set to true, if the message is encrypted using symmetric cryptography. passphrase The passphrase that should be used to decrypt the message (in the case of a message encrypted using a symmetric cipher) or the secret that will unlock the private key that should be used to decrypt the message. Example: $gpg->decrypt( ciphertext => "file.gpg", output => "file.txt" passphrase => $secret ); AUTHOR ====== Francis J. Lacoste COPYRIGHT ========= Copyright (c) 1999,2000 iNsu Innovations. Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== gpg(1) GnuPG::Tie(3)  File: pm.info, Node: GnuPG/Fingerprint, Next: GnuPG/Handles, Prev: GnuPG, Up: Module List GnuPG Fingerprint Objects ************************* NAME ==== GnuPG::Fingerprint - GnuPG Fingerprint Objects SYNOPSIS ======== # assumes a GnuPG::Key in $key my $fingerprint = $key->fingerprint->hex_data(); DESCRIPTION =========== GnuPG::Fingerprint objects are generally part of GnuPG::Key objects, and are not created on their own. OBJECT METHODS ============== Initialization Methods ---------------------- new( *%initialization_args* ) This methods creates a new object. The optional arguments are initialization of data members; the initialization is done in a manner according to the method created as described in `"new_hash_init"', *Note Class/MethodMaker: Class/MethodMaker,. hash_init( *%args* ). This method works as described in `"new_hash_init"', *Note Class/MethodMaker: Class/MethodMaker,. OBJECT DATA MEMBERS =================== Note that these data members are interacted with via object methods created using the methods described in `"get_set"', *Note Class/MethodMaker: Class/MethodMaker,, or `"object"', *Note Class/MethodMaker: Class/MethodMaker,. Please read there for more information. hex_data This is the hex value of the fingerprint that the object embodies. SEE ALSO ======== *Note GnuPG/Key: GnuPG/Key,, *Note Class/MethodMaker: Class/MethodMaker,  File: pm.info, Node: GnuPG/Handles, Next: GnuPG/Interface, Prev: GnuPG/Fingerprint, Up: Module List GnuPG handles bundle ******************** NAME ==== GnuPG::Handles - GnuPG handles bundle SYNOPSIS ======== use IO::Handle; my ( $stdin, $stdout, $stderr, $status_fh, $logger_fh, $passphrase_fh, ) = ( IO::Handle->new(), IO::Handle->new(), IO::Handle->new(), IO::Handle->new(), IO::Handle->new(), IO::Handle->new(), ); my $handles = GnuPG::Handle->new ( stdin => $stdin, stdout => $stdout, stderr => $stderr, status => $status_fh, logger => $logger_fh, passphrase => $passphrase_fh, ); DESCRIPTION =========== GnuPG::Handles objects are generally instantiated to be used in conjunction with methods of objects of the class GnuPG::Interface. GnuPG::Handles objects represent a collection of handles that are used to communicate with GnuPG. OBJECT METHODS ============== Initialization Methods ---------------------- new( *%initialization_args* ) This methods creates a new object. The optional arguments are initialization of data members; the initialization is done in a manner according to the method created as described in `"new_hash_init"', *Note Class/MethodMaker: Class/MethodMaker,. hash_init( *%args* ). This method works as described in `"new_hash_init"', *Note Class/MethodMaker: Class/MethodMaker,. OBJECT DATA MEMBERS =================== Note that these data members are interacted with via object methods created using the methods described in `"get_set"', *Note Class/MethodMaker: Class/MethodMaker,, or `"object"', *Note Class/MethodMaker: Class/MethodMaker,. Please read there for more information. stdin This handle is connected to the standard input of a GnuPG process. stdout This handle is connected to the standard output of a GnuPG process. stderr This handle is connected to the standard error of a GnuPG process. status This handle is connected to the status output handle of a GnuPG process. logger This handle is connected to the logger output handle of a GnuPG process. passphrase This handle is connected to the passphrase input handle of a GnuPG process. command This handle is connected to the command input handle of a GnuPG process. options This is a hash of hashrefs of settings pertaining to the handles in this object. The outer-level hash is keyed by the names of the handle the setting is for, while the inner is keyed by the setting being referenced. For example, to set the setting direct to true for the filehandle stdin, the following code will do: # assuming $handles is an already-created # GnuPG::Handles object, this sets all # options for the filehandle stdin in one blow, # clearing out all others $handles->options( 'stdin', { direct => 1 } ); # this is useful to just make one change # to the set of options for a handle $handles->options( 'stdin' )->{direct} = 1; # and to get the setting... $setting = $handles->options( 'stdin' )->{direct}; # and to clear the settings for stdin $handles->options( 'stdin', {} ); The currently-used settings are as follows: direct If the setting direct is true for a handle, the GnuPG process spawned will access the handle directly. This is useful for having the GnuPG process read or write directly to or from an already-opened file. SEE ALSO ======== *Note GnuPG/Interface: GnuPG/Interface,, *Note Class/MethodMaker: Class/MethodMaker,  File: pm.info, Node: GnuPG/Interface, Next: GnuPG/Key, Prev: GnuPG/Handles, Up: Module List Perl interface to GnuPG *********************** NAME ==== GnuPG::Interface - Perl interface to GnuPG SYNOPSIS ======== # A simple example use IO::Handle; use GnuPG::Interface; # settting up the situation my $gnupg = GnuPG::Interface->new(); $gnupg->options->hash_init( armor => 1, homedir => '/home/foobar' ); # Note you can set the recipients even if you aren't encrypting! $gnupg->options->push_recipients( 'ftobin@uiuc.edu' ); $gnupg->options->meta_interactive( 0 ); # how we create some handles to interact with GnuPG my $input = IO::Handle->new(); my $output = IO::Handle->new(); my $handles = GnuPG::Handles->new( stdin => $input, stdout => $output ); # Now we'll go about encrypting with the options already set my @plaintext = ( 'foobar' ); $gnupg->encrypt( handles => $handles ); # Now we write to the input of GnuPG print $input @plaintext; close $input; # now we read the output my @ciphertext = <$output>; close $output; wait; DESCRIPTION =========== GnuPG::Interface and it's associated modules are designed to provide an object-oriented method for interacting with GnuPG, being able to perform functions such as but not limited to encrypting, signing, decryption, verification, and key-listing parsing. How Data Member Accessor Methods are Created -------------------------------------------- Each module in the GnuPG::Interface bundle relies on Class::MethodMaker to generate the get/set methods used to set the object's data members. *This is very important to realize.* This means that any data member which is a list has special methods assigned to it for pushing, popping, and clearing the list. Understanding Bidirectional Communication ----------------------------------------- It is also imperative to realize that this package uses interprocess communication methods similar to those used in *Note IPC/Open3: IPC/Open3, and `"Bidirectional Communication with Another Process"', *Note Perlipc: (perl.info)perlipc,, and that users of this package need to understand how to use this method because this package does not abstract these methods for the user greatly. processes using these methods. This package is not designed to abstract this away (partly for security purposes) but rather to simply creating a 'proper' call to GnuPG, and to implement key-listing parsing. Please see `"Bidirectional Communication with Another Process"', *Note Perlipc: (perl.info)perlipc, to learn how to deal with these methods. Using this package to do message processing generally invovlves creating a GnuPG::Interface object, creating a GnuPG::Handles object, setting some options in its options data member, and then calling a method which invokes GnuPG, such as *clearsign*. One then interacts with with the handles appropriately, as described in `"Bidirectional Communication with Another Process"', *Note Perlipc: (perl.info)perlipc,. OBJECT METHODS ============== Initialization Methods ---------------------- new( *%initialization_args* ) This methods creates a new object. The optional arguments are initialization of data members; the initialization is done in a manner according to the method created as described in `"new_hash_init"', *Note Class/MethodMaker: Class/MethodMaker,. hash_init( *%args* ). This methods work as described in `"new_hash_init"', *Note Class/MethodMaker: Class/MethodMaker,. Object Methods which use a GnuPG::Handles Object ------------------------------------------------ list_public_keys( % ) list_sigs( % ) list_secret_keys( % ) encrypt( % ) encrypt_symmetrically( % ) sign( % ) clearsign( % ) detach_sign( % ) sign_and_encrypt( % ) decrypt( % ) verify( % ) import_keys( % ) export_keys( % ) recv_keys( % ) send_keys( % ) These methods each correspond directly to or are very similar to a GnuPG command described in `gpg' in this node. Each of these methods takes a hash, which currently must contain a key of handles which has the value of a GnuPG::Handles object. Another optional key is *gnupg_command_args* which should have the value of an array reference; these arguments will be passed to GnuPG as command arguments. These command arguments are used for such things as determining the keys to list in the *export_keys* method. *Please note that GnuPG command arguments are not the same as GnuPG options*. To understand what are options and what are command arguments please read `gpg' in this node and `gpg' in this node. Each of these calls returns the PID for the resulting GnuPG process. One can use this PID in a waitpid call instead of a wait call if more precise process reaping is needed. These methods will attach the handles specified in the handles object to the running GnuPG object, so that bidirectional communication can be established. That is, the optionally-defined stdin, stdout, stderr, status, logger, and passphrase handles will be attached to GnuPG's input, output, standard error, the handle created by setting *status-fd*, the handle created by setting *logger-fd*, and the handle created by setting *passphrase-fd* respectively. This tying of handles of similar to the process done in IPC::Open3. If you want the GnuPG process read or write directly to an already-opened filehandle, you cannot do this via the normal IPC::Open3 mechanisms. In order to accomplish this, set the appropriate handles data member to the already-opened filehandle, and then set the option direct to be true for that handle, as described in `options', *Note GnuPG/Handles: GnuPG/Handles,. For example, to have GnuPG read from the file `input.txt' and write to `output.txt', the following snippet may do: my $infile = IO::File->new( 'input.txt.' ); my $outfile = IO::File->new( 'output.txt' ); my $handles = GnuPG::Handles->new( stdin => $infile, stdout => $outfile, ); $handles->options( 'stdin' )->{direct} = 1; $handles->options( 'stdout' )->{direct} = 1; If any handle in the handles object is not defined, GnuPG's input, output, and standard error will be tied to the running program's standard error, standard output, or standard error. If the status or logger handle is not defined, this channel of communication is never established with GnuPG, and so this information is not generated and does not come into play. If the passphrase data member handle of the handles object is not defined, but the the passphrase data member handle of GnuPG::Interface object is, GnupG::Interface will handle passing this information into GnuPG for the user as a convience. Note that this will result in GnuPG::Interface storing the passphrase in memory, instead of having it simply 'pass-through' to GnuPG via a handle. Other Methods ------------- get_public_keys( @search_strings ) get_secret_keys( @search_strings ) get_public_keys_with_sigs( @search_strings ) These methods create and return objects of the type GnuPG::PublicKey or GnuPG::SecretKey respectively. This is done by parsing the output of GnuPG with the option *with-colons* enabled. The objects created do or do not have signature information stored in them, depending if the method ends in *_sigs*; this separation of functionality is there because of performance hits when listing information with signatures. test_default_key_passphrase() This method will return a true or false value, depending on whether GnupG reports a good passphrase was entered while signing a short message using the values of the passphrase data member, and the default key specified in the options data member. OBJECT DATA MEMBERS =================== Note that these data members are interacted with via object methods created using the methods described in `"get_set"', *Note Class/MethodMaker: Class/MethodMaker,, or `"object"', *Note Class/MethodMaker: Class/MethodMaker,. Please read there for more information. gnupg_call This defines the call made to invoke GnuPG. Defaults to 'gpg'; this should be changed if 'gpg' is not in your path, or there is a different name for the binary on your system. passphrase In order to lessen the burden of using handles by the user of this package, setting this option to one's passphrase for a secret key will allow the package to enter the passphrase via a handle to GnuPG by itself instead of leaving this to the user. See also `passphrase', *Note GnuPG/Handles: GnuPG/Handles,. options This data member, of the type GnuPG::Options; the setting stored in this data member are used to determine the options used when calling GnuPG via any of the object methods described in this package. See *Note GnuPG/Options: GnuPG/Options, for more information. EXAMPLES ======== The following setup can be done before any of the following examples: use IO::Handle; use GnupG::Interface; my @original_plaintext = ( "How do you doo?" ); my $passphrsae = "Three Little Pigs"; my $gnupg = GnupG::Interface->new(); $gnupg->options->hash_init( armor => 1, recipients => [ 'ftobin@uiuc.edu', '0xABCD1234' ], meta_interactive( 0 ), ); Encrypting ---------- # We'll let standard error to to our standard error my ( $input, $output ) = ( IO::Handle->new(), IO::Handle->new() ); my $handles = GnupG::Handles->new( stdin => $input, stdout => $output ); # this sets up the communication # Note that the recipients were specified earlier # in the 'options' data member of the $gnupg object. $gnupg->encrypt( handles => $handles ); # this passes in the plaintext print $input @original_plaintext; # this closes the communication channel, # indicating we are done close $input; my @ciphertext = <$output>; # reading the output wait; # clean up the finished GnuPG process Signing ------- # This time we'll catch the standard error for our perusing my ( $input, $output, $error ) = ( IO::Handle->new(), IO::Handle->new(), IO::Handle->new(), ); my $handles = GnupG::Handles->new( stdin => $input, stdout => $output, stderr => $error, ); # indicate our pasphrase through the # convience method $gnupg->passphrase( $passphrase ); # this sets up the communication $gnupg->sign( handles => $handles ); # this passes in the plaintext print $input @original_plaintext; # this closes the communication channel, # indicating we are done close $input; my @ciphertext = <$output>; # reading the output my @error_output = <$error>; # reading the error close $output; close $error; wait; # clean up the finished GnuPG process Decryption ---------- # This time we'll catch the standard error for our perusing # as well as passing in the passphrase manually # as well as the status information given by GnuPG my ( $input, $output, $error, $passphrase_fh, $status_fh ) = ( IO::Handle->new(), IO::Handle->new(), IO::Handle->new(), IO::Handle->new(), IO::Handle->new(), ); my $handles = GnupG::Handles->new( stdin => $input, stdout => $output, stderr => $error, passphrase => $passphrase_fh, status => $status_fh, ); # this time we'll also demonstrate decrypting # a file written to disk # Make sure you "use IO::File" if you use this module! my $cipher_file = IO::File->new( 'encrypted.gpg' ); # this sets up the communication $gnupg->decrypt( handles => $handles ); # This passes in the passphrase print $passphrase_fd $passphrase; close $passphrase_fd; # this passes in the plaintext print $input $_ while <$cipher_file> # this closes the communication channel, # indicating we are done close $input; close $cipher_file; my @plaintext = <$output>; # reading the output my @error_output = <$error>; # reading the error my @status_info = <$status_fh> # read the status info # clean up... close $output; close $error; close $status_fh; wait; # clean up the finished GnuPG process Printing Keys ------------- # This time we'll just let GnuPG print to our own output # and read from our input, because no input is needed! my $handles = GnuPG::Handles->new(); my @ids = [ 'ftobin', '0xABCD1234' ]; # this time we need to specify something for # gnupg_command_args because --list-public-keys takes # search ids as arguments $gnupg->list_public_keys( handles => $handles, gnupg_command_args => [ @ids ] ); wait; Creating GnuPG::PublicKey Objects --------------------------------- my @ids = [ 'ftobin', '0xABCD1234' ]; my @keys = $gnupg->get_public_keys( @ids ); # no wait is required this time; it's handled internally # since the entire call is encapsulated FAQ === How do I get GnuPG::Interface to read/write directly from a filehandle? You need to set GnuPG::Handles direct option to be true for the filehandles in concern. See `options', *Note GnuPG/Handles: GnuPG/Handles, and `"Object Methods which use a GnuPG::Handles Object"' in this node for more information. Why do you make it so difficult to get GnuPG to write/read from a filehandle? In the shell, I can just call GnuPG with the -outfile option! There are lots of issues when trying to tell GnuPG to read/write directly from a file, such as if the file isn't there, or there is a file, and you want to write over it! What do you want to happen then? Having the user of this module handle these questions beforehand by opening up filehandles to GnuPG lets the user know fully what is going to happen in these circumstances, and makes the module less error-prone. When having GnuPG process a large message, sometimes it just hanges there. Your problem may be due to buffering issues; when GnuPG reads/writes to *non-direct* filehandles (those that are sent to filehandles which you read to from into memory, not that those access the disk), buffering issues can mess things up. I recommend looking into `options', *Note GnuPG/Handles: GnuPG/Handles,. NOTES ===== This package is the successor to PGP::GPG::MessageProcessor, which I found to be too inextensible to carry on further. A total redesign was needed, and this is the resulting work. After any call to a GnuPG-command method of GnuPG::Interface in which one passes in the handles, one should all wait to clean up GnuPG from the process table. BUGS ==== Currently there are problems when transmitting large quantities of information over handles; I'm guessing this is due to buffering issues. This bug does not seem specific to this package; IPC::Open3 also appears affected. I don't know yet how well this modules handles parsing OpenPGP v3 keys. SEE ALSO ======== *Note GnuPG/Options: GnuPG/Options,, *Note GnuPG/Handles: GnuPG/Handles,, *Note GnuPG/PublicKey: GnuPG/PublicKey,, *Note GnuPG/SecretKey: GnuPG/SecretKey,, `gpg' in this node, *Note Class/MethodMaker: Class/MethodMaker,, `"Bidirectional Communication with Another Process"', *Note Perlipc: (perl.info)perlipc, AUTHOR ====== Frank J. Tobin, ftobin@uiuc.edu PACKAGE UPDATES =============== Package updates may be found on http://GnuPG-Interface.sourceforge.net/ or CPAN, http://www.cpan.org/.