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.

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);
}

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
  ...;
}

multi method

multi method myfunc {
  ...;
}

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

multi method myfunc ( HashRef *collection, Int *index ) {
  ...;
}

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;
}

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.

SEE ALSO

Zydeco manual: Zydeco::Manual.

Zydeco website: http://zydeco.toby.ink/.

Less magic version: MooX::Press. (Zydeco is just a wrapper around MooX::Press, providing a nicer syntax.)

Important underlying technologies: Moo, Type::Tiny::Manual, Sub::HandlesVia, Sub::MultiMethod, Lexical::Accessor, Syntax::Keyword::Try, Role::Hooks.

Similar modules: Moops, Kavorka, Dios, MooseX::Declare.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2020 by Toby Inkster.

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.