<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">###############################################################################
#
#   Package: NaturalDocs::Parser::ParsedTopic
#
###############################################################################
#
#   A class for parsed topics of source files.  Also encompasses some of the &lt;TopicType&gt;-specific behavior.
#
###############################################################################

# This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg Valure
# Natural Docs is licensed under the GPL

use strict;
use integer;

package NaturalDocs::Parser::ParsedTopic;


###############################################################################
# Group: Implementation

#
#   Constants: Members
#
#   The object is a blessed arrayref with the following indexes.
#
#       TYPE           - The &lt;TopicType&gt;.
#       TITLE          - The title of the topic.
#       PACKAGE    - The package &lt;SymbolString&gt; the topic appears in, or undef if none.
#       USING         - An arrayref of additional package &lt;SymbolStrings&gt; available to the topic via "using" statements, or undef if
#                           none.
#       PROTOTYPE - The prototype, if it exists and is applicable.
#       SUMMARY    - The summary, if it exists.
#       BODY          - The body of the topic, formatted in &lt;NDMarkup&gt;.  Some topics may not have bodies, and if not, this
#                           will be undef.
#       LINE_NUMBER  - The line number the topic appears at in the file.
#       IS_LIST - Whether the topic is a list.
#
use NaturalDocs::DefineMembers 'TYPE', 'TITLE', 'PACKAGE', 'USING', 'PROTOTYPE', 'SUMMARY', 'BODY',
                                                 'LINE_NUMBER', 'IS_LIST';
# DEPENDENCY: New() depends on the order of these constants, and that this class is not inheriting any members.


#
#   Architecture: Title, Package, and Symbol Behavior
#
#   Title, package, and symbol behavior is a little awkward so it deserves some explanation.  Basically you set them according to
#   certain rules, but you get computed values that try to hide all the different scoping situations.
#
#   Normal Topics:
#
#       Set them to the title and package as they appear.  "Function" and "PkgA.PkgB" will return "Function" for the title,
#       "PkgA.PkgB" for the package, and "PkgA.PkgB.Function" for the symbol.
#
#       In the rare case that a title has a separator symbol it's treated as inadvertant, so "A vs. B" in "PkgA.PkgB" still returns just
#       "PkgA.PkgB" for the package even though if you got it from the symbol it can be seen as "PkgA.PkgB.A vs".
#
#   Scope Topics:
#
#       Set the title normally and leave the package undef.  So "PkgA.PkgB" and undef will return "PkgA.PkgB" for the title as well
#       as for the package and symbol.
#
#       The only time you should set the package is when you have full language support and they only documented the class with
#       a partial title.  So if you documented "PkgA.PkgB" with just "PkgB", you want to set the package to "PkgA".  This
#       will return "PkgB" as the title for presentation and will return "PkgA.PkgB" for the package and symbol, which is correct.
#
#   Always Global Topics:
#
#       Set the title and package normally, do not set the package to undef.  So "Global" and "PkgA.PkgB" will return "Global" as
#       the title, "PkgA.PkgB" as the package, and "Global" as the symbol.
#
#   Um, yeah...:
#
#       So does this suck?  Yes, yes it does.  But the suckiness is centralized here instead of having to be handled everywhere these
#       issues come into play.  Just realize there are a certain set of rules to follow when you *set* these variables, and the results
#       you see when you *get* them are computed rather than literal.
#


###############################################################################
# Group: Functions

#
#   Function: New
#
#   Creates a new object.
#
#   Parameters:
#
#       type          - The &lt;TopicType&gt;.
#       title           - The title of the topic.
#       package    - The package &lt;SymbolString&gt; the topic appears in, or undef if none.
#       using         - An arrayref of additional package &lt;SymbolStrings&gt; available to the topic via "using" statements, or undef if
#                          none.
#       prototype   - The prototype, if it exists and is applicable.  Otherwise set to undef.
#       summary   - The summary of the topic, if any.
#       body          - The body of the topic, formatted in &lt;NDMarkup&gt;.  May be undef, as some topics may not have bodies.
#       lineNumber - The line number the topic appears at in the file.
#       isList          - Whether the topic is a list topic or not.
#
#   Returns:
#
#       The new object.
#
sub New #(type, title, package, using, prototype, summary, body, lineNumber, isList)
    {
    # DEPENDENCY: This depends on the order of the parameter list being the same as the constants, and that there are no
    # members inherited from a base class.

    my $package = shift;

    my $object = [ @_ ];
    bless $object, $package;

    if (defined $object-&gt;[USING])
        {  $object-&gt;[USING] = [ @{$object-&gt;[USING]} ];  };

    return $object;
    };


