1Sub::HandlesVia::HandleUrsLeirbrCaornyt:r:iSbturtieSndugb(P:3e:)rHlanDdolceusmVeinat:a:tHiaonndlerLibrary::String(3)
2
3
4

NAME

6       Sub::HandlesVia::HandlerLibrary::String - library of string-related
7       methods
8

SYNOPSIS

10         package My::Class {
11           use Moo;
12           use Sub::HandlesVia;
13           use Types::Standard 'Str';
14           has attr => (
15             is => 'rwp',
16             isa => Str,
17             handles_via => 'String',
18             handles => {
19               'my_append' => 'append',
20               'my_chomp' => 'chomp',
21               'my_chop' => 'chop',
22               'my_clear' => 'clear',
23               'my_cmp' => 'cmp',
24               'my_cmpi' => 'cmpi',
25               'my_contains' => 'contains',
26               'my_contains_i' => 'contains_i',
27               'my_ends_with' => 'ends_with',
28               'my_ends_with_i' => 'ends_with_i',
29               'my_eq' => 'eq',
30               'my_eqi' => 'eqi',
31               'my_fc' => 'fc',
32               'my_ge' => 'ge',
33               'my_gei' => 'gei',
34               'my_get' => 'get',
35               'my_gt' => 'gt',
36               'my_gti' => 'gti',
37               'my_inc' => 'inc',
38               'my_lc' => 'lc',
39               'my_le' => 'le',
40               'my_lei' => 'lei',
41               'my_length' => 'length',
42               'my_lt' => 'lt',
43               'my_lti' => 'lti',
44               'my_match' => 'match',
45               'my_match_i' => 'match_i',
46               'my_ne' => 'ne',
47               'my_nei' => 'nei',
48               'my_prepend' => 'prepend',
49               'my_replace' => 'replace',
50               'my_replace_globally' => 'replace_globally',
51               'my_reset' => 'reset',
52               'my_set' => 'set',
53               'my_starts_with' => 'starts_with',
54               'my_starts_with_i' => 'starts_with_i',
55               'my_substr' => 'substr',
56               'my_uc' => 'uc',
57             },
58           );
59         }
60

DESCRIPTION

62       This is a library of methods for Sub::HandlesVia.
63

DELEGATABLE METHODS

