This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: ExtUtils/Miniperl, Next: ExtUtils/Mkbootstrap, Prev: ExtUtils/Manifest, Up: Module List write the C code for perlmain.c ******************************* NAME ==== ExtUtils::Miniperl, writemain - write the C code for perlmain.c SYNOPSIS ======== `use ExtUtils::Miniperl;' `writemain(@directories);' DESCRIPTION =========== This whole module is written when perl itself is built from a script called minimod.PL. In case you want to patch it, please patch minimod.PL in the perl distribution instead. writemain() takes an argument list of directories containing archive libraries that relate to perl modules and should be linked into a new perl binary. It writes to STDOUT a corresponding perlmain.c file that is a plain C file containing all the bootstrap code to make the modules associated with the libraries available from within perl. The typical usage is from within a Makefile generated by ExtUtils::MakeMaker. So under normal circumstances you won't have to deal with this module directly. SEE ALSO ======== *Note ExtUtils/MakeMaker: ExtUtils/MakeMaker,  File: pm.info, Node: ExtUtils/Mkbootstrap, Next: ExtUtils/Mksymlists, Prev: ExtUtils/Miniperl, Up: Module List make a bootstrap file for use by DynaLoader ******************************************* NAME ==== ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader SYNOPSIS ======== `mkbootstrap' DESCRIPTION =========== Mkbootstrap typically gets called from an extension Makefile. There is no `*.bs' file supplied with the extension. Instead, there may be a `*_BS' file which has code for the special cases, like posix for berkeley db on the NeXT. This file will get parsed, and produce a maybe empty `@DynaLoader::dl_resolve_using' array for the current architecture. That will be extended by $BSLOADLIBS, which was computed by ExtUtils::Liblist::ext(). If this array still is empty, we do nothing, else we write a .bs file with an `@DynaLoader::dl_resolve_using' array. The `*_BS' file can put some code into the generated `*.bs' file by placing it in `$bscode'. This is a handy 'escape' mechanism that may prove useful in complex situations. If @DynaLoader::dl_resolve_using contains `-L*' or `-l*' entries then Mkbootstrap will automatically add a dl_findfile() call to the generated `*.bs' file.  File: pm.info, Node: ExtUtils/Mksymlists, Next: ExtUtils/Packlist, Prev: ExtUtils/Mkbootstrap, Up: Module List write linker options files for dynamic extension ************************************************ NAME ==== ExtUtils::Mksymlists - write linker options files for dynamic extension SYNOPSIS ======== use ExtUtils::Mksymlists; Mksymlists({ NAME => $name , DL_VARS => [ $var1, $var2, $var3 ], DL_FUNCS => { $pkg1 => [ $func1, $func2 ], $pkg2 => [ $func3 ] }); DESCRIPTION =========== ExtUtils::Mksymlists produces files used by the linker under some OSs during the creation of shared libraries for dynamic extensions. It is normally called from a MakeMaker-generated Makefile when the extension is built. The linker option file is generated by calling the function `Mksymlists', which is exported by default from ExtUtils::Mksymlists. It takes one argument, a list of key-value pairs, in which the following keys are recognized: DLBASE This item specifies the name by which the linker knows the extension, which may be different from the name of the extension itself (for instance, some linkers add an '_' to the name of the extension). If it is not specified, it is derived from the NAME attribute. It is presently used only by OS2 and Win32. DL_FUNCS This is identical to the DL_FUNCS attribute available via MakeMaker, from which it is usually taken. Its value is a reference to an associative array, in which each key is the name of a package, and each value is an a reference to an array of function names which should be exported by the extension. For instance, one might say `DL_FUNCS => { Homer::Iliad => [ qw(trojans greeks) ], Homer::Odyssey => [ qw(travellers family suitors) ] }'. The function names should be identical to those in the XSUB code; `Mksymlists' will alter the names written to the linker option file to match the changes made by xsubpp. In addition, if none of the functions in a list begin with the string *boot_*, `Mksymlists' will add a bootstrap function for that package, just as xsubpp does. (If a *boot_* function is present in the list, it is passed through unchanged.) If DL_FUNCS is not specified, it defaults to the bootstrap function for the extension specified in NAME. DL_VARS This is identical to the DL_VARS attribute available via MakeMaker, and, like DL_FUNCS, it is usually specified via MakeMaker. Its value is a reference to an array of variable names which should be exported by the extension. FILE This key can be used to specify the name of the linker option file (minus the OS-specific extension), if for some reason you do not want to use the default value, which is the last word of the NAME attribute (*e.g.* for `Tk::Canvas', FILE defaults to Canvas). FUNCLIST This provides an alternate means to specify function names to be exported from the extension. Its value is a reference to an array of function names to be exported by the extension. These names are passed through unaltered to the linker options file. Specifying a value for the FUNCLIST attribute suppresses automatic generation of the bootstrap function for the package. To still create the bootstrap name you have to specify the package name in the DL_FUNCS hash: Mksymlists({ NAME => $name , FUNCLIST => [ $func1, $func2 ], DL_FUNCS => { $pkg => [] } }); IMPORTS This attribute is used to specify names to be imported into the extension. It is currently only used by OS/2 and Win32. NAME This gives the name of the extension (*e.g.* `Tk::Canvas') for which the linker option file will be produced. When calling `Mksymlists', one should always specify the NAME attribute. In most cases, this is all that's necessary. In the case of unusual extensions, however, the other attributes can be used to provide additional information to the linker. AUTHOR ====== Charles Bailey ** REVISION ======== Last revised 14-Feb-1996, for Perl 5.002.  File: pm.info, Node: ExtUtils/Packlist, Next: ExtUtils/PerlPP, Prev: ExtUtils/Mksymlists, Up: Module List manage .packlist files ********************** NAME ==== ExtUtils::Packlist - manage .packlist files SYNOPSIS ======== use ExtUtils::Packlist; my ($pl) = ExtUtils::Packlist->new('.packlist'); $pl->read('/an/old/.packlist'); my @missing_files = $pl->validate(); $pl->write('/a/new/.packlist'); $pl->{'/some/file/name'}++; or $pl->{'/some/other/file/name'} = { type => 'file', from => '/some/file' }; DESCRIPTION =========== ExtUtils::Packlist provides a standard way to manage .packlist files. Functions are provided to read and write .packlist files. The original .packlist format is a simple list of absolute pathnames, one per line. In addition, this package supports an extended format, where as well as a filename each line may contain a list of attributes in the form of a space separated list of key=value pairs. This is used by the installperl script to differentiate between files and links, for example. USAGE ===== The hash reference returned by the new() function can be used to examine and modify the contents of the .packlist. Items may be added/deleted from the .packlist by modifying the hash. If the value associated with a hash key is a scalar, the entry written to the .packlist by any subsequent write() will be a simple filename. If the value is a hash, the entry written will be the filename followed by the key=value pairs from the hash. Reading back the .packlist will recreate the original entries. FUNCTIONS ========= new() This takes an optional parameter, the name of a .packlist. If the file exists, it will be opened and the contents of the file will be read. The new() method returns a reference to a hash. This hash holds an entry for each line in the .packlist. In the case of old-style .packlists, the value associated with each key is undef. In the case of new-style .packlists, the value associated with each key is a hash containing the key=value pairs following the filename in the .packlist. read() This takes an optional parameter, the name of the .packlist to be read. If no file is specified, the .packlist specified to new() will be read. If the .packlist does not exist, Carp::croak will be called. write() This takes an optional parameter, the name of the .packlist to be written. If no file is specified, the .packlist specified to new() will be overwritten. validate() This checks that every file listed in the .packlist actually exists. If an argument which evaluates to true is given, any missing files will be removed from the internal hash. The return value is a list of the missing files, which will be empty if they all exist. packlist_file() This returns the name of the associated .packlist file EXAMPLE ======= Here's `modrm', a little utility to cleanly remove an installed module. #!/usr/local/bin/perl -w use strict; use IO::Dir; use ExtUtils::Packlist; use ExtUtils::Installed; sub emptydir($) { my ($dir) = @_; my $dh = IO::Dir->new($dir) || return(0); my @count = $dh->read(); $dh->close(); return(@count == 2 ? 1 : 0); } # Find all the installed packages print("Finding all installed modules...\n"); my $installed = ExtUtils::Installed->new(); foreach my $module (grep(!/^Perl$/, $installed->modules())) { my $version = $installed->version($module) || "???"; print("Found module $module Version $version\n"); print("Do you want to delete $module? [n] "); my $r = ; chomp($r); if ($r && $r =~ /^y/i) { # Remove all the files foreach my $file (sort($installed->files($module))) { print("rm $file\n"); unlink($file); } my $pf = $installed->packlist($module)->packlist_file(); print("rm $pf\n"); unlink($pf); foreach my $dir (sort($installed->directory_tree($module))) { if (emptydir($dir)) { print("rmdir $dir\n"); rmdir($dir); } } } } AUTHOR ====== Alan Burlison  File: pm.info, Node: ExtUtils/PerlPP, Next: ExtUtils/TBone, Prev: ExtUtils/Packlist, Up: Module List A Perl Preprocessor ******************* NAME ==== ExtUtils::PerlPP - A Perl Preprocessor SYNOPSIS ======== use ExtUtils::PerlPP; my $config = { 'version' => $VERSION, 'driver' => $DRIVER }; # The long and winding road ... my $self = ExtUtils::PerlPP->new(); $self->{'in_fh'} = IO::File->new('file.PL', 'r'); $self->{'out_fh'} = IO::File->new('file', 'w'); $self->{'config'} = $self->parse(); # And now a short cut for the same: ppp('file.PL', 'file', $config); DESCRIPTION =========== Perl's installation suite, ExtUtils::MakeMaker, contains a mechanism for installing preparsed files, so-called *PL* files: If the MakeMaker utility detects files with the extension `.PL' then these files are executed by make, usually creating a file of the same name, except the `.PL' extension. Writing these PL files is usually always the same, for example a typical `.PL' file might look like this: my $script = <<'SCRIPT'; ... # True file following here SCRIPT # Modify variable $script, depending on configuration, local # site or whatever ... if (!open(FILE, ">file") || !(print FILE $script) || !close(FILE)) { die "Cannot write file: $!"; } But in essence, what else is this than a Perl preprocessor? Traditionally you have to write such a Perl preprocessor for yourself all the time, although I have found that they always do the same, for example: - Fix defaults, for example installation paths. - Including or excluding code sections. It is a matter of taste whether one likes to see if ($] < 5.003) { # Thirty lines of code following here ... } else { # A single line of code ... } when already using Perl 5.005. I don't. This module is dedicated to simplify such tasks. In short, you can use it like this: Create a new preprocessor ------------------------- You start with creating an instance of *ExtUtils::PerlPP* by calling the new constructor: my $ppp = ExtUtils::PerlPP->new(%attr); The constructor accepts a list of attributes, including the following: in_fh The input file, any kind of IO object, for example an instance of IO::File or IO::Scalar. More general: It can be any object that offers a getline method. A scalar value (to be distinguished from an IO::Scalar instance!) will be interpreted as a file name that the method opens for you. out_fh The output file; another IO object or any other object that offers a print method. A scalar value is accepted as output file name. config A hash ref of preprocessor variables. In other words $ppp->{'config'}->{'var'} = 1; is what `-Dvar=val' is for the C preprocessor. Similarly you can compare delete $ppp->{'config'}; with `-Uvar'. See `"Macro replacements"' in this node below. Unlike C, variables may be arbitrarily complex, in particular you can use hash or array refs as values. Surprisingly you may pass a scalar value again: In that case the file of the same name evaluated and the result is used as a configuration hash. In other words $ppp->{'config'} = "myapp.cfg"; is similar to $ppp->{'config'} = do "myapp.cfg"; Such config files can easily be created using the Data::Dumper module. `Data::Dumper(3)' in this node. no_config_default If a variable name is used, but no such attribute is present in the config hash, then by default the variable is looked up in the `$Config' from the Config module. This behaviour is suppressed, if you set no_config_default to a TRUE value. `Config(3)' in this node. no_makedirs By default directories are created silently if required. For example, if you pass a value of `/usr/local/foo/bar' as output file and only `/usr/local' exists, then the subdirectory foo will be created. The option no_makedirs suppresses this behaviour. Running the preprocessor ------------------------ This is done by executing $ppp->parse(); A Perl exception will be thrown in case of errors, thus the complete use might look like this: eval { $ppp->parse(); }; if ($@) { print "An error occurred: $@\n" } Using the frontend ------------------ Most applications won't call the new or parse methods directly, but rather do a use ExtUtils::PerlPP; ppp('infile', 'outfile', 'configfile'); This is equivalent to my $parser = ExtUtils::PerlPP->new('in_fh' => 'infile', 'out_fh' => 'outfile', 'config' => 'configfile'); $parser->parse(); In order to be easily used within Makefiles, the ppp frontend can read from @ARGV. That is, you can use the module like this: perl -MExtUtils::PerlPP -e ppp from the commandline. Macro replacements ------------------ The primary use of preprocessor variables (aka attributes of `$ppp-'{'config'}>) is replacing patterns in the stream written to the output file. With `$c = $ppp-'{'config'}> in mind the typical patterns and their replacements are: ~~a~~ $c->{'a'} ~~b~~ $c->{'b'} ~~a->b~~ $c->{'a'}->{'b'} ~~a->e~~ $c->{'a'}->{'e'} ~~a->1~~ $c->{'a'}->[1] ~~a->1->b~~ $c->{'a'}->[1]->{'b'} I hope the idea is obvious. Real world examples might be: my $config_file = "~~etc_dir~~/configuration"; my $VERSION = "~~version~~"; Preprocessor variables need not be scalar values: If a variable contains a code ref, then the module will execute &$var($ppp, $text); and replace the pattern with the result. $text is the pattern being replaced, for example, if `$ppp-'{'config'}->{'bar'}> has the value `\&foo', then `~~bar~~' will be replaced with the result of foo($ppp, "bar"); Arguments are not yet supported. Creating macros --------------- When talking about code refs, we need a possibility to create them. The best possibility is creating them within the input file, as in ~&foo&~ my($self, $text) = @_; $text x 2; ~&&~ This example is mainly equivalent to $ppp->{'config'}->{'foo'} = sub { my($self, $text) = @_; $text x 2; }; The `~&var&~' definition must start at the beginning of a line, much like the C preprocessor. The end pattern ~&&~ may appear at any point, but the remaining line will be ignored. Conditional output ------------------ The next application of a preprocessor is conditional output, as in an #ifdef var ... #endif segment. This can be done with ~#if#~ ... ~#elsif#~ ... ~#else#~ ... ~#endif#~ `' is handled as follows: First it is subject to the usual pattern replacements and then it is evaluated as a Perl expression returning a TRUE or FALSE value. Examples: ~#if#~ "~~a~~" is TRUE, if and only if $ppp->{'config'}->{'a'} is TRUE. Currently conditionals must start at the beginning of a line and expressions must not exceed a single line. Nesting conditions is possible. Embedding into MakeMaker ------------------------ For using the preprocessor from within MakeMaker, I propose the following: First of all you create a config file from within Makefile.PL. For example the *libnet* suite creates a file `libnet.cfg' and the *SNMP::Monitor* and *Cisco::Conf* modules create a file `configuration'. The Data::Dumper module will aid you in that task. `Data::Dumper(3)' in this node. Then you add the following to your Makefile.PL, I assume the name `myapp.cnf' for the config file: package MY; sub processPL { my($self) = shift; return "" unless $self->{PL_FILES}; my(@m, $from, $to); foreach $from (sort keys %{$self->{PL_FILES}}) { $to = $self->{PL_FILES}->{$from}; push @m, " all :: $self->{PL_FILES}->{$plfile} $self->{NOECHO}\$(NOOP) $self->{PL_FILES}->{$plfile} :: $plfile \$(PERL) -I\$(INST_ARCHLIB) -I\$(INST_LIB) \ -I\$(PERL_ARCHLIB) -I\$(PERL_LIB) \ -MExtUtils::PerlPP -e 'ppp($from, $to, \"myapp.cnf\")' "; } join "", @m; } Next you create your template files under their usual names, but add an extension `.PL'. The MakeMaker utility will automatically detect these files for you and add appropriate rules to the Makefile it generates. AUTHOR AND COPYRIGHT ==================== This module is Copyright (C) 1998 by Jochen Wiedmann Am Eisteich 9 72555 Metzingen Germany Email: joe@ispsoft.de Phone: +49 7123 14887 All rights reserved. You may distribute this module under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file. SEE ALSO ======== `ExtUtils::MakeMaker(3)' in this node, `Data::Dumper(3)' in this node  File: pm.info, Node: ExtUtils/TBone, Next: ExtUtils/testlib, Prev: ExtUtils/PerlPP, Up: Module List a "skeleton" for writing "t/*.t" test files. ******************************************** NAME ==== ExtUtils::TBone - a "skeleton" for writing "t/*.t" test files. SYNOPSIS ======== Include a copy of this module in your t directory (as t/ExtUtils/TBone.pm), and then write your t/*.t files like this: use lib "./t"; # to pick up a ExtUtils::TBone use ExtUtils::TBone; # Make a tester... here are 3 different alternatives: my $T = typical ExtUtils::TBone; # standard log my $T = new ExtUtils::TBone; # no log my $T = new ExtUtils::TBone "testout/Foo.tlog"; # explicit log # Begin testing, and expect 3 tests in all: $T->begin(3); # expect 3 tests $T->msg("Something for the log file"); # message for the log # Run some tests: $T->ok($this); # test 1: no real info logged $T->ok($that, # test 2: logs a comment "Is that ok, or isn't it?"); $T->ok(($this eq $that), # test 3: logs comment + vars "Do they match?", This => $this, That => $that); # That last one could have also been written... $T->ok_eq($this, $that); # does 'eq' and logs operands $T->ok_eqnum($this, $that); # does '==' and logs operands # End testing: $T->end; DESCRIPTION =========== This module is intended for folks who release CPAN modules with "t/*.t" tests. It makes it easy for you to output syntactically correct test-output while at the same time logging all test activity to a log file. Hopefully, bug reports which include the contents of this file will be easier for you to investigate. LOG FILE ======== A typical log file output by this module looks like this: 1..3 ** A message logged with msg(). ** Another one. 1: My first test, using test(): how'd I do? 1: ok 1 ** Yet another message. 2: My second test, using test_eq()... 2: A: The first string 2: B: The second string 2: not ok 2 3: My third test. 3: ok 3 END Each test() is logged with the test name and results, and the test-number prefixes each line. This allows you to scan a large file easily with "grep" (or, ahem, "perl"). A blank line follows each test's record, for clarity. PUBLIC INTERFACE ================ Construction ------------ new [ARGS...] *Class method, constructor.* Create a new tester. Any arguments are sent to log_open(). typical *Class method, constructor.* Create a typical tester. Use this instead of new() for most applicaitons. The directory "testout" is created for you automatically, to hold the output log file. Doing tests ----------- begin NUMTESTS *Instance method.* Start testing. end *Instance method.* End testing. ok BOOL, [TESTNAME], [PARAMHASH...] *Instance method.* Do a test, and log some information connected with it. Use it like this: $T->ok(-e $dotforward); Or better yet, like this: $T->ok((-e $dotforward), "Does the user have a .forward file?"); Or even better, like this: $T->ok((-e $dotforward), "Does the user have a .forward file?", User => $ENV{USER}, Path => $dotforward, Fwd => $ENV{FWD}); That last one, if it were test #3, would be logged as: 3: Does the user have a .forward file? 3: User: "alice" 3: Path: "/home/alice/.forward" 3: Fwd: undef 3: ok You get the idea. Note that defined quantities are logged with delimiters and with all nongraphical characters suitably escaped, so you can see evidence of unexpected whitespace and other badnasties. Had "Fwd" been the string "this\nand\nthat", you'd have seen: 3: Fwd: "this\nand\nthat" And unblessed array refs like ["this", "and", "that"] are treated as multiple values: 3: Fwd: "this" 3: Fwd: "and" 3: Fwd: "that" ok_eq ASTRING, BSTRING, [TESTNAME], [PARAMHASH...] *Instance method.* Convenience front end to ok(): test whether `ASTRING eq BSTRING', and logs the operands as 'A' and 'B'. ok_eqnum ANUM, BNUM, [TESTNAME], [PARAMHASH...] *Instance method.* Convenience front end to ok(): test whether `ANUM == BNUM', and logs the operands as 'A' and 'B'. Logging messages ---------------- log_open PATH *Instance method.* Open a log file for messages to be output to. This is invoked for you automatically by `new(PATH)' and `typical()'. log_close *Instance method.* Close the log file and stop logging. You shouldn't need to invoke this directly; the destructor does it. log MESSAGE... *Instance method.* Log a message to the log file. No alterations are made on the text of the message. See msg() for an alternative. msg MESSAGE... *Instance method.* Log a message to the log file. Lines are prefixed with "** " for clarity, and a terminating newline is forced. Utilities --------- catdir DIR, ..., DIR *Class/instance method.* Concatenate several directories into a path ending in a directory. Lightweight version of the one in the (very new) File::Spec. Paths are assumed to be absolute. To signify a relative path, the first DIR must be ".", which is processed specially. On Mac, the path *does* end in a ':'. On Unix, the path *does not* end in a '/'. catfile DIR, ..., DIR, FILE *Class/instance method.* Like catdir(), but last element is assumed to be a file. Note that, at a minimum, you must supply at least a single DIR. CHANGE LOG ========== *Current version:* $Id: TBone.pm,v 1.117 2000/08/16 05:08:09 eryq Exp $ Version 1.116 Cosmetic improvements only. Version 1.112 Added lightweight catdir() and catfile() (a la File::Spec) to enhance portability to Mac environment. Version 1.111 Now uses File::Basename to create "typical" logfile name, for portability. Version 1.110 Fixed bug in constructor that surfaced if no log was being used. Created: Friday-the-13th of February, 1998. AUTHOR ====== Eryq (`eryq@zeegee.com'). President, ZeeGee Software Inc. (`http://www.zeegee.com')  File: pm.info, Node: ExtUtils/testlib, Next: FAQ/OMatic/API, Prev: ExtUtils/TBone, Up: Module List add blib/* directories to @INC ****************************** NAME ==== ExtUtils::testlib - add blib/* directories to @INC SYNOPSIS ======== `use ExtUtils::testlib;' DESCRIPTION =========== After an extension has been built and before it is installed it may be desirable to test it bypassing make test. By adding use ExtUtils::testlib; to a test program the intermediate directories used by make are added to @INC.  File: pm.info, Node: FAQ/OMatic/API, Next: FCGI, Prev: ExtUtils/testlib, Up: Module List a Perl API to manipulate FAQ-O-Matics ************************************* NAME ==== FAQ::OMatic::API - a Perl API to manipulate FAQ-O-Matics SYNOPSIS ======== use FAQ::OMatic::API; my $fom_api = new FAQ::OMatic::API(); DESCRIPTION =========== `FAQ::OMatic::API' is a class that makes HTTP requests to a FAQ-O-Matic. It provides a way to manipulate a FAQ-O-Matic from Perl code. Operations are performed by making HTTP requests on the FAQ-O-Matic server; this ensures that any operation is performed in exactly the same environment as it would be if it were requested by a human using a web browser. Setup ===== The following methods are used to set up an API object. $fom_api = new FAQ::OMatic::API([$url, [$id, $pass]]); Constructs a new `FAQ::OMatic::API' object that points at the FAQ whose CGI is at `$url'. Requests will be authenticated on behalf of FAQ user $id using password `$pass'. $fom_api->setURL($url); Sets the URL of the target FAQ's CGI. This is where requests will be sent. $fom_api->setAuth($id, $pass); Sets the ID and password that will be used to authenticate requests. $fom_api->setAuth('query'); Passing in 'query' will cause the script to query the terminal for the id and password at runtime. Queries ======= The following methods retrieve information about a FAQ-O-Matic. $fom_api->getCategories() Returns a list of the categories (by file name) in the FAQ. $item = $fom_api->getItem($filename) Returns a local FAQ::OMatic::Item object created by retrieving $filename from the FAQ. You can perform operations on the result such as: print $item->getTitle(); $parentItem = $item->getParent(); print $item->displayHTML({'render'=>'text'}); my ($rc, $result) = $fom_api->fuzzyMatch(['Parent Category','child cat']) my ($rc, $result) = $fom_api->fuzzyMatch(['Parent Category','child cat']) die $result if (not $rc); my $item = $fom_api->getItem($result->[0]); `fuzzyMatch()' attempts to figure out which category the last string in its array argument represents. The category name is matched "fuzzily" against existing categories. If a unique match is found, it is returned (as an array ref `[$filename, $parent, $title]'). If the match is ambiguous, the previous array element is matched against the parents of the set of fuzzy matches. This is performed recursively until the child category is disambiguated. Fuzzy matching means that (a) You don't have to get the parent category names right if they're not needed to disambiguate the child category. (b) Category names are matched without respect to case, spacing, or punctuation: only alphanumerics matter. Also, the name you supply only has to appear somewhere inside the one you want to match. (Exact matches are preferred; this allows you to match categories whose names are prefixes of other category names.) Operations ========== The following methods perform operations on a FAQ-O-Matic. $fom_api->newAnswer($parent, $title, $text) A new answer is created as a child of item `$parent'. The new answer has title `$title' and a single text part containing $text. REQUIRES ======== *Note LWP: LWP, and its hierarchy of helper classes.  File: pm.info, Node: FCGI, Next: FCGI/ProcManager, Prev: FAQ/OMatic/API, Up: Module List Fast CGI module *************** NAME ==== FCGI - Fast CGI module SYNOPSIS ======== use FCGI; my $count = 0; my $request = FCGI::Request(); while($request->Accept() >= 0) { print("Content-type: text/html\r\n\r\n", ++$count); } DESCRIPTION =========== Functions: FCGI::Request Creates a request handle. It has the following optional parameters: input perl file handle (default: \*STDIN) output perl file handle (default: \*STDOUT) error perl file handle (default: \*STDERR) These filehandles will be setup to act as input/output/error on succesful Accept. environment hash reference (default: \%ENV) The hash will be populated with the environment. socket (default: 0) Socket to communicate with the server. Can be the result of the OpenSocket function. For the moment, it's the file descriptor of the socket that should be passed. This may change in the future. flags (default: 0) Possible values: FCGI::FAIL_ACCEPT_ON_INTR If set, Accept will fail if interrupted. It not set, it will just keep on waiting. Example usage: my $req = FCGI::Request; or: my %env; my $in = new IO::Handle; my $out = new IO::Handle; my $err = new IO::Handle; my $req = FCGI::Request($in, $out, $err, \%env); FCGI::OpenSocket(path, backlog) Creates a socket suitable to use as an argument to Request. path Pathname of socket or colon followed by local tcp port. backlog Maximum length of the queue of pending connections. If a connection request arrives with the queue full the client may receive an error with an indication of ECONNREFUSED. FCGI::CloseSocket(socket) Close a socket opened with OpenSocket. $req->Accept() Accepts a connection on $req, attaching the filehandles and populating the environment hash. Returns 0 on success. If a connection has been accepted before, the old one will be finished first. Note that unlike with the old interface, no die and warn handlers are installed by default. This means that if you are not running an sfio enabled perl, any warn or die message will not end up in the server's log by default. It is advised you set up die and warn handlers yourself. FCGI.pm contains an example of die and warn handlers. $req->Finish() Finishes accepted connection. Also detaches filehandles. $req->Flush() Flushes accepted connection. $req->Detach() Temporarily detaches filehandles on an accepted connection. $req->Attach() Re-attaches filehandles on an accepted connection. $env = $req->GetEnvironment() Returns the environment parameter passed to FCGI::Request. ($in, $out, $err) = $req->GetHandles() Returns the file handle parameters passed to FCGI::Request. $isfcgi = $req->IsFastCGI() Returns whether or not the program was run as a FastCGI. AUTHOR ====== Sven Verdoolaege  File: pm.info, Node: FCGI/ProcManager, Next: FFI, Prev: FCGI, Up: Module List functions for managing FastCGI applications. ******************************************** NAME ==== FCGI::ProcManager - functions for managing FastCGI applications. SYNOPSIS ======== { # In Object-oriented style. use CGI::Fast; use FCGI::ProcManager; my $proc_manager = FCGI::ProcManager->new({ n_processes => 10 }); $proc_manager->pm_manage(); while (my $cgi = CGI::Fast->new()) { $proc_manager->pm_pre_dispatch(); # ... handle the request here ... $proc_manager->pm_post_dispatch(); } # This style is also supported: use CGI::Fast; use FCGI::ProcManager qw(pm_manage pm_pre_dispatch pm_post_dispatch); pm_manage( n_processes => 10 ); while (my $cgi = CGI::Fast->new()) { pm_pre_dispatch(); #... pm_post_dispatch(); } DESCRIPTION =========== FCGI::ProcManager is used to serve as a FastCGI process manager. By re-implementing it in perl, developers can more finely tune performance in their web applications, and can take advantage of copy-on-write semantics prevalent in UNIX kernel process management. The process manager should be invoked before the caller"s request loop The primary routine, pm_manage, enters a loop in which it maintains a number of FastCGI servers (via fork(2)), and which reaps those servers when they die (via wait(2)). pm_manage provides too hooks: C - called just before the manager enters the manager loop. C - called just before a server is returns from C It is necessary for the caller, when implementing its request loop, to insert a call to pm_pre_dispatch at the top of the loop, and then 7pm_post_dispatch at the end of the loop. METHODS ======= new --- class or instance (ProcManager) new([hash parameters]) Constructs a new process manager. Takes an option has of initial parameter values, and assigns these to the constructed object HASH, overriding any default values. The default parameter values currently are: role => manager start_delay => 0 die_timeout => 60 Manager methods =============== pm_manage --------- instance or export (int) pm_manage([hash parameters]) DESCRIPTION: When this is called by a FastCGI script to manage application servers. It defines a sequence of instructions for a process to enter this method and begin forking off and managing those handlers, and it defines a sequence of instructions to intialize those handlers. If n_processes < 1, the managing section is subverted, and only the handling sequence is executed. Either returns the return value of pm_die() and/or pm_abort() (which will not ever return in general), or returns 1 to the calling script to begin handling requests. managing_init ------------- instance () managing_init() DESCRIPTION: Overrideable method which initializes a process manager. In order to handle signals, manage the PID file, and change the process name properly, any method which overrides this should call SUPER::managing_init(). pm_die ------ instance or export () pm_die(string msg[, int exit_status]) DESCRIPTION: This method is called when a process manager receives a notification to shut itself down. pm_die() attempts to shutdown the process manager gently, sending a SIGTERM to each managed process, waiting die_timeout() seconds to reap each process, and then exit gracefully once all children are reaped, or to abort if all children are not reaped. pm_wait ------- instance or export (int pid) pm_wait() DESCRIPTION: This calls wait() which suspends execution until a child has exited. If the process ID returned by wait corresponds to a managed process, pm_notify() is called with the exit status of that process. pm_wait() returns with the return value of wait(). pm_write_pid_file ----------------- instance or export () pm_write_pid_file([string filename]) DESCRIPTION: Writes current process ID to optionally specified file. If no filename is specified, it uses the value of the pid_fname parameter. pm_remove_pid_file ------------------ instance or export () pm_remove_pid_file() DESCRIPTION: Removes optionally specified file. If no filename is specified, it uses the value of the pid_fname parameter. sig_manager ----------- instance () sig_manager(string name) DESCRIPTION: Handles signals of the process manager. Takes as input the name of signal being handled. Handler methods =============== handling_init ------------- instance or export () handling_init() DESCRIPTION: pm_pre_dispatch --------------- instance or export () pm_pre_dispatch() DESCRIPTION: pm_post_dispatch ---------------- instance or export () pm_post_dispatch() DESCRIPTION: sig_handler ----------- instance or export () sig_handler() DESCRIPTION: Common methods and routines =========================== self_or_default --------------- private global (ProcManager, @args) self_or_default([ ProcManager, ] @args); DESCRIPTION: This is a helper subroutine to acquire or otherwise create a singleton default object if one is not passed in, e.g., a method call. pm_change_process_name ---------------------- instance or export () pm_change_process_name() DESCRIPTION: pm_received_signal ------------------ instance or export () pm_received signal() DESCRIPTION: parameters ========== pm_parameter ------------ instance or export () pm_parameter() DESCRIPTION: n_processes ----------- no_signals ---------- pid_fname --------- die_timeout ----------- role ---- start_delay ----------- DESCRIPTION: notification and death ====================== pm_warn ------- instance or export () pm_warn() DESCRIPTION: pm_notify --------- instance or export () pm_notify() DESCRIPTION: pm_exit ------- instance or export () pm_exit(string msg[, int exit_status]) DESCRIPTION: pm_abort -------- instance or export () pm_abort(string msg[, int exit_status]) DESCRIPTION: BUGS ==== No known bugs, but this does not mean no bugs exist. SEE ALSO ======== *Note FCGI: FCGI,. COPYRIGHT ========= FCGI-ProcManager - A Perl FCGI Process Manager Copyright (c) 2000, FundsXpress Financial Network, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. BECAUSE THIS LIBRARY IS LICENSED FREE OF CHARGE, THIS LIBRARY IS BEING PROVIDED "AS IS WITH ALL FAULTS," WITHOUT ANY WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF TITLE, NONINFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND THE ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS WITH THE YOU. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA  File: pm.info, Node: FFI, Next: FFI/Library, Prev: FCGI/ProcManager, Up: Module List Perl Foreign Function Interface ******************************* NAME ==== FFI - Perl Foreign Function Interface SYNOPSIS ======== use FFI; $addr =
$signature = $ret = FFI::call($addr, $signature, ...); $cb = FFI::callback($signature, sub {...}); $ret = FFI::call($addr, $signature, $cb->addr, ...); DESCRIPTION =========== This module provides a low-level foreign function interface to Perl. It allows the calling of any function for which the user can supply an address and calling signature. Furthermore, it provides a method of encapsulating Perl subroutines as callback functions whose addresses can be passed to C code. FUNCTION SIGNATURES =================== Function interfaces are defined by signatures. A function's signature is a string which specifies the function's return type, argument types and calling convention. The first character of the string is the function's calling convention. This is one of s The standard calling convention for dynamically linked functions c The calling convention used by C functions Note that on many platforms, these two calling conventions may be identical. On the Windows platform, the s code corresponds to the `stdcall' calling convention, which is used for most dynamic link libraries. The c code corresponds to the `cdecl' calling convention, which is used for C functions, such as those in the C runtime library. The remaining characters of the string are the return type of the function, followed by the argument types, in left-to-right order. Valid values are based on the codes used for the `pack' in this node function, namely c A signed char value. C An unsigned char value. s A signed short value. S An unsigned short value. i A signed integer value. I An unsigned integer value. l A signed long value. L An unsigned long value. f A single-precision float. d A double-precision float. p A pointer. v No value (only valid as a return type). Note that all of the above codes refer to "native" format values. The p code as an argument type simply passes the address of the Perl value's memory to the foreign function. It is the caller's responsibility to be sure that the called function does not overwrite memory outside that allocated by Perl. The p code as a return type treats the returned value as a null-terminated string, and passes it back to Perl as such. There is currently no support for functions which return pointers to structures, or to other blocks of memory which do not contain strings, nor for functions which return memory which the caller must free. To pass pointers to strings, use the p code. Perl ensures that strings are null-terminated for you. To pass pointers to structures, use `pack' in this node. To pass an arbitrary block of memory, use something like the following: $buf = ' ' x 100; # Use $buf via a 'p' parameter as a 100-byte memory block At the present time, there is no direct support for passing pointers to 'native' types (like int). To work around this, use `$buf = pack('i', 12);' to put an integer into a block of memory, then use the p pointer type, and obtain any returned value using `$n = unpack('i', $buf);' In the future, better support may be added (but remember that this is intended as a low-level interface!) EXAMPLES ======== It is somewhat difficult to provide examples of using this module in isolation, as it is necessary to (somehow) obtain the address of a function to call. In general, this task is delegated to higher-level wrapper modules. However, the standard DynaLoader module returns symbol references via the `DynaLoader::dl_find_symbol()' function. While these references are not documented as being addresses, in practice, they seem to be. Code to obtain the address of various C library functions can be built around this $clib_file = ($^O eq "MSWin32") ? "MSVCRT40.DLL" : "-lc"; $clib = DynaLoader::dl_findfile($clib_file); $strlen = DynaLoader::dl_find_symbol($clib, "strlen"); $n = FFI::call($strlen, "cIp", $my_string); DynaLoader::dl_free_file($clib); Clearly, code like this needs to be encapsulated in a module of some form... NOTE: In fact, the DynaLoader interface has problems in ActiveState Perl, and probably in other binary distributions of Perl. (The issue is related to the way in which the DynaLoader module is built, and may be addressed in future versions of Perl). In the interim, the higher-level wrapper module FFI::Library does not use DynaLoader on Win32 - it uses the (deprecated, but still available) Win32::LoadLibrary and related calls. TODO ==== * Improve support for returning pointers to things other than null-terminated strings. * Possibly, improve support for passing pointers to "native" types. LICENSE ======= Substantial portions of the code for this module (the underlying FFI code) are licensed under the Gnu General Public License. Under the terms of that license, my understanding is that this module has to be distrubuted under that same license. My personal preference would be to distribute this module under the same terms as Perl. However, I understand that this is not possible, given the licensing of the FFI code. AUTHOR ====== Paul Moore, gustav@morpheus.demon.co.uk SEE ALSO ======== http://clisp.cons.org/~haible/clisp.html Bruno Haible's CLisp Common Lisp implementation, from which the underlying foreign function interface code was taken.  File: pm.info, Node: FFI/Library, Next: FakeHash, Prev: FFI, Up: Module List Perl Access to Dynamically Loaded Libraries ******************************************* NAME ==== FFI::Library - Perl Access to Dynamically Loaded Libraries SYNOPSIS ======== use FFI::Library; $lib = FFI::Library->new("mylib"); $fn = $lib->function("fn", "signature"); $ret = $fn->(...); DESCRIPTION =========== This module provides access from Perl to functions exported from dynamically linked libraries. Functions are described by signatures, for details of which see the *Note FFI: FFI, module's documentation. EXAMPLES ======== $clib_file = ($^O eq "MSWin32") ? "MSVCRT40.DLL" : "-lc"; $clib = FFI::Library->new($clib_file); $strlen = $clib->function("strlen", "cIp"); $n = $strlen->($my_string); TODO ==== LICENSE ======= This module can be distributed under the same terms as Perl. However, as it depends on the *Note FFI: FFI, module, please note the licensing terms for the FFI code. AUTHOR ====== Paul Moore, gustav@morpheus.demon.co.uk SEE ALSO ======== The *Note FFI: FFI, module.  File: pm.info, Node: FakeHash, Next: Fame, Prev: FFI/Library, Up: Module List Simulate the behavior of a Perl hash variable ********************************************* NAME ==== FakeHash - Simulate the behavior of a Perl hash variable SYNOPSIS ======== use FakeHash; my $hash = FakeHash->new; $hash->store($key, $value); # analogous to $h{$key} = $value @keys = $hash->keys; # analogous to @keys = keys %h $hash->delete($key); # analogous to delete $h{$key} $value = $hash->fetch($key); # analogous to $value = $h{$key} $string = $hash->scalarval; # analogous to $string = %h $string = $hash->clear; # analogous to %h = () $hash->iterate(...); # Invoke callbacks for each bucket and node # Caution: Not tested my $hash = tie %h => FakeHash; # $hash will mirror the changes to %h use FakeHash 'hashval'; $n = hashval($string); # hash value for string FakeHash->version(5.005); # Use Perl 5.005 hashval function $version = FakeHash->version; # Return Perl version currently in force DESCRIPTION =========== `FakeHash' simulates the behavior of a Perl hash variable, maintaining a synthetic data structure that mirrors the true data structure inside of Perl. This can be used to investigate hash performance or behavior. For example, see the `FakeHash::DrawHash' class, described below, which draws a box-and-arrow diagram representing the memory layout of a hash. The store, fetch, keys, and delete methods perform the corresponding operations on the simulated hash. The iterate method iterates over the simulated structure and invokes user-supplied callbacks. The arguments to iterate are a hash of actions, and an optional *user parameter*. The actions hash may have any or all of the following keys: prebucket A function that is called once for each bucket in the hash, prior to iterating over the nodes in the bucket. The arguments to the prebucket function are: the bucket number; a `FakeHash::Node' object representing the first node in the bucket (or an undefined value of the bucket is empty,) and the user parameter. prebucket The same, except that the function is called after iterating over the nodes in the bucket. node A function that is called once for each node (key-value pair) in the hash. The node function is called for a node after the prebucket function and before the `postbucket' function is called for the node's bucket. The arguments to the node function are: The bucket number; a `FakeHash::Node' object representing the first node in the bucket; the node's number within the bucket (0 for the first node in the bucket); the node itself; and the user parameter. maxbucket If this is a number, say n, iterate will only iterate over the first n buckets, and will skip the later buckets and their contents. If this is a function, iterate will call it once, with the user paramater as its argument, and will expect it to return a number n to be used as above. If it is omitted, iterate will iterate over all buckets and their contents. For example, the keys method is implemented as a call to iterate, as follows: sub keys { my $self = shift; my @r; $self->iterate({node => sub { my ($i, $b, $n, $node) = @_; push @r, $node->key; }, }); @r; } Other Methods ------------- `FakeHash->DEBUG' will return the current setting of the DEBUG flag, and will change the value of the flag if given an argument. When the DEBUG flag is set to a true value, the module may emit diagnostic messages to `STDERR'. Each `FakeHash' object may carry auxiliary information. Auxiliary information is not used by `FakeHash' but may be used by subclasses. `$hash->set_defaults(key, value, key, value,...)' sets the specified auxiliariy data values for the `FakeHash' object. A hashref may be passed instead; its contents will be appended to the values already installed. To query the currently-set values, use `$hash->defaults(key, key, ...)', which will return a list of the corresponding values, or, in scalar context, a reference to an array of the corresponding values. `$hash->size' retrieves the number of buckets in the hash. The Perl hash function changed between versions 5.005 and 5.6, so the behavior of Perl hashes changed at the same time. By default, `FakeHash' will emulate the behavior of whatever version of Perl it is running under. To change this, use the version method. Its argument is the version of Perl that you would like to emulate. It returns the version number prior to setting. Draw a `pic' diagram of the internal structure of a hash ******************************************************** NAME ==== FakeHash::DrawHash - Draw a `pic' diagram of the internal structure of a hash SYNOPSIS ======== my $hash = FakeHash::DrawHash->new; # see L for more details $hash->draw($filehandle); # Print 'pic' commands to filehandle DESCRIPTION =========== `FakeHash::DrawHash' is a subclass of `FakeHash' that can draw a picture of the internal structure of a Perl hash variable. It emits code suitable for the Unix `pic' drawing program. `FakeHash::DrawHash' provides the following methods: draw ---- Emit `pic' code for a box-and-arrow diagram that represents the current state of the simulated hash. A filehandle argument may be provided to receive the output. If omitted, output goes to STDOUT. Additionally, a user parameter argument may be provided, which will be passed to the other `draw_*' methods. draw_param ---------- Set or retrieve various parameters dermining box size and layout. Takes a name and an optional value argument and returns the old value associated with the name. If the value is provided, sets the new value. Valid names are: BUCKET Determines the size of the boxes used to represent each hash bucket. The value should be a reference to an array of the height and width, in inches. Defaults to `[1, 0.55]', or one inch wide by 0.55 inches tall. BUCKETSPACE Amount of horizontal space,in inches, between the box that represents a bucket and the bixes that represent the bucket contents. If zero, the buckets will abut their contents. Defaults to 1/5 inch. KVP The size of the boxes used to represent each key-value node. The value should be a reference to an array of the height and width, in inches. Defaults to `[1, 0.5]', or one inch wide by half an inch tall. draw_start ---------- Called once, each time drawing commences. Arguments: The filehandle and user parameter, if any, that were passed to draw. draw_end -------- Called once, just at the end of each call to draw. Arguments: The filehandle and user parameter, if any, that were passed to draw. draw_bucket ----------- Called each time draw needs to draw a single bucket. Arguments: The filehandle that was passed to draw; the bucket number (starting from 0) of the current bucket; a boolean value which is true if and only if the bucket is nonempty; and the user parameter that was passed to draw. draw_node --------- Called each time draw needs to draw a single key-value node. Arguments: The filehandle that was passed to draw; the bucket number (starting from 0) of the bucket in which the current node resides; the number of the node in the current bucket (the first node is node zero); a `FakeHash::Node' object representing the node itself; and the user parameter that was passed to draw. IDEA ==== The theory here is that it should be easy to override these methods with corresponding methods that draw the diagram in PostScript or GD or whatever. If you do this, please send me the code so that I can distribute it. Class used internally by `FakeHash' to represent key-value pairs **************************************************************** NAME ==== FakeHash::Node - Class used internally by `FakeHash' to represent key-value pairs SYNOPSIS ======== $key = $node->key; $value = $node->value; $hash = $node->hash; $next = $node->next; DESCRIPTION =========== `FakeHash::Node' is used internally by `FakeHash' for various purposes. For example, the `FakeHash::iterate' function invokes a user-supplied callback for each key-value pair, passing it a series of `FakeHash::Node' objects that represent the key-value pairs. The key and value methods retrieve the key and value of a node. The hash method retrieves the key's hash value. `$node->next' method retrieves the node that follows $node in its bucket, or an undefined value if $node is last in its bucket. If any of these methods is passed an additional argument, it will set the corresponding value. It will return the old value in any case. AUTHOR ====== Mark-Jason Dominus (`mjd-perl-fakehash+@plover.com') COPYRIGHT ========= `FakeHash.pm' is a Perl module that simulates the behavior of a Perl hash variable. `FakeHash::DrawHash' renders a diagram of a simulated hash. Copyright (C) 200 Mark-Jason Dominus 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. 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 the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.