NAME

Sympatic - A more producive perl thanks to CPAN

STATUS

Any bug report or feedback that can help to improve Sympatic 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 CPAN RT or even Github.

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 "USAGE" section for more details.

DESCRIPTION

The default behavior of Perl 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 Sympa project project.

Some of the recommendations are inspired by the Perl Best Practices book from Damian Conway (known as PBP in this document).

The goals behind Sympatic

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

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.

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.

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.

Less typing and opt out policy

Sympatic has the ability to provide different sets of features (see features 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 Moo keywords are exported by default.

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

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 Perl Documentation (the `*tut` sections). Here we provide a very short description

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

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

feature 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 smart match like the given/when flow control as they were abundantly criticized and will be removed in perl 5.28.

English - enable the english (named against awk variables) names for the variables documented in the perlvar manual.

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

print $(;
print $GID;

Function::Parameters introduces the keywords fun and method to allow function signatures with gradual typin, named parameters and other features probably inspired by perl6, python and javascript. See examples section.

Types::Standard provides nice generic way to define types that can be used from the fun and method signatures or the isa constraint of a Moo property declaration.

USAGE

Declaring functions

In addition to the sub keyword provided by perl (documented in the perlsub manual), Sympatic comes with fun and method (provided and documented in Function::Parameters).

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

Use fun when you can provide a signature for a function. fun provide a signature syntax inspired by perl6 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 sub keyword fully variadic functions (the parameters are stored in the @_ 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 @_

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

Common cases are list reduction or partial application like

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

Default perl signatures, prototypes and attributes

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

Those signatures appear as experimental in perl5.20 and are finally a feature in perl5.26 with a changing behaviour in perl5.26 to make prototypes happy. Plus, we are bound to perl5.16. Also, the signatures provided by Function::Parameters) 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 :prototype() attribute as described in the OMGTODOFINDALINK. For exemple

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

Object Oriented programming

Sympatic imports Moo and Function::Parameters which means that you can declare an object using

has to define a new property
extends to inherit from a super class
with to compose your class using roles
method to combine with roles

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 add() is almost useless when $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
}

Work with the filesystem

The "all in one" path helper from Path::Tiny is exported by Sympatic. Refer to the documentation for examples.

set/unset features

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

CONTRIBUTE

Any kind of contribution that can help to improve Sympatic and the Sympa project 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 us on the freenode #sympa channel or the the sympa users mailing list. French people can also join us in the freenode #sympa channel or the the sympa users mailing list.

You are welcome to discuss about the Sympatic 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

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.

Other CPAN modules

Those we also rely on

Dancer2 for web development, Template Toolkit for text templating,

Those which can be useful too

Curry eases the creation of streams and callbacks.

sub { $self->foo('bar') }

can be written as

$self->curry::foo('bar')

Perlude is the way to manipulate and combine streams.

AUTHORS

Thanks to the people who contributed to the sympatic module (by date)

Marc Chantreux
David Verdin
Mohammad S Anwar
Stefan Hornburg (Racke)

CONTACTS

let's pick up the most confortable way for you

IRC

you can contact us via IRC on the main IRC channel (freenode #sympa channel). The used langage is english but don't hésitate to speak another one if you're not confortable enough. there is also a (freenode #sympa-fr channel) for french people and you are really welcome to create a new channel for your own langage (just let us now).

mailing lists

pick the most relevant group there

developers
packagers
security

CONTRIBUTE

join us

Any kind of contribution that can help to improve Sympatic and the Sympa project|http://www.sympa.org 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, ... If you need help on helping us, don't hesitate to contact us. (see the contact section)

bug report and feedback

any bugfixe, improvement, documentation, proposal to do? let's talk about it ...

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 [CPAN RT|https://rt.cpan.org/Public/Bug/Report.html?Queue=Sympatic> or even [Github|https://github.com/sympa-community/p5-sympatic/issues>.

LICENSE AND COPYRIGHT

This package is free software and is provided "as is" without express or implied warranty. you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

LICENCE

Copyright (C) 2017,2018 Sympa Community

Sympatic is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.

Sympatic is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, see <http://www.gnu.org/licenses/>.

To install Sympatic, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Sympatic

CPAN shell

perl -MCPAN -e shell
install Sympatic

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

STATUS

SYNOPSIS

DESCRIPTION

The goals behind Sympatic

No one left behind

Reduce infrastructure code

Make perl more familiar for newcommers

Less typing and opt out policy

What using Sympatic means?

USAGE

Declaring functions

Default perl signatures, prototypes and attributes

Object Oriented programming

Work with the filesystem

set/unset features

CONTRIBUTE

Sympa and CPAN

Other CPAN modules

Those we also rely on

Those which can be useful too

AUTHORS

CONTACTS

IRC

mailing lists

CONTRIBUTE

join us

bug report and feedback

LICENSE AND COPYRIGHT

LICENCE

Module Install Instructions