NaturalDocs:: Languages:: SimpleNaturalDocs::Languages::Simple |
A class containing the characteristics of a particular programming language for basic support within Natural Docs. Also serves as a base class for languages that break from general conventions, such as not having parameter lists use parenthesis and commas. Summary | A class containing the characteristics of a particular programming language for basic support within Natural Docs. | | | | The class is implemented as a blessed arrayref. | | | | | | | | Returns the name of the language. | | Returns all the possible extensions of the language’s files as an arrayref. | | Returns all the possible strings that can appear in a shebang line (#!) | | Returns an arrayref of symbols used to start a single line comment, or undef if none. | | Returns an arrayref of symbols used to start a multi-line comment, or undef if none. | | Returns an arrayref of symbols used to end a multi-line comment, or undef if none. | | Returns whether the entire file should be treated as one big comment. | | Returns an arrayref of the symbols that end a function prototype, or undef if not applicable. | | Returns an arrayref of the symbols that end a variable declaration, or undef if not applicable. | | Returns the symbol used to extend a line of code past a line break, or undef if not applicable. | | | | | | Called whenever a section of code is encountered by the parser. | | | | Returns whether the language accepts prototypes from the passed <Topic Types>. | | Returns the index of the end of the prototype in a string. | | | | Returns the index of the end of an arbitrary prototype in a string. | | Returns an existence hashref of potential false positives for languages that can end a function prototype with a semicolon but also use them to separate parameters. |
MembersThe class is implemented as a blessed arrayref. The following constants are used as indexes. | NAME | The name of the language. | | EXTENSIONS | An arrayref of the all-lowercase extensions of the language’s files. | | SHEBANG_STRINGS | An arrayref of the all-lowercase strings that can appear in the language’s shebang lines. | | LINE_COMMENT_SYMBOLS | An arrayref of symbols that start a single line comment. Undef if none. | | OPENING_COMMENT_SYMBOLS | An arrayref of symbols that start a multi-line comment. Undef if none. | | CLOSING_COMMENT_SYMBOLS | An arrayref of symbols that ends a multi-line comment. Undef if none. | | FUNCTION_ENDERS | An arrayref of symbols that can end a function prototype. Undef if not applicable. | | VARIABLE_ENDERS | An arrayref of symbols that can end a variable declaration. Undef if not applicable. | | LINE_EXTENDER | The symbol to extend a line of code past a line break. Undef if not applicable. |
New| sub New # | ( | name, | | | extensions,
shebangStrings,
lineCommentSymbols,
openingCommentSymbols,
closingCommentSymbols,
functionEnders,
variableEnders, | | | lineExtender | ) | |
|
Returns a new language object and adds it to NaturalDocs::Languages. Parameters| name | The name of the language. | | extensions | The extensions of the language’s files. A string or an arrayref of strings. | | shebangStrings | The strings to search for in the #! line of the language’s files. Only used when the file has a .cgi extension or no extension at all. A string, an arrayref of strings, or undef if not applicable. | | lineCommentSymbols | The symbols that start a single-line comment. A string, an arrayref of strings, or undef if none. | | openingCommentSymbols | The symbols that start a multi-line comment. A string, an arrayref of strings, or undef if none. | | closingCommentSymbols | The symbols that end a multi-line comment. A string, an arrayref of strings, or undef if none. | | functionEnders | The symbols that can end a function prototype. A string, an arrayref of strings, or undef if not applicable. | | variableEnders | The symbols that can end a variable declaration. A string, an arrayref of strings, or undef if not applicable. | | lineExtender | The symbel to extend a line of code past a line break. A string or undef if not applicable. |
Note that if neither opening/closingCommentSymbols or lineCommentSymbols are specified, the file will be interpreted as one big comment. NameReturns the name of the language. ExtensionsReturns all the possible extensions of the language’s files as an arrayref. Each one is in all lowercase. ShebangStringsReturns all the possible strings that can appear in a shebang line (#!) of the language’s files. It is returned as an arrayref, or undef if not applicable, and all the strings are in all lowercase. LineCommentSymbolsReturns an arrayref of symbols used to start a single line comment, or undef if none. OpeningCommentSymbolssub OpeningCommentSymbols |
Returns an arrayref of symbols used to start a multi-line comment, or undef if none. ClosingCommentSymbolssub ClosingCommentSymbols |
Returns an arrayref of symbols used to end a multi-line comment, or undef if none. FileIsCommentReturns whether the entire file should be treated as one big comment. FunctionEndersReturns an arrayref of the symbols that end a function prototype, or undef if not applicable. VariableEndersReturns an arrayref of the symbols that end a variable declaration, or undef if not applicable. LineExtenderReturns the symbol used to extend a line of code past a line break, or undef if not applicable. ParseFile| sub ParseFile # | ( | sourceFile, | | | topicsList | ) | |
|
Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment() and all other sections to OnCode(). ParametersReturnsSince this class cannot automatically document the code or generate a scope record, it always returns ( undef, undef ). OnCode| sub OnCode # | ( | codeLines, | | | codeLineNumber,
topicList, | | | lastCommentTopicCount | ) | |
|
Called whenever a section of code is encountered by the parser. Is used to find the prototype of the last topic created. Parameters| codeLines | The source code as an arrayref of lines. | | codeLineNumber | The line number of the first line of code. | | topicList | A reference to the list of NaturalDocs::Parser::ParsedTopics being built by the file. | | lastCommentTopicCount | The number of Natural Docs topics that were created by the last comment. |
HasPrototypeReturns whether the language accepts prototypes from the passed <Topic Types>. EndOfPrototype| sub EndOfPrototype # | ( | type, | | | stringRef, | | | falsePositives | ) | |
|
Returns the index of the end of the prototype in a string. Parameters| type | The topic type of the prototype. | | stringRef | A reference to the string. | | falsePositives | An existence hashref of indexes into the string that would trigger false positives, and thus should be ignored. This is for use by derived classes only, so set to undef. |
ReturnsThe zero-based offset into the string of the end of the prototype, or -1 if the string doesn’t contain a symbol that would end it. RemoveExtenderssub RemoveExtenders #(stringRef) |
Strips any LineExtender() symbols out of the prototype. Parameters| stringRef | A reference to the string. It will be altered rather than a new one returned. |
FindEndOfPrototype| sub FindEndOfPrototype # | ( | stringRef, | | | falsePositives, | | | symbols | ) | |
|
Returns the index of the end of an arbitrary prototype in a string. Parameters| stringRef | A reference to the string. | | falsePositives | An existence hashref of indexes into the string that would trigger false positives, and thus should be ignored. Undef if none. | | symbols | An arrayref of the symbols that can end the prototype. |
ReturnsThe zero-based offset into the string of the end of the prototype, or -1 if the string doesn’t contain a symbol from the arrayref. FalsePositivesForSemicolonsInParenthesissub FalsePositivesForSemicolonsInParenthesis #(stringRef) |
Returns an existence hashref of potential false positives for languages that can end a function prototype with a semicolon but also use them to separate parameters. For example: function MyFunction( param1: type; param2, param3: type; param4: type); It will create false positives for every semicolon appearing within parenthesis. Parameters| stringRef | The potential function prototype. |
ReturnsAn existence hashref of false positive indexes. If none, will return an empty hashref. |