Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Pragmatic(3)	      User Contributed Perl Documentation	  Pragmatic(3)

       Pragmatic - Adds	pragmata to Exporter

       In module

	 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

       Pragmatic implements a default "import" method for processing pragmata
       before passing the rest of the import to	Exporter.

       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 Pragmatic 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
       Pragmatic is transparent).

       If you want to pass the pragma arguments, use syntax similar to that of
       the -M switch to	perl (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 Pragmatic	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; }

	     (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).

   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 Exporter:
	   (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;


       Exporter	does all the heavy-lifting (and	is a very interesting module
       to study) after Pragmatic has stripped out the pragmata from the	"use".

       The following are the diagnostics generated by Pragmatic.  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.

       B. K. Oxley (binkley) <>

	 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 to Kevin Caswick <> for a	great patch to
       run under Perl 5.8.

perl v5.32.0			  2005-03-15			  Pragmatic(3)


Want to link to this manual page? Use this URL:

home | help