File Coverage

blib/lib/Class/Plain.pm

Criterion	Covered	Total	%
statement	28	30	93.3
branch	2	4	50.0
condition	1	2	50.0
subroutine	9	9	100.0
pod	0	1	0.0
total	40	46	86.9

package Class::Plain 0.06;

use v5.16;
use warnings;

use Carp;

use mro;
use Role::Tiny ();
use Role::Tiny::With ();

sub dl_load_flags { 0x01 }

require DynaLoader;
__PACKAGE__->DynaLoader::bootstrap( our $VERSION );

our $XSAPI_VERSION = "0.48";

use Class::Plain::Base;

sub import {
  my $class = shift;
  my $caller = caller;

  my %syms = map { $_ => 1 } @_;

  # Default imports
  unless( %syms ) {
     $syms{$_}++ for qw(class method field);
  }

  delete $syms{$_} and $^H{"Class::Plain/$_"}++ for qw( class method field);

  croak "Unrecognised import symbols @{[ keys %syms ]}" if keys %syms;
}

=encoding UTF-8

=head1 Name

C -  a class syntax for the hash-based Perl OO.

=head1 Usage

  use Class::Plain;

  class Point {
    field x : reader;
    field y : reader;

    method new : common {
      my $self = $class->SUPER::new(@_);

      $self->{x} //= 0;
      $self->{y} //= 0;

      return $self;
    }

    method move {
      my ($x, $y) = @_;

      $self->{x} += $x;
      $self->{y} += $y;
    }

    method to_string {
      return "($self->{x},$self->{y})";
    }
  }

  my $point = Point->new(x => 5, y => 10);
  print $point->x . "\n";
  print $point->y . "\n";
  print $point->to_string . "\n";

Inheritance:

  class Point3D : isa(Point) {
    field z : reader;

    method new : common {
      my $self = $class->SUPER::new(@_);

      $self->{z} //= 0;

      return $self;
    }

    method move {
      my ($x, $y, $z) = @_;

      $self->SUPER::move($x, $y);
      $self->{z} += $z;
    }

    method to_string {
      return "($self->{x},$self->{y},$self->{z})";
    }
  }

  my $point3d = Point3D->new(x => 5, y => 10, z => 15);
  print $point3d->x . "\n";
  print $point3d->y . "\n";
  print $point3d->z . "\n";
  print $point3d->to_string . "\n";

See also L.

=head1 Description

This module provides a class syntax for the hash-based Perl OO.

=head1 Class

=head2 class Keyword

A class is defined by the C keyword.

  class NAME { ... }

  class NAME : ATTRS... { ... }

Behaves similarly to the C keyword, but provides a package that
defines a new class.

As with C, an optional block may be provided. If so, the contents of
that block define the new class and the preceding package continues
afterwards. If not, it sets the class as the package context of following
keywords and definitions.

=head2 Class Attribute

The following class attributes are supported.

=head3 isa Class Attribute

 # The single inheritance
 : isa(SUPER_CLASS)

 # The multiple inheritance
 : isa(SUPER_CLASS1) isa(SUPER_CLASS2)

 # The super class is nothing
 : isa()

Specifies a supper classes that this class extends.

If the supper class is not specified by C attribute, the class inherits L.

The super class is added to the end of C<@ISA>.

If the the super class name doesn't exists in the Perl's symbol table, the super class is loaded.

Otherwise if the super class doesn't have the C method and doesn't have the class names in C<@ISA>, the super class is loaded.

=head3 does Class Attribute

 : does(ROLE)

 : does(ROLE1) does(ROLE2)

Specifies roles that this class does. This is the alias for L.

See also L.

=head1 Field

=head2 field Keyword

A field is defined by the C keyword.

  field NAME;

  field NAME : ATTR ATTR...;

The following field attributes are supported:

=head2 field Attribute

=head3 reader Field Attribute

  : reader

  : reader(METHOD_NAME)

