HeaderDoc::PythonParse

Declared In:

Introduction

Internal parser routines for parsing Python code.

Discussion

The PythonParse package parses a Python declaration. It is essentially a language-specific replacement for parts of the BlockParse class.

In general, you should not call routines in this package directly. Instead, call the appropriate routines in the BlockParse package with the appropriate language values and let them call these routines for you.

Member Functions

pylength: Converts tabs to spaces and calculates indentation.
pySpaceTest: Runs a single python space handling test.
pythonParse: Parses a Python declaration.
runPythonSpaceTests: Runs a series of tests on Python tab-to-space conversion.

pylength

Converts tabs to spaces and calculates indentation.

sub pylength

Parameters

string: The string of spaces.

Discussion

Converts tabs to spaces using the variable

pySpaceTest

Runs a single python space handling test.

sub pySpaceTest

Parameters

testnum: The test number (string).
test: The string of spaces and tabs to test.
testresult: The expected test result.

Return Value

Returns 1 for a successful test, 0 for a failed test.

pythonParse

Parses a Python declaration.

sub pythonParse

Parameters

fullpath: The path to the file being parsed.
fileoffset: The line number where the current block begins. The line number printed is (fileoffset + inputCounter).
inputLinesRef: A reference to an array of code lines.
inputCounter: The offset within the array. This is added to fileoffset when printing the line number.
argparse: Disable warnings when parsing arguments to avoid seeing them twice.
ignoreref: A reference to a hash of tokens to ignore on all headers.
perheaderignoreref: A reference to a hash of tokens, generated from @ignore headerdoc comments.
perheaderignorefuncmacrosref: A reference to a hash of tokens, generated from @ignorefunmacro headerdoc comments.
keywordhashref: A reference to a hash of keywords.
case_sensitive: Boolean value that controls whether keywords should be processed in a case-sensitive fashion.

Return Value

Returns the array ($inputCounter, $declaration, $typelist, $namelist, $posstypes, $value, @pplStack, $returntype, $privateDeclaration, $treeTop, $simpleTDcontents, $availability) to the caller.

Discussion

Python is a painful language to parse because it has no tokens to end most block structures (except, thankfully, for multi-line comments, without which supporting it would be almost impossible). Merging this into the main parser would be way too messy, so its parser lives in a separate block of code.

This function is called at the start of blockParse and replaces its functionality. Upon completion, it passes its state to blockParseReturnState just like the main parser does, then returns the result.

Local Variables

State variables

continue: Indicates that parsing should continue. Upon receiving a terminating token, this gets set to zero, and parsing ends at the end of the line.
parserState: The ParserState object used for storing most of the parser state variables.

Token and line variables

line: The (input) line being parsed.
part: The current token being processed (from curline).
nextpart: The token after the token being processed (from line).
treepart: In some cases, it is necessary to drop a token for formatting purposes but keep it in the parse tree. When this is needed, the treepart variable contains the original token, and the part variable contains a placeholder value (generally a space).

Parse tree nodes

treeTop: The top of the current parse tree.
treeCur: The current position in the parse tree.

runPythonSpaceTests

Runs a series of tests on Python tab-to-space conversion.

sub runPythonSpaceTests

Return Value

Returns an array containing the number of successes and failures.

Member Data

HeaderDoc::python_tab_spaces: The number of spaces that a tab should be replaced with when parsing Python.
HeaderDoc::PythonParse::VERSION: The revision control revision number for this module.

HeaderDoc::python_tab_spaces

The number of spaces that a tab should be replaced with when parsing Python.

$HeaderDoc::python_tab_spaces = 8;

Discussion

This value can be changed with the -w flag on the command line.

HeaderDoc::PythonParse::VERSION

The revision control revision number for this module.

$HeaderDoc::PythonParse::VERSION = '$Revision: 1330472279 $';

Discussion

In the git repository, contains the number of seconds since January 1, 1970.

Last Updated: Saturday, August 06, 2016