perlsub man page on OPENSTEP

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


PERLSUB(1)							    PERLSUB(1)

NAME
       perlsub - Perl subroutines

SYNOPSIS
       To declare subroutines:

	   sub NAME;	  # A "forward" declaration.
	   sub NAME BLOCK # A declaration and a definition.

       To define an anonymous subroutine at runtime:

	   $subref = sub BLOCK;

       To import subroutines:

	   use PACKAGE qw(NAME1 NAME2 NAME3);

       To call subroutines:

	   &NAME	  # Passes current @_ to subroutine.
	   &NAME(LIST);	  # Parens required with & form.
	   NAME(LIST);	  # & is optional with parens.
	   NAME LIST;	  # Parens optional if predeclared/imported.

DESCRIPTION
       Any arguments passed to the routine come in as array @_, that is
       ($_[0], $_[1], ...).  The array @_ is a local array, but its values are
       references to the actual scalar parameters.  The return value of the
       subroutine is the value of the last expression evaluated, and can be
       either an array value or a scalar value.	 Alternatively, a return
       statement may be used to specify the returned value and exit the
       subroutine.  To create local variables see the local() and my()
       operators.

       A subroutine may be called using the "&" prefix.	 The "&" is optional
       in Perl 5, and so are the parens if the subroutine has been
       predeclared.  (Note, however, that the "&" is NOT optional when you're
       just naming the subroutine, such as when it's used as an argument to
       defined() or undef().  Nor is it optional when you want to do an
       indirect subroutine call with a subroutine name or reference using the
       &$subref() or &{$subref}() constructs.  See the perlref manpage for
       more on that.)

       Example:

	   sub MAX {
	       my $max = pop(@_);
	       foreach $foo (@_) {
		   $max = $foo if $max < $foo;
	       }
	       $max;
	   }

	   ...
	   $bestday = &MAX($mon,$tue,$wed,$thu,$fri);

       Example:

	   # get a line, combining continuation lines
	   #  that start with whitespace

	   sub get_line {
	       $thisline = $lookahead;
	       LINE: while ($lookahead = <STDIN>) {
		   if ($lookahead =~ /^[ \t]/) {
		       $thisline .= $lookahead;
		   }
		   else {
		       last LINE;
		   }
	       }
	       $thisline;
	   }

	   $lookahead = <STDIN>;       # get first line
	   while ($_ = get_line()) {
	       ...
	   }

       Use array assignment to a local list to name your formal arguments:

	   sub maybeset {
	       my($key, $value) = @_;
	       $foo{$key} = $value unless $foo{$key};
	   }

       This also has the effect of turning call-by-reference into call-by-
       value, since the assignment copies the values.

       Subroutines may be called recursively.  If a subroutine is called using
       the "&" form, the argument list is optional.  If omitted, no @_ array
       is set up for the subroutine; the @_ array at the time of the call is
       visible to subroutine instead.

	   &foo(1,2,3);	       # pass three arguments
	   foo(1,2,3);	       # the same

	   foo();	       # pass a null list
	   &foo();	       # the same
	   &foo;	       # pass no arguments--more efficient

       If a module wants to create a private subroutine that cannot be called
       from outside the module, it can declare a lexical variable containing
       an anonymous sub reference:

	   my $subref = sub { ... }
	   &$subref(1,2,3);

       As long as the reference is never returned by any function within the
       module, no outside module can see the subroutine, since its name is not
       in any package's symbol table.

       Passing Symbol Table Entries

       [Note:  The mechanism described in this section works fine in Perl 5,
       but the new reference mechanism is generally easier to work with.  See
       the perlref manpage.]

       Sometimes you don't want to pass the value of an array to a subroutine
       but rather the name of it, so that the subroutine can modify the global
       copy of it rather than working with a local copy.  In perl you can
       refer to all the objects of a particular name by prefixing the name
       with a star: *foo.  This is often known as a "type glob", since the
       star on the front can be thought of as a wildcard match for all the
       funny prefix characters on variables and subroutines and such.

       When evaluated, the type glob produces a scalar value that represents
       all the objects of that name, including any filehandle, format or
       subroutine.  When assigned to, it causes the name mentioned to refer to
       whatever "*" value was assigned to it.  Example:

	   sub doubleary {
	       local(*someary) = @_;
	       foreach $elem (@someary) {
		   $elem *= 2;
	       }
	   }
	   doubleary(*foo);
	   doubleary(*bar);

       Note that scalars are already passed by reference, so you can modify
       scalar arguments without using this mechanism by referring explicitly
       to $_[0] etc.  You can modify all the elements of an array by passing
       all the elements as scalars, but you have to use the * mechanism (or
       the equivalent reference mechanism) to push, pop or change the size of
       an array.  It will certainly be faster to pass the typeglob (or
       reference).

       Even if you don't want to modify an array, this mechanism is useful for
       passing multiple arrays in a single LIST, since normally the LIST
       mechanism will merge all the array values so that you can't extract out
       the individual arrays.

       Overriding builtin functions

       Many builtin functions may be overridden, though this should only be
       tried occasionally and for good reason.	Typically this might be done
       by a package attempting to emulate missing builtin functionality on a
       non-Unix system.

       Overriding may only be done by importing the name from a
       module--ordinary predeclaration isn't good enough.  However, the subs
       pragma (compiler directive) lets you, in effect, predeclare subs via
       the import syntax, and these names may then override the builtin ones:

	   use subs 'chdir', 'chroot', 'chmod', 'chown';
	   chdir $somewhere;
	   sub chdir { ... }

       Library modules should not in general export builtin names like "open"
       or "chdir" as part of their default @EXPORT list, since these may sneak
       into someone else's namespace and change the semantics unexpectedly.
       Instead, if the module adds the name to the @EXPORT_OK list, then it's
       possible for a user to import the name explicitly, but not implicitly.
       That is, they could say

	   use Module 'open';

       and it would import the open override, but if they said

	   use Module;

       they would get the default imports without the overrides.

       Autoloading

       If you call a subroutine that is undefined, you would ordinarily get an
       immediate fatal error complaining that the subroutine doesn't exist.
       (Likewise for subroutines being used as methods, when the method
       doesn't exist in any of the base classes of the class package.) If,
       however, there is an AUTOLOAD subroutine defined in the package or
       packages that were searched for the original subroutine, then that
       AUTOLOAD subroutine is called with the arguments that would have been
       passed to the original subroutine.  The fully qualified name of the
       original subroutine magically appears in the $AUTOLOAD variable in the
       same package as the AUTOLOAD routine.  The name is not passed as an
       ordinary argument because, er, well, just because, that's why...

       Most AUTOLOAD routines will load in a definition for the subroutine in
       question using eval, and then execute that subroutine using a special
       form of "goto" that erases the stack frame of the AUTOLOAD routine
       without a trace.	 (See the standard AutoLoader module, for example.)
       But an AUTOLOAD routine can also just emulate the routine and never
       define it.  A good example of this is the standard Shell module, which
       can treat undefined subroutine calls as calls to Unix programs.

       There are mechanisms available for modules to help them split
       themselves up into autoloadable files to be used with the standard
       AutoLoader module.  See the document on extensions.

3rd Berkeley Distribution					    PERLSUB(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