Next / Previous / Contents / Shipman's homepage

20.7. InputFile.__findBreaks(): Implement --break

When this method is called, self.__blockList contains the entire input file. It is a container for instances derived from Section 22, “class OutBlock: One output block”: instances of FirstBlock for the first or only output block for each line, and possibly instances of OverflowBlock for the wrapped parts of overly long lines.

In the FirstBlock instances that represent lines that start with the --break string, the .goodBreak attribute is set to True; in the rest of them, it is False.

We define chunks as the parts of the input file separated by the --break string.

The purpose of this method is to divide these chunks into column-sized pieces, grouping multiple chunks within a column if all will fit. This division is done by calling the .setBreak() method on the OutBlock instances for output lines that start in a new column.

The algorithm uses a variable named count to keep track of the number of lines in the current column. To add the next chunk, there are two cases.

  1. If the next chunk will fit in the space remaining in the column, we add the size of that chunk to count and we are done.

  2. If the next chunk will not fit in the space remaining in the column, we mark the first line of the chunk so that it will start a new column, and set count back to zero.

    If the chunk still doesn't fit (because it is larger than an entire column), we slice the chunk into multiple chunks by marking every Nth line, where N lines will fit into a column. Then count is set to the number of lines left over after this process.

    There is one more problem: we don't want to force a column break for the very first column. However, there is a simple test for this case: once we have added at least one chunk to a column, the count is always positive (and also less than or equal to the maximum). So, to avoid this problem, we mark lines only when count is positive.

# - - -   I n p u t F i l e . _ _ f i n d B r e a k s

    def __findBreaks(self):
        '''Implement --break.

          [ self.__blockList  :=  self.__blockList with column
                breaks as specified by Args() marked as breaks
            self.nOutCols  +:=  number of column breaks ]

After initializing the count to zero, for each output line, we call Section 20.8, “InputFile.__genChunks(): Bracket the chunks separated by break strings” to generate the (first, last) pairs within self.__blockList that bracket each chunk. For each chunk, we then call Section 20.9, “InputFile.__addChunk(): Add one chunk of lines to the column structure”, which handles marking of breaks and returns the new value for count that tells out how much space now remains in the current column.

        #-- 1
        count = 0

        #-- 2
        # [ count  :=  size of last column
        #   blockList  :=  blockList with breaks marked on lines
        #       such that no region bracketed by marks contains
        #       more than self.bodyLayout.linesPerCol lines
        #   self.nOutCols  +:=  number of column breaks generated ]
        for (first, last) in self.__genChunks():
            #-- 2 body
            # [ self.__blockList  :=  self.__blockList with
            #       breaks marked in the region starting at
            #       (first) such that no region bracketed by
            #       marks contains more than self.bodyLayout.linesPerCol
            #       lines
            #   count  :=  number of lines left in the last column ]
            count = self.__addChunk(count, first, last)