.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 .\" ======================================================================== .\" .IX Title "Sub::HandlesVia::HandlerLibrary::String 3pm" .TH Sub::HandlesVia::HandlerLibrary::String 3pm "2023-04-09" "perl v5.36.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::HandlesVia::HandlerLibrary::String \- library of string\-related methods .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& package My::Class { \& use Moo; \& use Sub::HandlesVia; \& use Types::Standard \*(AqStr\*(Aq; \& has attr => ( \& is => \*(Aqrwp\*(Aq, \& isa => Str, \& handles_via => \*(AqString\*(Aq, \& handles => { \& \*(Aqmy_append\*(Aq => \*(Aqappend\*(Aq, \& \*(Aqmy_chomp\*(Aq => \*(Aqchomp\*(Aq, \& \*(Aqmy_chop\*(Aq => \*(Aqchop\*(Aq, \& \*(Aqmy_clear\*(Aq => \*(Aqclear\*(Aq, \& \*(Aqmy_cmp\*(Aq => \*(Aqcmp\*(Aq, \& \*(Aqmy_cmpi\*(Aq => \*(Aqcmpi\*(Aq, \& \*(Aqmy_contains\*(Aq => \*(Aqcontains\*(Aq, \& \*(Aqmy_contains_i\*(Aq => \*(Aqcontains_i\*(Aq, \& \*(Aqmy_ends_with\*(Aq => \*(Aqends_with\*(Aq, \& \*(Aqmy_ends_with_i\*(Aq => \*(Aqends_with_i\*(Aq, \& \*(Aqmy_eq\*(Aq => \*(Aqeq\*(Aq, \& \*(Aqmy_eqi\*(Aq => \*(Aqeqi\*(Aq, \& \*(Aqmy_fc\*(Aq => \*(Aqfc\*(Aq, \& \*(Aqmy_ge\*(Aq => \*(Aqge\*(Aq, \& \*(Aqmy_gei\*(Aq => \*(Aqgei\*(Aq, \& \*(Aqmy_get\*(Aq => \*(Aqget\*(Aq, \& \*(Aqmy_gt\*(Aq => \*(Aqgt\*(Aq, \& \*(Aqmy_gti\*(Aq => \*(Aqgti\*(Aq, \& \*(Aqmy_inc\*(Aq => \*(Aqinc\*(Aq, \& \*(Aqmy_lc\*(Aq => \*(Aqlc\*(Aq, \& \*(Aqmy_le\*(Aq => \*(Aqle\*(Aq, \& \*(Aqmy_lei\*(Aq => \*(Aqlei\*(Aq, \& \*(Aqmy_length\*(Aq => \*(Aqlength\*(Aq, \& \*(Aqmy_lt\*(Aq => \*(Aqlt\*(Aq, \& \*(Aqmy_lti\*(Aq => \*(Aqlti\*(Aq, \& \*(Aqmy_match\*(Aq => \*(Aqmatch\*(Aq, \& \*(Aqmy_match_i\*(Aq => \*(Aqmatch_i\*(Aq, \& \*(Aqmy_ne\*(Aq => \*(Aqne\*(Aq, \& \*(Aqmy_nei\*(Aq => \*(Aqnei\*(Aq, \& \*(Aqmy_prepend\*(Aq => \*(Aqprepend\*(Aq, \& \*(Aqmy_replace\*(Aq => \*(Aqreplace\*(Aq, \& \*(Aqmy_replace_globally\*(Aq => \*(Aqreplace_globally\*(Aq, \& \*(Aqmy_reset\*(Aq => \*(Aqreset\*(Aq, \& \*(Aqmy_set\*(Aq => \*(Aqset\*(Aq, \& \*(Aqmy_starts_with\*(Aq => \*(Aqstarts_with\*(Aq, \& \*(Aqmy_starts_with_i\*(Aq => \*(Aqstarts_with_i\*(Aq, \& \*(Aqmy_substr\*(Aq => \*(Aqsubstr\*(Aq, \& \*(Aqmy_uc\*(Aq => \*(Aquc\*(Aq, \& }, \& ); \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a library of methods for Sub::HandlesVia. .SH "DELEGATABLE METHODS" .IX Header "DELEGATABLE METHODS" .ie n .SS """append( $tail )""" .el .SS "\f(CWappend( $tail )\fP" .IX Subsection "append( $tail )" Arguments: \fBStr\fR. .PP Appends another string to the end of the current string and updates the attribute. .PP .Vb 3 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& $object\->my_append( \*(Aqbar\*(Aq ); \& say $object\->attr; ## ==> \*(Aqfoobar\*(Aq .Ve .ie n .SS """chomp()""" .el .SS "\f(CWchomp()\fP" .IX Subsection "chomp()" Like \f(CW\*(C`chomp\*(C'\fR from perlfunc. .ie n .SS """chop()""" .el .SS "\f(CWchop()\fP" .IX Subsection "chop()" Like \f(CW\*(C`chop\*(C'\fR from perlfunc. .ie n .SS """clear()""" .el .SS "\f(CWclear()\fP" .IX Subsection "clear()" Sets the string to the empty string. .PP .Vb 3 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& $object\->my_clear; \& say $object\->attr; ## nothing .Ve .ie n .SS """cmp( $str )""" .el .SS "\f(CWcmp( $str )\fP" .IX Subsection "cmp( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`$object\->attr cmp $str\*(C'\fR. .ie n .SS """cmpi( $str )""" .el .SS "\f(CWcmpi( $str )\fP" .IX Subsection "cmpi( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`fc($object\->attr) cmp fc($str)\*(C'\fR. Uses \f(CW\*(C`lc\*(C'\fR instead of \f(CW\*(C`fc\*(C'\fR in versions of Perl older than 5.16. .ie n .SS """contains( $str )""" .el .SS "\f(CWcontains( $str )\fP" .IX Subsection "contains( $str )" Arguments: \fBStr\fR. .PP Returns true iff the string contains \f(CW$str\fR. .ie n .SS """contains_i( $str )""" .el .SS "\f(CWcontains_i( $str )\fP" .IX Subsection "contains_i( $str )" Arguments: \fBStr\fR. .PP Returns true iff the string contains \f(CW$str\fR case-insensitvely. .ie n .SS """ends_with( $tail )""" .el .SS "\f(CWends_with( $tail )\fP" .IX Subsection "ends_with( $tail )" Arguments: \fBStr\fR. .PP Returns true iff the string ends with \f(CW$tail\fR. .ie n .SS """ends_with_i( $tail )""" .el .SS "\f(CWends_with_i( $tail )\fP" .IX Subsection "ends_with_i( $tail )" Arguments: \fBStr\fR. .PP Returns true iff the string ends with \f(CW$tail\fR case-insensitvely. .ie n .SS """eq( $str )""" .el .SS "\f(CWeq( $str )\fP" .IX Subsection "eq( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`$object\->attr eq $str\*(C'\fR. .ie n .SS """eqi( $str )""" .el .SS "\f(CWeqi( $str )\fP" .IX Subsection "eqi( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`fc($object\->attr) eq fc($str)\*(C'\fR. Uses \f(CW\*(C`lc\*(C'\fR instead of \f(CW\*(C`fc\*(C'\fR in versions of Perl older than 5.16. .ie n .SS """fc()""" .el .SS "\f(CWfc()\fP" .IX Subsection "fc()" Returns \f(CW\*(C`fc($object\->attr)\*(C'\fR. .ie n .SS """ge( $str )""" .el .SS "\f(CWge( $str )\fP" .IX Subsection "ge( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`$object\->attr ge $str\*(C'\fR. .ie n .SS """gei( $str )""" .el .SS "\f(CWgei( $str )\fP" .IX Subsection "gei( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`fc($object\->attr) ge fc($str)\*(C'\fR. Uses \f(CW\*(C`lc\*(C'\fR instead of \f(CW\*(C`fc\*(C'\fR in versions of Perl older than 5.16. .ie n .SS """get()""" .el .SS "\f(CWget()\fP" .IX Subsection "get()" Gets the current value of the string. .PP .Vb 2 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& say $object\->my_get; ## ==> \*(Aqfoo\*(Aq .Ve .ie n .SS """gt( $str )""" .el .SS "\f(CWgt( $str )\fP" .IX Subsection "gt( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`$object\->attr gt $str\*(C'\fR. .ie n .SS """gti( $str )""" .el .SS "\f(CWgti( $str )\fP" .IX Subsection "gti( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`fc($object\->attr) gt fc($str)\*(C'\fR. Uses \f(CW\*(C`lc\*(C'\fR instead of \f(CW\*(C`fc\*(C'\fR in versions of Perl older than 5.16. .ie n .SS """inc()""" .el .SS "\f(CWinc()\fP" .IX Subsection "inc()" Performs \f(CW\*(C`++\*(C'\fR on the string. .ie n .SS """lc()""" .el .SS "\f(CWlc()\fP" .IX Subsection "lc()" Returns \f(CW\*(C`lc($object\->attr)\*(C'\fR. .ie n .SS """le( $str )""" .el .SS "\f(CWle( $str )\fP" .IX Subsection "le( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`$object\->attr le $str\*(C'\fR. .ie n .SS """lei( $str )""" .el .SS "\f(CWlei( $str )\fP" .IX Subsection "lei( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`fc($object\->attr) le fc($str)\*(C'\fR. Uses \f(CW\*(C`lc\*(C'\fR instead of \f(CW\*(C`fc\*(C'\fR in versions of Perl older than 5.16. .ie n .SS """length()""" .el .SS "\f(CWlength()\fP" .IX Subsection "length()" Like \f(CW\*(C`length\*(C'\fR from perlfunc. .PP .Vb 2 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& say $object\->my_length; ## ==> 3 .Ve .ie n .SS """lt( $str )""" .el .SS "\f(CWlt( $str )\fP" .IX Subsection "lt( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`$object\->attr lt $str\*(C'\fR. .ie n .SS """lti( $str )""" .el .SS "\f(CWlti( $str )\fP" .IX Subsection "lti( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`fc($object\->attr) lt fc($str)\*(C'\fR. Uses \f(CW\*(C`lc\*(C'\fR instead of \f(CW\*(C`fc\*(C'\fR in versions of Perl older than 5.16. .ie n .SS """match( $regexp )""" .el .SS "\f(CWmatch( $regexp )\fP" .IX Subsection "match( $regexp )" Arguments: \fBStr|RegexpRef\fR. .PP Returns true iff the string matches the regexp. .PP .Vb 4 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& if ( $object\->my_match( \*(Aq^f..$\*(Aq ) ) { \& say \*(Aqmatched!\*(Aq; \& } .Ve .ie n .SS """match_i( $regexp )""" .el .SS "\f(CWmatch_i( $regexp )\fP" .IX Subsection "match_i( $regexp )" Arguments: \fBStr|RegexpRef\fR. .PP Returns true iff the string matches the regexp case-insensitively. .PP .Vb 4 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& if ( $object\->my_match_i( \*(Aq^F..$\*(Aq ) ) { \& say \*(Aqmatched!\*(Aq; \& } .Ve .ie n .SS """ne( $str )""" .el .SS "\f(CWne( $str )\fP" .IX Subsection "ne( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`$object\->attr ne $str\*(C'\fR. .ie n .SS """nei( $str )""" .el .SS "\f(CWnei( $str )\fP" .IX Subsection "nei( $str )" Arguments: \fBStr\fR. .PP Returns \f(CW\*(C`fc($object\->attr) ne fc($str)\*(C'\fR. Uses \f(CW\*(C`lc\*(C'\fR instead of \f(CW\*(C`fc\*(C'\fR in versions of Perl older than 5.16. .ie n .SS """prepend( $head )""" .el .SS "\f(CWprepend( $head )\fP" .IX Subsection "prepend( $head )" Arguments: \fBStr\fR. .PP Prepends another string to the start of the current string and updates the attribute. .PP .Vb 3 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& $object\->my_prepend( \*(Aqbar\*(Aq ); \& say $object\->attr; ## ==> \*(Aqbarfoo\*(Aq .Ve .ie n .SS """replace( $regexp, $replacement )""" .el .SS "\f(CWreplace( $regexp, $replacement )\fP" .IX Subsection "replace( $regexp, $replacement )" Arguments: \fBStr|RegexpRef\fR, \fBStr|CodeRef\fR. .PP Replaces the first regexp match within the string with the replacement string. .PP .Vb 3 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& $object\->my_replace( \*(Aqo\*(Aq => \*(Aqa\*(Aq ); \& say $object\->attr; ## ==> \*(Aqfao\*(Aq \& \& my $object2 = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& $object2\->my_replace( qr/O/i => sub { return \*(Aqe\*(Aq } ); \& say $object2\->attr; ## ==> \*(Aqfeo\*(Aq .Ve .ie n .SS """replace_globally( $regexp, $replacement )""" .el .SS "\f(CWreplace_globally( $regexp, $replacement )\fP" .IX Subsection "replace_globally( $regexp, $replacement )" Arguments: \fBStr|RegexpRef\fR, \fBStr|CodeRef\fR. .PP Replaces the all regexp matches within the string with the replacement string. .PP .Vb 3 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& $object\->my_replace_globally( \*(Aqo\*(Aq => \*(Aqa\*(Aq ); \& say $object\->attr; ## ==> \*(Aqfaa\*(Aq \& \& my $object2 = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& $object2\->my_replace_globally( qr/O/i => sub { return \*(Aqe\*(Aq } ); \& say $object2\->attr; ## ==> \*(Aqfee\*(Aq .Ve .ie n .SS """reset()""" .el .SS "\f(CWreset()\fP" .IX Subsection "reset()" Resets the attribute to its default value, or an empty string if it has no default. .ie n .SS """set( $value )""" .el .SS "\f(CWset( $value )\fP" .IX Subsection "set( $value )" Arguments: \fBStr\fR. .PP Sets the string to a new value. .PP .Vb 3 \& my $object = My::Class\->new( attr => \*(Aqfoo\*(Aq ); \& $object\->my_set( \*(Aqbar\*(Aq ); \& say $object\->attr; ## ==> \*(Aqbar\*(Aq .Ve .ie n .SS """starts_with( $head )""" .el .SS "\f(CWstarts_with( $head )\fP" .IX Subsection "starts_with( $head )" Arguments: \fBStr\fR. .PP Returns true iff the string starts with \f(CW$head\fR. .ie n .SS """starts_with_i( $head )""" .el .SS "\f(CWstarts_with_i( $head )\fP" .IX Subsection "starts_with_i( $head )" Arguments: \fBStr\fR. .PP Returns true iff the string starts with \f(CW$head\fR case-insensitvely. .ie n .SS """substr( $start, $length?, $replacement? )""" .el .SS "\f(CWsubstr( $start, $length?, $replacement? )\fP" .IX Subsection "substr( $start, $length?, $replacement? )" Arguments: \fBInt\fR, \fBOptional[Int]\fR, \fBOptional[Str]\fR. .PP Like \f(CW\*(C`substr\*(C'\fR from perlfunc, but is not an lvalue. .ie n .SS """uc()""" .el .SS "\f(CWuc()\fP" .IX Subsection "uc()" Returns \f(CW\*(C`uc($object\->attr)\*(C'\fR. .SH "EXTENDED EXAMPLES" .IX Header "EXTENDED EXAMPLES" .SS "Using eq for Enum" .IX Subsection "Using eq for Enum" .Vb 2 \& use strict; \& use warnings; \& \& package My::Person { \& use Moo; \& use Sub::HandlesVia; \& use Types::Standard qw( Str Enum ); \& \& has name => ( \& is => \*(Aqro\*(Aq, \& isa => Str, \& required => 1, \& ); \& \& has status => ( \& is => \*(Aqrwp\*(Aq, \& isa => Enum[ \*(Aqalive\*(Aq, \*(Aqdead\*(Aq ], \& handles_via => \*(AqString\*(Aq, \& handles => { \& is_alive => [ eq => \*(Aqalive\*(Aq ], \& is_dead => [ eq => \*(Aqdead\*(Aq ], \& kill => [ set => \*(Aqdead\*(Aq ], \& }, \& default => \*(Aqalive\*(Aq, \& ); \& \& # Note: method modifiers work on delegated methods \& # \& before kill => sub { \& my $self = shift; \& warn "overkill" if $self\->is_dead; \& }; \& } \& \& my $bob = My::Person\->new( name => \*(AqRobert\*(Aq ); \& say $bob\->is_alive; ## ==> true \& say $bob\->is_dead; ## ==> false \& $bob\->kill; \& say $bob\->is_alive; ## ==> false \& say $bob\->is_dead; ## ==> true .Ve .PP See also Sub::HandlesVia::HandlerLibrary::Enum, MooX::Enumeration and MooseX::Enumeration. .SS "Match with curried regexp" .IX Subsection "Match with curried regexp" .Vb 2 \& use strict; \& use warnings; \& \& package My::Component { \& use Moo; \& use Sub::HandlesVia; \& use Types::Standard qw( Str Int ); \& \& has id => ( \& is => \*(Aqro\*(Aq, \& isa => Int, \& required => 1, \& ); \& \& has name => ( \& is => \*(Aqro\*(Aq, \& isa => Str, \& required => 1, \& handles_via => \*(AqString\*(Aq, \& handles => { \& name_is_safe_filename => [ match => qr/\eA[A\-Za\-z0\-9]+\ez/ ], \& _lc_name => \*(Aqlc\*(Aq, \& }, \& ); \& \& sub config_filename { \& my $self = shift; \& if ( $self\->name_is_safe_filename ) { \& return sprintf( \*(Aq%s.ini\*(Aq, $self\->_lc_name ); \& } \& return sprintf( \*(Aqcomponent\-%d.ini\*(Aq, $self\->id ); \& } \& } \& \& my $foo = My::Component\->new( id => 42, name => \*(AqFoo\*(Aq ); \& say $foo\->config_filename; ## ==> \*(Aqfoo.ini\*(Aq \& \& my $bar4 = My::Component\->new( id => 99, name => \*(AqBar #4\*(Aq ); \& say $bar4\->config_filename; ## ==> \*(Aqcomponent\-99.ini\*(Aq .Ve .SH "BUGS" .IX Header "BUGS" Please report any bugs to . .SH "SEE ALSO" .IX Header "SEE ALSO" Sub::HandlesVia. .SH "AUTHOR" .IX Header "AUTHOR" Toby Inkster . .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" This software is copyright (c) 2020, 2022 by Toby Inkster. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. .SH "DISCLAIMER OF WARRANTIES" .IX Header "DISCLAIMER OF WARRANTIES" \&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0