perlmod man page on OPENSTEP

Man page or keyword search:  
man Server   1419 pages
apropos Keyword Search (all sections)
Output format
OPENSTEP logo
[printable version]


PERLMOD(1)							    PERLMOD(1)

NAME
       perlmod - Perl modules (packages)

DESCRIPTION
       Packages

       Perl provides a mechanism for alternative namespaces to protect
       packages from stomping on each others variables.	 In fact, apart from
       certain magical variables, there's really no such thing as a global
       variable in Perl.  By default, a Perl script starts compiling into the
       package known as main.  You can switch namespaces using the package
       declaration.  The scope of the package declaration is from the
       declaration itself to the end of the enclosing block (the same scope as
       the local() operator).  Typically it would be the first declaration in
       a file to be included by the require operator.  You can switch into a
       package in more than one place; it merely influences which symbol table
       is used by the compiler for the rest of that block.  You can refer to
       variables and filehandles in other packages by prefixing the identifier
       with the package name and a double colon: $Package::Variable.  If the
       package name is null, the main package as assumed.  That is, $::sail is
       equivalent to $main::sail.

       (The old package delimiter was a single quote, but double colon is now
       the preferred delimiter, in part because it's more readable to humans,
       and in part because it's more readable to emacs macros.	It also makes
       C++ programmers feel like they know what's going on.)

       Packages may be nested inside other packages: $OUTER::INNER::var.  This
       implies nothing about the order of name lookups, however.  All symbols
       are either local to the current package, or must be fully qualified
       from the outer package name down.  For instance, there is nowhere
       within package OUTER that $INNER::var refers to $OUTER::INNER::var.  It
       would treat package INNER as a totally separate global package.

       Only identifiers starting with letters (or underscore) are stored in a
       package's symbol table.	All other symbols are kept in package main.
       In addition, the identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV,
       INC and SIG are forced to be in package main, even when used for other
       purposes than their built-in one.  Note also that, if you have a
       package called m, s or y, then you can't use the qualified form of an
       identifier because it will be interpreted instead as a pattern match, a
       substitution, or a translation.

       (Variables beginning with underscore used to be forced into package
       main, but we decided it was more useful for package writers to be able
       to use leading underscore to indicate private variables and method
       names.)

       Eval()ed strings are compiled in the package in which the eval() was
       compiled.  (Assignments to $SIG{}, however, assume the signal handler
       specified is in the main package.  Qualify the signal handler name if
       you wish to have a signal handler in a package.)	 For an example,
       examine perldb.pl in the Perl library.  It initially switches to the DB
       package so that the debugger doesn't interfere with variables in the
       script you are trying to debug.	At various points, however, it
       temporarily switches back to the main package to evaluate various
       expressions in the context of the main package (or wherever you came
       from).  See the perldebug manpage.

       Symbol Tables

       The symbol table for a package happens to be stored in the associative
       array of that name appended with two colons.  The main symbol table's
       name is thus %main::, or %:: for short.	Likewise the nested package
       mentioned earlier is named %OUTER::INNER::.

       The value in each entry of the associative array is what you are
       referring to when you use the *name notation.  In fact, the following
       have the same effect, though the first is more efficient because it
       does the symbol table lookups at compile time:

	   local(*main::foo) = *main::bar; local($main::{'foo'}) =
	   $main::{'bar'};

       You can use this to print out all the variables in a package, for
       instance.  Here is dumpvar.pl from the Perl library:

	  package dumpvar;
	  sub main::dumpvar {
	      ($package) = @_;
	      local(*stab) = eval("*${package}::");
	      while (($key,$val) = each(%stab)) {
		  local(*entry) = $val;
		  if (defined $entry) {
		      print "\$$key = '$entry'\n";
		  }

		  if (defined @entry) {
		      print "\@$key = (\n";
		      foreach $num ($[ .. $#entry) {
			  print "  $num\t'",$entry[$num],"'\n";
		      }
		      print ")\n";
		  }

		  if ($key ne "${package}::" && defined %entry) {
		      print "\%$key = (\n";
		      foreach $key (sort keys(%entry)) {
			  print "  $key\t'",$entry{$key},"'\n";
		      }
		      print ")\n";
		  }
	      }
	  }

       Note that even though the subroutine is compiled in package dumpvar,
       the name of the subroutine is qualified so that its name is inserted
       into package main.

       Assignment to a symbol table entry performs an aliasing operation,
       i.e.,

	   *dick = *richard;

       causes variables, subroutines and file handles accessible via the
       identifier richard to also be accessible via the symbol dick.  If you
       only want to alias a particular variable or subroutine, you can assign
       a reference instead:

	   *dick = \$richard;

       makes $richard and $dick the same variable, but leaves @richard and
       @dick as separate arrays.  Tricky, eh?

       Package Constructors and Destructors

       There are two special subroutine definitions that function as package
       constructors and destructors.  These are the BEGIN and END routines.
       The sub is optional for these routines.

       A BEGIN subroutine is executed as soon as possible, that is, the moment
       it is completely defined, even before the rest of the containing file
       is parsed.  You may have multiple BEGIN blocks within a file--they will
       execute in order of definition.	Because a BEGIN block executes
       immediately, it can pull in definitions of subroutines and such from
       other files in time to be visible to the rest of the file.

       An END subroutine is executed as late as possible, that is, when the
       interpreter is being exited, even if it is exiting as a result of a
       die() function.	(But not if it's is being blown out of the water by a
       signal--you have to trap that yourself (if you can).)  You may have
       multiple END blocks within a file--they will execute in reverse order
       of definition; that is: last in, first out (LIFO).

       Note that when you use the -n and -p switches to Perl, BEGIN and END
       work just as they do in awk, as a degenerate case.

       Perl Classes

       There is no special class syntax in Perl 5, but a package may function
       as a class if it provides subroutines that function as methods.	Such a
       package may also derive some of its methods from another class package
       by listing the other package name in its @ISA array.  For more on this,
       see the perlobj manpage.

       Perl Modules

       In Perl 5, the notion of packages has been extended into the notion of
       modules.	 A module is a package that is defined in a library file of
       the same name, and is designed to be reusable.  It may do this by
       providing a mechanism for exporting some of its symbols into the symbol
       table of any package using it.  Or it may function as a class
       definition and make its semantics available implicitly through method
       calls on the class and its objects, without explicit exportation of any
       symbols.	 Or it can do a little of both.

       Perl modules are included by saying

	   use Module;

       or

	   use Module LIST;

       This is exactly equivalent to

	   BEGIN { require "Module.pm"; import Module; }

       or

	   BEGIN { require "Module.pm"; import Module LIST; }

       All Perl module files have the extension .pm.  use assumes this so that
       you don't have to spell out "Module.pm" in quotes.  This also helps to
       differentiate new modules from old .pl and .ph files.  Module names are
       also capitalized unless they're functioning as pragmas, "Pragmas" are
       in effect compiler directives, and are sometimes called "pragmatic
       modules" (or even "pragmata" if you're a classicist).

       Because the use statement implies a BEGIN block, the importation of
       semantics happens at the moment the use statement is compiled, before
       the rest of the file is compiled.  This is how it is able to function
       as a pragma mechanism, and also how modules are able to declare
       subroutines that are then visible as list operators for the rest of the
       current file.  This will not work if you use require instead of use.
       Therefore, if you're planning on the module altering your namespace,
       use use; otherwise, use require.	 Otherwise you can get into this
       problem:

	   require Cwd;		       # make Cwd:: accessible
	   $here = Cwd::getcwd();

	   use Cwd;		       # import names from Cwd::
	   $here = getcwd();

	   require Cwd;		       # make Cwd:: accessible
	   $here = getcwd();	       # oops! no main::getcwd()

       Perl packages may be nested inside other package names, so we can have
       package names containing ::.  But if we used that package name directly
       as a filename it would makes for unwieldy or impossible filenames on
       some systems.  Therefore, if a module's name is, say, Text::Soundex,
       then its definition is actually found in the library file
       Text/Soundex.pm.

       Perl modules always have a .pm file, but there may also be dynamically
       linked executables or autoloaded subroutine definitions associated with
       the module.  If so, these will be entirely transparent to the user of
       the module.  It is the responsibility of the .pm file to load (or
       arrange to autoload) any additional functionality.  The POSIX module
       happens to do both dynamic loading and autoloading, but the user can
       just say use POSIX to get it all.

       For more information on writing extension modules, see the perlapi
       manpage and the perlguts manpage.

NOTE
       Perl does not enforce private and public parts of its modules as you
       may have been used to in other languages like C++, Ada, or Modula-17.
       Perl doesn't have an infatuation with enforced privacy.	It would
       prefer that you stayed out of its living room because you weren't
       invited, not because it has a shotgun.

       The module and its user have a contract, part of which is common law,
       and part of which is "written".	Part of the common law contract is
       that a module doesn't pollute any namespace it wasn't asked to.	The
       written contract for the module (AKA documentation) may make other
       provisions.  But then you know when you use RedefineTheWorld that
       you're redefining the world and willing to take the consequences.

THE PERL MODULE LIBRARY
       A number of modules are included the the Perl distribution.  These are
       described below, and all end in .pm.  You may also discover files in
       the library directory that end in either .pl or .ph.  These are old
       libraries supplied so that old programs that use them still run.	 The
       .pl files will all eventually be converted into standard modules, and
       the .ph files made by h2ph will probably end up as extension modules
       made by h2xs.  (Some .ph values may already be available through the
       POSIX module.)  The pl2pm file in the distribution may help in your
       conversion, but it's just a mechanical process, so is far from bullet
       proof.

       Pragmatic Modules

       They work somewhat like pragmas in that they tend to affect the
       compilation of your program, and thus will usually only work well when
       used within a use, or no.  These are locally scoped, so an inner BLOCK
       may countermand any of these by saying

	   no integer;
	   no strict 'refs';

       which lasts until the end of that BLOCK.

       The following programs are defined (and have their own documentation).

       integer	   Perl pragma to compute arithmetic in integer instead of
		   double

       less	   Perl pragma to request less of something from the compiler

       sigtrap	   Perl pragma to enable stack backtrace on unexpected signals

       strict	   Perl pragma to restrict unsafe constructs

       subs	   Perl pragma to predeclare sub names

       Standard Modules

       The following modules are all expected to behave in a well-defined
       manner with respect to namespace pollution because they use the
       Exporter module.	 See their own documentation for details.

       Abbrev	   create an abbreviation table from a list

       AnyDBM_File provide framework for multiple DBMs

       AutoLoader  load functions only on demand

       AutoSplit   split a package for autoloading

       Basename	   parse file name and path from a specification

       Benchmark   benchmark running times of code

       Carp	   warn or die of errors (from perspective of caller)

       CheckTree   run many filetest checks on a tree

       Collate	   compare 8-bit scalar data according to the current locale

       Config	   access Perl configuration option

       Cwd	   get pathname of current working directory

       DynaLoader  Dynamically load C libraries into Perl code

       English	   use nice English (or awk) names for ugly punctuation
		   variables

       Env	   Perl module that imports environment variables

       Exporter	   module to control namespace manipulations

       Fcntl	   load the C Fcntl.h defines

       FileHandle  supply object methods for filehandles

       Find	   traverse a file tree

       Finddepth   traverse a directory structure depth-first

       Getopt	   basic and extended getopt(3) processing

       MakeMaker   generate a Makefile for Perl extension

       Open2	   open a process for both reading and writing

       Open3	   open a process for reading, writing, and error handling

       POSIX	   Perl interface to IEEE 1003.1 namespace

       Ping	   check a host for upness

       Socket	   load the C socket.h defines

       Extension Modules

       Extension modules are written in C (or a mix of Perl and C) and get
       dynamically loaded into Perl if and when you need them.	Supported
       extension modules include the Socket, Fcntl, and POSIX modules.

       The following are popular C extension modules, which while available at
       Perl 5.0 release time, do not come bundled (at least, not completely)
       due to their size, volatility, or simply lack of time for adequate
       testing and configuration across the multitude of platforms on which
       Perl was beta-tested.  You are encouraged to look for them in
       archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
       authors before randomly posting asking for their present condition and
       disposition.  There's no guarantee that the names or addresses below
       have not changed since printing, and in fact, they probably have!

       Curses	   Written by William Setzer <William_Setzer@ncsu.edu>, while
		   not included with the standard distribution, this extension
		   module ports to most systems.  FTP from your nearest Perl
		   archive site, or try

			   ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz

		   It is currently in alpha test, so the name and ftp location
		   may change.

       DBI	   This is the portable database interface written by
		   <Tim.Bunce@ig.co.uk>.  This supersedes the many perl4 ports
		   for database extensions.  The official archive for DBperl
		   extensions is ftp.demon.co.uk:/pub/perl/db.	This archive
		   contains copies of perl4 ports for Ingres, Oracle, Sybase,
		   Informix, Unify, Postgres, and Interbase, as well as rdb
		   and shql and other non-SQL systems.

       DB_File	   Fastest and most restriction-free of the DBM bindings, this
		   extension module uses the popular Berkeley DB to tie() into
		   your hashes.	 This has a standardly-distributed man page
		   and dynamic loading extension module, but you'll have to
		   fetch the Berkeley code yourself.  See the DB_File manpage
		   for where.

       Sx	   This extension module is a front to the Athena and Xlib
		   libraries for Perl GUI programming, originally written by
		   by Dominic Giampaolo <dbg@sgi.com>, then and rewritten for
		   Sx by Frederic Chauveau <fmc@pasteur.fr>.  It's available
		   for FTP from

		       ftp.pasteur.fr:/pub/Perl/Sx.tar.gz

       Tk	   This extension module is an object-oriented Perl5 binding
		   to the popular tcl/tk X11 package.  However, you need know
		   no TCL to use it!  It was written by Malcolm Beattie
		   <mbeattie@sable.ox.ac.uk>.  If you are unable to locate it
		   using archie(1L) or a similar tool, you may try retrieving
		   it from /private/Tk-october.tar.gz from Malcolm's machine
		   listed above.

3rd Berkeley Distribution					    PERLMOD(1)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OPENSTEP

List of man pages available for OPENSTEP

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net