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 Sub::HandlesVia::HandlerLibrary::Enum, MooX::Enumeration and
339       MooseX::Enumeration.
340
341   Match with curried regexp
342         use strict;
343         use warnings;
344
345         package My::Component {
346           use Moo;
347           use Sub::HandlesVia;
348           use Types::Standard qw( Str Int );
349
350           has id => (
351             is => 'ro',
352             isa => Int,
353             required => 1,
354           );
355
356           has name => (
357             is => 'ro',
358             isa => Str,
359             required => 1,
360             handles_via => 'String',
361             handles => {
362               name_is_safe_filename => [ match => qr/\A[A-Za-z0-9]+\z/ ],
363               _lc_name => 'lc',
364             },
365           );
366
367           sub config_filename {
368             my $self = shift;
369             if ( $self->name_is_safe_filename ) {
370               return sprintf( '%s.ini', $self->_lc_name );
371             }
372             return sprintf( 'component-%d.ini', $self->id );
373           }
374         }
375
376         my $foo = My::Component->new( id => 42, name => 'Foo' );
377         say $foo->config_filename; ## ==> 'foo.ini'
378
379         my $bar4 = My::Component->new( id => 99, name => 'Bar #4' );
380         say $bar4->config_filename; ## ==> 'component-99.ini'
381

BUGS

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

SEE ALSO

387       Sub::HandlesVia.
388

AUTHOR

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

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

DISCLAIMER OF WARRANTIES

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