diff options
Diffstat (limited to 'docs/tool/Modules/NaturalDocs/Topics.pm')
| -rw-r--r-- | docs/tool/Modules/NaturalDocs/Topics.pm | 1319 |
1 files changed, 1319 insertions, 0 deletions
diff --git a/docs/tool/Modules/NaturalDocs/Topics.pm b/docs/tool/Modules/NaturalDocs/Topics.pm new file mode 100644 index 00000000..ea42f57b --- /dev/null +++ b/docs/tool/Modules/NaturalDocs/Topics.pm @@ -0,0 +1,1319 @@ +############################################################################### +# +# Package: NaturalDocs::Topics +# +############################################################################### +# +# The topic constants and functions to convert them to and from strings used throughout the script. All constants are exported +# by default. +# +############################################################################### + +# This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg Valure +# Natural Docs is licensed under the GPL + +use Text::Wrap ( ); +use Tie::RefHash ( ); + +use strict; +use integer; + +use NaturalDocs::Topics::Type; + +package NaturalDocs::Topics; + +use base 'Exporter'; +our @EXPORT = ( 'TOPIC_GENERAL', 'TOPIC_GENERIC', 'TOPIC_GROUP', 'TOPIC_CLASS', 'TOPIC_FILE', 'TOPIC_FUNCTION', + 'TOPIC_VARIABLE', 'TOPIC_PROPERTY', 'TOPIC_TYPE', 'TOPIC_ENUMERATION', 'TOPIC_CONSTANT', + 'TOPIC_INTERFACE', 'TOPIC_EVENT', 'TOPIC_DELEGATE', 'TOPIC_SECTION' ); + + + +############################################################################### +# Group: Types + + +# +# Type: TopicType +# +# A string representing a topic type as defined in <Topics.txt>. It's format should be treated as opaque; use <MakeTopicType()> +# to get them from topic names. However, they can be compared for equality with string functions. +# + + +# +# Constants: Default TopicTypes +# +# Exported constants of the default <TopicTypes>, so you don't have to go through <TypeFromName()> every time. +# +# TOPIC_GENERAL - The general <TopicType>, which has the special meaning of none in particular. +# TOPIC_GENERIC - Generic <TopicType>. +# TOPIC_GROUP - Group <TopicType>. +# TOPIC_CLASS - Class <TopicType>. +# TOPIC_INTERFACE - Interface <TopicType>. +# TOPIC_FILE - File <TopicType>. +# TOPIC_SECTION - Section <TopicType>. +# TOPIC_FUNCTION - Function <TopicType>. +# TOPIC_VARIABLE - Variable <TopicType>. +# TOPIC_PROPERTY - Property <TopicType>. +# TOPIC_TYPE - Type <TopicType>. +# TOPIC_CONSTANT - Constant <TopicType>. +# TOPIC_ENUMERATION - Enum <TopicType>. +# TOPIC_DELEGATE - Delegate <TopicType>. +# TOPIC_EVENT - Event <TopicType>. +# +use constant TOPIC_GENERAL => 'general'; +use constant TOPIC_GENERIC => 'generic'; +use constant TOPIC_GROUP => 'group'; +use constant TOPIC_CLASS => 'class'; +use constant TOPIC_INTERFACE => 'interface'; +use constant TOPIC_FILE => 'file'; +use constant TOPIC_SECTION => 'section'; +use constant TOPIC_FUNCTION => 'function'; +use constant TOPIC_VARIABLE => 'variable'; +use constant TOPIC_PROPERTY => 'property'; +use constant TOPIC_TYPE => 'type'; +use constant TOPIC_CONSTANT => 'constant'; +use constant TOPIC_ENUMERATION => 'enumeration'; +use constant TOPIC_DELEGATE => 'delegate'; +use constant TOPIC_EVENT => 'event'; +# Dependency: The values of these constants must match what is generated by MakeTopicType(). +# Dependency: These types must be added to requiredTypeNames so that they always exist. + + + + +############################################################################### +# Group: Variables + + +# +# handle: FH_TOPICS +# +# The file handle used when writing to <Topics.txt>. +# + + +# +# hash: types +# +# A hashref that maps <TopicTypes> to <NaturalDocs::Topics::Type>s. +# +my %types; + + +# +# hash: names +# +# A hashref that maps various forms of the all-lowercase type names to <TopicTypes>. All are in the same hash because +# two names that reduce to the same thing it would cause big problems, and we need to catch that. Keys include +# +# - Topic names +# - Plural topic names +# - Alphanumeric-only topic names +# - Alphanumeric-only plural topic names +# +my %names; + + +# +# hash: keywords +# +# A hashref that maps all-lowercase keywords to their <TopicTypes>. Must not have any of the same keys as +# <pluralKeywords>. +# +my %keywords; + + +# +# hash: pluralKeywords +# +# A hashref that maps all-lowercase plural keywords to their <TopicTypes>. Must not have any of the same keys as +# <keywords>. +# +my %pluralKeywords; + + +# +# hash: indexable +# +# An existence hash of all the indexable <TopicTypes>. +# +my %indexable; + + +# +# array: requiredTypeNames +# +# An array of the <TopicType> names which are required to be defined in the main file. Are in the order they should appear +# when reformatting. +# +my @requiredTypeNames = ( 'Generic', 'Class', 'Interface', 'Section', 'File', 'Group', 'Function', 'Variable', 'Property', 'Type', + 'Constant', 'Enumeration', 'Event', 'Delegate' ); + + +# +# array: legacyTypes +# +# An array that converts the legacy topic types, which were numeric constants prior to 1.3, to the current <TopicTypes>. +# The legacy types are used as an index into the array. Note that this does not support list type values. +# +my @legacyTypes = ( TOPIC_GENERAL, TOPIC_CLASS, TOPIC_SECTION, TOPIC_FILE, TOPIC_GROUP, TOPIC_FUNCTION, + TOPIC_VARIABLE, TOPIC_GENERIC, TOPIC_TYPE, TOPIC_CONSTANT, TOPIC_PROPERTY ); + + +# +# array: mainTopicNames +# +# An array of the <TopicType> names that are defined in the main <Topics.txt>. +# +my @mainTopicNames; + + + +############################################################################### +# Group: Files + + +# +# File: Topics.txt +# +# The configuration file that defines or overrides the topic definitions for Natural Docs. One version sits in Natural Docs' +# configuration directory, and another can be in a project directory to add to or override them. +# +# > # [comments] +# +# Everything after a # symbol is ignored. +# +# Except when specifying topic names, everything below is case-insensitive. +# +# > Format: [version] +# +# Specifies the file format version of the file. +# +# +# Sections: +# +# > Ignore[d] Keyword[s]: [keyword], [keyword] ... +# > [keyword] +# > [keyword], [keyword] +# > ... +# +# Ignores the keywords so that they're not recognized as Natural Docs topics anymore. Can be specified as a list on the same +# line and/or following like a normal Keywords section. +# +# > Topic Type: [name] +# > Alter Topic Type: [name] +# +# Creates a new topic type or alters an existing one. The name can only contain <CFChars> and isn't case sensitive, although +# the original case is remembered for presentation. +# +# The name General is reserved. There are a number of default types that must be defined in the main file as well, but those +# are governed by <NaturalDocs::Topics> and are not included here. The default types can have their keywords or behaviors +# changed, though, either by editing the default file or by overriding them in the user file. +# +# Enumeration is a special type. It is indexed with Types and its definition list members are listed with Constants according +# to the rules in <Languages.txt>. +# +# +# Topic Type Sections: +# +# > Plural: [name] +# +# Specifies the plural name of the topic type. Defaults to the singular name. Has the same restrictions as the topic type +# name. +# +# > Index: [yes|no] +# +# Whether the topic type gets an index. Defaults to yes. +# +# > Scope: [normal|start|end|always global] +# +# How the topic affects scope. Defaults to normal. +# +# normal - The topic stays within the current scope. +# start - The topic starts a new scope for all the topics beneath it, like class topics. +# end - The topic resets the scope back to global for all the topics beneath it, like section topics. +# always global - The topic is defined as a global symbol, but does not change the scope for any other topics. +# +# > Class Hierarchy: [yes|no] +# +# Whether the topic is part of the class hierarchy. Defaults to no. +# +# > Page Title if First: [yes|no] +# +# Whether the title of this topic becomes the page title if it is the first topic in a file. Defaults to no. +# +# > Break Lists: [yes|no] +# +# Whether list topics should be broken into individual topics in the output. Defaults to no. +# +# > Can Group With: [topic type], [topic type], ... +# +# The list of <TopicTypes> the topic can possibly be grouped with. +# +# > [Add] Keyword[s]: +# > [keyword] +# > [keyword], [plural keyword] +# > ... +# +# A list of the topic type's keywords. Each line after the heading is the keyword and optionally its plural form. This continues +# until the next line in "keyword: value" format. "Add" isn't required. +# +# - Keywords can only have letters and numbers. No punctuation or spaces are allowed. +# - Keywords are not case sensitive. +# - Subsequent keyword sections add to the list. They don't replace it. +# - Keywords can be redefined by other keyword sections. +# +# +# Revisions: +# +# 1.3: +# +# The initial version of this file. +# + + +############################################################################### +# Group: File Functions + + +# +# Function: Load +# +# Loads both the master and the project version of <Topics.txt>. +# +sub Load + { + my $self = shift; + + # Add the special General topic type. + + $types{::TOPIC_GENERAL()} = NaturalDocs::Topics::Type->New('General', 'General', 1, ::SCOPE_NORMAL(), undef); + $names{'general'} = ::TOPIC_GENERAL(); + $indexable{::TOPIC_GENERAL()} = 1; + # There are no keywords for the general topic. + + + $self->LoadFile(1); # Main + + # Dependency: All the default topic types must be checked for existence. + + # Check to see if the required types are defined. + foreach my $name (@requiredTypeNames) + { + if (!exists $names{lc($name)}) + { NaturalDocs::ConfigFile->AddError('The ' . $name . ' topic type must be defined in the main topics file.'); }; + }; + + my $errorCount = NaturalDocs::ConfigFile->ErrorCount(); + + if ($errorCount) + { + NaturalDocs::ConfigFile->PrintErrorsAndAnnotateFile(); + NaturalDocs::Error->SoftDeath('There ' . ($errorCount == 1 ? 'is an error' : 'are ' . $errorCount . ' errors') + . ' in ' . NaturalDocs::Project->MainConfigFile('Topics.txt')); + } + + + $self->LoadFile(); # User + + $errorCount = NaturalDocs::ConfigFile->ErrorCount(); + + if ($errorCount) + { + NaturalDocs::ConfigFile->PrintErrorsAndAnnotateFile(); + NaturalDocs::Error->SoftDeath('There ' . ($errorCount == 1 ? 'is an error' : 'are ' . $errorCount . ' errors') + . ' in ' . NaturalDocs::Project->UserConfigFile('Topics.txt')); + } + }; + + +# +# Function: LoadFile +# +# Loads a particular version of <Topics.txt>. +# +# Parameters: +# +# isMain - Whether the file is the main file or not. +# +sub LoadFile #(isMain) + { + my ($self, $isMain) = @_; + + my ($file, $status); + + if ($isMain) + { + $file = NaturalDocs::Project->MainConfigFile('Topics.txt'); + $status = NaturalDocs::Project->MainConfigFileStatus('Topics.txt'); + } + else + { + $file = NaturalDocs::Project->UserConfigFile('Topics.txt'); + $status = NaturalDocs::Project->UserConfigFileStatus('Topics.txt'); + }; + + my $version; + + if ($version = NaturalDocs::ConfigFile->Open($file)) + { + # The format hasn't changed since the file was introduced. + + if ($status == ::FILE_CHANGED()) + { NaturalDocs::Project->ReparseEverything(); }; + + my ($topicTypeKeyword, $topicTypeName, $topicType, $topicTypeObject, $inKeywords, $inIgnoredKeywords); + + # Keys are topic type objects, values are unparsed strings. + my %canGroupWith; + tie %canGroupWith, 'Tie::RefHash'; + + while (my ($keyword, $value) = NaturalDocs::ConfigFile->GetLine()) + { + if ($keyword) + { + $inKeywords = 0; + $inIgnoredKeywords = 0; + }; + + if ($keyword eq 'topic type') + { + $topicTypeKeyword = $keyword; + $topicTypeName = $value; + + # Resolve conflicts and create the type if necessary. + + $topicType = $self->MakeTopicType($topicTypeName); + my $lcTopicTypeName = lc($topicTypeName); + + my $lcTopicTypeAName = $lcTopicTypeName; + $lcTopicTypeAName =~ tr/a-z0-9//cd; + + if (!NaturalDocs::ConfigFile->HasOnlyCFChars($topicTypeName)) + { + NaturalDocs::ConfigFile->AddError('Topic names can only have ' . NaturalDocs::ConfigFile->CFCharNames() . '.'); + } + elsif ($topicType eq ::TOPIC_GENERAL()) + { + NaturalDocs::ConfigFile->AddError('You cannot define a General topic type.'); + } + elsif (defined $types{$topicType} || defined $names{$lcTopicTypeName} || defined $names{$lcTopicTypeAName}) + { + NaturalDocs::ConfigFile->AddError('Topic type ' . $topicTypeName . ' is already defined or its name is too ' + . 'similar to an existing name. Use Alter Topic Type if you meant to override ' + . 'its settings.'); + } + else + { + $topicTypeObject = NaturalDocs::Topics::Type->New($topicTypeName, $topicTypeName, 1, ::SCOPE_NORMAL(), + 0, 0); + + $types{$topicType} = $topicTypeObject; + $names{$lcTopicTypeName} = $topicType; + $names{$lcTopicTypeAName} = $topicType; + + $indexable{$topicType} = 1; + + if ($isMain) + { push @mainTopicNames, $topicTypeName; }; + }; + } + + elsif ($keyword eq 'alter topic type') + { + $topicTypeKeyword = $keyword; + $topicTypeName = $value; + + # Resolve conflicts and create the type if necessary. + + $topicType = $names{lc($topicTypeName)}; + + if (!defined $topicType) + { NaturalDocs::ConfigFile->AddError('Topic type ' . $topicTypeName . ' doesn\'t exist.'); } + elsif ($topicType eq ::TOPIC_GENERAL()) + { NaturalDocs::ConfigFile->AddError('You cannot alter the General topic type.'); } + else + { + $topicTypeObject = $types{$topicType}; + }; + } + + elsif ($keyword =~ /^ignored? keywords?$/) + { + $inIgnoredKeywords = 1; + + my @ignoredKeywords = split(/ ?, ?/, lc($value)); + + foreach my $ignoredKeyword (@ignoredKeywords) + { + delete $keywords{$ignoredKeyword}; + delete $pluralKeywords{$ignoredKeyword}; + }; + } + + # We continue even if there are errors in the topic type line so that we can find any other errors in the file as well. We'd + # rather them all show up at once instead of them showing up one at a time between Natural Docs runs. So we just ignore + # the settings if $topicTypeObject is undef. + + + elsif ($keyword eq 'plural') + { + my $pluralName = $value; + my $lcPluralName = lc($pluralName); + + my $lcPluralAName = $lcPluralName; + $lcPluralAName =~ tr/a-zA-Z0-9//cd; + + if (!NaturalDocs::ConfigFile->HasOnlyCFChars($pluralName)) + { + NaturalDocs::ConfigFile->AddError('Plural names can only have ' + . NaturalDocs::ConfigFile->CFCharNames() . '.'); + } + elsif ($lcPluralAName eq 'general') + { + NaturalDocs::ConfigFile->AddError('You cannot use General as a plural name for ' . $topicTypeName . '.'); + } + elsif ( (defined $names{$lcPluralName} && $names{$lcPluralName} ne $topicType) || + (defined $names{$lcPluralAName} && $names{$lcPluralAName} ne $topicType) ) + { + NaturalDocs::ConfigFile->AddError($topicTypeName . "'s plural name, " . $pluralName + . ', is already defined or is too similar to an existing name.'); + } + + elsif (defined $topicTypeObject) + { + $topicTypeObject->SetPluralName($pluralName); + + $names{$lcPluralName} = $topicType; + $names{$lcPluralAName} = $topicType; + }; + } + + elsif ($keyword eq 'index') + { + $value = lc($value); + + if ($value eq 'yes') + { + if (defined $topicTypeObject) + { + $topicTypeObject->SetIndex(1); + $indexable{$topicType} = 1; + }; + } + elsif ($value eq 'no') + { + if (defined $topicTypeObject) + { + $topicTypeObject->SetIndex(0); + delete $indexable{$topicType}; + }; + } + else + { + NaturalDocs::ConfigFile->AddError('Index lines can only be "yes" or "no".'); + }; + } + + elsif ($keyword eq 'class hierarchy') + { + $value = lc($value); + + if ($value eq 'yes') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetClassHierarchy(1); }; + } + elsif ($value eq 'no') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetClassHierarchy(0); }; + } + else + { + NaturalDocs::ConfigFile->AddError('Class Hierarchy lines can only be "yes" or "no".'); + }; + } + + elsif ($keyword eq 'scope') + { + $value = lc($value); + + if ($value eq 'normal') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetScope(::SCOPE_NORMAL()); }; + } + elsif ($value eq 'start') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetScope(::SCOPE_START()); }; + } + elsif ($value eq 'end') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetScope(::SCOPE_END()); }; + } + elsif ($value eq 'always global') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetScope(::SCOPE_ALWAYS_GLOBAL()); }; + } + else + { + NaturalDocs::ConfigFile->AddError('Scope lines can only be "normal", "start", "end", or "always global".'); + }; + } + + elsif ($keyword eq 'page title if first') + { + $value = lc($value); + + if ($value eq 'yes') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetPageTitleIfFirst(1); }; + } + elsif ($value eq 'no') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetPageTitleIfFirst(undef); }; + } + else + { + NaturalDocs::ConfigFile->AddError('Page Title if First lines can only be "yes" or "no".'); + }; + } + + elsif ($keyword eq 'break lists') + { + $value = lc($value); + + if ($value eq 'yes') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetBreakLists(1); }; + } + elsif ($value eq 'no') + { + if (defined $topicTypeObject) + { $topicTypeObject->SetBreakLists(undef); }; + } + else + { + NaturalDocs::ConfigFile->AddError('Break Lists lines can only be "yes" or "no".'); + }; + } + + elsif ($keyword eq 'can group with') + { + if (defined $topicTypeObject) + { $canGroupWith{$topicTypeObject} = lc($value); }; + } + + elsif ($keyword =~ /^(?:add )?keywords?$/) + { + $inKeywords = 1; + } + + elsif (defined $keyword) + { NaturalDocs::ConfigFile->AddError($keyword . ' is not a valid keyword.'); } + + elsif (!$inKeywords && !$inIgnoredKeywords) + { + NaturalDocs::ConfigFile->AddError('All lines in ' . $topicTypeKeyword . ' sections must begin with a keyword.'); + } + + else # No keyword but in keyword section. + { + $value = lc($value); + + if ($value =~ /^([a-z0-9 ]*[a-z0-9]) ?, ?([a-z0-9 ]+)$/) + { + my ($singular, $plural) = ($1, $2); + + if ($inIgnoredKeywords) + { + delete $keywords{$singular}; + delete $keywords{$plural}; + delete $pluralKeywords{$singular}; + delete $pluralKeywords{$plural}; + } + elsif (defined $topicTypeObject) + { + $keywords{$singular} = $topicType; + delete $pluralKeywords{$singular}; + + $pluralKeywords{$plural} = $topicType; + delete $keywords{$plural}; + }; + } + elsif ($value =~ /^[a-z0-9 ]+$/) + { + if ($inIgnoredKeywords) + { + delete $keywords{$value}; + delete $pluralKeywords{$value}; + } + elsif (defined $topicType) + { + $keywords{$value} = $topicType; + delete $pluralKeywords{$value}; + }; + } + else + { + NaturalDocs::ConfigFile->AddError('Keywords can only have letters, numbers, and spaces. ' + . 'Plurals must be separated by a comma.'); + }; + }; + }; + + NaturalDocs::ConfigFile->Close(); + + + # Parse out the Can Group With lines now that everything's defined. + + while (my ($typeObject, $value) = each %canGroupWith) + { + my @values = split(/ ?, ?/, $value); + my @types; + + foreach my $value (@values) + { + # We're just going to ignore invalid items. + if (exists $names{$value}) + { push @types, $names{$value}; }; + }; + + if (scalar @types) + { $typeObject->SetCanGroupWith(\@types); }; + }; + } + + else # couldn't open file + { + if ($isMain) + { die "Couldn't open topics file " . $file . "\n"; } + else + { NaturalDocs::Project->ReparseEverything(); }; + }; + }; + + +# +# Function: Save +# +# Saves the main and user versions of <Topics.txt>. +# +sub Save + { + my $self = shift; + + $self->SaveFile(1); # Main + $self->SaveFile(0); # User + }; + + +# +# Function: SaveFile +# +# Saves a particular version of <Topics.txt>. +# +# Parameters: +# +# isMain - Whether the file is the main file or not. +# +sub SaveFile #(isMain) + { + my ($self, $isMain) = @_; + + my $file; + + if ($isMain) + { + if (NaturalDocs::Project->MainConfigFileStatus('Topics.txt') == ::FILE_SAME()) + { return; }; + $file = NaturalDocs::Project->MainConfigFile('Topics.txt'); + } + else + { + # We have to check the main one two because this lists the topics defined in it. + if (NaturalDocs::Project->UserConfigFileStatus('Topics.txt') == ::FILE_SAME() && + NaturalDocs::Project->MainConfigFileStatus('Topics.txt') == ::FILE_SAME()) + { return; }; + $file = NaturalDocs::Project->UserConfigFile('Topics.txt'); + }; + + + # Array of topic type names in the order they appear in the file. If Alter Topic Type is used, the name will end with an asterisk. + my @topicTypeOrder; + + # Keys are topic type names, values are property hashrefs. Hashref keys are the property names, values the value. + # For keywords, the key is Keywords and the values are arrayrefs of singular and plural pairs. If no plural is defined, the entry + # will be undef. + my %properties; + + # List of ignored keywords specified as Ignore Keywords: [keyword], [keyword], ... + my @inlineIgnoredKeywords; + + # List of ignored keywords specified in [keyword], [plural keyword] lines. Done in pairs, like for regular keywords. + my @separateIgnoredKeywords; + + my $inIgnoredKeywords; + + if (NaturalDocs::ConfigFile->Open($file)) + { + # We can assume the file is valid. + + my ($keyword, $value, $topicTypeName); + + while (($keyword, $value) = NaturalDocs::ConfigFile->GetLine()) + { + $keyword = lc($keyword); + + if ($keyword eq 'topic type' || $keyword eq 'alter topic type') + { + $topicTypeName = $types{ $names{lc($value)} }->Name(); + + if ($keyword eq 'alter topic type') + { $topicTypeName .= '*'; }; + + push @topicTypeOrder, $topicTypeName; + + if (!exists $properties{$topicTypeName}) + { $properties{$topicTypeName} = { 'keywords' => [ ] }; }; + } + + elsif ($keyword eq 'plural') + { + $properties{$topicTypeName}->{$keyword} = $value; + } + + elsif ($keyword eq 'index' || + $keyword eq 'scope' || + $keyword eq 'page title if first' || + $keyword eq 'class hierarchy' || + $keyword eq 'break lists' || + $keyword eq 'can group with') + { + $properties{$topicTypeName}->{$keyword} = lc($value); + } + + elsif ($keyword =~ /^(?:add )?keywords?$/) + { + $inIgnoredKeywords = 0; + } + + elsif ($keyword =~ /^ignored? keywords?$/) + { + $inIgnoredKeywords = 1; + if ($value) + { push @inlineIgnoredKeywords, split(/ ?, ?/, $value); }; + } + + elsif (!$keyword) + { + my ($singular, $plural) = split(/ ?, ?/, lc($value)); + + if ($inIgnoredKeywords) + { push @separateIgnoredKeywords, $singular, $plural; } + else + { push @{$properties{$topicTypeName}->{'keywords'}}, $singular, $plural; }; + }; + }; + + NaturalDocs::ConfigFile->Close(); + }; + + + if (!open(FH_TOPICS, '>' . $file)) + { + # The main file may be on a shared volume or some other place the user doesn't have write access to. Since this is only to + # reformat the file, we can ignore the failure. + if ($isMain) + { return; } + else + { die "Couldn't save " . $file; }; + }; + + print FH_TOPICS 'Format: ' . NaturalDocs::Settings->TextAppVersion() . "\n\n"; + + # Remember the 80 character limit. + + if ($isMain) + { + print FH_TOPICS + "# This is the main Natural Docs topics file. If you change anything here, it\n" + . "# will apply to EVERY PROJECT you use Natural Docs on. If you'd like to\n" + . "# change something for just one project, edit the Topics.txt in its project\n" + . "# directory instead.\n"; + } + else + { + print FH_TOPICS + "# This is the Natural Docs topics file for this project. If you change anything\n" + . "# here, it will apply to THIS PROJECT ONLY. If you'd like to change something\n" + . "# for all your projects, edit the Topics.txt in Natural Docs' Config directory\n" + . "# instead.\n\n\n"; + + if (scalar @inlineIgnoredKeywords || scalar @separateIgnoredKeywords) + { + if (scalar @inlineIgnoredKeywords == 1 && !scalar @separateIgnoredKeywords) + { + print FH_TOPICS 'Ignore Keyword: ' . $inlineIgnoredKeywords[0] . "\n"; + } + else + { + print FH_TOPICS + 'Ignore Keywords: ' . join(', ', @inlineIgnoredKeywords) . "\n"; + + for (my $i = 0; $i < scalar @separateIgnoredKeywords; $i += 2) + { + print FH_TOPICS ' ' . $separateIgnoredKeywords[$i]; + + if (defined $separateIgnoredKeywords[$i + 1]) + { print FH_TOPICS ', ' . $separateIgnoredKeywords[$i + 1]; }; + + print FH_TOPICS "\n"; + }; + }; + } + else + { + print FH_TOPICS + "# If you'd like to prevent keywords from being recognized by Natural Docs, you\n" + . "# can do it like this:\n" + . "# Ignore Keywords: [keyword], [keyword], ...\n" + . "#\n" + . "# Or you can use the list syntax like how they are defined:\n" + . "# Ignore Keywords:\n" + . "# [keyword]\n" + . "# [keyword], [plural keyword]\n" + . "# ...\n"; + }; + }; + + print FH_TOPICS # [CFChars] + "\n\n" + . "#-------------------------------------------------------------------------------\n" + . "# SYNTAX:\n" + . "#\n"; + + if ($isMain) + { + print FH_TOPICS + "# Topic Type: [name]\n" + . "# Creates a new topic type. Each type gets its own index and behavior\n" + . "# settings. Its name can have letters, numbers, spaces, and these\n" + . "# charaters: - / . '\n" + . "#\n" + . "# The Enumeration type is special. It's indexed with Types but its members\n" + . "# are indexed with Constants according to the rules in Languages.txt.\n" + . "#\n" + } + else + { + print FH_TOPICS + "# Topic Type: [name]\n" + . "# Alter Topic Type: [name]\n" + . "# Creates a new topic type or alters one from the main file. Each type gets\n" + . "# its own index and behavior settings. Its name can have letters, numbers,\n" + . "# spaces, and these charaters: - / . '\n" + . "#\n"; + }; + + print FH_TOPICS + "# Plural: [name]\n" + . "# Sets the plural name of the topic type, if different.\n" + . "#\n" + . "# Keywords:\n" + . "# [keyword]\n" + . "# [keyword], [plural keyword]\n" + . "# ...\n"; + + if ($isMain) + { + print FH_TOPICS + "# Defines a list of keywords for the topic type. They may only contain\n" + . "# letters, numbers, and spaces and are not case sensitive. Plural keywords\n" + . "# are used for list topics.\n"; + } + else + { + print FH_TOPICS + "# Defines or adds to the list of keywords for the topic type. They may only\n" + . "# contain letters, numbers, and spaces and are not case sensitive. Plural\n" + . "# keywords are used for list topics. You can redefine keywords found in the\n" + . "# main topics file.\n"; + } + + print FH_TOPICS + "#\n" + . "# Index: [yes|no]\n" + . "# Whether the topics get their own index. Defaults to yes. Everything is\n" + . "# included in the general index regardless of this setting.\n" + . "#\n" + . "# Scope: [normal|start|end|always global]\n" + . "# How the topics affects scope. Defaults to normal.\n" + . "# normal - Topics stay within the current scope.\n" + . "# start - Topics start a new scope for all the topics beneath it,\n" + . "# like class topics.\n" + . "# end - Topics reset the scope back to global for all the topics\n" + . "# beneath it.\n" + . "# always global - Topics are defined as global, but do not change the scope\n" + . "# for any other topics.\n" + . "#\n" + . "# Class Hierarchy: [yes|no]\n" + . "# Whether the topics are part of the class hierarchy. Defaults to no.\n" + . "#\n" + . "# Page Title If First: [yes|no]\n" + . "# Whether the topic's title becomes the page title if it's the first one in\n" + . "# a file. Defaults to no.\n" + . "#\n" + . "# Break Lists: [yes|no]\n" + . "# Whether list topics should be broken into individual topics in the output.\n" + . "# Defaults to no.\n" + . "#\n" + . "# Can Group With: [type], [type], ...\n" + . "# Defines a list of topic types that this one can possibly be grouped with.\n" + . "# Defaults to none.\n" + . "#-------------------------------------------------------------------------------\n\n"; + + my $listToPrint; + + if ($isMain) + { + print FH_TOPICS + "# The following topics MUST be defined in this file:\n" + . "#\n"; + $listToPrint = \@requiredTypeNames; + } + else + { + print FH_TOPICS + "# The following topics are defined in the main file, if you'd like to alter\n" + . "# their behavior or add keywords:\n" + . "#\n"; + $listToPrint = \@mainTopicNames; + } + + print FH_TOPICS + Text::Wrap::wrap('# ', '# ', join(', ', @$listToPrint)) . "\n" + . "\n" + . "# If you add something that you think would be useful to other developers\n" + . "# and should be included in Natural Docs by default, please e-mail it to\n" + . "# topics [at] naturaldocs [dot] org.\n"; + + # Existence hash. We do this because we want the required ones to go first by adding them to @topicTypeOrder, but we don't + # want them to appear twice. + my %doneTopicTypes; + my ($altering, $numberOfProperties); + + if ($isMain) + { unshift @topicTypeOrder, @requiredTypeNames; }; + + my @propertyOrder = ('Plural', 'Index', 'Scope', 'Class Hierarchy', 'Page Title If First', 'Break Lists'); + + foreach my $topicType (@topicTypeOrder) + { + if (!exists $doneTopicTypes{$topicType}) + { + if (substr($topicType, -1) eq '*') + { + print FH_TOPICS "\n\n" + . 'Alter Topic Type: ' . substr($topicType, 0, -1) . "\n\n"; + + $altering = 1; + $numberOfProperties = 0; + } + else + { + print FH_TOPICS "\n\n" + . 'Topic Type: ' . $topicType . "\n\n"; + + $altering = 0; + $numberOfProperties = 0; + }; + + foreach my $property (@propertyOrder) + { + if (exists $properties{$topicType}->{lc($property)}) + { + print FH_TOPICS + ' ' . $property . ': ' . ucfirst( $properties{$topicType}->{lc($property)} ) . "\n"; + + $numberOfProperties++; + }; + }; + + if (exists $properties{$topicType}->{'can group with'}) + { + my @typeStrings = split(/ ?, ?/, lc($properties{$topicType}->{'can group with'})); + my @types; + + foreach my $typeString (@typeStrings) + { + if (exists $names{$typeString}) + { push @types, $names{$typeString}; }; + }; + + if (scalar @types) + { + for (my $i = 0; $i < scalar @types; $i++) + { + my $name = NaturalDocs::Topics->NameOfType($types[$i], 1); + + if ($i == 0) + { print FH_TOPICS ' Can Group With: ' . $name; } + else + { print FH_TOPICS ', ' . $name; }; + }; + + print FH_TOPICS "\n"; + $numberOfProperties++; + }; + }; + + if (scalar @{$properties{$topicType}->{'keywords'}}) + { + if ($numberOfProperties > 1) + { print FH_TOPICS "\n"; }; + + print FH_TOPICS + ' ' . ($altering ? 'Add ' : '') . 'Keywords:' . "\n"; + + my $keywords = $properties{$topicType}->{'keywords'}; + + for (my $i = 0; $i < scalar @$keywords; $i += 2) + { + print FH_TOPICS ' ' . $keywords->[$i]; + + if (defined $keywords->[$i + 1]) + { print FH_TOPICS ', ' . $keywords->[$i + 1]; }; + + print FH_TOPICS "\n"; + }; + }; + + $doneTopicTypes{$topicType} = 1; + }; + }; + + close(FH_TOPICS); + }; + + + +############################################################################### +# Group: Functions + + +# +# Function: KeywordInfo +# +# Returns information about a topic keyword. +# +# Parameters: +# +# keyword - The keyword, which may be plural. +# +# Returns: +# +# The array ( topicType, info, isPlural ), or an empty array if the keyword doesn't exist. +# +# topicType - The <TopicType> of the keyword. +# info - The <NaturalDocs::Topics::Type> of its type. +# isPlural - Whether the keyword was plural or not. +# +sub KeywordInfo #(keyword) + { + my ($self, $keyword) = @_; + + $keyword = lc($keyword); + + my $type = $keywords{$keyword}; + + if (defined $type) + { return ( $type, $types{$type}, undef ); }; + + $type = $pluralKeywords{$keyword}; + + if (defined $type) + { return ( $type, $types{$type}, 1 ); }; + + return ( ); + }; + + +# +# Function: NameInfo +# +# Returns information about a topic name. +# +# Parameters: +# +# name - The topic type name, which can be plural and/or alphanumeric only. +# +# Returns: +# +# The array ( topicType, info ), or an empty array if the name doesn't exist. Note that unlike <KeywordInfo()>, this +# does *not* tell you whether the name is plural or not. +# +# topicType - The <TopicType> of the name. +# info - The <NaturalDocs::Topics::Type> of the type. +# +sub NameInfo #(name) + { + my ($self, $name) = @_; + + my $type = $names{lc($name)}; + + if (defined $type) + { return ( $type, $types{$type} ); } + else + { return ( ); }; + }; + + +# +# Function: TypeInfo +# +# Returns information about a <TopicType>. +# +# Parameters: +# +# type - The <TopicType>. +# +# Returns: +# +# The <NaturalDocs::Topics::Type> of the type, or undef if it didn't exist. +# +sub TypeInfo #(type) + { + my ($self, $type) = @_; + return $types{$type}; + }; + + +# +# Function: NameOfType +# +# Returns the name of the passed <TopicType>, or undef if it doesn't exist. +# +# Parameters: +# +# topicType - The <TopicType>. +# plural - Whether to return the plural instead of the singular. +# alphanumericOnly - Whether to strips everything but alphanumeric characters out. Case isn't modified. +# +# Returns: +# +# The topic type name, according to what was specified in the parameters, or undef if it doesn't exist. +# +sub NameOfType #(topicType, plural, alphanumericOnly) + { + my ($self, $topicType, $plural, $alphanumericOnly) = @_; + + my $topicObject = $types{$topicType}; + + if (!defined $topicObject) + { return undef; }; + + my $topicName = ($plural ? $topicObject->PluralName() : $topicObject->Name()); + + if ($alphanumericOnly) + { $topicName =~ tr/a-zA-Z0-9//cd; }; + + return $topicName; + }; + + +# +# Function: TypeFromName +# +# Returns a <TopicType> for the passed topic name. +# +# Parameters: +# +# topicName - The name of the topic, which can be plural and/or alphanumeric only. +# +# Returns: +# +# The <TopicType>. It does not specify whether the name was plural or not. +# +sub TypeFromName #(topicName) + { + my ($self, $topicName) = @_; + + return $names{lc($topicName)}; + }; + + +# +# Function: IsValidType +# +# Returns whether the passed <TopicType> is defined. +# +sub IsValidType #(type) + { + my ($self, $type) = @_; + return exists $types{$type}; + }; + + +# +# Function: TypeFromLegacy +# +# Returns a <TopicType> for the passed legacy topic type integer. <TopicTypes> were changed from integer constants to +# strings in 1.3. +# +sub TypeFromLegacy #(legacyInt) + { + my ($self, $int) = @_; + return $legacyTypes[$int]; + }; + + +# +# Function: AllIndexableTypes +# +# Returns an array of all possible indexable <TopicTypes>. +# +sub AllIndexableTypes + { + my ($self) = @_; + return keys %indexable; + }; + + + +############################################################################### +# Group: Support Functions + + +# +# Function: MakeTopicType +# +# Returns a <TopicType> for the passed topic name. It does not check to see if it exists already. +# +# Parameters: +# +sub MakeTopicType #(topicName) + { + my ($self, $topicName) = @_; + + # Dependency: The values of the default topic type constants must match what is generated here. + + # Turn everything to lowercase and strip non-alphanumeric characters. + $topicName = lc($topicName); + $topicName =~ tr/a-z0-9//cd; + + return $topicName; + }; + + + +1; |