=head1 NAME

Object::Simple::Guide -  Object::Simple Guide

=head1 GUIDE

=head2 1. Create accessor

At first, you create a class inheriting L<Object::Simple> by C<-base> flag.

  package SomeClass;
  use Object::Simple -base;

L<Object::Simple> have C<new> method. This is a constructor.
It can receive hash and hash reference as arguments.
  
  my $obj = SomeClass->new;
  my $obj = SomeClass->new(foo => 1, bar => 2);
  my $obj = SomeClass->new({foo => 1, bar => 2});

You can create accessor by C<has> function.

  has 'foo';

You can set and get the value by accessor.

  # Set the value
  $obj->foo(1);
  
  # Get the value
  my $foo = $obj->foo;

You can specify a default value for the accessor.

  has foo => 1;

If the value of C<foo> is not exists and C<foo> is called,
You can get the default value.

  my $default_value = $obj->foo;

If you want to specify a reference or object as default value,
it must be sub reference, whose return value is the default value.
This is requirment not to share the default value with other objects.

  has foo => sub { [] };
  has foo => sub { {} };
  has foo => sub { SomeClass->new };

You can create accessors at once.

  has [qw/foo bar baz/];
  has [qw/foo bar baz/] => 0;

You can create all accessors at once.

  has [qw/foo bar baz/],
    some => 1,
    other => sub { 5 };

If arguments count is odd number, first argument is
for accessor not having default value.

=head2 Create Class

I show a example to understand L<Object::Simple> well.

Point class, which have two accessor, C<x> and C<y>,
and C<clear> method to set C<x> and C<y> to 0.

  package Point;
  use Object::Simple -base;

  has x => 0;
  has y => 0;
  
  sub clear {
    my $self = shift;
    
    $self->x(0);
    $self->y(0);
  }

You can use Point class in the folowing way.

  use Point;
  my $point = Point->new(x => 3, y => 5);
  print $point->x;
  $point->y(9);
  $point->clear;

Point3D class, which inherit L<Point> class.
This class has C<z> accessor in addition to C<x> and C<y>.
C<clear> method is overridden to clear C<x>, C<y> and C<z>.
  
  package Point3D;
  use Point -base;
  
  has z => 0;
  
  sub clear {
    my $self = shift;
    
    $self->SUPER::clear;
    
    $self->z(0);
  }

You can use Point3D class in the folowing way.

  use Point3D;
  my $point = Point->new(x => 3, y => 5, z => 8);
  print $point->z;
  $point->z(9);
  $point->clear;

=head2 2. Concepts of Object-Oriented programing

=head3 Inheritance

I explain the essence of Object-Oriented programing
to use L<Object::Simple> well.

First concept of Object-Oriented programing is Inheritance.
Inheritance means that
If Class Q inherit Class P, Class Q can call all method of class P.

  +---+
  | P | Base class
  +---+   having method1 and method2
    |
  +---+
  | Q | Sub class
  +---+   having method3

Class Q inherits Class P,
so Q can call all methods of P in addition to methods of Q.
In other words, Q can call
C<method1>, C<method2>, and C<method3>

To inherit a class, use L<base> module.

  package P;
  use Object::Simple -base;
  
  sub method1 { ... }
  sub method2 { ... }
  
  package Q;
  use P -base;
  
  sub method3 { ... }

Perl has useful functions and methods to help Object-Oriented programing.

To know the object is belong to what class, use C<ref> function.

  my $class = ref $obj;

To know whether the object inherits the specified class, use C<isa> method.

  $obj->isa('SomeClass');

To know whether the object(or class)
can call the specified method,
use C<can> method 

  SomeClass->can('method1');
  $obj->can('method1');

=head3 Capsulation

Second concept of Object-Oriented programing is capsulation.
Capsulation means that
you don't touch internal data directory.
You must use public methods in documentation.
If you keep this rule, All the things become simple.

To keep this rule,
Use accessor to get and set to the value.

  my $value = $obj->foo;
  $obj->foo(1);

To access the value directory is bad manner.

  # Bad manner!
  my $value = $obj->{foo}; 
  $obj->{foo} = 1;

=head3 Polymorphism

Third concept Object-Oriented programing is polymorphism.
Polymorphism is devieded into two concepts,
overloading and overriding.

Perl programer don't have to care overloading.
Perl is dynamic language,
so subroutine can receive any value.
Overloading is worth for languages having static type variable,
like C++ or Java.

Overriding means that in sub class you can change the process of the base class's method.

  package P;
  use Object::Simple -base;
  
  sub method1 { return 1 }
  
  package Q;
  use P -base;
  
  sub method1 { return 2 }

C<method1> of class P return 1. C<method1> of class Q return 2.
That is to say, C<method1> is overridden in class Q.

  my $obj_a = P->new;
  $obj_p->method1; # Return value is 1
  
  my $obj_b = Q->new;
  $obj_q->method1; # Return value is 2

If you want to call the method of base class from sub class,
use SUPER pseudo-class.

  package Q;
  
  sub method1 {
    my $self = shift;
    
    # return 1
    my $value = $self->SUPER::method1;
    
    return 2 + $value;
  }

If you understand only these three concepts,
you can do enough powerful Object-Oriented programming.
and source code is readable for other language users.

=head2 3. Offten used techniques

=head3 Override new method

C<new> method is overridden if needed.

B<Example:>

Initialize the object

  sub new {
    my $self = shift->SUPER::new(@_);
    
    # Initialization
    
    return $self;
  }

B<Example:>

Change arguments of C<new>.
  
  sub new {
    my $self = shift;
    
    $self->SUPER::new(x => $_[0], y => $_[1]);
    
    return $self;
  }

You can pass array to C<new> method by overridden C<new> method.

  my $point = Point->new(4, 5);

=head3 Import methods

You can import methods of L<Object::Simple>.
This is useful in case you don't want to use multiple inheritance.

  package SomeClass;
  use Object::Simple qw/new attr/;
  
  has 'foo';

Note that you can't override C<new> method
because C<new> method is imported in the class,
not inherited from base class.