Generates a reader method to return the current value of the field. If no name
is given, the name of the field is used.

  field x : reader;

  # This is the same as the following code.
  method x {
    $self->{x};
  }

The different method name can be specified.

  field x : reader(x_different_name);

=head3 writer Field Attribute

  : writer

  : writer(METHOD_NAME)

Generates a writer method to set a new value of the field from its arguments.
If no name is given, the name of the field is used prefixed by C.

  field x : writer;

  # This is the same as the following code.
  method set_x {
    $self->{x} = shift;
    return $self;
  }

The different method name can be specified.

  field x : writer(set_x_different_name);

=head3 rw Field Attribute

  : rw

  : rw(METHOD_NAME)

Generates a read-write method to set and get the value of the field.
If no name is given, the name of the field is used.

  field x : rw;

  # This is the same as the following code.
  method x {
    if (@_) {
      $self->{x} = shift;
      return $self;
    }
    $self->{x};
  }

The different method name can be specified.

  field x : rw(x_different_name);

=head1 Method

=head2 method Keyword

  method NAME {
     ...
  }

  method NAME : ATTR ATTR ... {
     ...
  }

Define a new named method. This behaves similarly to the C keyword.
In addition, the method body will have a lexical called C<$self>
which contains the invocant object directly; it will already have been shifted
from the C<@_> array.

B

  # An instance method
  method to_string {

    my $string = "($self->{x},$self->{y})";

    return $string;
  }

=head2 Method Attribute

The following method attributes are supported.

=head3 common Method Attribute

  : common

Marks that this method is a class-common method, instead of a regular instance
method. A class-common method may be invoked on class names instead of
instances. Within the method body there is a lexical C<$class> available instead of C<$self>.
It will already have been shifted from the C<@_> array.

B

  # A class method
  method new : common {
    my $self = $class->SUPER::new(@_);

    # ...

    return $self;
  }

=head1 Role

=head2 role Keyword

A role is defined by the C keyword.

  role NAME { ... }

  role NAME : ATTRS... { ... }

C adopts the role features of L. All features of L can be used.

B

The examples in the document of L is rewritten to the following codes.

  use Class::Plain;

  role Some::Role {

    method foo { ... }

    method bar { ... }
  }

  class Some::Class : does(Some::Role) {
    method foo { ... }

    # baz is wrapped in the around modifier by Class::Method::Modifiers
    method baz { ... }
  }

=head2 Role Attribute

=head3 does Role Attribute

 : does(ROLE)

 : does(ROLE1) does(ROLE2)

The same as L.

=head2 Required Method

In roles, the required method for the composed class can be defined by omitting its method block.

  method required_method;

This is alias for L.

  requires "required_method";

=head2 does Method

  $object->does('Some::Role');

Checks if the object does the role.

=head1 Required Perl Version

Perl 5.16+.

=head1 Subroutine Signatures Support

C> supports the L from C.

The L was supported from C,
but the parser L used in C can parse only the subroutine signatures after C.

  use feature 'signatures';

  use Class::Plain;

  Class Point {

    # ...

    method move($x = 0, $y = 0) {
      $self->{x} += $x;
      $self->{y} += $y;
    }

    # ...

  }

=head1 Cookbook

Exmples of C.

L

=head1 See Also

=head2 Object::Pad

The implementation of the C module is started from the copy of the source code of L.

=head2 Corinna

C uses the keywords and attributes that are specified in L.

The keywords: C, C, C.

The attributes: C, C, C, C.

Only the C attribute is got from L, L, L.

=head2 XS::Parse::Keyword

The C and C keywords are parsed by L.

=head2 XS::Parse::Sublike

The C keyword is parsed by L.

=head2 Role::Tiny

L is used to implement role features of C.

=head1 Repository

L

=head1 Author

Yuki Kimoto [e-mail]

=head1 Copyright & LICENSE

Copyright 2022-2022 Yuki Kimoto, all rights reserved.

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

=cut

1;