.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Sub::Override 3"
.TH Sub::Override 3 2025-12-14 "perl v5.42.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sub::Override \- Perl extension for easily overriding subroutines
.SH VERSION
.IX Header "VERSION"
0.12
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Sub::Override;
\&
\&  sub foo { \*(Aqoriginal sub\*(Aq };
\&  print foo(); # prints \*(Aqoriginal sub\*(Aq
\&
\&  my $override = Sub::Override\->new( foo => sub { \*(Aqoverridden sub\*(Aq } );
\&  print foo(); # prints \*(Aqoverridden sub\*(Aq
\&  $override\->restore;
\&  print foo(); # prints \*(Aqoriginal sub\*(Aq
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
.SS "The Problem"
.IX Subsection "The Problem"
Sometimes subroutines need to be overridden.  In fact, your author does this
frequently for tests.  Particularly when testing, using a Mock Object can be
overkill when all you want to do is override one tiny, little function.
.PP
Overriding a subroutine is often done with syntax similar to the following.
.PP
.Vb 5
\& {
\&   local *Some::sub = sub {\*(Aqsome behavior\*(Aq};
\&   # do something
\& }
\& # original subroutine behavior restored
.Ve
.PP
This has a few problems.
.PP
.Vb 4
\& {
\&   local *Get::some_feild = { \*(Aqsome behavior\*(Aq };
\&   # do something
\& }
.Ve
.PP
In the above example, not only have we probably misspelled the subroutine name,
but even if there had been a subroutine with that name, we haven\*(Aqt overridden
it.  These two bugs can be subtle to detect.
.PP
Further, if we\*(Aqre attempting to localize the effect by placing this code in a
block, the entire construct is cumbersome.
.PP
Hook::LexWrap also allows us to override sub behavior, but I can never remember
the exact syntax.
.SS "An easier way to replace subroutines"
.IX Subsection "An easier way to replace subroutines"
Instead, \f(CW\*(C`Sub::Override\*(C'\fR allows the programmer to simply name the sub to
replace and to supply a sub to replace it with.
.PP
.Vb 1
\&  my $override = Sub::Override\->new(\*(AqSome::sub\*(Aq, sub {\*(Aqnew data\*(Aq});
\&
\&  # which is equivalent to:
\&  my $override = Sub::Override\->new;
\&  $override\->replace(\*(AqSome::sub\*(Aq, sub { \*(Aqnew data\*(Aq });
.Ve
.PP
You can replace multiple subroutines, if needed:
.PP
.Vb 3
\&  $override\->replace(\*(AqSome::sub1\*(Aq, sub { \*(Aqnew data1\*(Aq });
\&  $override\->replace(\*(AqSome::sub2\*(Aq, sub { \*(Aqnew data2\*(Aq });
\&  $override\->replace(\*(AqSome::sub3\*(Aq, sub { \*(Aqnew data3\*(Aq });
.Ve
.PP
If replacing the subroutine succeeds, the object is returned.  This allows the
programmer to chain the calls, if this style of programming is preferred:
.PP
.Vb 3
\&  $override\->replace(\*(AqSome::sub1\*(Aq, sub { \*(Aqnew data1\*(Aq })
\&           \->replace(\*(AqSome::sub2\*(Aq, sub { \*(Aqnew data2\*(Aq })
\&           \->replace(\*(AqSome::sub3\*(Aq, sub { \*(Aqnew data3\*(Aq });
.Ve
.PP
If the subroutine has a prototype, the new subroutine should be declared with
same prototype as original one:
.PP
.Vb 1
\&  $override\->replace(\*(AqSome::sub_with_proto\*(Aq, sub ($$) { ($_[0], $_ [1]) });
.Ve
.PP
A subroutine may be replaced as many times as desired.  This is most useful
when testing how code behaves with multiple conditions.
.PP
.Vb 2
\&  $override\->replace(\*(AqSome::thing\*(Aq, sub { 0 });
\&  is($object\->foo, \*(Aqwibble\*(Aq, \*(Aqwibble is returned if Some::thing is false\*(Aq);
\&
\&  $override\->replace(\*(AqSome::thing\*(Aq, sub { 1 });
\&  is($object\->foo, \*(Aqpuppies\*(Aq, \*(Aqpuppies are returned if Some::thing is true\*(Aq);
.Ve
.SS "Injecting a subroutine"
.IX Subsection "Injecting a subroutine"
If you want to inject a subroutine into a package, you can use the \f(CWinject()\fR
method. This is identical to \f(CWreplace()\fR, except that it requires that the
subroutine does not exist:
.PP
.Vb 1
\&  $override\->inject(\*(AqSome::sub\*(Aq, sub {\*(Aqnew data\*(Aq});
.Ve
.PP
This is useful if you want to add a subroutine to a package that doesn\*(Aqt
already have it.
.PP
If you attempt to inject a subroutine that already exists, an exception will be
thrown.
.PP
.Vb 2
\&  $override\->inject(\*(AqSome::sub\*(Aq, sub {\*(Aqnew data\*(Aq}); # works
\&  $override\->inject(\*(AqSome::sub\*(Aq, sub {\*(Aqnew data\*(Aq}); # throws an exception
.Ve
.PP
Calling \f(CWrestore()\fR or allowing the \f(CW$override\fR to go out of scope will
remove the injected subroutine.
.PP
.Vb 2
\&  $override\->inject(\*(AqSome::sub\*(Aq, sub {\*(Aqnew data\*(Aq});
\&  $override\->restore(\*(AqSome::sub\*(Aq); # removes the injected subroutine
.Ve
.SS "Inheriting a subroutine"
.IX Subsection "Inheriting a subroutine"
Similar to \*(Aqinject\*(Aq, \*(Aqinherit\*(Aq will only allow you to create a new subroutine
on a child object that inherits the routine from the parent, and doesn\*(Aqt
exist in the child:
.PP
.Vb 3
\&  package Parent;
\&  sub foo {}
\&  sub bar {}
\&
\&  package Child;
\&  use parent \*(AqParent\*(Aq;
\&  sub foo {}
.Ve
.PP
\&\*(AqInherit\*(Aq will allow you to set up a new \*(AqChild::bar\*(Aq subroutine since it is
inherited from Parent. Attempting to \*(Aqinherit\*(Aq \*(AqChild::foo\*(Aq will result in an
exception being thrown since \*(Aqfoo\*(Aq already exists in Child. Similarly,
attempting to \*(Aqinherit\*(Aq new subroutine \*(Aqsomething\*(Aq in Child will also result
in an exception since it doesn\*(Aqt exist in Parent and won\*(Aqt be inherited by Child.
.SS "Wrapping a subroutine"
.IX Subsection "Wrapping a subroutine"
There may be times when you want to \*(Aqconditionally\*(Aq replace a subroutine \- for
example, to override the original subroutine only if certain args are passed.
For this you can specify \f(CW\*(C`wrap\*(C'\fR instead of \f(CW\*(C`replace\*(C'\fR. \f(CW\*(C`wrap\*(C'\fR is identical to
\&\f(CW\*(C`replace\*(C'\fR, except the original subroutine is passed as the first arg to your
new subroutine. You can call the original sub via \*(Aqshift\->(@_)\*(Aq:
.PP
.Vb 7
\&  $override\->wrap(\*(AqSome::sub\*(Aq,
\&    sub {
\&      my ($old_sub, @args) = @_;
\&      return 1 if $args[0];
\&      return $old_sub\->(@args);
\&    }
\&  );
.Ve
.SS "Restoring subroutines"
.IX Subsection "Restoring subroutines"
If the object falls out of scope, the original subs are restored.  However, if
you need to restore a subroutine early, just use the \f(CWrestore()\fR method:
.PP
.Vb 3
\&  my $override = Sub::Override\->new(\*(AqSome::sub\*(Aq, sub {\*(Aqnew data\*(Aq});
\&  # do stuff
\&  $override\->restore;
.Ve
.PP
Which is somewhat equivalent to:
.PP
.Vb 4
\&  {
\&    my $override = Sub::Override\->new(\*(AqSome::sub\*(Aq, sub {\*(Aqnew data\*(Aq});
\&    # do stuff
\&  }
.Ve
.PP
If you have overridden more than one subroutine with an override object, you
will have to explicitly name the subroutine you wish to restore:
.PP
.Vb 1
\&  $override\->restore(\*(AqThis::sub\*(Aq);
.Ve
.PP
Note \f(CWrestore()\fR will always restore the original behavior of the subroutine
no matter how many times you have overridden it.
.SS "Which package is the subroutine in?"
.IX Subsection "Which package is the subroutine in?"
Ordinarily, you want to fully qualify the subroutine by including the package
name.  However, failure to fully qualify the subroutine name will assume the
current package.
.PP
.Vb 7
\&  package Foo;
\&  use Sub::Override;
\&  sub foo { 23 };
\&  my $override = Sub::Override\->new( foo => sub { 42 } ); # assumes Foo::foo
\&  print foo(); # prints 42
\&  $override\->restore;
\&  print foo(); # prints 23
.Ve
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 2
\&  my $sub = Sub::Override\->new;
\&  my $sub = Sub::Override\->new($sub_name, $sub_ref);
.Ve
.PP
Creates a new \f(CW\*(C`Sub::Override\*(C'\fR instance.  Optionally, you may override a
subroutine while creating a new object.
.SS replace
.IX Subsection "replace"
.Vb 1
\& $sub\->replace($sub_name, $sub_body);
.Ve
.PP
Temporarily replaces a subroutine with another subroutine.  Returns the
instance, so chaining the method is allowed:
.PP
.Vb 2
\& $sub\->replace($sub_name, $sub_body)
\&     \->replace($another_sub, $another_body);
.Ve
.PP
This method will \f(CW\*(C`croak\*(C'\fR if the subroutine to be replaced does not exist.
.SS override
.IX Subsection "override"
.Vb 2
\& my $sub = Sub::Override\->new;
\& $sub\->override($sub_name, $sub_body);
.Ve
.PP
\&\f(CW\*(C`override\*(C'\fR is an alternate name for \f(CW\*(C`replace\*(C'\fR.  They are the same method.
.SS inject
.IX Subsection "inject"
.Vb 1
\& $sub\->inject($sub_name, $sub_body);
.Ve
.PP
Temporarily injects a subroutine into a package.  Returns the instance, so
chaining the method is allowed:
.PP
.Vb 2
\& $sub\->inject($sub_name, $sub_body)
\&     \->inject($another_sub, $another_body);
.Ve
.SS inherit
.IX Subsection "inherit"
.Vb 1
\& $sub\->inherit($sub_name, $sub_body);
.Ve
.PP
Checks that the subroutine exists in a parent class, but not in the current
class, and injects it into the current class to inherit the parent\*(Aqs version.
.SS restore
.IX Subsection "restore"
.Vb 1
\& $sub\->restore($sub_name);
.Ve
.PP
Restores the previous behavior of the subroutine.  This will happen
automatically if the \f(CW\*(C`Sub::Override\*(C'\fR object falls out of scope.
.SS wrap
.IX Subsection "wrap"
.Vb 1
\& $sub\->wrap($sub_name, $sub_body);
.Ve
.PP
Temporarily wraps a subroutine with another subroutine. The original subroutine
is passed as the first arg to the new subroutine.
.SH EXPORT
.IX Header "EXPORT"
None by default.
.SH CAVEATS
.IX Header "CAVEATS"
If you need to override the same sub several times do not create a new
\&\f(CW\*(C`Sub::Override\*(C'\fR object, but instead always reuse the existing one and call
\&\f(CW\*(C`replace\*(C'\fR on it. Creating a new object to override the same sub will result
in weird behavior.
.PP
.Vb 3
\& # Do not do this!
\& my $sub_first = Sub::Override\->new( \*(AqFoo:bar\*(Aq => sub { \*(Aqfirst\*(Aq } );
\& my $sub_second = Sub::Override\->new( \*(AqFoo::bar\*(Aq => sub { \*(Aqsecond\*(Aq } );
\&
\& # Do not do this either!
\& my $sub = Sub::Override\->new( \*(AqFoo::bar\*(Aq => sub { \*(Aqfirst\*(Aq } );
\& $sub = Sub::Override\->new( \*(AqFoo::bar\*(Aq => sub { \*(Aqsecond\*(Aq } );
.Ve
.PP
Both of those usages could result in of your subs being lost, depending
on the order in which you restore them.
.PP
Instead, call \f(CW\*(C`replace\*(C'\fR on the existing \f(CW$sub\fR.
.PP
.Vb 2
\& my $sub = Sub::Override\->new( \*(AqFoo::bar\*(Aq => sub { \*(Aqfirst\*(Aq } );
\& $sub\->replace( \*(AqFoo::bar\*(Aq => sub { \*(Aqsecond\*(Aq } );
.Ve
.SH BUGS
.IX Header "BUGS"
Probably.  Tell me about \*(Aqem.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
Hook::LexWrap \-\- can also override subs, but with different capabilities
.IP \(bu 4
Test::MockObject \-\- use this if you need to alter an entire class
.SH MAINTAINER
.IX Header "MAINTAINER"
Robin Murray (mvsjes2 on github)
.SH AUTHOR
.IX Header "AUTHOR"
Curtis "Ovid" Poe, \f(CW\*(C`<ovid [at] cpan [dot] org>\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2004\-2013 by Curtis "Ovid" Poe
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.2 or,
at your option, any later version of Perl 5 you may have available.