lib/MooseX/AttributeHelpers/String.pm

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