perlclass: work out the initial document structure

pod/perlclass.pod

@@ -1,79 +1,210 @@
 =head1 NAME
 
-perlclass - Perl class syntax
+perlclass - Perl class syntax reference
 
-=head1 DESCRIPTION
+=head1 SYNOPSIS
 
     use v5.36;
     use feature 'class';
 
     class My::Example 1.234 {
         field $x;
-        ADJUST { $x = "Hello, world"; }
 
-        method print_message { say $x; }
+        ADJUST {
+            $x = "Hello, world";
+        }
+
+        method print_message {
+            say $x;
+        }
     }
 
     My::Example->new->print_message;
 
-C<class> is like C<package>. Classes automatically get a C<new> method; you
-don't have to (and should not) write one.
+=head1 DESCRIPTION
+
+This document describes the syntax of the Perl's C<class> feature, which
+provider native keywords supporting object oriented programming paradigm.
+
+=head2 History
+
+Since Perl 5, support for objects resolved around the concept of
+I<blessing> references with a package name. Such reference could then be used
+to call subroutines from the package it was blessed with (or any of its
+parents). This system, while bare-bones, was flexible enough to allow creation
+of multiple more advanced, community-driven systems for object orientation.
+
+Class feature is a core implementation of class syntax which is familiar to
+what one would find in other programming languages. It isn't a C<bless>
+wrapper, but a completely new system built right into the perl interpreter.
+
+=head1 KEYWORDS
+
+Enabling the C<class> feature allows the usage of the following new keywords in
+the scope of current package:
+
+=head2 class
+
+    class NAME BLOCK
+
+    class NAME VERSION BLOCK
 
-C<method> is like C<sub> but automatically gains a C<$self> lexical.
+The C<class> keyword declares a new package which is intended to be a class.
+All other keywords from the C<class> feature should be used in scope of this
+declaration.
 
-C<ADJUST> blocks run during construction and are the way to add code that runs
-during the construction time of each instance. They also have a C<$self>
-lexical.
+    class WithVersion 1.000 {
+        # class definition goes here
+    }
+
+C<class> and C<package> declarations are similar, but classes automatically get
+a constructor named C<new> - You don't have to (and should not) write one.
+Additionally, in the class BLOCK you are allowed to declare fields and methods.
+
+=head2 field
+
+    field VARIABLE_NAME;
 
-C<field> is like C<my> but only visible within C<methods> and C<ADJUST>
-blocks.
+Fields are variables which are visible in the scope of the class - more
+specifically within L<method> and L<ADJUST> blocks. Each class instance get
+their own storage of fields, independent of each other.
 
-Instances get their own value storage for fields
+A field behaves like a normal lexically scoped variable. It has a sigil and is
+private to the class (though creation of an accessor method will make it
+accessible from the outside). The main difference is that different instances
+access different values in the same scope.
 
-    class My::Counter {
-        field $count; ADJUST { $count = 0; }
+    class WithFields {
+        field $scalar;
+        field @array;
+        field %hash;
 
-        method incr { $count++ }
-        method val  { return $count; }
+        ADJUST {
+            $scalar = 42;
+            @array = qw(this is just an array);
+            %hash = (species => 'Marsian', planet => 'Mars');
+        }
     }
 
-    my $ca = My::Counter->new;
-    $ca->incr; $ca->incr; $ca->incr;
+=head2 method
+
+    method METHOD_NAME SIGNATURE BLOCK
+
+    method METHOD_NAME BLOCK
 
-    my $cb = My::Counter->new;
-    $cb->incr;
+    method SIGNATURE BLOCK
 
-    say "Counter A is at ", $ca->val;
-    say "Counter B is at ", $cb->val;
+    method BLOCK
 
-C<methods> always act as if C<use feature 'signatures'> is in effect. You do
-not need to worry about the C<$self> lexical: it is automatically created and
-populated with the object instance, which will not appear in the arguments
-list as far as the signature is concerned.
+Methods are subroutines intended to be called in the context of class objects.
+
+A variable named C<$self> populated with the current object instance will automatically be
+created in the lexical scope of C<method>.
+
+Methods always act as if C<use feature 'signatures'> is in effect, but C<$self>
+will not appear in the arguments list as far as the signature is concerned.
+
+    class WithMethods {
+        field $greetings;
+
+        ADJUST {
+            $greetings = "Hello";
+        }
 
-    class Example::WithSignatures {
         method greet($name = "someone") {
-            say "Hello, $name";
+            say "$greetings, $name";
+        }
+    }
+
+Just like regular subroutines, methods I<can> be anonymous:
+
+    class AnonMethodFactory {
+
+        method get_anon_method {
+            return method {
+                return 'this is an anonymous method';
+            };
         }
     }
 
+=head1 ATTRIBUTES
+
+Specific aspects of the keywords mentioned above are managed using
+I<attributes>. Attributes all start with a colon, and one or more of them can
+be appended after the item's name, separated by a space.
+
+=head2 Class attributes
+
+=head3 :isa
+
 Classes may inherit from B<one> superclass, by using the C<:isa> class
 attribute.
 
-  class Example::Base { ... }
+    class Example::Base { ... }
 
-  class Example::Subclass :isa(Example::Base) { ... }
+    class Example::Subclass :isa(Example::Base) { ... }
 
 Inherited methods are visible and may be invoked. Fields are always lexical
 and therefore not visible by inheritence.
 
 The C<:isa> attribute may request a minimum version of the base class; it is
-applied similar to C<use>; if the provided version is too low it will fail at
+applied similar to C<use> - if the provided version is too low it will fail at
 compile time.
 
-  class Example::Subclass :isa(Example::Base 2.345) { ... }
+    class Example::Subclass :isa(Example::Base 2.345) { ... }
 
 The C<:isa> attribute will attempt to C<require> the named module if it is not
 already loaded.
 
+=head2 Field attributes
+
+None yet.
+
+=head2 Method attributes
+
+None yet.
+
+=head1 OBJECT LIFECYCLE
+
+=head2 Construction
+
+Each object begins its life with a constructor call. The constructor is always
+named C<new> and is invoked like a method call on the class name:
+
+    my $object = My::Class->new(%arguments);
+
+During the construction, class fields are compared to C<%arguments> hash and
+populated where possible.
+
+=head2 Adjustment
+
+Object adjustment can be performed during the construction to run user-defined
+code. It is done with the help of C<ADJUST> blocks, which are called in order
+of declaration.
+
+They are similar to C<BEGIN> blocks, which run during the compilation of a
+package. However, they also have access to C<$self> lexical (object instance)
+and all object fields created up to that point.
+
+=head2 Lifetime
+
+After the construction phase, object is ready to be used.
+
+Using C<blessed> (C<Scalar::Util::blessed> or C<builtin::blessed>) on the
+object will return the name of the class, while C<reftype>
+(C<Scalar::Util::reftype> or C<builtin::reftype>) will return the string
+C<'OBJECT'>.
+
+=head2 Destruction
+
+Just like with other references, when object reference count reaches zero it
+will automatically be destroyed.
+
+=head1 AUTHORS
+
+Paul Evans
+
+Bartosz Jarzyna
+
 =cut
+