extract README and mkdn from module

README

@@ -1,27 +1,112 @@
-This is Perl module MouseX::AttributeHelpers.
+NAME
+    MouseX::AttributeHelpers - Extend your attribute interfaces
 
-INSTALLATION
+SYNOPSIS
+        package MyClass;
 
-MouseX::AttributeHelpers installation is straightforward. If your CPAN shell is set up,
-you should just be able to do
+        use Mouse;
+        use MouseX::AttributeHelpers;
 
-    % cpan MouseX::AttributeHelpers
+        has 'mapping' => (
+            metaclass => 'Collection::Hash',
+            is        => 'rw',
+            isa       => 'HashRef',
+            default   => sub { +{} },
+            provides  => {
+                exists => 'exists_in_mapping',
+                keys   => 'ids_in_mapping',
+                get    => 'get_mapping',
+                set    => 'set_mapping',
+            },
+        );
 
-Download it, unpack it, then build it as per the usual:
+        package main;
 
-    % perl Makefile.PL
-    % make && make test
+        my $obj = MyClass->new;
+        $obj->set_quantity(10);      # quantity => 10
+        $obj->set_mapping(4, 'foo'); # 4 => 'foo'
+        $obj->set_mapping(5, 'bar'); # 5 => 'bar'
+        $obj->set_mapping(6, 'baz'); # 6 => 'baz'
 
-Then install it:
+        # prints 'bar'
+        print $obj->get_mapping(5) if $obj->exists_in_mapping(5);
 
-    % make install
+        # prints '4, 5, 6'
+        print join ', ', $obj->ids_in_mapping;
 
-DOCUMENTATION
+DESCRIPTION
+    MouseX::AttributeHelpers provides commonly used attribute helper methods
+    for more specific types of data.
 
-MouseX::AttributeHelpers documentation is available as in POD. So you can do:
+    As seen in the "SYNOPSIS", you specify the extension via the "metaclass"
+    parameter.
 
-    % perldoc MouseX::AttributeHelpers
+PARAMETERS
+  provides
+    This points to a hashref that uses "provider" for the keys and "method"
+    for the values. The method will be added to the object itself and do
+    what you want.
 
-to read the documentation online with your favorite pager.
+  curries
+    This points to a hashref that uses "provider" for the keys and has two
+    choices for the value:
+
+    You can supply "{ method => \@args }" for the values. The method will be
+    added to the object itself (always using @args as the beginning
+    arguments).
+
+    Another approach to curry a method provider is to supply a coderef
+    instead of an arrayref. The code ref takes $self, $body, and any
+    additional arguments passed to the final method.
+
+METHOD PROVIDERS
+  Counter
+    Methods for incrementing and decrementing a counter attribute.
+
+  Number
+    Common numerical operations.
+
+  String
+    Common methods for string values.
+
+  Bool
+    Common methods for boolean values.
+
+  Collection::List
+    Common list methods for array references.
+
+  Collection::Array
+    Common methods for array references.
+
+  Collection::ImmutableHash
+    Common methods for hash references.
+
+  Collection::Hash
+    Common additional methods for hash references.
+
+  Collection::Bag
+    Methods for incrementing and decrementing a value of collection.
+
+AUTHOR
+    NAKAGAWA Masaki <masaki@cpan.org>
+
+THANKS TO
+    "AUTHOR" in MooseX::AttributeHelpers
+
+LICENSE
+    This library is free software; you can redistribute it and/or modify it
+    under the same terms as Perl itself.
+
+SEE ALSO
+    Mouse
+
+    MouseX::AttributeHelpers::Counter, MouseX::AttributeHelpers::Number,
+    MouseX::AttributeHelpers::String, MouseX::AttributeHelpers::Bool,
+    MouseX::AttributeHelpers::Collection::List,
+    MouseX::AttributeHelpers::Collection::Array,
+    MouseX::AttributeHelpers::Collection::ImmutableHash,
+    MouseX::AttributeHelpers::Collection::Hash,
+    MouseX::AttributeHelpers::Collection::Bag
+
+    MooseX::AttributeHelpers
 
-NAKAGAWA Masaki

README.mkdn

