lib/MooseX/AttributeHelpers/String.pm

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