lib/MooseX/AttributeHelpers/Trait/String.pm

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