=encoding utf8

=head1 NAME

OODoc::Text - text component as found in a manual

=head1 INHERITANCE

 OODoc::Text
   is an OODoc::Object

 OODoc::Text is extended by
   OODoc::Text::Default
   OODoc::Text::Diagnostic
   OODoc::Text::Example
   OODoc::Text::Option
   OODoc::Text::Structure
   OODoc::Text::Subroutine

=head1 SYNOPSIS

  # Cannot be instantiated itself

=head1 DESCRIPTION

The parsers (implemented in the L<OODoc::Parser|OODoc::Parser> classes) scan
the documentation as written down by the author of the module, and
build a tree of these L<OODoc::Text|OODoc::Text> objects from it. Then, any formatter
(implemented by the L<OODoc::Format|OODoc::Format> classes) can take this tree of text
objects and convert it into manual pages.

Extends L<"DESCRIPTION" in OODoc::Object|OODoc::Object/"DESCRIPTION">.

=head1 OVERLOADED

Extends L<"OVERLOADED" in OODoc::Object|OODoc::Object/"OVERLOADED">.

=over 4

=item overload: B<'""' (stringification)>

Returned is the name of the text object.

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

Inherited, see L<OODoc::Object/"OVERLOADED">

=item overload: B<'bool'>

Inherited, see L<OODoc::Object/"OVERLOADED">

=item overload: B<'cmp' (string comparison)>

True when both object have same name.  Numeric comparison operators
check whether it is the same object: subtilly different.

=back

=head1 METHODS

Extends L<"METHODS" in OODoc::Object|OODoc::Object/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in OODoc::Object|OODoc::Object/"Constructors">.

=over 4

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

Inherited, see L<OODoc::Object/"Constructors">

 -Option     --Default
  container    <required>
  description  <empty string>
  linenr       <required>
  name         undef
  type         <required>

=over 2

=item container => OBJECT

All text objects except chapters are contained in some other object.

=item description => STRING

The text which is contained in the body of this text item.  Often, this
is filled in later by L<openDescription()|OODoc::Text/"Collected">.

=item linenr => INTEGER

=item name => STRING

The name contains the main data about the text piece.

=item type => STRING

The type of this text element.  This is used for debugging only.

=back

=back

=head2 Attributes

Extends L<"Attributes" in OODoc::Object|OODoc::Object/"Attributes">.

=over 4

=item $obj-E<gt>B<container>( [$object] )

The text element which encapsulates the text element at hand.  This
defines the structure of the documentation.
Only for chapters, this value will be undefined.

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

Returns the description text for this object.  Nearly all objects
contains some kind of introductory description.

=item $obj-E<gt>B<extends>( [$object] )

Close to all elements used within OODoc can have an inheritance relation.
The returned object is extended by the current object.  Multiple inheritance
is not supported here.

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

Z<>

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

The manual of the text object is returned.

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

The name of this text element.  Stringification is overloaded to call
this name method.

example: 

  print $text->name;
  print $text;   # via overload

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

Returns the type name of this data object.

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

Inherited, see L<OODoc::Object/"Attributes">

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

Returns the source of the text item: the filename name and the line
number of the start of it.

=back

=head2 Manual Repository

Extends L<"Manual Repository" in OODoc::Object|OODoc::Object/"Manual Repository">.

=over 4

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

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

Inherited, see L<OODoc::Object/"Manual Repository">

=back

=head2 Collected

=over 4

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

Add a new example (an L<OODoc::Text::Example|OODoc::Text::Example> object) to the list already
in this object.  You can not search for a specific example, because they
have no real name (only a sequence number).

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

Returns a LIST of all examples contained in this text element.

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

From the current object, search in the extends until an object is found
which has a content for the description field.

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

Returns a reference to the scalar which will contain the description for
this object.

example: 

  my $descr = $text->openDescription;
  $$descr  .= "add a line\n";

=back

=head1 DIAGNOSTICS

=over 4

=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.

