+ $self->save();
+ };
+
+ $file->$sub();
+
+This is exactly equivalent to writing C<< $sub->($file) >>. You may see
+this idiom in the wild combined with a call to C<can>:
+
+ if ( my $meth = $object->can('foo') ) {
+ $object->$meth();
+ }
+
+=head2 Invoking Class Methods
+X<invocation>
+
+Because Perl allows you to use barewords for package names and
+subroutine names, it can sometimes guess wrong about what you intend a
+bareword to be. The construct C<< Class->new() >> can be interpreted as
+C<< Class()->new() >>. In English, that reads as "call a subroutine
+named Class(), then call new() as a method on the return value".
+
+You can force Perl to interpret this as a class method call in two
+ways. First, you can append a C<::> to the class name:
+
+ Class::->new()
+
+Perl will always interpret this as a method call. You can also quote
+the class name:
+
+ 'Class'->new()
+
+Of course, if the class name is in a scalar Perl will do the right
+thing as well:
+
+ my $class = 'Class';
+ $class->new();
+
+=head3 Indirect Object Syntax
+X<indirect object>
+
+B<Outside of the file handle case, use of this syntax is discouraged,
+as it can confuse the Perl interpreter. See below for more details.>
+
+Perl suports another method invocation syntax called "indirect object"
+notation.
+
+This notation is quite common when used with file handles:
+
+ print $fh $data;
+
+This is really like calling C<< $fh->print($data) >>. This syntax is
+called "indirect" because the method comes before the object it is
+being invoked on.
+
+This syntax can be used with any class or object method:
+
+ my $file = new File $path, $data;
+ save $file;
+
+We recommend that you avoid this syntax, for several reasons.
+
+First, it can be confusing to read. In the above example, it's not
+clear if C<save> is a method or simply a subroutine that expects a file
+object as its first argument.
+
+When used with class methods, the problem is even worse. Because Perl
+allows subroutine names to be written as barewords, Perl has to guess
+whether the bareword after the method is a class name or subroutine
+name. In other words, Perl can resolve the syntax as either C<<
+File->new( $path, $data ) >> B<or> C<< new( File( $path, $data ) ) >>.
+
+To parse this code, Perl uses a heuristic based on what package names
+it has seen, what subroutines exist in the current package, and what
+barewords it has seen previously. Needless to say, heuristics can
+produce very surprising results!
+
+Older documentation (and some CPAN modules) encouraged this syntax,
+particularly for constructors, so you may still find it in the wild.
+However, we encourage you to avoid using it in new code.
+
+=head2 C<bless>, C<blessed>, and C<ref>
+
+As we saw earlier, an object is simply a reference that has been
+blessed into a class with the C<bless> function. The C<bless> function
+has can take either one or two arguments:
+
+ my $object = bless {}, $class;
+ my $object = bless {};
+
+In the first form, the anonymous hash reference is being blessed into
+the class in C<$class>. In the second form, the reference is blessed
+into the current package.
+
+The second form is discouraged, because it breaks the ability of a
+subclass to reuse the parent's constructor, but you may still run
+across it in existing code.
+
+If you want to know whether a particular scalar is an object, you can
+use the C<blessed> function exported by L<Scalar::Util>, which is
+shipped with the Perl core.
+
+ use Scalar::Util 'blessed';
+
+ if ( blessed($thing) ) { ... }
+
+If the C<$thing> has been blessed, then this function returns the name
+of the package the object has been blessed into. Note that the example
+above will return false if C<$thing> has been blessed into a class
+named "0". If the C<$thing> is not a blessed reference, the C<blessed>
+function returns false.
+
+Similarly, Perl's built in C<ref> function treats a blessed reference
+specially. If you call C<ref($thing)> and C<$thing> is an object, it
+will return the name of the class that the object has been blessed
+into.
+
+If you simply want to check that a variable contains an object, we
+recommend that you use C<blessed>, since C<ref> returns true values for
+all references, not just objects.
+
+=head2 The UNIVERSAL Class
+X<UNIVERSAL>
+
+All classes automatically inherit from the L<UNIVERSAL> class, which is
+built in to the Perl core. This class provides a number of methods, all
+of which can be called on either a class or an object. You can also
+choose to override some of these methods in your class. If you do so,
+we recommend that you follow the built in semantics described below.
+
+=over 4
+
+=item isa($class)
+X<isa>
+
+The C<isa> method returns I<true> if the object is a member of the
+class in C<$class>, or a member of a subclass of C<$class>.
+
+=item DOES($role)
+X<DOES>
+
+The C<DOES> method returns I<true> if its object claims to perform the
+role C<$role>. By default, this is equivalent to C<isa>. This method is
+provided for use by object system extensions that implement roles, like
+C<Moose> and C<Role::Tiny>.
+
+=item can($method)
+X<can>
+
+The C<can> method checks to see if its object has a method called
+C<$method>. If it does, then a reference to the subroutine is returned.
+If it does not then C<undef> is returned.
+
+This will return true if the object's class or any of it's parent
+classes contain C<$method>.
+
+If your class responds to method calls via C<AUTOLOAD>, you may want to
+overload C<can> to respond true for methods which C<AUTOLOAD> handles.
+
+=item VERSION($need)
+X<VERSION>
+
+The C<VERSION> method returns the version number of the class
+(package).
+
+If the C<$need> argument is given then it will check that the current
+version (as defined by the $VERSION variable in the package) is greater
+than or equal to C<$need>; it will die if this is not the case. This
+method is called automatically by the C<VERSION> form of C<use>.
+
+ use Package 1.2 qw(some imported subs);
+ # implies:
+ Package->VERSION(1.2);
+
+We recommend that you use this method to access another package's
+version, rather than looking directly at C<$Package::VERSION>. The
+package you are looking at could have overridden the C<VERSION> method.
+
+We also recommend using this method to check whether a module has a
+sufficient version. The internal implementation uses the L<version>
+module to make sure that different types of version numbers are
+compared correctly.