@@ -0,0 +1,133 @@
+# NAME
+
+MouseX::AttributeHelpers - Extend your attribute interfaces
+
+# SYNOPSIS
+
+    package MyClass;
+
+    use Mouse;
+    use MouseX::AttributeHelpers;
+
+    has 'mapping' => (
+        metaclass => 'Collection::Hash',
+        is        => 'rw',
+        isa       => 'HashRef',
+        default   => sub { +{} },
+        provides  => {
+            exists => 'exists_in_mapping',
+            keys   => 'ids_in_mapping',
+            get    => 'get_mapping',
+            set    => 'set_mapping',
+        },
+    );
+
+    package main;
+
+    my $obj = MyClass->new;
+    $obj->set_quantity(10);      # quantity => 10
+    $obj->set_mapping(4, 'foo'); # 4 => 'foo'
+    $obj->set_mapping(5, 'bar'); # 5 => 'bar'
+    $obj->set_mapping(6, 'baz'); # 6 => 'baz'
+
+    # prints 'bar'
+    print $obj->get_mapping(5) if $obj->exists_in_mapping(5);
+
+    # prints '4, 5, 6'
+    print join ', ', $obj->ids_in_mapping;
+
+# DESCRIPTION
+
+MouseX::AttributeHelpers provides commonly used attribute helper
+methods for more specific types of data.
+
+As seen in the L</SYNOPSIS>, you specify the extension via the
+`metaclass` parameter.
+
+# PARAMETERS
+
+## provides
+
+This points to a hashref that uses `provider` for the keys and
+`method` for the values. The method will be added to the object
+itself and do what you want.
+
+## curries
+
+This points to a hashref that uses `provider` for the keys and
+has two choices for the value:
+
+You can supply `{ method => \@args }` for the values.
+The method will be added to the object itself (always using `@args`
+as the beginning arguments).
+
+Another approach to curry a method provider is to supply a coderef
+instead of an arrayref. The code ref takes `$self`, `$body`,
+and any additional arguments passed to the final method.
+
+# METHOD PROVIDERS
+
+## L<Counter|MouseX::AttributeHelpers::Counter>
+
+Methods for incrementing and decrementing a counter attribute.
+
+## L<Number|MouseX::AttributeHelpers::Number>
+
+Common numerical operations.
+
+## L<String|MouseX::AttributeHelpers::String>
+
+Common methods for string values.
+
+## L<Bool|MouseX::AttributeHelpers::Bool>
+
+Common methods for boolean values.
+
+## L<Collection::List|MouseX::AttributeHelpers::Collection::List>
+
+Common list methods for array references.
+
+## L<Collection::Array|MouseX::AttributeHelpers::Collection::Array>
+
+Common methods for array references.
+
+## L<Collection::ImmutableHash|MouseX::AttributeHelpers::Collection::ImmutableHash>
+
+Common methods for hash references.
+
+## L<Collection::Hash|MouseX::AttributeHelpers::Collection::Hash>
+
+Common additional methods for hash references.
+
+## L<Collection::Bag|MouseX::AttributeHelpers::Collection::Bag>
+
+Methods for incrementing and decrementing a value of collection.
+
+# AUTHOR
+
+NAKAGAWA Masaki <masaki@cpan.org>
+
+# THANKS TO
+
+L<MooseX::AttributeHelpers/AUTHOR>
+
+# LICENSE
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+# SEE ALSO
+
+[Mouse](http://search.cpan.org/search?mode=module&query=Mouse)
+
+[MouseX::AttributeHelpers::Counter](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::Counter),
+[MouseX::AttributeHelpers::Number](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::Number),
+[MouseX::AttributeHelpers::String](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::String),
+[MouseX::AttributeHelpers::Bool](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::Bool),
+[MouseX::AttributeHelpers::Collection::List](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::Collection::List),
+[MouseX::AttributeHelpers::Collection::Array](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::Collection::Array),
+[MouseX::AttributeHelpers::Collection::ImmutableHash](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::Collection::ImmutableHash),
+[MouseX::AttributeHelpers::Collection::Hash](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::Collection::Hash),
+[MouseX::AttributeHelpers::Collection::Bag](http://search.cpan.org/search?mode=module&query=MouseX::AttributeHelpers::Collection::Bag)
+
+[MooseX::AttributeHelpers](http://search.cpan.org/search?mode=module&query=MooseX::AttributeHelpers)