This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: PDL/PP/Dump, Next: PDL/PP/Signature, Prev: PDL/PP, Up: Module List dump pp_xxx calls to stdout *************************** NAME ==== PDL::PP::Dump - dump pp_xxx calls to stdout SYNOPSIS ======== perl -MPDL::PP::Dump Basic/Ops/ops.pd DESCRIPTION =========== The most basic PP script debugger thinkable. AUTHOR ====== Christian Soeller .  File: pm.info, Node: PDL/PP/Signature, Next: PDL/Philosophy, Prev: PDL/PP/Dump, Up: Module List Internal module to handle signatures ************************************ NAME ==== PDL::PP::Signature - Internal module to handle signatures DESCRIPTION =========== Internal module to handle signatures SYNOPSIS ======== use PDL::PP::Signature; AUTHOR ====== Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu) and by Christian Soeller (c.soeller@auckland.ac.nz). All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Philosophy, Next: PDL/Pod/Html, Prev: PDL/PP/Signature, Up: Module List what's behind PDL? ****************** NAME ==== PDL::Philosophy - what's behind PDL? DESCRIPTION =========== This is an attempt to summarize some of the common spirit between pdl developers in order to answer the question "Why PDL"? If you are a PDL developer and I haven't caught your favorite ideas about PDL, please let me know! An often-asked question is: Why not settle for some of the existing systems like Matlab or IDL or GnuPlot or whatever? Major ideas ----------- The first tenet of our philosophy is the "free software" idea: software being free has several advantages (less bugs because more people see the code, you can have the source and port it to your own working environment with you, ... and of course, that you don't need to pay anything). The second idea is a pet peeve of many: many languages like matlab are pretty well suited for their specific tasks but for a different application, you need to change to an entirely different tool and regear yourself mentally. Not to speak about doing an application that does two things at once... Because we use Perl, we have the power and ease of perl syntax, regular expressions, hash tables etc at our fingertips at all times. By extending an existing language, we start from a much healthier base than languages like matlab which have grown into existence from a very small functionality at first and expanded little by little, making things look badly planned. We stand by the Perl sayings: "simple things should be simple but complicated things should be possible" and "There is more than one way to do it" (TIMTOWTDI). The third idea is interoperability: we want to be able to use PDL to drive as many tools as possible, we can connect to OpenGL or Mesa for graphics or whatever. There isn't anything out there that's really satisfactory as a tool and can do everything we want easily. And be portable. The fourth idea is related to PDL::PP and is Tuomas's personal favorite: code should only specify as little as possible redundant info. If you find yourself writing very similar-looking code much of the time, all that code could probably be generated by a simple perl script. The PDL C preprocessor takes this to an extreme. Minor goals and purposes ------------------------ We want speed. Optimally, it should ultimately (e.g. with the Perl compiler) be possible to compile PDL::PP subs to C and obtain the top vectorized speeds on supercomputers. Also, we want to be able to calculate things at near top speed from inside perl, by using dataflow to avoid memory allocation and deallocation (the overhead should ultimately be only a little over one indirect function call plus couple of ifs per function in the pipe). We want handy syntax. Want to do something and cannot do it easily? Tell us about it... We want lots of goodies. A good mathematical library etc. AUTHOR ====== Copyright(C) 1997 Tuomas J. Lukka (lukka@fas.harvard.edu). Redistribution in the same form is allowed but reprinting requires a permission from the author.  File: pm.info, Node: PDL/Pod/Html, Next: PDL/Pod/Parser, Prev: PDL/Philosophy, Up: Module List module to convert pod files to HTML *********************************** NAME ==== PDL::Pod::Html - module to convert pod files to HTML SYNOPSIS ======== use PDL::Pod::Html; pod2html([options]); DESCRIPTION =========== Converts files from pod format (see *Note Perlpod: (perl.info)perlpod,) to HTML format. It can automatically generate indexes and cross-references, and it keeps a cache of things it knows how to cross-reference. ARGUMENTS ========= PDL::Pod::Html takes the following arguments: help --help Displays the usage message. htmlroot --htmlroot=name Sets the base URL for the HTML files. When cross-references are made, the HTML root is prepended to the URL. infile --infile=name Specify the pod file to convert. Input is taken from STDIN if no infile is specified. outfile --outfile=name Specify the HTML file to create. Output goes to STDOUT if no outfile is specified. podroot --podroot=name Specify the base directory for finding library pods. podpath --podpath=name:...:name Specify which subdirectories of the podroot contain pod files whose HTML converted forms can be linked-to in cross-references. libpods --libpods=name:...:name List of page names (eg, "perlfunc") which contain linkable =items. netscape --netscape Use Netscape HTML directives when applicable. nonetscape --nonetscape Do not use Netscape HTML directives (default). index --index Generate an index at the top of the HTML file (default behaviour). noindex --noindex Do not generate an index at the top of the HTML file. recurse --recurse Recurse into subdirectories specified in podpath (default behaviour). norecurse --norecurse Do not recurse into subdirectories specified in podpath. title --title=title Specify the title of the resulting HTML file. verbose --verbose Display progress messages. EXAMPLE ======= pod2html("pod2html", "--podpath=lib:ext:pod:vms", "--podroot=/usr/src/perl", "--htmlroot=/perl/nmanual", "--libpods=perlfunc:perlguts:perlvar:perlrun:perlop", "--recurse", "--infile=foo.pod", "--outfile=/perl/nmanual/foo.html"); AUTHOR ====== Tom Christiansen, . BUGS ==== Has trouble with etc in = commands. SEE ALSO ======== *Note Perlpod: (perl.info)perlpod, COPYRIGHT ========= This program is distributed under the Artistic License.  File: pm.info, Node: PDL/Pod/Parser, Next: PDL/Pod/Select, Prev: PDL/Pod/Html, Up: Module List base class for creating pod filters and translators *************************************************** NAME ==== PDL::Pod::Parser - base class for creating pod filters and translators SYNOPSIS ======== use PDL::Pod::Parser; package PDL::MyParser; @ISA = qw(PDL::Pod::Parser); sub new { ## constructor code ... } ## implementation of appropriate subclass methods ... package main; $parser = new PDL::MyParser; @ARGV = ('-') unless (@ARGV > 0); for (@ARGV) { $parser->parse_from_file($_); } DESCRIPTION =========== *PDL::Pod::Parser* is an abstract base class for implementing filters and/or translators to parse pod documentation into other formats. It handles most of the difficulty of parsing the pod sections in a file and leaves it to the subclasses to override various methods to provide the actual translation. The other thing that *PDL::Pod::Parser* provides is the ability to process only selected sections of pod documentation from the input. SECTION SPECIFICATIONS ---------------------- Certain methods and functions provided by *PDL::Pod::Parser* may be given one or more "section specifications" to restrict the text processed to only the desired set of sections and their corresponding subsections. A section specification is a string containing one or more Perl-style regular expressions separated by forward slashes ("/"). If you need to use a forward slash literally within a section title you can escape it with a backslash ("\/"). The formal syntax of a section specification is: *head1-title-regexp*/*head2-title-regexp*/... Any omitted or empty regular expressions will default to ".*". Please note that each regular expression given is implicitly anchored by adding "^" and "$" to the beginning and end. Also, if a given regular expression starts with a "!" character, then the expression is negated (so `!foo' would match anything except foo). Some example section specifications follow. Match the NAME and SYNOPSIS sections and all of their subsections: `NAME|SYNOPSIS' Match only the `Question' and `Answer' subsections of the DESCRIPTION section: `DESCRIPTION/Question|Answer' Match the Comments subsection of all sections: `/Comments' Match all subsections of DESCRIPTION except for Comments: `DESCRIPTION/!Comments' Match the DESCRIPTION section but do not match any of its subsections: `DESCRIPTION/!.+' Match all top level sections but none of their subsections: `/!.+' FUNCTIONS ========= *PDL::Pod::Parser* provides the following functions (please note that these are functions and not methods, they do not take an object reference as an implicit first parameter): version() --------- Return the current version of this package. INSTANCE METHODS ================ *PDL::Pod::Parser* provides several methods, some of which should be overridden by subclasses. They are as follows: new() ----- This is the the constructor for the base class. You should only use it if you want to create an instance of a *PDL::Pod::Parser* instead of one of its subclasses. The constructor for this class and all of its subclasses should return a blessed reference to an associative array (hash). initialize() ------------ This method performs any necessary base class initialization. It takes no arguments (other than the object instance of course). If subclasses override this method then they must be sure to invoke the superclass' initialize() method. select($section_spec1, $section_spec2, ...) ------------------------------------------- This is the method that is used to select the particular sections and subsections of pod documentation that are to be printed and/or processed. If the first argument is the string "+", then the remaining section specifications are added to the current list of selections; otherwise the given section specifications will replace the current list of selections. Each of the `$section_spec' arguments should be a section specification as described in `"SECTION SPECIFICATIONS"' in this node. The section specifications are parsed by this method and the resulting regular expressions are stored in the array referenced by `$self->{SELECTED}' (please see the description of this member variable in `"INSTANCE DATA"' in this node). This method should not normally be overridden by subclasses. want_section($head1_title, $head2_title, ...) --------------------------------------------- Returns a value of true if the given section and subsection titles match any of the section specifications passed to the select() method (or if no section specifications were given). Returns a value of false otherwise. If `$headN_title' is ommitted then it defaults to the current `headN' section title in the input. This method should not normally be overridden by subclasses. begin_input() ------------- This method is invoked by parse_from_filehandle() immediately before processing input from a filehandle. The base class implementation does nothing but subclasses may override it to perform any per-file intializations. end_input() ----------- This method is invoked by parse_from_filehandle() immediately after processing input from a filehandle. The base class implementation does nothing but subclasses may override it to perform any per-file cleanup actions. preprocess_line($text) ---------------------- This methods should be overridden by subclasses that wish to perform any kind of preprocessing for each line of input (before it has been determined whether or not it is part of a pod paragraph). The parameter $text is the input line and the value returned should correspond to the new text to use in its place. If the empty string or an undefined value is returned then no further process will be performed for this line. If desired, this method can call the parse_paragraph() method directly with any preprocessed text and return an empty string (to indicate that no further processing is needed). Please note that the preprocess_line() method is invoked before the preprocess_paragraph() method. After all (possibly preprocessed) lines in a paragraph have been assembled together and it has been determined that the paragraph is part of the pod documentation from one of the selected sections, then preprocess_paragraph() is invoked. The base class implementation of this method returns the given text. preprocess_paragraph($text) --------------------------- This method should be overridden by subclasses that wish to perform any kind of preprocessing for each block (paragraph) of pod documentation that appears in the input stream. The parameter $text is the pod paragraph from the input file and the value returned should correspond to the new text to use in its place. If the empty string is returned or an undefined value is returned, then the given $text is ignored (not processed). This method is invoked by parse_paragraph(). After it returns, parse_paragraph() examines the current cutting state (which is stored in `$self->{CUTTING}'). If it evaluates to false then input text (including the given $text) is cut (not processed) until the next pod directive is encountered. Please note that the preprocess_line() method is invoked before the preprocess_paragraph() method. After all (possibly preprocessed) lines in a paragraph have been assembled together and it has been determined that the paragraph is part of the pod documentation from one of the selected sections, then preprocess_paragraph() is invoked. The base class implementation of this method returns the given text. parse_pragmas($cmd, $text, $sep) -------------------------------- This method is called when an =pod directive is encountered. When such a pod directive is seen in the input, this method is called and is passed the command name `$cmd' (which should be "pod") and the remainder of the text paragraph $text which appeared immediately after the command name. If desired, the text which separated the =pod directive from its corresponding text may be found in `$sep'. Each word in $text is examined to see if it is a pragma specification. Pragma specifications are of the form `pragma_name=pragma_value'. Unless the given object is an instance of the *PDL::Pod::Parser* class, the base class implementation of this method will invoke the *pragma()* method for each pragma specification in $text. *If and only if* the given object *is* an instance of the *PDL::Pod::Parser* class, the base class version of this method will simply reproduce the =pod command exactly as it appeared in the input. Derived classes should not usually need to reimplement this method. pragma($pragma_name, $pragma_value) ----------------------------------- This method is invoked for each pragma encountered inside an =pod paragraph (see the description of the *parse_pragmas()* method). The pragma name is passed in `$pragma_name' (which should always be lowercase) and the corresponding value is `$pragma_value'. The base class implementation of this method does nothing. Derived class implementations of this method should be able to recognize at least the following pragmas and take any necessary actions when they are encountered: fill=value The argument value should be one of `on', `off', or previous. Specifies that "filling-mode" should set to 1, 0, or its previous value (respectively). If value is omitted then the default is `on'. Derived classes may use this to decide whether or not to perform any filling (wrapping) of subsequent text. style=value The argument value should be one of bold, italic, code, `plain', or previous. Specifies that the current default paragraph font should be set to bold, italic, code, the empty string , or its previous value (respectively). If value is omitted then the default is `plain'. Derived classes may use this to determine the default font style to use for subsequent text. indent=value The argument value should be an integer value (with an optional sign). Specifies that the current indentation level should be reset to the given value. If a plus (minus) sign precedes the number then the indentation level should be incremented (decremented) by the given number. If only a plus or minus sign is given (without a number) then the current indentation level is incremented or decremented by some default amount (to be determined by subclasses). The value returned will be 1 if the pragma name was recognized and 0 if it wasnt (in which case the pragma was ignored). Derived classes should override this method if they wish to implement any pragmas. The base class implementation of this method does nothing but it does contain some commented-out code which subclasses may want to make use of when implementing pragmas. command($cmd, $text, $sep) -------------------------- This method should be overridden by subclasses to take the appropriate action when a pod command paragraph (denoted by a line beginning with "=") is encountered. When such a pod directive is seen in the input, this method is called and is passed the command name `$cmd' and the remainder of the text paragraph $text which appears immediately after the command name. If desired, the text which separated the command from its corresponding text may be found in `$sep'. Note that this method is not called for =pod paragraphs. The base class implementation of this method simply prints the raw pod command to the output filehandle and then invokes the textblock() method, passing it the $text parameter. verbatim($text) --------------- This method may be overridden by subclasses to take the appropriate action when a block of verbatim text is encountered. It is passed the text block $text as a parameter. The base class implementation of this method simply prints the textblock (unmodified) to the output filehandle. textblock($text) ---------------- This method may be overridden by subclasses to take the appropriate action when a normal block of pod text is encountered (although the base class method will usually do what you want). It is passed the text block $text as a parameter. In order to process interior sequences, subclasses implementations of this method will probably want invoke the interpolate() method, passing it the text block $text as a parameter and then perform any desired processing upon the returned result. The base class implementation of this method simply prints the text block as it occurred in the input stream). interior_sequence($seq_cmd, $seq_arg) ------------------------------------- This method should be overridden by subclasses to take the appropriate action when an interior sequence is encountered. An interior sequence is an embedded command within a block of text which appears as a command name (usually a single uppercase character) followed immediately by a string of text which is enclosed in angle brackets. This method is passed the sequence command `$seq_cmd' and the corresponding text $seq_arg and is invoked by the interpolate() method for each interior sequence that occurs in the string that it is passed. It should return the desired text string to be used in place of the interior sequence. Subclass implementationss of this method may wish to examine the the array referenced by `$self->{SEQUENCES}' which is a stack of all the interior sequences that are currently being processed (they may be nested). The current interior sequence (the one given by `$seq_cmd<$seq_arg>') should always be at the top of this stack. The base class implementation of the interior_sequence() method simply returns the raw text of the of the interior sequence (as it occurred in the input) to the output filehandle. interpolate($text, $end_re) --------------------------- This method will translate all text (including any embedded interior sequences) in the given text string $text and return the interpolated result. If a second argument is given, then it is taken to be a regular expression that indicates when to quit interpolating the string. Upon return, the $text parameter will have been modified to contain only the un-processed portion of the given string (which will not contain any text matched by `$end_re'). This method should probably not be overridden by subclasses. It should be noted that this method invokes itself recursively to handle any nested interior sequences. parse_paragraph($text) ---------------------- This method takes the text of a pod paragraph to be processed and invokes the appropriate method (one of command(), verbatim(), or textblock()). This method does not usually need to be overridden by subclasses. parse_from_filehandle($infilehandle, $outfilehandle) ---------------------------------------------------- This method takes a glob to a filehandle (which is assumed to already be opened for reading) and reads the entire input stream looking for blocks (paragraphs) of pod documentation to be processed. For each block of pod documentation encountered it will call the parse_paragraph() method. If a second argument is given then it should be a filehandle glob where output should be sent (otherwise the default output filehandle is STDOUT). If no first argument is given the default input filehandle STDIN is used. The input filehandle that is currently in use is stored in the member variable whose key is "INPUT" (e.g. `$self->{INPUT}'). The output filehandle that is currently in use is stored in the member variable whose key is "OUTPUT" (e.g. `$self->{OUTPUT}'). Input is read line-by-line and assembled into paragraphs (which are separated by lines containing nothing but whitespace). The current line number is stored in the member variable whose key is "LINE" (e.g. `$self->{LINE}') and the current paragraph number is stored in the member variable whose key is "PARAGRAPH" (e.g. `$self->{PARAGRAPH}'). This method does not usually need to be overridden by subclasses. parse_from_file($filename, $outfile) ------------------------------------ This method takes a filename and does the following: * opens the input and output files for reading (creating the appropriate filehandles) * invokes the parse_from_filehandle() method passing it the corresponding input and output filehandles. * closes the input and output files. If the special input filename "-" or "<&STDIN" is given then the STDIN filehandle is used for input (and no open or close is performed). If no input filename is specified then "-" is implied. If a reference is passed instead of a filename then it is assumed to be a glob-style reference to a filehandle. If a second argument is given then it should be the name of the desired output file. If the special output filename "-" or ">&STDOUT" is given then the STDOUT filehandle is used for output (and no open or close is performed). If the special output filename ">&STDERR" is given then the STDERR filehandle is used for output (and no open or close is performed). If no output filename is specified then "-" is implied. If a reference is passed instead of a filename then it is assumed to be a glob-style reference to a filehandle. The name of the input file that is currently being read is stored in the member variable whose key is "INFILE" (e.g. `$self->{INFILE}'). The name of the output file that is currently being written is stored in the member variable whose key is "OUTFILE" (e.g. `$self->{OUTFILE}'). This method does not usually need to be overridden by subclasses. INSTANCE DATA ============= *PDL::Pod::Parser* uses the following data members for each of its instances (where `$self' is a reference to such an instance): $self->{INPUT} -------------- The current input filehandle. $self->{OUTPUT} --------------- The current output filehandle. $self->{INFILE} --------------- The name of the current input file. $self->{OUTFILE} ---------------- The name of the current output file. $self->{LINE} ------------- The current line number from the input stream. $self->{PARAGRAPH} ------------------ The current paragraph number from the input stream (which includes input paragraphs that are not part of the pod documentation). $self->{HEADINGS} ----------------- A reference to an array of the current section heading titles for each heading level (note that the first heading level title is at index 0). $self->{SELECTED} ----------------- A reference to an array of references to arrays. Each subarray is a list of anchored regular expressions (preceded by a "!" if the regexp is to be negated). The index of the expression in the subarray should correspond to the index of the heading title in *$self->{HEADINGS}* that it is to be matched against. $self->{CUTTING} ---------------- A boolean-valued scalar which evaluates to true if text from the input file is currently being "cut". $self->{SEQUENCES} ------------------ An array reference to the stack of interior sequence commands that are currently in the middle of being processed. NOTES ===== To create a pod translator to translate pod documentation to some other format, you usually only need to create a subclass of *PDL::Pod::Parser* which overrides the base class implementation for the following methods: * *pragma()* * command() * verbatim() * textblock() * interior_sequence() You may also want to implement the begin_input() and end_input() methods for your subclass (to perform any needed per-file intialization or cleanup). If you need to perform any preprocesssing of input before it is parsed you may want to implement one or both of the preprocess_line() and/or preprocess_paragraph() methods. Also, don't forget to make sure your subclass constructor invokes the base class' initialize() method. Sometimes it may be necessary to make more than one pass over the input files. This isn't a problem as long as none of the input files correspond to STDIN. You can override either the parse_from_filehandle() method or the parse_from_file() method to make the first pass yourself to collect all the information you need and then invoke the base class method to do the rest of the standard processing. Feel free to add any member data fields you need to keep track of things like current font, indentation, horizontal or vertical position, or whatever else you like. For the most part, the *PDL::Pod::Parser* base class should be able to do most of the input parsing for you and leave you free to worry about how to intepret the commands and translate the result. AUTHOR ====== Brad Appleton Based on code for Pod::Text written by Tom Christiansen  File: pm.info, Node: PDL/Pod/Select, Next: PDL/Pod/Usage, Prev: PDL/Pod/Parser, Up: Module List function to extract selected sections of pod documentation ********************************************************** NAME ==== podselect - function to extract selected sections of pod documentation SYNOPSIS ======== use PDL::Pod::Select; podselect (@filelist); podselect ({OUTPUT => "tmp.out"}, @filelist): podselect ({SELECT => ["NAME|SYNOPSIS", "OPTIONS"]}, @filelist): podselect ({OUTPUT => ">&STDERR", SELECT => ["DESCRIPTION"]}, "-"); DESCRIPTION =========== podselect() is a function which will extract specified sections of pod documentation from an input stream. This ability is already provided in the *PDL::Pod::Parser* module. Subclasses of *PDL::Pod::Parser* that wish to take advantage of this feature do not need to derive from *PDL::Pod::Select*. *PDL::Pod::Select* merely provides a single function named podselect() which provides this capability in function form (as opposed to object form) for extracting the raw pod docs. podselect(\%options, @filelist) ------------------------------- *podselect* will print the raw (untranslated) pod documentation of all pod sections in the given input files specified by `@filelist' according to the given options. If any argument to *podselect* is a reference to a hash (associative array) then the values with the following keys are processed as follows: OUTPUT A string corresponding to the desired output file (or ">&STDOUT" or ">&STDERR"). The default is to use standard output. SELECT A reference to an array of sections specifications (as described in `"SECTION SPECIFICATIONS"', *Note PDL/Pod/Parser: PDL/Pod/Parser,) which indicate the desired set of pod sections and subsections to be selected from input. If no section specifications are given, then all sections of pod documentation are used. All other arguments should correspond to the names of input files containing pod documentation. A file name of "-" or "<&STDIN" will be interpeted to mean standard input (which is the default if no filenames are given). SEE ALSO ======== *Note PDL/Pod/Parser: PDL/Pod/Parser, AUTHOR ====== Brad Appleton Based on code for *pod2text* written by Tom Christiansen  File: pm.info, Node: PDL/Pod/Usage, Next: PDL/Primitive, Prev: PDL/Pod/Select, Up: Module List print a usage message using a script's embedded pod documentation ***************************************************************** NAME ==== pod2usage - print a usage message using a script's embedded pod documentation SYNOPSIS ======== use PDL::Pod::Usage; pod2usage(); pod2usage(2); pod2usage({EXIT => 2}); pod2usage({EXIT => 2, VERBOSE => 0}); pod2usage(EXIT => 1, VERBOSE => 2, OUTPUT=\*STDERR); pod2usage(VERBOSE => 2); DESCRIPTION =========== *pod2usage* will print a usage message for the invoking script (using its embedded pod documentation) and then exit the script with the specified exit value. It takes a single argument which is either a numeric value corresponding to the desired exit status (which defaults to 2), or a reference to a hash. If more than one argument is given then the entire argument list is assumed to be a hash. If a hash is supplied it should contain elements with one or more of the following keys: `EXIT' The desired exit status to pass to the exit() function. VERBOSE The desired level of "verboseness" to use when printing the usage message. If the corresponding value is 0, then only the "SYNOPSIS" section of the pod documentation is printed. If the corresponding value is 1, then the "SYNOPSIS" section, along with any section entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is printed. If the corresponding value is 2 or more then the entire manpage is printed. OUTPUT A reference to a filehandle, or the pathname of a file to which the usage message should be written. The default is `\*STDERR' unless the exit value is less than 2 (in which case the default is `\*STDOUT'). INPUT A reference to a filehandle, or the pathname of a file from which the invoking script's pod documentation should be read. It defaults to the file indicated by $0 ($PROGRAM_NAME for `use English;' users). If neither the exit value nor the verbose level is specified, then the default is to use an exit value of 2 with a verbose level of 0. If an exit value is specified but the verbose level is not, then the verbose level will default to 1 if the exit value is less than 2 and will default to 0 otherwise. If a verbose level is specified but an exit value is not, then the exit value will default to 2 if the verbose level is 0 and will default to 1 otherwise. EXAMPLE ======= Most scripts should print some type of usage message to STDERR when a command line syntax error is detected. They should also provide an option (usually -h or `-help') to print a (possibly more verbose) usage message to STDOUT. Some scripts may even wish to go so far as to provide a means of printing their complete documentation to STDOUT (perhaps by allowing a `-man' option). The following example uses *pod2usage* in combination with Getopt::Long to do all of these things: use PDL::Pod::Usage; use Getopt::Long; GetOptions("help", "man") || pod2usage(2); pod2usage(1) if ($opt_help); pod2usage(VERBOSE => 2) if ($opt_man); CAVEATS ======= By default, *pod2usage()* will use $0 as the path to the pod input file. Unfortunately, not all systems on which Perl runs will set $0 properly (although if $0 isn't found, *pod2usage()* will search `$ENV{PATH}'). If this is the case for your system, you may need to explicitly specify the path to the pod docs for the invoking script using something similar to the following: * `pod2usage(EXIT => 2, INPUT => "/path/to/your/pod/docs");' AUTHOR ====== Brad Appleton Based on code for *Pod::Text::pod2text()* written by Tom Christiansen  File: pm.info, Node: PDL/Primitive, Next: PDL/Reduce, Prev: PDL/Pod/Usage, Up: Module List primitive operations for pdl **************************** NAME ==== PDL::Primitive - primitive operations for pdl DESCRIPTION =========== This module provides some primitive and useful functions defined using PDL::PP and able to use the new indexing tricks. See `PDL::Indexing|PDL::Indexing' in this node for how to use indices creatively. For explanation of the signature format, see `PDL::PP|PDL::PP' in this node. SYNOPSIS ======== use PDL::Primitive; FUNCTIONS ========= inner ----- c = sum_i a_i * b_i outer ----- Naturally, it is possible to achieve the effects of outer product simply by threading over the "*" operator but this function is provided for convenience. matmult ------- We peruse the inner product to define matrix multiplication via a threaded inner product innerwt ------- d = sum_i a(i) b(i) c(i) inner2 ------ d = sum_ij a(i) b(i,j) c(j) Note that you should probably not thread over a and c since that would be very wasteful. Instead, you should use a temporary for `b*c'. inner2d ------- Equivalent to $c = inner($a->clump(2), $b->clump(2)) inner2t ------- Efficiency comes from by using the temporary `tmp'. This operation only scales as `N**3' whereas threading using `inner2|' in this node would scale as `N**4'. The reason for having this routine is that you do not need to have the same thread-dimensions for `tmp' as for the other arguments, which in case of large numbers of matrices makes this much more memory-efficient. It is hoped that things like this could be taken care of as a kind of closures at some point. crossp ------ After the inner product `$c*$a' and `$c*$b' will be zero, i.e. $c is orthogonal to `$a' and $b norm ---- indadd ------ sum(ind) += a $a = 2; $ind = 3; $sum = zeroes(10); indadd($a,$ind, $sum); print $sum #Result: ( 2 added to element 3 of $sum) # [0 0 0 2 0 0 0 0 0 0] Threaded Example: $a = pdl( 1,2,3); $ind = pdl( 1,4,6); $sum = zeroes(10); indadd($a,$ind, $sum); print $sum."\n"; #Result: ( 1, 2, and 3 added to elements 1,4,6 $sum) # [0 1 0 0 2 0 3 0 0 0] conv1d ------ By default, periodic boundary conditions are assumed (i.e. wrap around). Alternatively, you can request reflective boundary conditions using the Boundary option: {Boundary => 'reflect'} # case in 'reflect' doesn't matter The convolution is performed along the first dimension. To apply it across another dimension use the slicing routines, e.g. $b = $a->mv(2,0)->conv1d($kernel)->mv(0,2); # along third dim This function is useful for threaded filtering of 1D signals. Compare also `conv2d|PDL::Image2D' in this node, `convolve|PDL::ImageND' in this node, `fftconvolve|PDL::FFT' in this node, `fftwconv|PDL::FFTW' in this node, `rfftwconv|PDL::FFTW' in this node hclip ----- lclip ----- clip ---- wtstat ------ This calculates a weighted statistic over the vector a. The formula is b() = (sum_i wt_i * (a_i ** degree - avg)) / (sum_i wt_i) stats ----- This utility calculates all the most useful quantities in one call. Note: The RMS value that this function returns in the RMS deviation from the mean, also known as the population standard- deviation. histogram --------- The histogram will contain `$numbins' bins starting from `$min', each `$step' wide. The value in each bin is the number of values in $data that lie within the bin limits. Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin. The output is reset in a different threadloop so that you can take a histogram of `$a(10,12)' into `$b(15)' and get the result you want. Use `hist|PDL::Basic' in this node instead for a high-level interface. whistogram ---------- The histogram will contain `$numbins' bins starting from `$min', each `$step' wide. The value in each bin is the sum of the values in `$weights' that correspond to values in $data that lie within the bin limits. Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin. The output is reset in a different threadloop so that you can take a histogram of `$a(10,12)' into `$b(15)' and get the result you want. histogram2d ----------- The histogram will contain `$nbinx' x `$nbiny' bins, with the lower limits of the first one at `($minx, $miny)', and with bin size `($stepx, $stepy)'. The value in each bin is the number of values in `$datax' and `$datay' that lie within the bin limits. Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin. whistogram2d ------------ The histogram will contain `$nbinx' x `$nbiny' bins, with the lower limits of the first one at `($minx, $miny)', and with bin size `($stepx, $stepy)'. The value in each bin is the sum of the values in `$weights' that correspond to values in `$datax' and `$datay' that lie within the bin limits. Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin. fibonacci --------- append ------ append appends two piddles along their first dims. Rest of the dimensions must be compatible in the threading sense. Resulting size of first dim is the sum of the sizes of the first dims of the two argument piddles - ie `n + m'. axisvalues ---------- axisvalues is the internal primitive that implements `axisvals|PDL::Basic' in this node and alters its argument. random ------ etc (see `zeroes|PDL::Core' in this node). This is the uniform distribution between 0 and 1 (assumedly excluding 1 itself). The arguments are the same as zeroes (q.v.) - i.e. one can specify dimensions, types or give a template. randsym ------- etc (see `zeroes|PDL::Core' in this node). This is the uniform distribution between 0 and 1 (excluding both 0 and 1, cf `random|' in this node). The arguments are the same as zeroes (q.v.) - i.e. one can specify dimensions, types or give a template. grandom ------- etc (see `zeroes|PDL::Core' in this node). This is generated using the math library routine ndtri. Mean = 0, Stddev = 1 vsearch ------- Returns for each value of `$vals' the index of the least larger member of `$xs' (which need to be in increasing order). If the value is larger than any member of `$xs', the index to the last element of `$xs' is returned. $a = pdl(.01,.86,.93,1); # Barnsley IFS probabilities cumulatively $b = random 20; $c = vsearch($b, $a); # Now, $c will have the appropriate distr. It is possible to use the `cumusumover|' in this node function to obtain cumulative probabilities from absolute probabilities. interpolate ----------- Given a set of points `($x,$y)', use linear interpolation to find the values `$yi' at a set of points `$xi'. interpolate uses a binary search to find the suspects, er..., interpolation indices and therefore abscissas (ie $x) have to be *strictly* ordered (increasing or decreasing). For interpolation at lots of closely spaced abscissas an approach that uses the last index found as a start for the next search can be faster (compare Numerical Recipes `hunt' routine). Feel free to implement that on top of the binary search if you like. For out of bounds values it just does a linear extrapolation and sets the corresponding element of $err to 1, which is otherwise 0. See also `interpol|' in this node, which uses the same routine, differing only in the handling of extrapolation - an error message is printed rather than returning an error piddle. interpol -------- interpol uses the same search method as `interpolate|' in this node, hence $x must be *strictly* ordered (either increasing or decreasing). The difference occurs in the handling of out-of-bounds values; here an error message is printed. one2nd ------ returns an array of piddles containing the ND indexes corresponding to the one dimensional list indices. The indices are assumed to correspond to array `$a' clumped using `clump(-1)'. This routine is used in `whichND|' in this node, but is useful on its own occasionally. which ----- returns a pdl with indices for all those elements that are nonzero in the mask. Note that mask really has to be 1-D (use `clump(-1)' if you need to work with ND-images) If you want to return both the indices of non-zero values and the complement, use the function `which_both|' in this node. which_both ---------- This works just as which, but the complement of $i will be in `$c_i'. where ----- Note: $i is always 1-D, even if $x is >1-D. The first argument (the values) and the second argument (the mask) currently have to have the same initial dimensions (or horrible things happen). It is also possible to use the same mask for several piddles with the same call: ($i,$j,$k) = where($x,$y,$z, $x+5>0); whichND ------- returns an array of piddles containing the coordinates of the elements that are non-zero in $mask. AUTHOR ====== Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu). Contributions by Christian Soeller (c.soeller@auckland.ac.nz) and Karl Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Reduce, Next: PDL/Slatec, Prev: PDL/Primitive, Up: Module List a reduce function for PDL ************************* NAME ==== PDL::Reduce - a reduce function for PDL DESCRIPTION =========== Many languages have a reduce function used to reduce the rank of an N-D array by one. It works by applying a selected operation along a specified dimension. This module implements such a function for PDL by providing a simplified interface to the existing projection functions (e.g. sumover, maximum, average, etc). SYNOPSIS ======== use PDL::Reduce; $a = sequence 5,5; # reduce by adding all # elements along 2nd dimension $b = $a->reduce(add,1); @ops = $a->canreduce; # return a list of all allowed operations FUNCTIONS ========= reduce ------ reduce dimension of piddle by one by applying an operation along the specified dimension [ As an aside: if you are familiar with threading you will see that this is actually the same as $b = $a->mv(1,0)->sumover ] reduce provides a simple and unified interface to the *projection* functions and makes people coming from other data/array languages hopefully feel more at home. reduce applies the named operation along the specified dimension reducing the input piddle dimension by one. If the dimension is omitted the operation is applied along the first dimension. To get a list of valid operations see `canreduce' in this node. canreduce --------- This list is useful if you want to make sure which operations can be used with reduce.  File: pm.info, Node: PDL/Slatec, Next: PDL/Slices, Prev: PDL/Reduce, Up: Module List PDL interface to the slatec numerical programming library ********************************************************* NAME ==== PDL::Slatec - PDL interface to the slatec numerical programming library SYNOPSIS ======== use PDL::Slatec; ($ndeg, $r, $ierr, $a) = polyfit($x, $y, $w, $maxdeg, $eps); DESCRIPTION =========== This module serves the dual purpose of providing an interface to parts of the slatec library and showing how to interface PDL to an external library. Using this library requires a fortran compiler; the source for the routines is provided for convenience. Currently available are routines to: manipulate matrices; calculate FFT's; fit data using polynomials; and interpolate/integrate data using piecewise cubic Hermite interpolation. Piecewise cubic Hermite interpolation (PCHIP) --------------------------------------------- PCHIP is the slatec package of routines to perform piecewise cubic Hermite interpolation of data. It features software to produce a monotone and "visually pleasing" interpolant to monotone data. According to Fritsch & Carlson ("Monotone piecewise cubic interpolation", SIAM Journal on Numerical Analysis 17, 2 (April 1980), pp. 238-246), such an interpolant may be more reasonable than a cubic spline if the data contains both "steep" and "flat" sections. Interpolation of cumulative probability distribution functions is another application. These routines are cryptically named (blame FORTRAN), beginning with 'ch', and accept either float or double piddles. Most of the routines require an integer parameter called check; if set to 0, then no checks on the validity of the input data are made, otherwise these checks are made. The value of check can be set to 0 if a routine such as `chim|' in this node has already been successfully called. * If not known, estimate derivative values for the points using the `chim|' in this node, `chic|' in this node, or `chsp|' in this node routines (the following routines require both the function (f) and derivative (d) values at a set of points (x)). * Evaluate, integrate, or differentiate the resulting PCH function using the routines: `chfd|' in this node; `chfe|' in this node; `chia|' in this node; `chid|' in this node. * If desired, you can check the monotonicity of your data using `chcm|' in this node. FUNCTIONS ========= eigsys ------ Note: this function should be extended to calculate only eigenvalues if called in scalar context! matinv ------ polyfit ------- Convenience wrapper routine about the polfit `slatec' function. Separates supplied arguments and return values. `eps' is modified to contain the rms error of the fit. polycoef -------- Convenience wrapper routine around the pcoef `slatec' function. Separates supplied arguments and return values. polyvalue --------- Convenience wrapper routine around the pvalue `slatec' function. Separates supplied arguments and return values. For multiple input x positions, a corresponding y position is calculated. The derivatives PDL is one dimensional (of size `nder') if a single x position is supplied, two dimensional if more than one x position is supplied. svdc ---- poco ---- Factor a real symmetric positive definite matrix and estimate the condition number of the matrix. geco ---- Factor a matrix using Gaussian elimination and estimate the condition number of the matrix. gefa ---- podi ---- Compute the determinant and inverse of a certain real symmetric positive definite matrix using the factors computed by `poco|' in this node. gedi ---- Compute the determinant and inverse of a matrix using the factors computed by `geco|' in this node or `gefa|' in this node. gesl ---- Solve the real system `A*X=B' or `TRANS(A)*X=B' using the factors computed by `geco|' in this node or `gefa|' in this node. rs -- This subroutine calls the recommended sequence of subroutines from the eigensystem subroutine package (EISPACK) to find the eigenvalues and eigenvectors (if desired) of a REAL SYMMETRIC matrix. ezffti ------ Subroutine ezffti initializes the work array `wsave()' which is used in both `ezfftf|' in this node and `ezfftb|' in this node. The prime factorization of n together with a tabulation of the trigonometric functions are computed and stored in `wsave()'. ezfftf ------ *ezfftf = \&PDL::ezfftf; ezfftb ------ *ezfftb = \&PDL::ezfftb; polfit ------ Fit discrete data in a least squares sense by polynomials in one variable. `x()', `y()' and `w()' must be of the same type. pcoef ----- Convert the polfit coefficients to Taylor series form. c and `a()' must be of the same type. pvalue ------ Use the coefficients generated by polfit to evaluate the polynomial fit of degree l, along with the first `nder' of its derivatives, at a specified point. x and a must be of the same type. chim ---- Calculate the derivatives at the given set of points (`$x,$f', where $x is strictly increasing). The resulting set of points - `$x,$f,$d', referred to as the cubic Hermite representation - can then be used in other functions, such as `chfe|' in this node, `chfd|' in this node, and `chia|' in this node. The boundary conditions are compatible with monotonicity, and if the data are only piecewise monotonic, the interpolant will have an extremum at the switch points; for more control over these issues use `chic|' in this node. Error status returned by `$ierr': * 0 if successful. * > 0 if there were `ierr' switches in the direction of monotonicity (data still valid). * -1 if `nelem($x) < 2'. * -3 if $x is not strictly increasing. chic ---- Calculate the derivatives at the given points (`$x,$f', where $x is strictly increasing). Control over the boundary conditions is given by the `$ic' and `$vc' piddles, and the value of `$mflag' determines the treatment of points where monotoncity switches direction. A simpler, more restricted, interface is available using `chim|' in this node. The first and second elements of `$ic' determine the boundary conditions at the start and end of the data respectively. If the value is 0, then the default condition, as used by `chim|' in this node, is adopted. If greater than zero, no adjustment for monotonicity is made, otherwise if less than zero the derivative will be adjusted. The allowed magnitudes for `ic(0)' are: * 1 if first derivative at `x(0)' is given in `vc(0)'. * 2 if second derivative at `x(0)' is given in `vc(0)'. * 3 to use the 3-point difference formula for `d(0)'. (Reverts to the default b.c. if `n < 3') * 4 to use the 4-point difference formula for `d(0)'. (Reverts to the default b.c. if `n < 4') * 5 to set `d(0)' so that the second derivative is continuous at `x(1)'. (Reverts to the default b.c. if `n < 4') The values for `ic(1)' are the same as above, except that the first-derivative value is stored in `vc(1)' for cases 1 and 2. The values of `$vc' need only be set if options 1 or 2 are chosen for `$ic'. Set `$mflag = 0' if interpolant is required to be monotonic in each interval, regardless of the data. This causes $d to be set to 0 at all switch points. Set `$mflag' to be non-zero to use a formula based on the 3-point difference formula at switch points. If `$mflag > 0', then the interpolant at swich points is forced to not deviate from the data by more than `$mflag*dfloc', where `dfloc' is the maximum of the change of $f on this interval and its two immediate neighbours. If `$mflag < 0', no such control is to be imposed. The piddle `$wk' is only needed for work space. However, I could not get it to work as a temporary variable, so you must supply it; it is a 1D piddle with `2*n' elements. Error status returned by `$ierr': * 0 if successful. * 1 if `ic(0) < 0' and `d(0)' had to be adjusted for monotonicity. * 2 if `ic(1) < 0' and `d(n-1)' had to be adjusted for monotonicity. * 3 if both 1 and 2 are true. * -1 if `n < 2'. * -3 if $x is not strictly increasing. * -4 if `abs(ic(0)) > 5'. * -5 if `abs(ic(1)) > 5'. * -6 if both -4 and -5 are true. * -7 if `nwk < 2*(n-1)'. chsp ---- Calculate the derivatives, using cubic spline interpolation, at the given points (`$x,$f'), with the specified boundary conditions. Control over the boundary conditions is given by the `$ic' and `$vc' piddles. The resulting values - `$x,$f,$d' - can be used in all the functions which expect a cubic Hermite function. The first and second elements of `$ic' determine the boundary conditions at the start and end of the data respectively. The allowed values for `ic(0)' are: * 0 to set `d(0)' so that the third derivative is continuous at `x(1)'. * 1 if first derivative at `x(0)' is given in `vc(0'). * 2 if second derivative at `x(0') is given in `vc(0)'. * 3 to use the 3-point difference formula for `d(0)'. (Reverts to the default b.c. if `n < 3'.) * 4 to use the 4-point difference formula for `d(0)'. (Reverts to the default b.c. if `n < 4'.) The values for `ic(1)' are the same as above, except that the first-derivative value is stored in `vc(1)' for cases 1 and 2. The values of `$vc' need only be set if options 1 or 2 are chosen for `$ic'. The piddle `$wk' is only needed for work space. However, I could not get it to work as a temporary variable, so you must supply it; it is a 1D piddle with `2*n' elements. Error status returned by `$ierr': * 0 if successful. * -1 if `nelem($x) < 2'. * -3 if $x is not strictly increasing. * -4 if `ic(0) < 0' or `ic(0) > 4'. * -5 if `ic(1) < 0' or `ic(1) > 4'. * -6 if both of the above are true. * -7 if `nwk < 2*n'. * -8 in case of trouble solving the linear system for the interior derivative values. chfd ---- Given a piecewise cubic Hermite function - such as from `chim|' in this node - evaluate the function (`$fe') and derivative (`$de') at a set of points (`$xe'). If function values alone are required, use `chfe|' in this node. Set check to 0 to skip checks on the input data. Error status returned by `$ierr': * 0 if successful. * >0 if extrapolation was performed at `ierr' points (data still valid). * -1 if `nelem($x) < 2' * -3 if $x is not strictly increasing. * -4 if `nelem($xe) < 1'. * -5 if an error has occurred in a lower-level routine, which should never happen. chfe ---- Given a piecewise cubic Hermite function - such as from `chim|' in this node - evaluate the function (`$fe') at a set of points (`$xe'). If derivative values are also required, use `chfd|' in this node. Set check to 0 to skip checks on the input data. Error status returned by `$ierr': * 0 if successful. * >0 if extrapolation was performed at `ierr' points (data still valid). * -1 if `nelem($x) < 2' * -3 if $x is not strictly increasing. * -4 if `nelem($xe) < 1'. chia ---- Evaluate the definite integral of a a piecewise cubic Hermite function over an arbitrary interval, given by `[$a,$b]'. See `chid|' in this node if the integration limits are data points. Set check to 0 to skip checks on the input data. The values of `$a' and $b do not have to lie within $x, although the resulting integral value will be highly suspect if they are not. Error status returned by `$ierr': * 0 if successful. * 1 if `$a' lies outside $x. * 2 if $b lies outside $x. * 3 if both 1 and 2 are true. * -1 if `nelem($x) < 2' * -3 if $x is not strictly increasing. * -4 if an error has occurred in a lower-level routine, which should never happen. chid ---- Evaluate the definite integral of a a piecewise cubic Hermite function between `x($ia)' and `x($ib)'. See `chia|' in this node for integration between arbitrary limits. Although using a fortran routine, the values of `$ia' and `$ib' are zero offset. Set check to 0 to skip checks on the input data. Error status returned by `$ierr': * 0 if successful. * -1 if `nelem($x) < 2'. * -3 if $x is not strictly increasing. * -4 if `$ia' or `$ib' is out of range. chcm ---- The outout piddle `$ismon' indicates over which intervals the function is monotonic. Set check to 0 to skip checks on the input data. For the data interval `[x(i),x(i+1)]', the values of `ismon(i)' can be: * -3 if function is probably decreasing * -1 if function is strictly decreasing * 0 if function is constant * 1 if function is strictly increasing * 2 if function is non-monotonic * 3 if function is probably increasing If `abs(ismon(i)) == 3', the derivative values are near the boundary of the monotonicity region. A small increase produces non-monotonicity, whereas a decrease produces strict monotonicity. The above applies to `i = 0 .. nelem($x)-1'. The last element of `$ismon' indicates whether the entire function is monotonic over $x. Error status returned by `$ierr': * 0 if successful. * -1 if `n < 2'. * -3 if $x is not strictly increasing. AUTHOR ====== Copyright (C) 1997 Tuomas J. Lukka. Copyright (C) 2000 Tim Jenness, Doug Burke. All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.