lib/MooseX/AttributeHelpers/Trait/String.pm

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