NAME

Zydeco - Jazz up your Perl

SYNOPSIS

MyApp.pm


            
              
              use v5.14;
use strict;
use warnings;
package MyApp {
  use Zydeco;
   
  class Person {
    has name   ( type => Str, required => true );
    has gender ( type => Str );
     
    factory new_man (Str $name) {
      return $class->new(name => $name, gender => 'male');
    }
     
    factory new_woman (Str $name) {
      return $class->new(name => $name, gender => 'female');
    }
     
    method greet (Person *friend, Str *greeting = "Hello") {
      printf("%s, %s!\n", $arg->greeting, $arg->friend->name);
    }
     
    coerce from Str via from_string {
      return $class->new(name => $_);
    }
  }
}

my_script.pl


            
              
              use v5.14;
use strict;
use warnings;
use MyApp;
use MyApp::Types qw( is_Person );
# Create a new MyApp::Person object.
#
my $alice  = MyApp->new_woman("Alice");
is_Person($alice) or die;
# The string "Bob" will be coerced to a MyApp::Person.
#
$alice->greet(friend => "Bob", greeting => 'Hi');

DESCRIPTION

Zydeco is a Perl module to jazz up your object-oriented programming. It fuses together:

Classes, roles, and interfaces
Powerful and concise attribute definitions
Methods with signatures, type constraints, and coercion
Factories to help your objects make other objects
Multimethods
Method modifiers to easily wrap or override inherited methods
Powerful delegation features
True private methods and attributes
Parameterizable classes and roles
Syntactic sugar as sweet as pecan pie

Zydeco::Manual is probably the best place to start.

If Zydeco is too slow or has too many dependencies for you, check out Zydeco::Lite.

KEYWORDS

`class`


            
              
              class MyClass;
class MyClass { ... }
class BaseClass {
  class SubClass;
}
class MyGenerator (@args) { ... }
my $class = MyApp->generate_mygenerator(...);
my $class = do { class; };
my $class = do { class { ... } };
my $generator = do { class (@args) { ... } };
my $class = $generator->generate_package(...);

`abstract class`


            
              
              abstract class MyClass;
abstract class MyClass { ... }
abstract class BaseClass {
  class SubClass;
}
my $class = do { abstract class; };
my $class = do { abstract class { ... } };

`role`


            
              
              role MyRole;
role MyRole { ... }
role MyGenerator (@args) { ... }
my $role = MyApp->generate_mygenerator(...);
my $role = do { role; };
my $role = do { role { ... } };
my $generator = do { role (@args) { ... } };
my $role = $generator->generate_package(...);

`interface`


            
              
              interface MyIface;
interface MyIface { ... }
interface MyGenerator (@args) { ... }
my $interface = MyApp->generate_mygenerator(...);
my $iface = do { interface; };
my $iface = do { interface { ... } };
my $generator = do { interface (@args) { ... } };
my $iface = $generator->generate_package(...);

`toolkit`


            
              
              class MyClass {
  toolkit Moose;
}
class MyClass {
  toolkit Mouse;
}
class MyClass {
  toolkit Moo;
}
class MyClass {
  toolkit Moose (StrictConstructor);
}

Modules in parentheses are prefixed by "$toolkit\::X" unless they start with "::" and loaded. Not all modules are useful to load this way because they are loaded too late to have a lexical effect, and because code inside the class will not be able to see functions exported into the class.

`extends`


            
              
              class MyClass extends BaseClass;
class MyClass extends BaseClass, OtherClass;
class MyClass {
  extends BaseClass;
}
class MyClass {
  extends BaseClass, OtherClass;
}

`with`


            
              
              class MyClass with SomeRole;
class MyClass with SomeRole, OtherRole;
class MyClass extends BaseClass with SomeRole, OtherRole;
class MyClass {
  with SomeRole;
}
class MyClass {
  with SomeRole, OtherRole;
}
class MyClass {
  with RoleGenerator(@args), OtherRole;
}
class MyClass {
  with TagRole?, OtherTagRole?;
}
role MyRole {
  with OtherRole;
}
role MyRole with OtherRole {
  ...;
}
role MyRole with SomeRole, OtherRole;

`begin`


            
              
              class MyClass {
  begin { say "defining $kind $package"; }
}
role MyRole {
  begin { say "defining $kind $package"; }
}

`end`


            
              
              class MyClass {
  end { say "finished defining $kind $package"; }
}
role MyRole {
  end { say "finished defining $kind $package"; }
}

`before_apply`


            
              
              role MyRole {
  before_apply { say "applying $role to $package"; }
}

`after_apply`


            
              
              role MyRole {
  after_apply { say "finished applying $role to $package"; }
}

`has`


            
              
              class MyClass {
  has foo;
}
class MyClass {
  has foo;
  class MySubClass {
    has +foo;
  }
}
class MyClass {
  has foo, bar;
}
class MyClass {
  has foo!, bar;
}
class MyClass {
  has { "fo" . "o" };
}
class MyClass {
  has $foo;  # private attribute withg lexical accessor
}
class MyClass {
  has foo ( is => ro, type => Int, default => 1 ) ;
}
class MyClass {
  has name     = "Anonymous";
  has uc_name  = uc($self->name);
}

`param`

Synonym for has but defaults to required => true.


            
              
              class MyClass {
  param foo ( type => Str );
}

`field`

Synonym for has but defaults to init_arg => undef.


            
              
              class MyClass {
  field foo ( builder => true );
  method _build_foo { ... }
}

`constant`


            
              
              class MyClass {
  constant PI = 3.2;
}
interface Serializable {
  requires serialize;
  constant PRETTY    = 1;
  constant UTF8      = 2;
  constant CANONICAL = 4;
}

