Pragmatic(3pm)

💖 Pragmatic — the 3pm page, but make it cute 💖

okay bestie, so this is Pragmatic, straight out of the User Contributed Perl Documentation section (it's a 3pm page, iykyk). Sit down, grab a strawberry 🍓, we're gonna make Exporter do tricks.

---

✨ NAME ✨

Pragmatic — it adds pragmata to Exporter. That's it. That's the whole vibe. 🫶

---

🌸 SYNOPSIS 🌸

So first, inside a module called MyModule.pm:

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

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

And then in any other file that wants to use MyModule:

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

periodt. that's the entire flex. 💅

---

🦋 DESCRIPTION 🦋

okay so here's the tea ☕ — Pragmatic implements a default "import" method, and its whole job is to handle all the pragmata first, before it hands the rest of the import off to Exporter. literally a little bouncer at the club door of your module. 👑

Perl calls the "import" method automatically whenever it's processing a use statement for a module. (Modules and use are both documented over in perlfunc and perlmod if you want the lore.)

🚨 not me confusing things 🚨 — do NOT mix up Pragmatic with pragmatic modules like less, strict, and friends. Those are standalone pragmata and have nothing to do with any other module. different girl, different era.

💜 Using Pragmatic Modules

Using Pragmatic modules is so easy, bestie. To fire off a particular pragma for a given module, just drop it into the argument list of use, with a hyphen in front:

use MyModule qw (-mypragma);

Pragmatic::import scoops out all those hyphen-y arguments and passes the leftovers from the use statement straight along to Exporter::import (okay technically it goes to Exporter::export_to_level so that Pragmatic stays invisible — transparency, slay ✨).

Wanna pass arguments to the pragma? Use the same kind of syntax as the -M switch to perl (see perlrun):

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

And if there are any warnings or fatal errors? They'll look like they came from the use statement itself, not from Pragmatic::import. main character energy, but make it humble. 🎀

🌈 Writing Pragmatic Modules

Writing Pragmatic modules is genuinely straight-forward, no cap. Step one: require Pragmatic (you could use it instead, but it exports nothing so there's basically no gain — lowkey pointless, do what you want tho). Then declare a package global %PRAGMATA — the keys are the names of the pragmata, and the values are the code references you want invoked. 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 shows up in a use statement, that leading hyphen gets removed, and then the code reference matching that key in %PRAGMATA — or a subroutine with the name of the value — gets invoked, with the name of the package as the first item in the argument list (exactly the same as what happens with "import"). Plus, any arguments the caller gave get thrown in too (scroll up to "Using Pragmatic Modules" if you forgot already 😭).

---

🔥 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 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;

---

👑 SEE ALSO 👑

• Exporter

Exporter does literally ALL the heavy-lifting (and honestly it's a very interesting module to study) — but only after Pragmatic has stripped all the pragmata out of the use. team work makes the dream work 🫶

---

💀 DIAGNOSTICS 💀

These are the diagnostics Pragmatic generates. Items marked "(W)" are non-fatal (they invoke "Carp::carp"), and those marked "(F)" are fatal (they invoke "Carp::croak"). choose your fighter.

• No such pragma '%s' (F) — the caller tried something like use MyModule (-xxx) but there was no pragma xxx defined for MyModule. ghost pragma. doesn't exist. 💀
• 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 isn't a method in that package. ma'am that is not a sub.
• Pragma '%s' failed (W) — the pramga returned a false value. The module is possibly in an inconsisten state after this. Proceed with caution. ⚠️ no fr fr, be careful here.

---

🌟 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. king behavior, we love to see it 👑

---

and that's the whole page bestie — this was Pragmatic(3pm), generated with perl v5.36.0 on 2022-12-12. mwah 💅✨