lib/Moose/Meta/Attribute/Native/Trait/String.pm

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