NAME

    Signature::Attribute::Alias - make signature parameters that alias
    caller-provided values

SYNOPSIS

       use v5.26;
       use Sublike::Extended;
       use Signature::Attribute::Alias;
       use experimental 'signatures';
    
       extended sub trim_spaces ($s :Alias) {
          $s =~ s/^\s+//;
          $s =~ s/\s+$//;
       }
    
       my $string = "  hello, world!    ";
       trim_spaces $string;
       say "<$string>";

DESCRIPTION

    This module provides a third-party subroutine parameter attribute via
    XS::Parse::Sublike, which declares that the parameter will alias the
    value passed by the caller, rather than take a copy of it.

    WARNING The ability for sublike constructions to take third-party
    parameter attributes is still new and highly experimental, and subject
    to much API change in future. As a result, this module should be
    considered equally experimental. Core perl's parser does not permit
    parameters to take attributes. This ability must be requested
    specially; either by using Sublike::Extended, or perhaps enabled
    directly by some other sublike keyword using the XS::Parse::Sublike
    infrastructure.

PARAMETER ATTRIBUTES

 :Alias

       extended sub f($x :Alias) { ... }

    Declares that the lexical variable created by the parameter will be an
    alias to the value passed in by the caller rather than, as would
    normally be the case, simply contain a copy it. This means that any
    modifications of the lexical within the subroutine will be reflected in
    the value from the caller - which, therefore - must be mutable.

    It is not automatically an error if the caller passes in an immutable
    value (such as a constant), but any attempt to modify it will yield the
    usual "Modification of read-only value attempted ..." warning from
    within the body of the subroutine.

    This attribute can only be applied to positional, scalar parameters
    that are mandatory; i.e. do not have a defaulting expression.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>