lib/Moose/AttributeHelpers/Trait/String.pm

   1
   2 package Moose::AttributeHelpers::Trait::String;
   3 use Moose::Role;
   4
   5 our $VERSION   = '0.85';
   6 $VERSION = eval $VERSION;
   7 our $AUTHORITY = 'cpan:STEVAN';
   8
   9 use Moose::AttributeHelpers::MethodProvider::String;
  10
  11 with 'Moose::AttributeHelpers::Trait::Base';
  12
  13 has 'method_provider' => (
  14     is        => 'ro',
  15     isa       => 'ClassName',
  16     predicate => 'has_method_provider',
  17     default   => 'Moose::AttributeHelpers::MethodProvider::String',
  18 );
  19
  20 sub helper_type { 'Str' }
  21
  22 sub _default_default { q{} }
  23 sub _default_is { 'rw' }
  24
  25 after '_check_handles_values' => sub {
  26     my $self    = shift;
  27     my $handles = $self->handles;
  28
  29     unless ( scalar keys %$handles ) {
  30         my $method_constructors = $self->method_constructors;
  31         my $attr_name           = $self->name;
  32
  33         foreach my $method ( keys %$method_constructors ) {
  34             $handles->{$method} = ( $method . '_' . $attr_name );
  35         }
  36     }
  37 };
  38
  39 no Moose::Role;
  40
  41 # register the alias ...
  42 package # hide me from search.cpan.org
  43     Moose::Meta::Attribute::Custom::Trait::String;
  44 sub register_implementation { 'Moose::AttributeHelpers::Trait::String' }
  45
  46 1;
  47
  48 __END__
  49
  50 =pod
  51
  52 =head1 NAME
  53
  54 Moose::AttributeHelpers::String
  55
  56 =head1 SYNOPSIS
  57
  58   package MyHomePage;
  59   use Moose;
  60   use Moose::AttributeHelpers;
  61
  62   has 'text' => (
  63       metaclass => 'String',
  64       is        => 'rw',
  65       isa       => 'Str',
  66       default   => q{},
  67       handles  => {
  68           add_text     => 'append',
  69           replace_text => 'replace',
  70       }
  71   );
  72
  73   my $page = MyHomePage->new();
  74   $page->add_text("foo"); # same as $page->text($page->text . "foo");
  75
  76 =head1 DESCRIPTION
  77
  78 This module provides a simple string attribute, to which mutating string
  79 operations can be applied more easily (no need to make an lvalue attribute
  80 metaclass or use temporary variables). Additional methods are provided for
  81 completion.
  82
  83 If your attribute definition does not include any of I<is>, I<isa>,
  84 I<default> or I<handles> but does use the C<String> metaclass,
  85 then this module applies defaults as in the L</SYNOPSIS>
  86 above. This allows for a very basic counter definition:
  87
  88   has 'foo' => (metaclass => 'String');
  89   $obj->append_foo;
  90
  91 =head1 METHODS
  92
  93 =over 4
  94
  95 =item B<meta>
  96
  97 =item B<method_provider>
  98
  99 =item B<has_method_provider>
 100
 101 =item B<helper_type>
 102
 103 =item B<process_options_for_handles>
 104
 105 Run before its superclass method.
 106
 107 =item B<check_handles_values>
 108
 109 Run after its superclass method.
 110
 111 =back
 112
 113 =head1 PROVIDED METHODS
 114
 115 It is important to note that all those methods do in place
 116 modification of the value stored in the attribute.
 117
 118 =over 4
 119
 120 =item I<inc>
 121
 122 Increments the value stored in this slot using the magical string autoincrement
 123 operator. Note that Perl doesn't provide analogous behavior in C<-->, so
 124 C<dec> is not available.
 125
 126 =item I<append> C<$string>
 127
 128 Append a string, like C<.=>.
 129
 130 =item I<prepend> C<$string>
 131
 132 Prepend a string.
 133
 134 =item I<replace> C<$pattern> C<$replacement>
 135
 136 Performs a regexp substitution (L<perlop/s>). There is no way to provide the
 137 C<g> flag, but code references will be accepted for the replacement, causing
 138 the regex to be modified with a single C<e>. C</smxi> can be applied using the
 139 C<qr> operator.
 140
 141 =item I<match> C<$pattern>
 142
 143 Like I<replace> but without the replacement. Provided mostly for completeness.
 144
 145 =item C<chop>
 146
 147 L<perlfunc/chop>
 148
 149 =item C<chomp>
 150
 151 L<perlfunc/chomp>
 152
 153 =item C<clear>
 154
 155 Sets the string to the empty string (not the value passed to C<default>).
 156
 157 =back
 158
 159 =head1 BUGS
 160
 161 All complex software has bugs lurking in it, and this module is no
 162 exception. If you find a bug please either email me, or add the bug
 163 to cpan-RT.
 164
 165 =head1 AUTHOR
 166
 167 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 168
 169 =head1 COPYRIGHT AND LICENSE
 170
 171 Copyright 2007-2009 by Infinity Interactive, Inc.
 172
 173 L<http://www.iinteractive.com>
 174
 175 This library is free software; you can redistribute it and/or modify
 176 it under the same terms as Perl itself.
 177
 178 =cut