Copyright © 2003-2010 Greg Valure
Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL). Refer to the License for the complete details.
- Every package function is called with an arrow operator. It’s needed for inheritance in some places, and consistency when it’s not.
- No constant will ever be zero or undef. Those are reserved so any piece of code can allow a “none of the above” option and not worry about conflicts with an existing value.
- Existence hashes are hashes where the value doesn’t matter. It acts more as a set, where the existence of the key is the significant part.
File Format Conventions
- All integers appear in big-endian format. So a UInt16 should be handled with a ‘n’ in pack and unpack, not with a ‘S’.
- UString16’s are a big-endian UInt16 followed by that many UTF-8 bytes. A null-terminator is not stored.
- If a higher-level type is described in a file format, that means the loading and saving format is handled by that package. For example, if you see SymbolString in the format, that means NaturalDocs::SymbolString->ToBinaryFile() and NaturalDocs::SymbolString->FromBinaryFile() are used to manipulate it, and the underlying format should be treated as opaque.
Types used throughout the program. As Perl is a weakly-typed language unless you box things into objects, these types are for documentation purposes and are not enforced.
A string representing the absolute, platform-dependent path to a file. Relative file paths are no longer in use anywhere in the program. All path manipulation should be done through NaturalDocs::File.
A comparable integer representing a version number. Converting them to and from text and binary should be handled by NaturalDocs::Version.
A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol. All symbols must be retrieved from plain text via NaturalDocs::SymbolString->FromText() so that the separation and normalization is always consistent. SymbolStrings are comparable via string compare functions and are sortable.
All the information about a reference that makes it unique encoded into a string. This includes the SymbolString of the reference, the scope SymbolString it appears in, the scope SymbolStrings it has access to via “using”, and the ReferenceType. This is done because if any of those parameters change, it needs to be treated as a completely separate reference.
General functions that are used throughout the program, and that don’t really fit anywhere else.
Compares two strings so that the result is good for proper sorting. A proper sort orders the characters as follows:
- End of string.
- Whitespace. Line break-tab-space.
- Symbols, which is anything not included in the other entries.
- Numbers, 0-9.
- Letters, case insensitive except to break ties.
If you use cmp instead of this function, the result would go by ASCII/Unicode values which would place certain symbols between letters and numbers instead of having them all grouped together. Also, you would have to choose between case sensitivity or complete case insensitivity, in which ties are broken arbitrarily.
Like cmp, it returns zero if A and B are equal, a positive value if A is greater than B, and a negative value if A is less than B.
|sub ShortenToMatchStrings #(||sharedArrayRef,|
Compares two arrayrefs and shortens the first array to only contain shared entries. Assumes all entries are strings.
|sharedArrayRef||The arrayref that will be shortened to only contain common elements.|
|compareArrayRef||The arrayref to match.|
|sub FindFirstSymbol #(||string,|
Searches a string for a number of symbols to see which appears first.
|string||The string to search.|
|symbols||An arrayref of symbols to look for.|
|index||The index to start at, if any.|
The array ( index, symbol ).
|index||The index the first symbol appears at, or -1 if none appear.|
|symbol||The symbol that appeared, or undef if none.|