65   "append( $tail )"
66       Arguments: Str.
67
68       Appends another string to the end of the current string and updates the
69       attribute.
70
71         my $object = My::Class->new( attr => 'foo' );
72         $object->my_append( 'bar' );
73         say $object->attr; ## ==> 'foobar'
74
75   "chomp()"
76       Like "chomp" from perlfunc.
77
78   "chop()"
79       Like "chop" from perlfunc.
80
81   "clear()"
82       Sets the string to the empty string.
83
84         my $object = My::Class->new( attr => 'foo' );
85         $object->my_clear;
86         say $object->attr; ## nothing
87
88   "cmp( $str )"
89       Arguments: Str.
90
91       Returns "$object->attr cmp $str".
92
93   "cmpi( $str )"
94       Arguments: Str.
95
96       Returns "fc($object->attr) cmp fc($str)". Uses "lc" instead of "fc" in
97       versions of Perl older than 5.16.
98
99   "contains( $str )"
100       Arguments: Str.
101
102       Returns true iff the string contains $str.
103
104   "contains_i( $str )"
105       Arguments: Str.
106
107       Returns true iff the string contains $str case-insensitvely.
108
109   "ends_with( $tail )"
110       Arguments: Str.
111
112       Returns true iff the string ends with $tail.
113
114   "ends_with_i( $tail )"
115       Arguments: Str.
116
117       Returns true iff the string ends with $tail case-insensitvely.
118
119   "eq( $str )"
120       Arguments: Str.
121
122       Returns "$object->attr eq $str".
123
124   "eqi( $str )"
125       Arguments: Str.
126
127       Returns "fc($object->attr) eq fc($str)". Uses "lc" instead of "fc" in
128       versions of Perl older than 5.16.
129
130   "fc()"
131       Returns "fc($object->attr)".
132
133   "ge( $str )"
134       Arguments: Str.
135
136       Returns "$object->attr ge $str".
137
138   "gei( $str )"
139       Arguments: Str.
140
141       Returns "fc($object->attr) ge fc($str)". Uses "lc" instead of "fc" in
142       versions of Perl older than 5.16.
143
144   "get()"
145       Gets the current value of the string.
146
147         my $object = My::Class->new( attr => 'foo' );
148         say $object->my_get; ## ==> 'foo'
149
150   "gt( $str )"
151       Arguments: Str.
152
153       Returns "$object->attr gt $str".
154
155   "gti( $str )"
156       Arguments: Str.
157
158       Returns "fc($object->attr) gt fc($str)". Uses "lc" instead of "fc" in
159       versions of Perl older than 5.16.
160
161   "inc()"
162       Performs "++" on the string.
163
164   "lc()"
165       Returns "lc($object->attr)".
166
167   "le( $str )"
168       Arguments: Str.
169
170       Returns "$object->attr le $str".
171
172   "lei( $str )"
173       Arguments: Str.
174
175       Returns "fc($object->attr) le fc($str)". Uses "lc" instead of "fc" in
176       versions of Perl older than 5.16.
177
178   "length()"
179       Like "length" from perlfunc.
180
181         my $object = My::Class->new( attr => 'foo' );
182         say $object->my_length; ## ==> 3
183
184   "lt( $str )"
185       Arguments: Str.
186
187       Returns "$object->attr lt $str".
188
189   "lti( $str )"
190       Arguments: Str.
191
192       Returns "fc($object->attr) lt fc($str)". Uses "lc" instead of "fc" in
193       versions of Perl older than 5.16.
194
195   "match( $regexp )"
196       Arguments: Str|RegexpRef.
197
198       Returns true iff the string matches the regexp.
199
200         my $object = My::Class->new( attr => 'foo' );
201         if ( $object->my_match( '^f..$' ) ) {
202           say 'matched!';
203         }
204
205   "match_i( $regexp )"
206       Arguments: Str|RegexpRef.
207
208       Returns true iff the string matches the regexp case-insensitively.
209
210         my $object = My::Class->new( attr => 'foo' );
211         if ( $object->my_match_i( '^F..$' ) ) {
212           say 'matched!';
213         }
214
215   "ne( $str )"
216       Arguments: Str.
217
218       Returns "$object->attr ne $str".
219
220   "nei( $str )"
221       Arguments: Str.
222
223       Returns "fc($object->attr) ne fc($str)". Uses "lc" instead of "fc" in
224       versions of Perl older than 5.16.
225
226   "prepend( $head )"
227       Arguments: Str.
228
229       Prepends another string to the start of the current string and updates
230       the attribute.
231
232         my $object = My::Class->new( attr => 'foo' );
233         $object->my_prepend( 'bar' );
234         say $object->attr; ## ==> 'barfoo'
235
236   "replace( $regexp, $replacement )"
237       Arguments: Str|RegexpRef, Str|CodeRef.
238
239       Replaces the first regexp match within the string with the replacement
240       string.
241
242         my $object = My::Class->new( attr => 'foo' );
243         $object->my_replace( 'o' => 'a' );
244         say $object->attr; ## ==> 'fao'
245
246         my $object2 = My::Class->new( attr => 'foo' );
247         $object2->my_replace( qr/O/i => sub { return 'e' } );
248         say $object2->attr; ## ==> 'feo'
249
250   "replace_globally( $regexp, $replacement )"
251       Arguments: Str|RegexpRef, Str|CodeRef.
252
253       Replaces the all regexp matches within the string with the replacement
254       string.
255
256         my $object = My::Class->new( attr => 'foo' );
257         $object->my_replace_globally( 'o' => 'a' );
258         say $object->attr; ## ==> 'faa'
259
260         my $object2 = My::Class->new( attr => 'foo' );
261         $object2->my_replace_globally( qr/O/i => sub { return 'e' } );
262         say $object2->attr; ## ==> 'fee'
263
264   "reset()"
265       Resets the attribute to its default value, or an empty string if it has
266       no default.
267
268   "set( $value )"
269       Arguments: Str.
270
271       Sets the string to a new value.
272
273         my $object = My::Class->new( attr => 'foo' );
274         $object->my_set( 'bar' );
275         say $object->attr; ## ==> 'bar'
276
277   "starts_with( $head )"
278       Arguments: Str.
279
280       Returns true iff the string starts with $head.
281
282   "starts_with_i( $head )"
283       Arguments: Str.
284
285       Returns true iff the string starts with $head case-insensitvely.
286
287   "substr( $start, $length?, $replacement? )"
288       Arguments: Int, Optional[Int], Optional[Str].
289
290       Like "substr" from perlfunc, but is not an lvalue.
291
292   "uc()"
293       Returns "uc($object->attr)".
294

