GPL_bin_fullset/NaturalDocs/Modules/NaturalDocs/Parser/ParsedTopic.pm

   1 ###############################################################################
   2 #
   3 #   Package: NaturalDocs::Parser::ParsedTopic
   4 #
   5 ###############################################################################
   6 #
   7 #   A class for parsed topics of source files.  Also encompasses some of the <TopicType>-specific behavior.
   8 #
   9 ###############################################################################
  10
  11 # This file is part of Natural Docs, which is Copyright © 2003-2010 Greg Valure
  12 # Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
  13 # Refer to License.txt for the complete details
  14
  15 use strict;
  16 use integer;
  17
  18 package NaturalDocs::Parser::ParsedTopic;
  19
  20
  21 ###############################################################################
  22 # Group: Implementation
  23
  24 #
  25 #   Constants: Members
  26 #
  27 #   The object is a blessed arrayref with the following indexes.
  28 #
  29 #       TYPE           - The <TopicType>.
  30 #       TITLE          - The title of the topic.
  31 #       PACKAGE    - The package <SymbolString> the topic appears in, or undef if none.
  32 #       USING         - An arrayref of additional package <SymbolStrings> available to the topic via "using" statements, or undef if
  33 #                           none.
  34 #       PROTOTYPE - The prototype, if it exists and is applicable.
  35 #       SUMMARY    - The summary, if it exists.
  36 #       BODY          - The body of the topic, formatted in <NDMarkup>.  Some topics may not have bodies, and if not, this
  37 #                           will be undef.
  38 #       LINE_NUMBER  - The line number the topic appears at in the file.
  39 #       IS_LIST - Whether the topic is a list.
  40 #
  41 use NaturalDocs::DefineMembers 'TYPE', 'TITLE', 'PACKAGE', 'USING', 'PROTOTYPE', 'SUMMARY', 'BODY',
  42                                                  'LINE_NUMBER', 'IS_LIST';
  43 # DEPENDENCY: New() depends on the order of these constants, and that this class is not inheriting any members.
  44
  45
  46 #
  47 #   Architecture: Title, Package, and Symbol Behavior
  48 #
  49 #   Title, package, and symbol behavior is a little awkward so it deserves some explanation.  Basically you set them according to
  50 #   certain rules, but you get computed values that try to hide all the different scoping situations.
  51 #
  52 #   Normal Topics:
  53 #
  54 #       Set them to the title and package as they appear.  "Function" and "PkgA.PkgB" will return "Function" for the title,
  55 #       "PkgA.PkgB" for the package, and "PkgA.PkgB.Function" for the symbol.
  56 #
  57 #       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
  58 #       "PkgA.PkgB" for the package even though if you got it from the symbol it can be seen as "PkgA.PkgB.A vs".
  59 #
  60 #   Scope Topics:
  61 #
  62 #       Set the title normally and leave the package undef.  So "PkgA.PkgB" and undef will return "PkgA.PkgB" for the title as well
  63 #       as for the package and symbol.
  64 #
  65 #       The only time you should set the package is when you have full language support and they only documented the class with
  66 #       a partial title.  So if you documented "PkgA.PkgB" with just "PkgB", you want to set the package to "PkgA".  This
  67 #       will return "PkgB" as the title for presentation and will return "PkgA.PkgB" for the package and symbol, which is correct.
  68 #
  69 #   Always Global Topics:
  70 #
  71 #       Set the title and package normally, do not set the package to undef.  So "Global" and "PkgA.PkgB" will return "Global" as
  72 #       the title, "PkgA.PkgB" as the package, and "Global" as the symbol.
  73 #
  74 #   Um, yeah...:
  75 #
  76 #       So does this suck?  Yes, yes it does.  But the suckiness is centralized here instead of having to be handled everywhere these
  77 #       issues come into play.  Just realize there are a certain set of rules to follow when you *set* these variables, and the results
  78 #       you see when you *get* them are computed rather than literal.
  79 #
  80
  81
  82 ###############################################################################
  83 # Group: Functions
  84
  85 #
  86 #   Function: New
  87 #
  88 #   Creates a new object.
  89 #
  90 #   Parameters:
  91 #
  92 #       type          - The <TopicType>.
  93 #       title           - The title of the topic.
  94 #       package    - The package <SymbolString> the topic appears in, or undef if none.
  95 #       using         - An arrayref of additional package <SymbolStrings> available to the topic via "using" statements, or undef if
  96 #                          none.
  97 #       prototype   - The prototype, if it exists and is applicable.  Otherwise set to undef.
  98 #       summary   - The summary of the topic, if any.
  99 #       body          - The body of the topic, formatted in <NDMarkup>.  May be undef, as some topics may not have bodies.
 100 #       lineNumber - The line number the topic appears at in the file.
 101 #       isList          - Whether the topic is a list topic or not.
 102 #
 103 #   Returns:
 104 #
 105 #       The new object.
 106 #
 107 sub New #(type, title, package, using, prototype, summary, body, lineNumber, isList)
 108     {
 109     # DEPENDENCY: This depends on the order of the parameter list being the same as the constants, and that there are no
 110     # members inherited from a base class.
 111
 112     my $package = shift;
 113
 114     my $object = [ @_ ];
 115     bless $object, $package;
 116
 117     if (defined $object->[USING])
 118         {  $object->[USING] = [ @{$object->[USING]} ];  };
 119
 120     return $object;
 121     };
 122
 123
 124 # Function: Type
 125 # Returns the <TopicType>.
 126 sub Type
 127     {  return $_[0]->[TYPE];  };
 128
 129 # Function: SetType
 130 # Replaces the <TopicType>.
 131 sub SetType #(type)
 132     {  $_[0]->[TYPE] = $_[1];  };
 133
 134 # Function: IsList
 135 # Returns whether the topic is a list.
 136 sub IsList
 137     {  return $_[0]->[IS_LIST];  };
 138
 139 # Function: SetIsList
 140 # Sets whether the topic is a list.
 141 sub SetIsList
 142     {  $_[0]->[IS_LIST] = $_[1];  };
 143
 144 # Function: Title
 145 # Returns the title of the topic.
 146 sub Title
 147     {  return $_[0]->[TITLE];  };
 148
 149 # Function: SetTitle
 150 # Replaces the topic title.
 151 sub SetTitle #(title)
 152     {  $_[0]->[TITLE] = $_[1];  };
 153
 154 #
 155 #   Function: Symbol
 156 #
 157 #   Returns the <SymbolString> defined by the topic.  It is fully resolved and does _not_ need to be joined with <Package()>.
 158 #
 159 #   Type-Specific Behavior:
 160 #
 161 #       - If the <TopicType> is always global, the symbol will be generated from the title only.
 162 #       - Everything else's symbols will be generated from the title and the package passed to <New()>.
 163 #
 164 sub Symbol
 165     {
 166     my ($self) = @_;
 167
 168     my $titleSymbol = NaturalDocs::SymbolString->FromText($self->[TITLE]);
 169
 170     if (NaturalDocs::Topics->TypeInfo($self->Type())->Scope() == ::SCOPE_ALWAYS_GLOBAL())
 171         {  return $titleSymbol;  }
 172     else
 173         {
 174         return NaturalDocs::SymbolString->Join( $self->[PACKAGE], $titleSymbol );
 175         };
 176     };
 177
 178
 179 #
 180 #   Function: Package
 181 #
 182 #   Returns the package <SymbolString> that the topic appears in.
 183 #
 184 #   Type-Specific Behavior:
 185 #
 186 #       - If the <TopicType> has scope, the package will be generated from both the title and the package passed to <New()>, not
 187 #         just the package.
 188 #       - If the <TopicType> is always global, the package will be the one passed to <New()>, even though it isn't part of it's
 189 #         <Symbol()>.
 190 #       - Everything else's package will be what was passed to <New()>, even if the title has separator symbols in it.
 191 #
 192 sub Package
 193     {
 194     my ($self) = @_;
 195
 196     # Headerless topics may not have a type yet.
 197     if ($self->Type() && NaturalDocs::Topics->TypeInfo($self->Type())->Scope() == ::SCOPE_START())
 198         {  return $self->Symbol();  }
 199     else
 200         {  return $self->[PACKAGE];  };
 201     };
 202
 203
 204 # Function: SetPackage
 205 # Replaces the package the topic appears in.  This will behave the same way as the package parameter in <New()>.  Later calls
 206 # to <Package()> will still be generated according to its type-specific behavior.
 207 sub SetPackage #(package)
 208     {  $_[0]->[PACKAGE] = $_[1];  };
 209
 210 # Function: Using
 211 # Returns an arrayref of additional scope <SymbolStrings> available to the topic via "using" statements, or undef if none.
 212 sub Using
 213     {  return $_[0]->[USING];  };
 214
 215 # Function: SetUsing
 216 # Replaces the using arrayref of sope <SymbolStrings>.
 217 sub SetUsing #(using)
 218     {  $_[0]->[USING] = $_[1];  };
 219
 220 # Function: Prototype
 221 # Returns the prototype if one is defined.  Will be undef otherwise.
 222 sub Prototype
 223     {  return $_[0]->[PROTOTYPE];  };
 224
 225 # Function: SetPrototype
 226 # Replaces the function or variable prototype.
 227 sub SetPrototype #(prototype)
 228     {  $_[0]->[PROTOTYPE] = $_[1];  };
 229
 230 # Function: Summary
 231 # Returns the topic summary, if it exists, formatted in <NDMarkup>.
 232 sub Summary
 233     {  return $_[0]->[SUMMARY];  };
 234
 235 # Function: Body
 236 # Returns the topic's body, formatted in <NDMarkup>.  May be undef.
 237 sub Body
 238     {  return $_[0]->[BODY];  };
 239
 240 # Function: SetBody
 241 # Replaces the topic's body, formatted in <NDMarkup>.  May be undef.
 242 sub SetBody #(body)
 243     {
 244     my ($self, $body) = @_;
 245     $self->[BODY] = $body;
 246     };
 247
 248 # Function: LineNumber
 249 # Returns the line the topic appears at in the file.
 250 sub LineNumber
 251     {  return $_[0]->[LINE_NUMBER];  };
 252
 253
 254 1;