NAME

    Sub::Attribute::Prototype - polyfill for :prototype attribute on older
    perls

SYNOPSIS

       use Sub::Attribute::Prototype;
    
       sub afunc :prototype(&@) {
          ...
       }

DESCRIPTION

    This polyfill allows a module to use the :prototype function attribute
    to apply a prototype to a function, even on perls too old to natively
    support it.

    Perl version 5.20 introduced the :prototype attribute, as part of the
    wider work surrounding subroutine signatures. This allows a function to
    declare a prototype even when the use feature 'signatures' pragma is in
    effect.

    If a newer version of perl switches the defaults to making signature
    syntax default, it will no longer be possible to write prototype-using
    functions using the old syntax, so authors will have to use :prototype
    instead. By using this polyfill module, an author can ensure such
    syntax is still recognised by perl versions older than 5.20.

    When used on a version of perl new enough to natively support the
    :prototype attribute (i.e. 5.20 or newer), this module does nothing.
    Any :prototype attribute syntax used by the user of this module is
    simply handled by core perl in the normal way.

    When used on an older version of perl, a polyfilled compatibility
    attribute is provided to the caller to (mostly) perform the same work
    that newer versions of perl would do; subject to some caveats.

 Caveats

    The following caveats should be noted about the pre-5.20 polyfilled
    version of the :prototype attribute.

      * Due to the way that attributes are applied to functions, it is not
      possible to apply the prototype immediately during compiletime.
      Instead, they must be deferred until a slightly later time. The
      earliest time that can feasibly be implemented is UNITCHECK time of
      the importing module.

      This has the unfortunate downside that function prototypes are NOT
      visible to later functions in the module itself, though they are
      visible to the importing code in the usual way. This means that
      exported functions will work just fine from the perspective of a
      module that uses them, they cannot be used internally within the
      module itself.

      Because this limitation only applies to the polyfilled version of the
      attribute for older versions of perl, it means the behavior will
      differ on a newer version of perl. Thus it is important that if you
      wish call a prototyped function from other parts of your module, you
      must use the prototype-defeating form of

         my $result = &one_of_my_functions( @args )

      in order to get reliable behaviour between older and newer perl
      versions.

      * Perl versions older than 5.20 will provoke a warning in the
      reserved category when they encounter the attribute syntax provided
      by this polyfill, even though the polyfill has consumed the
      attribute. In order not to cause this warning to appear to users of
      modules using this syntax, it is necessary for this polyfill to
      suppress the entire reserved warning category. This means that all
      such warnings will be silenced, including those about different
      attributes.

      * Because core perl does not have a built-in way for exporter to
      inject a UNITCHECK block into their importer, it is necessary to use
      a non-core XS module, B::CompilerPhase::Hook, to provide this. As a
      result, this polyfill has non-core depenencies when running on older
      perl versions, and this dependency includes XS (i.e. compiled) code,
      and is no longer Pure Perl. It will not be possible to use tools such
      as App::FatPacker to bundle this dependency in order to ship a
      pure-perl portable script.

    It should be stressed that none of these limitations apply when running
    on a version of perl 5.20 or later. Though in that case there is no
    need to use this polyfill at all, because the :prototype attribute will
    be natively recognised.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>