`method`


            
              
              method myfunc {
  ...;
}
method myfunc ( Int $x, ArrayRef $y ) {
  ...;
}
method myfunc ( HashRef *collection, Int *index ) {
  ...;
}
method myfunc :optimize ( Int $x, ArrayRef $y ) {
  ...;
}
my $myfunc = do { method () {
  ...;
}};
method $myfunc () {   # lexical method
  ...;
}

`symmethod`


            
              
              symmethod myfunc {
  ...;
}
symmethod myfunc ( Int $x, ArrayRef $y ) {
  ...;
}

`multi method`


            
              
              multi method myfunc {
  ...;
}
multi method myfunc ( Int $x, ArrayRef $y ) {
  ...;
}
multi method myfunc ( HashRef *collection, Int *index ) {
  ...;
}
# lexical multimethod - make sure you declare the variable first
#
my $otherfunc;
multi method $otherfunc ( CodeRef $x ) { ... }
multi method $otherfunc ( HashRef $x ) { ... }

`requires`


            
              
              role MyRole {
  requires serialize;
  requires deserialize (Str $input);
}

`before`


            
              
              before myfunc {
  ...;
}
before myfunc ( Int $x, ArrayRef $y ) {
  ...;
}

`after`


            
              
              after myfunc {
  ...;
}
after myfunc ( Int $x, ArrayRef $y ) {
  ...;
}

`around`


            
              
              around myfunc {
  ...;
  my $return = $self->$next( @_[2..$#_] );
  ...;
  return $return;
}
around myfunc ( Int $x, ArrayRef $y ) {
  ...;
  my $return = $self->$next(@_);
  ...;
  return $return;
}

`factory`


            
              
              class MyThing {
  factory new_thing {
    ...;
  }
}
class MyThing {
  factory new_thing ( Int $x, ArrayRef $y ) {
    ...;
  }
}
class MyThing {
  factory  new_thing ( HashRef *collection, Int *index ) {
    ...;
  }
}
class MyThing {
  method _make_thing {
    ...;
  }
  factory new_thing via _make_thing;
}
class MyThing {
  factory new_thing;
}

`multi factory`


            
              
              class MyThing {
  multi factory new_thing ( ArrayRef $x ) {
    ...;
  }
   
  multi factory new_thing ( HashRef $x ) {
    ...;
  }
}

`type_name`


            
              
              class Person {
  type_name Hooman;
}
role Serializer {
  type_name Ser;
}

`coerce`


            
              
              class Widget {
  has id (type => Int);
   
  coerce from Int via from_id {
    $class->new(id => $_);
  }
}
class Widget {
  has id (type => Int);
   
  coerce from Int via from_id;
   
  method from_id ($id) {
    $class->new(id => $id);
  }
}

`overload`


            
              
              class Person {
  has name (type => Str);
  overload(q[""] => 'name', fallback => true);
}

`version`


            
              
              class MyClass 1.0;
class MyClass {
  version '1.0';
}

`authority`


            
              
              class MyClass {
  authority 'cpan:TOBYINK';
}

`include`


            
              
              package MyApp {
  use Zydeco;
  include Roles;
  include Classes;
}
# MyApp/Roles.zydeco.pm
role Foo;
role Bar;
# MyApp/Classes.zydeco.pm
class Foo::Bar with Foo, Bar;

`Zydeco::PACKAGE_SPEC()`


            
              
              package MyApp {
  use Zydeco;
   
  class MyClass {
    has name;
    Zydeco::PACKAGE_SPEC()->{has}{name}{required} = true;
  }
}

IMPORTS

Booleans:

true
false

Attribute privacy:

rw
rwp
ro
lazy
bare
private

Utilities:

blessed($var)
confess($format, @args)

Types:


            
              
              use Types::Standard         qw( -types -is -assert );
use Types::Common::Numeric  qw( -types -is -assert );
use Types::Common::String   qw( -types -is -assert );

Pragmas:


            
              
              use strict;
use warnings;
# Perl 5.14 and Perl 5.16
use feature qw( say state unicode_strings );
# Perl 5.18 or above
use feature qw( say state unicode_strings
                unicode_eval evalbytes current_sub fc );

Zydeco also imports Syntax::Keyword::Try.

Selective Import

You can choose which parts of Zydeco you import:


            
              
              package MyApp {
  use Zydeco keywords => [qw/
    -booleans
    -privacy
    -utils
    -types
    -is
    -assert
    -features
    try
    class abstract role interface
    begin end before_apply after_apply
    include toolkit extends with requires
    has constant method multi factory before after around
    type_name coerce
    version authority overload
  /];

Unimport

no Zydeco will clear up:


            
              
              class abstract role interface
include toolkit begin end extends with requires
has constant method multi factory before after around
type_name coerce
version authority overload

But won't clear up things Zydeco imported for you from other packages. Use no MooX::Press::Keywords, no Types::Standard, etc to do that, or just use namespace::autoclean.

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Zydeco.

TODO

Plugin system

Zydeco can often load MooX/MouseX/MooseX plugins and work fine with them, but some things won't work, like plugins that rely on being able to wrap has. So it would be nice to have a plugin system that extensions can hook into.

If you're interested in extending Zydeco, file a bug report about it and let's have a conversation about the best way for that to happen. I probably won't start a plugin API until someone actually wants to write a plugin, because that will give me a better idea about what kind of API is required.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

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

cpanm

cpanm Zydeco

CPAN shell

perl -MCPAN -e shell
install Zydeco

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

SYNOPSIS

DESCRIPTION

KEYWORDS

class

abstract class

role

interface

toolkit

extends

with

begin

end

before_apply

after_apply

has

param

field

constant

method

symmethod

multi method

requires

before

after

around

factory

multi factory

type_name

coerce

overload

version

authority

include

Zydeco::PACKAGE_SPEC()