lib/MooseX/AttributeHelpers/String.pm

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