=encoding utf8

=head1 NAME

OODoc::Object - base class for all OODoc classes.

=head1 INHERITANCE

 OODoc::Object is extended by
   OODoc
   OODoc::Export
   OODoc::Format
   OODoc::Manifest
   OODoc::Manual
   OODoc::Parser
   OODoc::Text

=head1 SYNOPSIS

  # Never instantiated directly.

=head1 DESCRIPTION

Any object used in the OODoc module is derived from this L<OODoc::Object|OODoc::Object>
class.  This means that all functionality in this class is provided
for all of the other classes.

=head1 OVERLOADED

=over 4

=item overload: B<'==' and '!=' (numeric comparison)>

Numeric comparison is used to compare to objects whether they are
identical.  String comparison is overloaded to compare the names
of the objects.

=item overload: B<'bool'>

Always returns C<true>: "exists".

=back

=head1 METHODS

=head2 Constructors

=over 4

=item $class-E<gt>B<new>(%options)

Create a new object (instantiation).  All objects in OODoc are created
the same way: they carry a list of key-value pairs as option.  For
examples, see the description of this method in the manual page of
the specific object.

The validity of the options for C<new> is checked, in contrary to the
options when used with many other method defined by OODoc.

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<unique>()

Returns a unique id for this text item.  This is the easiest way to
see whether two references to the same (overloaded) objects point to
the same thing. The ids are numeric.

example: 

  if($obj1->unique == $obj2->unique) {...}
  if($obj1 == $obj2) {...}   # same via overload

=back

=head2 Manual Repository

All manuals can be reached everywhere in the program: it is a global
collection.

=over 4

=item $obj-E<gt>B<addManual>($manual)

The C<$manual> will be added to the list of known manuals.  The same package
name can appear in more than one manual.  This OBJECT shall be of type
L<OODoc::Manual|OODoc::Manual>.

=item $obj-E<gt>B<findManual>($name)

[3.00] Returns the manual with the specified name, or else C<undef>.

=item $obj-E<gt>B<mainManual>($name)

Returns the manual of the named package which contains the primar
documentation for the code of the package C<$name>.

=item $obj-E<gt>B<manuals>()

All manuals are returned.

=item $obj-E<gt>B<manualsForPackage>($name)

Returns a list package objects which are related to the specified C<$name>.
One C<$name> can appear in more than one file, and therefore a list is
returned.

=item $obj-E<gt>B<packageNames>()

Returns the names of all defined packages.

=item $obj-E<gt>B<publicationIndex>()

Returns the collected objects for publication.

=item $obj-E<gt>B<publish>(\%options)

Extract the data of an object for export, and register it in the index.
A HASH is returned which should get filled with useful data.

=back

=head1 DIAGNOSTICS

=over 4

=item Error: Unknown object attribute '$name' for $pkg

You have used the option with C<$name>, which is not defined with the
instantiation (the C<new> method) of this object.

=item Error: Unknown object attributes for $pkg: '$names'

You have used more than one option which is not defined to instantiate
the object.

=item Error: manual definition requires manual object

A call to L<addManual()|OODoc::Object/"Manual Repository"> expects a new manual object (a L<OODoc::Manual|OODoc::Manual>),
however an incompatible thing was passed.  Usually, intended was a call
to L<manualsForPackage()|OODoc::Object/"Manual Repository"> or L<mainManual()|OODoc::Object/"Manual Repository">.

=back

=head1 SEE ALSO

This module is part of OODoc version 3.02,
built on August 15, 2025. Website: F<https://perl.overmeer.net/oodoc/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2003-2025 by Mark Overmeer.

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

