Method transformFile

scripts/doctransformer.py:337–447

Transform lines, and possibly output to the given file.

(self, lines)

        return oldname.rstrip(upper) == newname.rstrip(upper)

    def transformFile(self, lines):
        """Transform lines, and possibly output to the given file."""

        for line in lines:
            self.state.incrLineNumber()

            # Is this a title line (leading '= ' followed by text)?
            thisTitle = False

            # The logic here is broken. If we are in a non-transformable block and
            # this line *does not* end the block, it should always be
            # accumulated.

            # Test for a blockCommonTransform delimiter comment first, to avoid
            # treating it solely as an end-Paragraph marker comment.
            if line == blockCommonTransform:
                # Starting or ending a pseudo-block for "common" VU statements.
                self.endParaBlockTransform(line, vuBlock = True)

            elif blockTransform.match(line):
                # Starting or ending a block whose contents may be transformed.
                # Blocks cannot be nested.

                # Is this is an explicit Valid Usage block?
                vuBlock = (self.state.lineNumber > 1 and
                           lines[self.state.lineNumber-2] == '.Valid Usage\n')

                self.endParaBlockTransform(line, vuBlock)

            elif endPara.match(line):
                # Ending a paragraph. Emit the current paragraph, if any, and
                # prepare to begin a new paragraph.

                self.endPara(line)

                # If this is an include:: line starting the definition of a
                # structure or command, track that for use in VUID generation.

                matches = includePat.search(line)
                if matches is not None:
                    generated_type = matches.group('generated_type')
                    include_type = matches.group('category')
                    if generated_type == 'api' and include_type in ('protos', 'structs', 'funcpointers'):
                        apiName = matches.group('entity_name')
                        if self.state.apiName != self.state.defaultApiName:
                            # This happens when there are multiple API include
                            # lines in a single block. The style guideline is to
                            # always place the API which others are promoted to
                            # first. In virtually all cases, the promoted API
                            # will differ solely in the vendor suffix (or
                            # absence of it), which is benign.
                            if not self.apiMatch(self.state.apiName, apiName):
                                logDiag(f'Promoted API name mismatch at line {self.state.lineNumber}: {apiName} does not match self.state.apiName (this is OK if it is just a spelling alias)')
                        else:
                            self.state.apiName = apiName

            elif endParaContinue.match(line):
                # For now, always just end the paragraph.