[libmoosex-has-sugar-perl] 115/120: Add README.mkdn

[Intrigeri]

This is an automated email from the git hooks/post-receive script.

intrigeri pushed a commit to annotated tag 0.05070422-source
in repository libmoosex-has-sugar-perl.

commit 01a56359f7e63abcb2e8e3d1386d0dc38f8bc346
Author: Kent Fredric <kentfredric at gmail.com>
Date:   Wed Nov 20 20:00:07 2013 +1300

    Add README.mkdn
---
 README.mkdn | 239 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 239 insertions(+)

diff --git a/README.mkdn b/README.mkdn
new file mode 100644
index 0000000..0d0c0e0
--- /dev/null
+++ b/README.mkdn
@@ -0,0 +1,239 @@
+# NAME
+
+MooseX::Has::Sugar - Sugar Syntax for moose 'has' fields
+
+# VERSION
+
+version 0.05070422
+
+# SYNOPSIS
+
+[Moose](https://metacpan.org/pod/Moose) `has` syntax is generally fine, but sometimes one gets bothered with
+the constant typing of string quotes for things. [The MooseX::Types module](https://metacpan.org/pod/MooseX::Types) exists and in
+many ways reduces the need for constant string creation.
+
+## Primary Benefits at a Glance
+
+### Reduced Typing in `has` declarations.
+
+The constant need to type `=>` and `''` is fine for one-off cases, but
+the instant you have more than about 4 attributes it starts to get annoying.
+
+### More compact declarations.
+
+Reduces much of the redundant typing in most cases, which makes your life easier,
+and makes it take up less visual space, which makes it faster to read.
+
+### No String Worries
+
+Strings are often problematic, due to white-space etc. Noted that if you do
+happen to mess them up, Moose should at _least_ warn you that you've done
+something daft. Using this alleviates that worry.
+
+## Before this Module.
+
+### Classical Moose
+
+    has foo => (
+            isa => 'Str',
+            is  => 'ro',
+            required => 1,
+    );
+
+    has bar => (
+            isa => 'Str',
+            is => 'rw'
+            lazy_build => 1,
+    );
+
+### Lazy Evil way to do it:
+
+__PLEASE DO NOT DO THIS__
+
+    has qw( foo isa Str is ro required 1 );
+    has qw( bar isa Str is rw lazy_build 1 );
+
+## With this module
+
+( and with MooseX::Types )
+
+    use MooseX::Types::Moose qw( Str );
+    use MooseX::Has::Sugar;
+
+    has foo => (
+            isa => Str,
+            ro,
+            required,
+    );
+    has bar => (
+            isa => Str,
+            rw,
+            lazy_build,
+    );
+
+Or even
+
+    use MooseX::Types::Moose qw( Str );
+    use MooseX::Has::Sugar;
+
+    has foo => ( isa => Str, ro,  required, );
+    has bar => ( isa => Str, rw,  lazy_build, );
+
+## Alternative Forms
+
+### Basic `is` Expansion Only
+
+( using [::Sugar::Minimal](https://metacpan.org/pod/MooseX::Has::Sugar::Minimal) instead )
+
+    use MooseX::Types::Moose qw( Str );
+    use MooseX::Has::Sugar::Minimal;
+
+    has foo => (
+            isa => Str,
+            is  => ro,
+            required => 1,
+    );
+    has bar => (
+            isa => Str,
+            is => rw,
+            lazy_build => 1,
+    );
+
+### Attribute Expansions with Basic Expansions
+
+( Combining parts of this and [::Sugar::Minimal](https://metacpan.org/pod/MooseX::Has::Sugar::Minimal) )
+
+    use MooseX::Types::Moose qw( Str );
+    use MooseX::Has::Sugar::Minimal;
+    use MooseX::Has::Sugar qw( :attrs );
+
+    has foo => (
+            isa => Str,
+            is  => ro,
+            required,
+    );
+    has bar => (
+            isa => Str,
+            is => rw,
+            lazy_build,
+    );
+
+# EXPORT GROUPS
+
+## :default
+
+Since 0.0300, this exports all our syntax, the same as `:attrs :isattrs`.
+Primarily because I found you generally want all the sugar, not just part of it.
+This also gets rid of that nasty exclusion logic.
+
+## :isattrs
+
+This exports `ro`, `rw` and `bare` as lists, so they behave as stand-alone attrs like
+["lazy"](#lazy) does.
+
+    has foo => (
+            required,
+            isa => 'Str',
+            ro,
+    );
+
+__NOTE: This option is incompatible with [::Sugar::Minimal](https://metacpan.org/pod/MooseX::Has::Sugar::Minimal)__ : ["CONFLICTS"](#CONFLICTS)
+
+## :attrs
+
+This exports ["lazy"](#lazy) , ["lazy_build"](#lazy_build) and ["required"](#required), ["coerce"](#coerce), ["weak_ref"](#weak_ref)
+and ["auto_deref"](#auto_deref) as subs that assume positive.
+
+    has foo => (
+            required,
+            isa => 'Str',
+    );
+
+__NOTE: This option is incompatible with [MooseX::Types](https://metacpan.org/pod/MooseX::Types) and [Moose's Type Constraints Module](https://metacpan.org/pod/Moose::Util::TypeConstraints)__ : ["CONFLICTS"](#CONFLICTS)
+
+## :is
+
+__DEPRECATED__. See [::Sugar::Minimal](https://metacpan.org/pod/MooseX::Has::Sugar::Minimal) for the same functionality
+
+## :allattrs
+
+__DEPRECATED__, just use [":default"](#:default) or do
+
+    use MooseX::Has::Sugar;
+
+# EXPORTED FUNCTIONS
+
+## bare
+
+returns `('is','bare')`
+
+## ro
+
+returns `('is','ro')`
+
+## rw
+
+returns `('is','rw')`
+
+## required
+
+returns `('required',1)`
+
+## lazy
+
+returns `('lazy',1)`
+
+## lazy\_build
+
+returns `('lazy_build',1)`
+
+## weak\_ref
+
+returns `('weak_ref',1)`
+
+## coerce
+
+returns `('coerce',1)`
+
+__WARNING:__ Conflict with [MooseX::Types](https://metacpan.org/pod/MooseX::Types) and [Moose::Util::TypeConstraints](https://metacpan.org/pod/Moose::Util::TypeConstraints), see ["CONFLICTS"](#CONFLICTS).
+
+## auto\_deref
+
+returns `('auto_deref',1)`
+
+# CONFLICTS
+
+## MooseX::Has::Sugar::Minimal
+
+## MooseX::Has::Sugar::Saccharin
+
+This module is not intended to be used in conjunction with
+ [::Sugar::Minimal](https://metacpan.org/pod/MooseX::Has::Sugar::Minimal) or [::Sugar::Saccharin](https://metacpan.org/pod/MooseX::Has::Sugar::Saccharin)
+
+We export many of the same symbols and its just not very sensible.
+
+## MooseX::Types
+
+## Moose::Util::TypeConstraints
+
+due to exporting the ["coerce"](#coerce) symbol, using us in the same scope as a call to
+
+    use MooseX::Types ....
+
+or
+    use Moose::Util::TypeConstraints
+
+will result in a symbol collision.
+
+We recommend using and creating proper type libraries instead, ( which will absolve you entirely of the need to use MooseX::Types and MooseX::Has::Sugar(::\*)? in the same scope )
+
+# AUTHOR
+
+Kent Fredric <kentnl at cpan.org>
+
+# COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2013 by Kent Fredric.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libmoosex-has-sugar-perl.git