home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 310.lha / ColumnSet / column_set.doc < prev    next >
Text File  |  1980-12-10  |  6KB  |  115 lines
  1. Documentation for Modula-2 program column_set, by Kent Paul Dolan.
  2.  
  3. The purpose of column _set is to act as a text filter, accepting a file
  4. with one "word" per line (the original was the output of the AmigaDOS
  5. command 'list lformat="%S"', after being sorted) as input, and producing a
  6. file with these "words" layed out in the same order in even columns, as
  7. many as will fit across the output screen or page with at least one space
  8. between columns.
  9.  
  10. The default input is the standard input, the default output is the standard
  11. output, the default output file line width is 77 character positions to
  12. match the AmigaShell window default width, and the default maximum allowed
  13. number of "words" or layout columns per line (maxcol) is (width+1)/2 to
  14. allow for laying out single character "words" with one space after all but
  15. the last one on a line. 
  16.  
  17. Optionally, command line parameters or redirection can name the input and
  18. output files, and command line parameters can modify the width and maxcol
  19. parameters.  The parameters are positional, in order: infile, outfile, width,
  20. maxcol, with missing parameters defaulted, but AmigaDOS style keywords can
  21. override the positional nature of the parameters, and optionally Unix style
  22. "-flag" type keywords can do the same.  Also, the command line is scanned
  23. twice, first to pull off keywords and their associated parameters, then to
  24. pull off missing positional parameters in order from any left over command
  25. line tokens, so some grotesque mixes of parameter styles work as hoped.
  26.  
  27. Except for errors writing output files, which sadly are not checked for in
  28. Modula-2's standard i/o module, "all" identified error conditions are
  29. caught and reported to the user.
  30.  
  31. Doing the column layout requires two passes over the input data, one to
  32. find the largest "word" in the input, which allows column number and
  33. spacing to be calculated, and one to copy the "words" to the output.  Since
  34. standard input may come from the keyboard, and so be unrewindable, in the
  35. case that input is from standard input, a copy of the input is written to a
  36. temporary file in "T:column_set.temp" for use in the second pass, then
  37. deleted when the filter is ready to exit.  (On a Unix system, this should be
  38. changed in the source code to "/tmp/column_set.temp", but I cannot do it on
  39. my Amiga because I don't have a conditional compilation prepass available.)
  40.  
  41. Program usage may be seen by typing in "column_set ?", and is reported when
  42. a command line error is detected as well.  Without going into all the
  43. possibilities of defaults, of mixing positional with keyword parameters,
  44. and of mixing Unix with AmigaDOS keywords; the usage, completely default,
  45. redirected, positional, AmigaDOS keyword, and Unix keyword formats,
  46. respectively, look like this, where "infile" and "outfile" are file path
  47. names, "ww" and "mm" are integers, and the spaces between keyword tokens
  48. and parameter tokens are mandatory:
  49.  
  50.     column_set ?
  51.     column_set
  52.     column_set < infile > outfile [{WIDTH | -w} ww] [{MAXCOL | -m} mm]
  53.     column_set infile outfile ww mm
  54.     column_set FROM infile TO outfile WIDTH ww MAXCOL mm
  55.     column_set -i infile -o outfile -w ww -m mm
  56.  
  57. while, just for example, this will also work:
  58.  
  59.     column_set MaXCoL mm -o outfile widTH ww infile
  60.  
  61. which is arrant nonsense, but did keep me up until dawn finding ways it
  62. wouldn't work and fixing them.
  63.  
  64. As expected, the program doesn't see the redirection commands in the
  65. version of the command line passed to it in the environment, so if you
  66. redirect anything, keyword all the other parameters (really, the
  67. functionality is less strict than that, but that is surely safe), or you
  68. might get positional parameter tokens attached to the wrong parameters.
  69.  
  70. When the command line handling and file handling code are stripped away,
  71. the remaining algorithm is simplicity itself: on the first pass through the
  72. input data, find the length of the longest input "word"; when done with the
  73. first pass, determine how many such words will fit on a line with at least
  74. one space between words, and how many spaces can be put between that many
  75. words without overflowing the line; on the second pass, copy words from
  76. input to output, following each but the last on each line with that number
  77. of spaces, and the last on each line with a newline, until all the words
  78. are copied.  A special case puts a newline rather than spaces after the
  79. last word of the input, if it would not normally be the last word on a
  80. line.
  81.  
  82. The program is copyrighted, but this is no big deal; steal what you want,
  83. just spell my name right in the credits, and don't take a profit on the
  84. whole thing (snips and snatches are OK) without cutting me in on the swag.
  85. Thanks!
  86.  
  87. Oh, yeah, to be fair, AmigaDOS, Amiga, and probably AmigaShell are trademarks
  88. belonging to Commodore, while Unix belongs to AT&T.
  89.  
  90. Kent Paul Dolan, 26 October 1989, Mountain View, California.
  91.  
  92. Example of use:
  93.  
  94. From the commands run in the Amiga directory where this code was developed
  95.  
  96.    list > t:junk1 lformat="%S"
  97.    sort t:junk1 t:junk2
  98.    column_set < t:junk2 > t:junk3
  99.  
  100. at the end, t:junk3 looked like this:
  101.  
  102. column_set                  column_set.doc              column_set.MOD
  103. column_set.OBM              column_set.RFM              column_set.uu
  104. column_set2.MOD             column_set3.MOD             jvert
  105. mycopy1.MOD                 mycopy2.MOD                 mycopy3.MOD
  106. ScheduleBasics.DEF          ScheduleBasics.MOD          SchedulePerson.DEF
  107. SchedulePerson.MOD          ScheduleTask.DEF            ScheduleTask.MOD
  108. Schedule_V0.01.MOD          TimeSliceHandler.DEF        TimeSliceHandler.MOD
  109. tvert                       
  110.  
  111. which allows a directory half again as long to fit on a single screen, by
  112. laying it out in three columns instead of two.  Of such small increments is
  113. happiness constructed.   Kent.
  114.  
  115.