File Coverage

blib/lib/Sympatic.pm

Criterion	Covered	Total	%
statement	32	36	88.8
branch	11	16	68.7
condition	2	2	100.0
subroutine	4	4	100.0
pod			n/a
total	49	58	84.4

package Sympatic;
our $VERSION = '0.2';
use strict;
use warnings;
require Import::Into;

sub import {

    my $to; # the NS to infect
    # Sympatic->import(@options)
    # Sympatic->import(to => $NS, @options)
    ('to' eq ( $_[1] // '' ))
    ? ( $to = $_[2], splice @_,0,3 )
    : ( $to = caller, shift );

    my %feature = qw<
      utf8all      .
      utf8         .
      utf8io       .
      oo           .
      class        .
      path         .
    >;

    English->import::into( $to, qw<  -no_match_vars > );
    feature->import::into( $to, qw< say state > );
    strict->import::into($to);
    warnings->import::into($to);
    Function::Parameters->import::into($to);

    while (@_) {

        # disable default features
        if ( $_[0] =~ /-(?
            utf8all |
            utf8    |
            utf8io  |
            oo      |
            class   |
            path
        )/x) {
            delete $feature{ $+{feature} };
            shift;
            next;
        }

        ...

    }

    $feature{path} and do { Path::Tiny->import::into($to) };

    $feature{oo} and do {
        ( $feature{class}
            ? 'Moo'
            : 'Moo::Role' )->import::into($to);
        MooX::LvalueAttribute->import::into($to);
    };

    $feature{utf8all} and do {
        utf8::all->import::into($to);
        delete $feature{$_} for qw<  utf8 utf8io >;
    };

    $feature{utf8} and do {
        utf8->import::into($to);
        feature->import::into( $to, qw< unicode_strings > );
    };

    $feature{utf8io} and do { 'open'->import::into( $to, qw< :UTF-8 :std > ) };

    # see https://github.com/pjf/autodie/commit/6ff9ff2b463af3083a02a7b5a2d727b8a224b970
    # TODO: is there a case when caller > 1 ?

    # $feature{autodie} and do {
    #      autodie->import::into(1);
    # }

}

1;

=encoding utf8

=head1 NAME

Sympatic - A more producive perl thanks to CPAN

=head1 STATUS

=for HTML




Any bug report or feedback that can help to improve C are very welcome.
The quickest way to report a bug in Sympatic is by sending email to
bug-Sympatic [at] rt.cpan.org. You can also report from the web using
L or even
L.

=head1 SYNOPSIS

    package Counter;
    use Sympatic;

    use Types::Standard qw< Int >;

    has qw( value is rw )
    , default => 0
    , lvalue  => 1
    , isa     => Int;

    method next { ++$self->value }
    method ( Int $add ) { $self->value += $add }

see L section for more details.

=head1 DESCRIPTION

The default behavior of L could be significantly
improved by the pragmas and CPAN modules so it can fit the expectations
of a community of developers and help them to enforce what they consider
as the best practices. For decades, the minimal boilerplate seems to be

    use strict;
    use warnings;

This boilerplate can evolve over time to be much larger. Fortunately, it
can be embedded into a module. Sympatic is the boilerplate module for
the L project.

Some of the recommendations are inspired by the
L
book from L (known as PBP in this document).

=head2 The goals behind Sympatic

This section describes the goals that leads to the choices made for Sympatic and
the coding style recommendations.

=head3 No one left behind

As we try to avoid leaving anyone behind, we also need to think about the future.

As some sympa servers run on quite old unix systems, we try to make our code
run on old versions of the perl interpreters. However, this should not
take us away from features of recent versions of perl that really help
performances, stability or good coding practices.

We are currently supporting all the versions of perl since perl 5.16
(released the 2012-May-2). That's the best we can afford. Please contact us
if you need support for older Perl.

=head3 Reduce infrastructure code

As perl emphasizes freedom, it leaves you on your own with minimal tooling
to write such simple and standard things most of us don't want to write by
hand anymore (like object properties getters and setters, function parameter
checkings, ...). This code is described by Damian Conway as "the infrastructure
code".

CPAN provide very good modules to make those disappear and we picked the ones
we think to be the most relevant. Putting them all together provides the ability
to write very expressive code without sacrifying the power of Perl.

=head3 Make perl more familiar for newcommers

Choosing the CPAN modules to reduce infrastructure codes and writing the coding
style recommendation below was made with our friends from the other dynamic langages
in mind. We really expect developers from the ruby, javascript and python to have
a much better experience using Sympatic as it provides some idioms close to the ones
they know in addition of the unique perl features.

=head3 Less typing and opt out policy

Sympatic has the ability to provide different sets of features
(see C section) and the ones that are imported by default
are the one that are used in the most common cases. For exemple: as
most of the sympa packages actually are objects, the L keywords
are exported by default.

See the L section to learn how to avoid some of them.

=head2 What using Sympatic means?

If you are an experimented Perl developer, the simplest way to
introduce Sympatic is to say that

    use Sympatic;

is equivalent to

    use strict;
    use warnings;
    use feature qw< unicode_strings say state >;
    use English qw< -no_match_vars >;
    use utf8;
    use Function::Parameters;
    use Moo;

If you're not, we highly recommend the well written L
Documentation|http://perldoc.perl.org> (the `*tut` sections).
Here we provide a very short description

The L pragma makes perl aware
that the code of your project is encoded in utf8.

The L pragma avoid the
the perl features requiring too much caution. Also the
L one provides very
informational messages when perl detects a potential mistake. You can
use L to get a
direct reference to the perl manual when a warning or an error message is
raised.

L is the Perl pragma to enable new
features from new versions of the perl interpreter. If the perl interpreter
you are using is too old, you will get an explicit message about the missing
feature. Note that we use

    use feature qw< unicode_strings say state >;
    use strict;
    use warnings;

instead of

    use v5.14;

to avoid the use of features related to
L
like the L
as they were abundantly criticized and will be removed in perl 5.28.

L - enable the english (named against
awk variables) names for the variables documented in
L.

So basically, using C, the two following instructions are the same.

    print $(;
    print $GID;

L introduces
the keywords C and C to allow function signatures with gradual typin,
named parameters and other features probably inspired by perl6, python and javascript.
See L section.

L provides nice generic
way to define types that can be used from the C and C
signatures or the C constraint of a Moo property declaration.

=head1 USAGE

=head2 Declaring functions

In addition to the C keyword provided by perl (documented in the
L manual), Sympatic comes with C and C
(provided and documented in L).

As those two documents are very well written, the current documentation
only discuss about picking one of them and providing some examples.

=for comment repetition of the last section ?

Use C when you can provide a signature for a function. C provide
a signature syntax inspired by L so you can use positional and
named parameters, default values, parameter destructuring and gradual typing.
You should use it in most cases.

Here are some examples:

    # positional parameter $x
    fun absolute ( $x ) { $x < 0 ? -$x : $x }

    # typing
    use Types::Standard qw< Int >;
    fun absolute ( Int $x ) { $x < 0 ? -$x : $x }

    # default parameters
    fun point ( $x = 0, $y = 0 ) { "( $x ; $y )" }
    point 12; # ( 12 ; 0 )

    # named parameters
    fun point3D ( :$x = 0, :$y = 0, :$z = 0 ) { "( $x ; $y ; $z )" }
    say point3D x => 12; # ( 12 ; 0 ; 0 )

Use the C keyword fully variadic functions (the parameters are stored in
the C<@_> array) or to use for example, let's assume you want to write a simple
CSV serializer usable like this

    print csv qw( header1 header2 header3 );
    # outputs:
    # header1;header2;header3

This is a naive implementation demonstrating the use of C<@_>

    sub csv { ( join ';', @_ ) , "\n" }


Common cases are list reduction or partial application like

    sub price_with_taxes { price tax_rate => .2, @_ }

=head3 Default perl signatures, prototypes and attributes

Experienced perl programmers should note that we don't use the perl
signatures as documented in L for two reasons:

Those signatures appear as experimental in L and
are finally a feature in L with a changing behaviour
in L to make prototypes happy. Plus, we are bound
to L. Also, the signatures provided by
L) are much more powerful than the
core ones (see description above).

Attributes are still available. If you need to declare a prototype, they are available
using the C<:prototype()> attribute as described in the
L. For exemple

    fun twice ( $block ) :prototype(&) { &$block; &$block }
    twice {say "hello"}
    # outputs:
    # hello
    # hello

=head2 Object Oriented programming

Sympatic imports L and L which means that
you can declare an object using

=over

=item

C to define a new property

=item

C to inherit from a super class

=item

C to compose your class using roles

=item

C to combine with roles

=back

TODO: that keywords like around, after ?

    use Sympatic;
    use Types::Standard qw< Int >;

    has value
        ( is      => 'rw'
        , isa     => Int
        , lvalue  => 1
        , default => 0 );

    method add ( Int $x ) { $self->value += $x }

Note that the method C is almost useless when C<< $self->value >> is lvalue.

    package Human;
    use Sympatic;
    use Types::Standard qw< InstanceOf Str >;

    has qw( name is rw )
    , isa  => Str;

    method greetings ( (InstanceOf['Human']) $other ) {
        sprintf "hello %s, i'm %s and i want to be a friend of you"
            , $self->name
            , $other->name
    }

=head2 Work with the filesystem

The "all in one" C helper from L
is exported by Sympatic. Refer to the documentation for examples.

=head2 set/unset features

    TODO: describe how to enable/disable features
    TODO: describe the features themselves

=head1 CONTRIBUTE

Any kind of contribution that can help to improve C and the
L are very welcome. We meant *all* of them!
from donating to setting up an hackathon, make some goodies or visual
materials, webmastering, help promoting, translating, documenting, mentoring,
... please contact L on
L or the
L.
French people can also join us in
L or the
L.

You are welcome to discuss about the C style on the Sympa project
developers mailing list. If your proposal is accepted, edit the module the
way you describe, update the documentation and test the whole thing.

    cpanm --installdeps .
    sh xt/bin/test_install_dist.sh

=head1 Sympa and CPAN

Every line of code that is used in the Sympa project should be carefully

The CPAN community reduces the cost of maintaining infrastructure code. And
by maintaining it, we mean it the great way: improve, optimize, document,
debug, test in a large number of perl bases, ...

We also want to benefit as much as possible from the experience, ideas and
knowledge of the CPAN members.

So if you want to contribute to Sympa, please consider picking a module on CPAN
that does the job and contributing to it if needed. Push your own stuff if
needed.

=head2 Other CPAN modules

=head3 Those we also rely on

L for web development,
L