---
name: "Pragmatic"
section: "3pm"
platform: "linux"
package: "libpragmatic-perl"
version: "1.7-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pragmatic"
---

# Pragmatic(3pm)

Adds pragmata to Exporter

## NAME

Pragmatic - Adds pragmata to Exporter

## 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

**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; }
    %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 **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 all the heavy-lifting (and is a very interesting module to study) after **Pragmatic** has stripped out the pragmata from the `"use"`.

## DIAGNOSTICS

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.

## 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.