GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PRAGMATIC (3)

.ds Aq ’

NAME

Pragmatic - Adds pragmata to Exporter

CONTENTS

SYNOPSIS

In module MyModule.pm:



  package MyModule;
  require Pragmatic;
  @ISA = qw (Pragmatic);

  %PRAGMATA = (mypragma => sub {...});



In other files which wish to use MyModule:



    use MyModule qw (-mypragma); # Execute pragma at import time
    use MyModule qw (-mypragma=1,2,3); # Pass pragma argument list



DESCRIPTION

<B>PragmaticB> implements a default import method for processing pragmata before passing the rest of the import to <B>ExporterB>.

Perl automatically calls the import method when processing a use statement for a module. Modules and use are documented in perlfunc and perlmod.

(Do not confuse <B>PragmaticB> with pragmatic modules, such as less, strict and the like. They are standalone pragmata, and are not associated with any other module.)

    Using Pragmatic Modules

Using Pragmatic modules is very simple. To invoke any particular pragma for a given module, include it in the argument list to use preceded by a hyphen:



    use MyModule qw (-mypragma);



Pragmatic::import will filter out these arguments, and pass the remainder of the argument list from the use statement to Exporter::import (actually, to Exporter::export_to_level so that <B>PragmaticB> is transparent).

If you want to pass the pragma arguments, use syntax similar to that of the -M switch to <B>perlB> (see perlrun):



    use MyModule qw (-mypragma=abc,1,2,3);



If there are any warnings or fatal errors, they will appear to come from the use statement, not from Pragmatic::import.

    Writing Pragmatic Modules

Writing Pragmatic modules with <B>PragmaticB> is straight-forward. First, require Pragmatic (you could use it instead, but it exports nothing, so there is little to gain thereby). Declare a package global %PRAGMATA, the keys of which are the names of the pragmata and their corresponding values the code references to invoke. Like this:



    package MyPackage;

    require Pragmatic;

    use strict;
    use vars qw (%PRAGMATA);

    sub something_else { 1; }

    %PRAGMATA =
      (first => sub { print "@_: first\n"; },
       second => sub { $SOME_GLOBAL = 1; },
       third => \&something_else,
       fourth => name_of_sub);



When a pragma is given in a use statement, the leading hyphen is removed, and the code reference corresponding to that key in %PRAGMATA, or a subroutine with the value’s name, is invoked with the name of the package as the first member of the argument list (this is the same as what happens with import). Additionally, any arguments given by the caller are included (see Using Pragmatic Modules, above).

EXAMPLES

    Using Pragmatic Modules

1. Simple use:


  use MyModule; # no pragmas

  use MyModule qw (-abc); # invoke C<abc>

  use MyModule qw (-p1 -p2); # invoke C<p1>, then C<p2>



2. Using an argument list:


  use MyModule qw (-abc=1,2,3); # invoke C<abc> with (1, 2, 3)

  use MyModule qw (-p1 -p2=here); # invoke C<p1>, then C<p2>
                                  # with (1, 2, 3)



3. Mixing with arguments for <B>ExporterB>: (Please see Exporter for a further explanatation.)



  use MyModule ( ); # no pragmas, no exports

  use MyModule qw (fun1 -abc fun2); # import C<fun1>, invoke C<abc>,
                                    # then import C<fun2>

  use MyModule qw (:set1 -abc=3); # import set C<set1>, invoke C<abc>
                                  # with (3)



    Writing Pragmatic Modules

1. Setting a package global:


  %PRAGMATA = (debug => sub { $DEBUG = 1; });



2. Selecting a method:


  my $fred = sub { fred; };
  my $barney = sub { barney; };

  %PRAGMATA =
    (fred => sub {
       local $^W = 0;
       *flintstone = $fred;
     },

     barney => sub {
       local $^W = 0;
       *flintstone = $barney;
     });



3. Changing inheritance:


  %PRAGMATA = (super => sub { shift; push @ISA, @_; });



4. Inheriting pragmata:


  package X;
  @ISA = qw(Pragmatic);
  %PRAGMATA = (debug => debug);
  $DEBUG = 0;

  sub debug { ${"$_[0]::DEBUG"} = 1; }

  package Y:
  @ISA = qw(X);
  %PRAGMATA = (debug => debug);
  $DEBUG = 0;



SEE ALSO

Exporter

<B>ExporterB> does all the heavy-lifting (and is a very interesting module to study) after <B>PragmaticB> has stripped out the pragmata from the use.

DIAGNOSTICS

The following are the diagnostics generated by <B>PragmaticB>. Items marked (W) are non-fatal (invoke Carp::carp); those marked (F) are fatal (invoke Carp::croak).
No such pragma ’%s’ (F) The caller tried something like use MyModule (-xxx) where there was no pragma xxx defined for MyModule.
Invalid pragma ’%s’ (F) The writer of the called package tried something like %PRAGMATA = (xxx => not_a_sub) and either assigned xxx a non-code reference, or xxx is not a method in that package.
Pragma ’%s’ failed (W) The pramga returned a false value. The module is possibly in an inconsisten state after this. Proceed with caution.

AUTHORS

B. K. Oxley (binkley) <binkley@alumni.rice.edu>

COPYRIGHT



  Copyright 1999-2005, B. K. Oxley.



This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

THANKS

Thanks to Kevin Caswick <KCaswick@wspackaging.com> for a great patch to run under Perl 5.8.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PRAGMATIC (3) 2005-03-15

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.