PPI::St...:Include(3)

✨ PPI::Statement::Include ✨

okay bestie, pull up a chair, because this one is PPI::Statement::Include(3) from the User Contributed Perl Documentation and it's genuinely so useful once it clicks 💖

---

🌸 NAME 🌸

PPI::Statement::Include — the class for all those statements that go and grab other code into your program 🫶

---

🎀 SYNOPSIS 🎀

like, all of these count as includes, no cap:

# The following are all includes
use 5.006;
use strict;
use My::Module;
use constant FOO => 'Foo';
require Foo::Bar;
require "Foo/Bar.pm";
require $foo if 1;
no strict 'refs';

---

🦋 INHERITANCE 🦋

the family tree, and yes it's giving royal lineage:

PPI::Statement::Include
isa PPI::Statement
    isa PPI::Node
        isa PPI::Element

---

💜 DESCRIPTION 💜

okay so the name is lowkey a lie, bestie 😭 despite being called PPI::Statement::Include, this class is actually the umbrella for a whole bunch of statement types — basically every statement that starts with use, no, or require. she contains multitudes 💅

but fr, it all boils down to three situations:

1. a dependency on a specific version of perl (and for this one, the version method returns true),
2. a pragma (where the pragma method returns true),
3. or the loading of modules — and the unloading of them too, via no.

---

🌈 METHODS 🌈

PPI::Statement::Include comes with a whole extra set of methods on top of the standard PPI::Statement, PPI::Node and PPI::Element methods. like, she does it all 💖

⭐ type

the type method tells you the general type of the statement — 'use', 'no', or 'require'.

she hands it back as a string, or undef if the type just can't be detected. no vibes detected, no answer 🙈

🌸 module

the module method returns the module name that an include statement specifies. and yes, this "includes" pragma names too, because pragmas are literally implemented as modules. (and let's be honest, the definition of a pragma is fuzzy at the best of times anyway, so like… it is what it is 💀)

this covers all of these:

use strict;
use My::Module;
no strict;
require My::Module;

…but it does not cover any of these:

use 5.006;
require 5.005;
require "explicit/file/name.pl";

returns the module name as a string, or undef if the include doesn't specify a module name. periodt.

🎀 module_version

the module_version method returns the minimum version of the module that the statement requires — if there even is one. sometimes she's just vibing with no version, and that's fine ✨

💅 pragma

the pragma method checks whether an include statement is being used as a pragma, and if so, returns it.

or at least, that's the claim 🙈 in practice it's way harder to say exactly what is or isn't a pragma, because the definition is fuzzy. the intent of a pragma is to change how the parser works, and that gets done through modules that do all kinds of internals magic.

for now, PPI assumes that any "module name" is only a set of lowercase letters (and maybe numbers, like use utf8;). this behaviour is expected to change — most likely into something that actually knows the specific names of the various "pragmas".

returns the name of the pragma, or false ('') if the include is not a pragma.

👑 version

the version method checks for an include statement that introduces a dependency on the version of perl the code is compatible with.

this covers two specific statements:

use 5.006;
require 5.006;

currently the version comes back as a string, although in future the version may be returned as a version object. if you want a numeric representation, use version_literal(). returns false if the statement is not a version dependency.

🦋 version_literal

the version_literal method behaves the same as version(), except the version comes back as a numeric literal instead. returns false if the statement is not a version dependency. same energy, different format 💖

🌈 arguments

the arguments method gives you the rest of the statement — everything after the module/pragma and the module version. i.e. the stuff that'll be used to construct what gets passed to the module's import() subroutine.

this does include the comma, etc. operators, but it doesn't include non-significant direct children or any final semicolon. so close, yet so semicolon-free 🎀

⭐ feature_mods

# `use feature 'signatures';`
my %mods = $include->feature_mods;
# { signatures => "perl" }

# `use 5.036;`
my %mods = $include->feature_mods;
# { signatures => "perl" }

returns a hashref of the features identified as enabled by the include, or undef if the include doesn't enable any features. the value for each feature tells you who the provider of that feature is 🔥

---

💀 TO DO 💀

• write specific unit tests for this package

(manifesting this one into existence bestie 🙏)

---

🫶 SUPPORT 🫶

see the support section in the main module. iykyk.

---

✨ AUTHOR ✨

Adam Kennedy <adamk@cpan.org>

---

🎀 COPYRIGHT 🎀

Copyright 2001 - 2011 Adam Kennedy.

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

The full text of the license can be found in the LICENSE file included with this module.

---

this was perl v5.42.0 doing its thing on 2026-01-17, and honestly? iconic. slay, go read the source, love u bye 💖🦋✨