# Function: Type
# Returns the &lt;TopicType&gt;.
sub Type
    {  return $_[0]-&gt;[TYPE];  };

# Function: SetType
# Replaces the &lt;TopicType&gt;.
sub SetType #(type)
    {  $_[0]-&gt;[TYPE] = $_[1];  };

# Function: IsList
# Returns whether the topic is a list.
sub IsList
    {  return $_[0]-&gt;[IS_LIST];  };

# Function: SetIsList
# Sets whether the topic is a list.
sub SetIsList
    {  $_[0]-&gt;[IS_LIST] = $_[1];  };

# Function: Title
# Returns the title of the topic.
sub Title
    {  return $_[0]-&gt;[TITLE];  };

# Function: SetTitle
# Replaces the topic title.
sub SetTitle #(title)
    {  $_[0]-&gt;[TITLE] = $_[1];  };

#
#   Function: Symbol
#
#   Returns the &lt;SymbolString&gt; defined by the topic.  It is fully resolved and does _not_ need to be joined with &lt;Package()&gt;.
#
#   Type-Specific Behavior:
#
#       - If the &lt;TopicType&gt; is always global, the symbol will be generated from the title only.
#       - Everything else's symbols will be generated from the title and the package passed to &lt;New()&gt;.
#
sub Symbol
    {
    my ($self) = @_;

    my $titleSymbol = NaturalDocs::SymbolString-&gt;FromText($self-&gt;[TITLE]);

    if (NaturalDocs::Topics-&gt;TypeInfo($self-&gt;Type())-&gt;Scope() == ::SCOPE_ALWAYS_GLOBAL())
        {  return $titleSymbol;  }
    else
        {
        return NaturalDocs::SymbolString-&gt;Join( $self-&gt;[PACKAGE], $titleSymbol );
        };
    };


#
#   Function: Package
#
#   Returns the package &lt;SymbolString&gt; that the topic appears in.
#
#   Type-Specific Behavior:
#
#       - If the &lt;TopicType&gt; has scope, the package will be generated from both the title and the package passed to &lt;New()&gt;, not
#         just the package.
#       - If the &lt;TopicType&gt; is always global, the package will be the one passed to &lt;New()&gt;, even though it isn't part of it's
#         &lt;Symbol()&gt;.
#       - Everything else's package will be what was passed to &lt;New()&gt;, even if the title has separator symbols in it.
#
sub Package
    {
    my ($self) = @_;

    # Headerless topics may not have a type yet.
    if ($self-&gt;Type() &amp;&amp; NaturalDocs::Topics-&gt;TypeInfo($self-&gt;Type())-&gt;Scope() == ::SCOPE_START())
        {  return $self-&gt;Symbol();  }
    else
        {  return $self-&gt;[PACKAGE];  };
    };


# Function: SetPackage
# Replaces the package the topic appears in.  This will behave the same way as the package parameter in &lt;New()&gt;.  Later calls
# to &lt;Package()&gt; will still be generated according to its type-specific behavior.
sub SetPackage #(package)
    {  $_[0]-&gt;[PACKAGE] = $_[1];  };

# Function: Using
# Returns an arrayref of additional scope &lt;SymbolStrings&gt; available to the topic via "using" statements, or undef if none.
sub Using
    {  return $_[0]-&gt;[USING];  };

# Function: SetUsing
# Replaces the using arrayref of sope &lt;SymbolStrings&gt;.
sub SetUsing #(using)
    {  $_[0]-&gt;[USING] = $_[1];  };

# Function: Prototype
# Returns the prototype if one is defined.  Will be undef otherwise.
sub Prototype
    {  return $_[0]-&gt;[PROTOTYPE];  };

# Function: SetPrototype
# Replaces the function or variable prototype.
sub SetPrototype #(prototype)
    {  $_[0]-&gt;[PROTOTYPE] = $_[1];  };

# Function: Summary
# Returns the topic summary, if it exists, formatted in &lt;NDMarkup&gt;.
sub Summary
    {  return $_[0]-&gt;[SUMMARY];  };

# Function: Body
# Returns the topic's body, formatted in &lt;NDMarkup&gt;.  May be undef.
sub Body
    {  return $_[0]-&gt;[BODY];  };

# Function: SetBody
# Replaces the topic's body, formatted in &lt;NDMarkup&gt;.  May be undef.
sub SetBody #(body)
    {
    my ($self, $body) = @_;
    $self-&gt;[BODY] = $body;
    };

# Function: LineNumber
# Returns the line the topic appears at in the file.
sub LineNumber
    {  return $_[0]-&gt;[LINE_NUMBER];  };


1;
</pre></body></html>