Arrange

Arranges the contents of each line of its input by column position, by word position, or by a combination of the two.

Header File

arrange.h

Description

An instance of this class is a filter object that rearranges each line of its input, then outputs the rearranged line. The rearranged line is constructed by starting with an empty line, then repeatedly selecting a part of the input line and overlaying it onto the rearranged line at a specified position. Where overlaid sections overlap the later one overlays the earlier one. Positions between overlaid sections are filled with spaces.

The way that a given Arrange filter object rearranges its input lines is specified by the argument string used to construct it. This argument string must consist of zero or more pairs of input ranges and output ranges:

      args = [inputrange outputrange] ... 
The input range specifies the part of the input line that is selected, and the output range specifies the position at which that selected part is overlayed onto the rearranged line.

An input range can take one of the following forms:

      n          select the n`th character (n > 0)
      n.m        select m characters, starting with the n`th character (n > 0, m > 0)
      n.-        select the n`th through the last character (n > 0)
      words n    select the n`th word (n > 0)
      words n.m  select m words, starting with the n`th word (n > 0, m > 0)
      words n.-  select the n`th through the last word (n > 0)
Any prefix of 'words' can be used in place of 'words' in an input range. For example, the input ranges 'words 2.2', 'word 2.2' and 'w 2.2' all select the second and third words from each input line.

If a given input line doesn`t contain some or all of the characters or specified by an input range, then the input range selects as much of the input input line as it can.

Words are delimited by whitespace. All whitespace before and after a word or range of words selected is discarded. If a range of words is selected, then all of the whitespace between the words in the range is kept intact.

An output range can take one of the following forms:

      n           overlay the selected string at column n (n > 0)
      n.m         pad/truncate the selected string to length m (m > 0) and overlay
                  it at column n (n > 0)
      next        overlay the selected string at the column after the string overlaid
                  by the previous output range
      next.m      pad/truncate the selected string to length m (m > 0) and overlay
                  it at the column after the string overlaid by the previous output
                  range
      nextword    prefix the selected string with a space and overlay it at the
                  column after the string overlaid by the previous output range,
      nextword.m  pad/truncate the selected string to length m (m > 0), prefix
                  it with a space, and overlay it at the column after the string
                  overlaid by the previous output range 
If a selected string is to be padded then it is padded with spaces. If an output range is the first in a string of arguments and it specifies the 'next' or 'nextword' positions, then it will overlay the selected string onto the string to be output starting at column 1. Any prefix of 'next' can be used in place of 'next' in an output range, and any prefix of 'nextword' can be used in place of 'nextword', provided that it is at least 5 letters long (so that it isn`t confused with 'next').

Constructors

Limitations

Known Bugs

Author and Copyright


Author: James MacKay
Last Updated: June 5, 1997
Copyright © 1997 James MacKay