EXTENDED EXAMPLES

296   Using eq for Enum
297         use strict;
298         use warnings;
299
300         package My::Person {
301           use Moo;
302           use Sub::HandlesVia;
303           use Types::Standard qw( Str Enum );
304
305           has name => (
306             is => 'ro',
307             isa => Str,
308             required => 1,
309           );
310
311           has status => (
312             is => 'rwp',
313             isa => Enum[ 'alive', 'dead' ],
314             handles_via => 'String',
315             handles => {
316               is_alive => [ eq  => 'alive' ],
317               is_dead  => [ eq  => 'dead' ],
318               kill     => [ set => 'dead' ],
319             },
320             default => 'alive',
321           );
322
323           # Note: method modifiers work on delegated methods
324           #
325           before kill => sub {
326             my $self = shift;
327             warn "overkill" if $self->is_dead;
328           };
329         }
330
331         my $bob = My::Person->new( name => 'Robert' );
332         say $bob->is_alive; ## ==> true
333         say $bob->is_dead;  ## ==> false
334         $bob->kill;
335         say $bob->is_alive; ## ==> false
336         say $bob->is_dead;  ## ==> true
337
338       See also MooX::Enumeration and MooseX::Enumeration.
339
340   Match with curried regexp
341         use strict;
342         use warnings;
343
344         package My::Component {
345           use Moo;
346           use Sub::HandlesVia;
347           use Types::Standard qw( Str Int );
348
349           has id => (
350             is => 'ro',
351             isa => Int,
352             required => 1,
353           );
354
355           has name => (
356             is => 'ro',
357             isa => Str,
358             required => 1,
359             handles_via => 'String',
360             handles => {
361               name_is_safe_filename => [ match => qr/\A[A-Za-z0-9]+\z/ ],
362               _lc_name => 'lc',
363             },
364           );
365
366           sub config_filename {
367             my $self = shift;
368             if ( $self->name_is_safe_filename ) {
369               return sprintf( '%s.ini', $self->_lc_name );
370             }
371             return sprintf( 'component-%d.ini', $self->id );
372           }
373         }
374
375         my $foo = My::Component->new( id => 42, name => 'Foo' );
376         say $foo->config_filename; ## ==> 'foo.ini'
377
378         my $bar4 = My::Component->new( id => 99, name => 'Bar #4' );
379         say $bar4->config_filename; ## ==> 'component-99.ini'
380

BUGS

382       Please report any bugs to
383       <https://github.com/tobyink/p5-sub-handlesvia/issues>.
384

SEE ALSO

386       Sub::HandlesVia.
387

AUTHOR

389       Toby Inkster <tobyink@cpan.org>.
390

392       This software is copyright (c) 2020, 2022 by Toby Inkster.
393
394       This is free software; you can redistribute it and/or modify it under
395       the same terms as the Perl 5 programming language system itself.
396

DISCLAIMER OF WARRANTIES

398       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
399       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
400       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
401
402
403
404perl v5.36.0                      202S2u-b1:2:-H1a7ndlesVia::HandlerLibrary::String(3)
Impressum