home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / txtutl / do30.arc / DO.DOC < prev   
Encoding:
Text File  |  1987-10-08  |  24.9 KB  |  475 lines
  1. ┌-DO (v3) $10 TO LARRIE HUTTON 701 WARREN ST, MARIETTA, OH 45750 614-374-8337-┐
  2. │ (s) Strip LF to CR/LF or (x)-out LFs.  (p) Paragraph or (o)ne-line lines.   │
  3. │ (w) WordStar from ASCII.               (h) High bits out [WS to ASCII].     │
  4. │ (u) Upper or (l)ower case only.        (q) Quicksort [2048 lins / 127 chr]. │
  5. │ (n) Number lines; no trailing spaces.  (b) Bomb repeated & blank lines.     │
  6. │ (e) Expand tabs with spaces.           (t) Tag lines within range.          │
  7. │ (c) Copy lines between two columns.    (i) Insert, at column, a string.     │
  8. │ (f) Find or (r)eplace string.          (a) Ask before replacing.            │
  9. │ (j) Join or (m)erge-alpha two files.   (g) Glue two files side by side.     │
  10. │ (k) Change all letters but 1st to low. (d) Makes "Tom Mix,OH" "Mix,Tom,OH"  │
  11. ├-----------------------------------------------------------------------------┤
  12. │ NOTES on find, replace, and ask:  Upper case (F,R,A) causes commands to     │
  13. │ ignore case.  ASCII values entered with #nnn#; eg, #13##10# is CR/LF.       │
  14. ├-----------------------------------------------------------------------------┤
  15. │ COMMAND LINE EXAMPLES (where: i=input  l=line  c=col  s=string  #n#=ascii)  │
  16. ├-----------------------------------------------------------------------------┤
  17. │ do s i           do p d:\dir\i        do w i > d:\dir\o do h i              │
  18. │ do u i           do q con: c c s      do n i > prn      do b con: > prn     │
  19. │ do e i c         do t i +/-l +/-l     do c i c c        do i i c s s s      │
  20. │ do r i s // s    do a i s#n#s // s    do j i i +/-l     do g i i            │
  21. ├-----------------------------------------------------------------------------┤
  22. │Choose from above (or "?" for cmnd ln sntx, "+" for 9 lns, "-" for 4 lns):   │
  23. │                                                                             │
  24. │                                                                             │
  25. └-----------------------------------------------------------------------------┘
  26.                                 D O . D O C
  27.                                      
  28.                              Larrie V. Hutton
  29.                              701 Warren Street
  30.                             Marietta, OH 45750
  31.                               (614) 374-8337
  32.                                      
  33. This is admittedly pretty sparse documentation for a fairly complicated
  34. program--the DO text file manipulator.  I had hoped the program screen
  35. would be self-explanatory.  It wasn't, so here goes.  The manual enclosed
  36. here (to use the term loosely) is divided into three small sections: [1] a
  37. BRIEF description of most of the less obvious commands, [2] a section
  38. providing some details of the screen and command line formats with a few
  39. sample batch file suggestions, and [3] a listing of the comments in the
  40. source code.  The latter is included because some of you may find it
  41. helpful to see the internal documentation, but I am not going to elaborate
  42. (I have a job!).  Incidentally, the last section was produced easily by
  43. using DO to search for all lines with an asterisk.
  44.  
  45.  
  46. INDIVIDUAL COMMANDS
  47.  
  48.      (s)  Strips LF's (ASCII 10) or CR's (ASCII 13) and replaces them with
  49.           a CR/LF combination.  Useful for files that overwrite lines (have
  50.           only CR's) or begin just below the end of the previous line (have
  51.           only LF's).
  52.  
  53.      (x)  Rubs out LF's and leaves only CR's.  Useful for uploading to UNIX
  54.           editors, for example, that count both CR's and LF's as valid line
  55.           terminators.  Without this ability, files are often double spaced
  56.           when they should not be.
  57.  
  58.      (p)  Paragraphs are formed from single lines by replacing CR/LF
  59.           combinations with spaces; joins consecutive lines.  Good for
  60.           putting ASCII text into form suitable for most word processors.
  61.           A CR/LF combination IS issued, however, for blank lines--in fact,
  62.           two CR/LF combinations are issued at blank lines to preserve the
  63.           "original intent".
  64.  
  65.      (o)  One-lines paragraphs--the previous command in reverse.  Useful
  66.           for taking long text strings and turning them into proper ASCII
  67.           format.  Lines are formed at the next word break whenever the
  68.           number of characters exceeds 60.
  69.  
  70.      (w)  WordStar from ASCII.  Not perfect, but does a pretty good job at
  71.           guessing, and much easier than hand-editing an ASCII file from
  72.           scratch.
  73.  
  74.      (h)  Reverse of the previous, but much easier to implement.  Simply
  75.           replaces all high bits with low, so produces proper ASCII text.
  76.           Useful for peeking at a WS file.
  77.  
  78.      (u)  Upper case text only produced.
  79.  
  80.      (l)  Lower case text only produced.
  81.  
  82.      (q)  Really a merge sort for text, and a shell sort for numbers.  Very
  83.           fast and flexible.  Maximum number of lines shows on screen;
  84.           since routine uses the heap, the maximum file size is dependent
  85.           upon available RAM.
  86.  
  87.      (n)  Numbers lines (default is to use first eight columns for this
  88.           information).  Also removes trailing blanks from all lines.
  89.           Sometimes the latter function is really what is needed; in that
  90.           case, number the lines and copy only from the ninth column and
  91.           beyond with the (c) option.  Blank lines are counted, but the
  92.           numbers aren't printed.
  93.  
  94.      (b)  Bombs (deletes) all blank lines and duplicate lines.  Sometimes
  95.           useful after sorting.
  96.  
  97.      (e)  Expands tabs with tabs.  Default is eight spaces.
  98.  
  99.      (t)  Tags lines: Lets you copy lines 37-94 only, for example.
  100.           Entering -5 to -1 would produce the LAST 5 lines.
  101.  
  102.      (c)  Copies only text that falls within the specified columns.  If the
  103.           end column is not specified, assumes to end.  If end column is
  104.           negative, pads with spaces if necessary to assure that all lines
  105.           are same length.
  106.  
  107.      (i)  Inserts a string at any given column position.  Could be used,
  108.           for example, to widen borders.  If a CR/LF is inserted (with
  109.           #13##10#), causes lines to be split at that point into two lines.
  110.  
  111.      (f)  Finds strings in text.  Again, can look for any ASCII string by
  112.           using #n# combinations.  Upper case F causes case to be ignored.
  113.  
  114.      (r)  Similar, but replaces all instances of one string with another.
  115.           Can also be used to produce output that has only lines containing
  116.           the string, or all lines NOT containing the string (by using
  117.           "????" or "!!!!" as the replacement string.  On the command line,
  118.           a double slash (//), with a space on each side, should separate
  119.           the old and new strings.  Again, ASCII values can be entered
  120.           directly.  An R causes case to be ignored.
  121.  
  122.      (a)  Asks before replacing.  Lets you see the line with and without
  123.           the replacement before you decide.
  124.  
  125.      (j)  Joins two files by letting you insert the second file at any line
  126.           in the first.
  127.  
  128.      (m)  Merges two files alphabetically.  In other words, if you have two
  129.           sorted files, this will create a single sorted file.  Since there
  130.           is no limit on file size, this would permit files too large to be
  131.           (q)uick sorted to be split into two (or many) files, sorted with
  132.           (q), and then merged.
  133.  
  134.      (g)  Glues two files side-by-side.  Most useful if the first file has
  135.           been padded with spaces to a consistent line length with the (c)
  136.           command.
  137.  
  138.      (k)  Change all letters but first letter in word to lower case; first
  139.           letter is capitalized.  Two common uses would be to take a
  140.           mailing list with all caps and turn it into a more respectable-
  141.           looking file, or to clean up inconsistently formatted source
  142.           code.
  143.  
  144.      (d)  Takes the last word in the first field of a comma-delimited data
  145.           file and creates a new, first field.  For example, mailing lists
  146.           that don't separate the last and first names with a comma (and
  147.           therefore can't be easily sorted by last name) will have a last-
  148.           name field first, followed by the rest of the name as the second
  149.           field.  All other fields are unchanged.  Rather special-purpose,
  150.           but can be a real time-saver.
  151.  
  152. DETAILS OF OPERATION
  153.  
  154.      Entering DO alone at the DOS command line brings up work area that
  155.      lets you see the operation of each command.  This is useful for
  156.      testing.  If you do not wish to produce a new file (or printer
  157.      output), merely press RETURN when you are asked for the output file
  158.      name.  You will be prompted for all other values.  If you press RETURN
  159.      at these prompts, a default value (usually appropriate) will be
  160.      assumed.
  161.  
  162.      Pressing the space bar during the operation of a command permits you
  163.      to step through the process--sometimes helpful to see what is going
  164.      on.  Depending upon the command, the stepping process may occur
  165.      character-by-character or line-by-line.  Pressing ENTER reverts to
  166.      full-speed operation.  Pressing ESC causes a graceful abort at that
  167.      point, and the output file (if any) is closed with all processing up
  168.      to that point contained therein.  DO NOT specify an extant file as
  169.      your output file unless you want to overwrite the file.  Summary
  170.      statistics are printed at the conclusion of each command.
  171.  
  172.      An exception to the space bar option during the operation of a command
  173.      is the sort, which cannot be single stepped (because the file must be
  174.      read in its entirety before processing can occur).  However, pressing
  175.      the "+" key lets you see how much room is left on the heap at any
  176.      point.  I originally had that feature for debugging purposes, and it
  177.      was interesting to watch, so I left it in.
  178.  
  179.      Before a command is issued, there are three options that may be
  180.      specified.  A "+" causes the input and output windows to be 9 lines
  181.      long, rather than 3; a "-" reverts to the default of 3.  Both commands
  182.      also turn off the blinking price of the program, if you find that
  183.      annoying.  A "?" shows you what the DOS command line syntax should be
  184.      for the last command issued.
  185.  
  186.      Issuing commands at the DOS prompt is MUCH faster, and permits you to
  187.      build batch files using DO, but you lose the feedback from the
  188.      windows.  The DOS option is forced by including a parameter (s, h, q,
  189.      etc.) at the DOS prompt.  If you do not specify enough parameters, and
  190.      defaults cannot be logically assumed by the program, you will be asked
  191.      for the missing information.  Output can be redirected if desired.
  192.      For example, the command
  193.  
  194.                DO h infile > outfile
  195.  
  196.      will cause a file named "outfile" to be produced that is created when
  197.      the high bits are stripped from "infile".  If you do redirect the
  198.      output at the DOS prompt, output will be directed to the screen.  This
  199.      is often a useful way to check your output before sending it to a disk
  200.      file or printer, or simply to peek at an otherwise unreadable file.
  201.  
  202.      To show the utility of using DO in batch files, I include one that
  203.      will take a WS file (%1) and produce, in ASCII paragraph format, a
  204.      sorted list of all unique words in the original file.  It might be
  205.      called by entering "getuniq infile outfile" at the DOS prompt:
  206.  
  207.           do h %1 > scrap.1
  208.           do r scrap.1 #32# // #13##10# > scrap.2
  209.           do q scrap.2 > scrap.1
  210.           do b scrap.1 > scrap.2
  211.           do p scrap.2 > scrap.1
  212.           do o scrap.1 > %2
  213.           del scrap.*
  214.  
  215.      This file will take, say, two batch files (%1 and %2) and produce a
  216.      third file (%3) in which the two original files are placed side-by-
  217.      side.  It might be invoked by a command like "glue in1 in2 outfile":
  218.  
  219.           do c %1 1 -40 > scrap.1
  220.           do g scrap.1 %2 > %3
  221.           del scrap.*
  222.  
  223.      One last point: it is permissible to use the console as an input file
  224.      in either the DOS command line or menu mode.  This may be done by
  225.      entering "con:" (or simply ENTER) at the prompt for the input file.
  226.      This is often useful for simply checking to see how a particular
  227.      command affects text of your choosing.  It is also a quick way to
  228.      create a small output file that is already processed.  To end console
  229.      entry, enter <control-Z> as your last character.
  230.  
  231.      Finally, if you wish merely to see summary statistics, just enter NUL
  232.      as your output file.  For example, "do h infile > nul" will give
  233.      information on high bit characters quickly, but without creating an
  234.      output file or showing output to the screen.
  235.  
  236.      It pays to spend some time experimenting if you deal very often with
  237.      text files.  Please feel free to pass this program on to friends.  If
  238.      you liked it (or didn't) or if you have suggestions, please let me
  239.      know.
  240.  
  241. SOURCE CODE COMMENTS
  242.  
  243. {****************************************************************************
  244. *
  245. *  Written by Larrie Hutton, 701 Warren St., Marietta, OH, (614) 374-8337.
  246. *  Version 3.0, last revised 10/1/87.
  247. *
  248. *  This program consists of a collection of useful utility routines.  They
  249. *  are intended to supplement the DOS commands, not to replace them.  Each
  250. *  routine is contained as a case statement in the ConvertFile procedure.
  251. *
  252. *  The commands can be entered as command line parameters, in which case all
  253. *  windowing of input and output is suppressed.  (This also speeds up the
  254. *  program by a factor of about 3.)
  255. *
  256. *  The BASIC OPERATION is as follows:  All file I/O (from the ConvertFile
  257. *  procedure) is handled through the ReadIn and WriteOut procedures, which
  258. *  in turn make decisions about windowing and character-vs-line processing.
  259. *  GetWindow, driven by ReadIn and WriteOut, handles the details of cursor
  260. *  positioning and window sizing.  The details of the three core procedures
  261. *  (GetWindow, ReadIn, and WriteOut) can be seen in the first three
  262. *  procedures of this program.
  263. *
  264. *  The original version of this program was an ASCII-to-WordStar conversion
  265. *  utility, which remains essentially unchanged.
  266. *
  267. *  Twenty-two other utility options are provided: (S)tripping all LFs [with
  268. *  CRs replaced by CR/LF], (X)-ing out all LFs, (P)aragraphing adjacent
  269. *  lines [with (O) to reverse], (Q)uicksort, (H)igh bit removal [or WS to
  270. *  ASCII], (U)pper case conversion [or (L) for lower], (N)umbering lines,
  271. *  (B)ombing repeated and empty lines, (E)xpanding tabs, (T)agging lines,
  272. *  (C)opying a file between any two column positions, (I)nserting a string at
  273. *  any column position, (F)inding or (R)eplacing one string with another,
  274. *  (A)sking before replacing, (J)oining one file into another at a given line
  275. *  or (M)erging them alphabetically, (G)luing two files line by line [useful
  276. *  for column formats], (K) converting all initial letters to upper case and
  277. *  all others to lower [useful for all upper-case mailing lists], and (D)
  278. *  making the last word in a comma-delimited file the first field [useful
  279. *  for mailing lists in which first and last names not entered separately].
  280. *
  281. *                          MAJOR GLOBAL VARIABLES
  282. *
  283. *  Choice - selection from menu.    Console - true if command line.
  284. *  Commands - records user input.   Cursor - array of cursor positions.
  285. *  Active - current window (of 3).  ActiveWin - array of window coordinates.
  286. *
  287. ****************************************************************************}
  288. {****************************************************************************
  289. *
  290. *  Given the appropriate window, calculates new coordinates and saves old
  291. *  cursor position in the Cursor array.  Makes WinNum the Active window.
  292. *
  293. ****************************************************************************}
  294. {****************************************************************************
  295. *
  296. *  Writes data into appropriate window (input or output), taking data type
  297. *  (line or character) into account.
  298. *
  299. ****************************************************************************}
  300. {****************************************************************************
  301. *
  302. *  Writes data into appropriate window (input or output), taking data type
  303. *  (line or character) into account.
  304. *
  305. ****************************************************************************}
  306. {****************************************************************************
  307. *
  308. *  Beeps speaker for msec duration.
  309. *
  310. ****************************************************************************}
  311. {****************************************************************************
  312. *
  313. *  Converts string to upper case.
  314. *
  315. ****************************************************************************}
  316. {****************************************************************************
  317. *
  318. *  Returns given string repeated Factor times.
  319. *
  320. ****************************************************************************}
  321. {****************************************************************************
  322. *
  323. *  Replaces instances of OldSt with NewSt in Line.
  324. *
  325. ****************************************************************************}
  326. {****************************************************************************
  327. *
  328. *  Determines space left on heap.
  329. *
  330. ****************************************************************************}
  331. {****************************************************************************
  332. *
  333. *  Determines number of lines that Mergesort can handle.
  334. *
  335. ****************************************************************************}
  336.   Lines := ( FreeMem * 16.0 - MaxArray * 4.0 - 8192 ) / ( MaxStr + 10.0 )
  337. {****************************************************************************
  338. *
  339. *  User escape and pause.
  340. *
  341. ****************************************************************************}
  342.       #43: writeln( con, 16.0 * FreeMem:6:0, ' bytes free on heap.... ' );
  343. {****************************************************************************
  344. *
  345. *   Performs standard Shell sort on numeric array.
  346. *
  347. ****************************************************************************}
  348.   {**************************************************************************
  349.   *  Converts any real number to a string representation that does not use
  350.   *  exponents; strips all trailing zeros.
  351.   **************************************************************************}
  352. {****************************************************************************
  353. *
  354. *  Read the data in, perform mergesort, and print results.  The Rev
  355. *  parameter controls reverse sort; the Col parameter the column on which
  356. *  the sort is performed.
  357. *
  358. ****************************************************************************}
  359.   {**************************************************************************
  360.   *  Initializes pointers and fields and reads data.
  361.   **************************************************************************}
  362.   {**************************************************************************
  363.   *  Returns pointer (Merge) to new list gotten from merged sublists.
  364.   **************************************************************************}
  365.     {************************************************************************
  366.     *  Sets calling variable and PntrB to PntrA; PntrA advances to next rec.
  367.     ************************************************************************}
  368.   {**************************************************************************
  369.   *  Recursively sorts sublist at First, or MergeSorts both; Merge is pntr.
  370.   **************************************************************************}
  371.   {**************************************************************************
  372.   *  Realigns pointer array; rsets link.
  373.   **************************************************************************}
  374.   {**************************************************************************
  375.   *  Prints out linked list and reclaims heap.
  376.   **************************************************************************}
  377. {****************************************************************************
  378. *
  379. *  Replaces any #nn# combination in Line with its ASCII representation.
  380. *
  381. ****************************************************************************}
  382. {****************************************************************************
  383. *
  384. *  Gets string values from keyboard or command line, as appropriate.
  385. *
  386. ****************************************************************************}
  387. {****************************************************************************
  388. *
  389. *  Returns number from string; default if error.  Gets input from command
  390. *  line if possible.
  391. *
  392. ****************************************************************************}
  393. {****************************************************************************
  394. *
  395. *  Returns adjusted line numbers, size of file, and string reps of lines.
  396. *
  397. ****************************************************************************}
  398. {****************************************************************************
  399. *
  400. *  Sets up information necessary for Replace and Ask operations.
  401. *
  402. ****************************************************************************}
  403. {****************************************************************************
  404. *
  405. *  Shows menu if there are no command line parameters.
  406. *
  407. ****************************************************************************}
  408. {****************************************************************************
  409. *
  410. *  Choose menu option.
  411. *
  412. ****************************************************************************}
  413. {****************************************************************************
  414. *
  415. *  Gets input and output file names.
  416. *
  417. ****************************************************************************}
  418.   {**************************************************************************
  419.   *  Checks for I/O errors and aborts if ambiguous.
  420.   **************************************************************************}
  421. {****************************************************************************
  422. *
  423. *  Strips high bit from all ASCII Characters (Choice = 'H'), or converts
  424. *  to standard WordStar file (Choice = 'W'). See menu for other options.
  425. *
  426. ****************************************************************************}
  427.     'S': {********************** STRIP LFs AND CHANGE ALL CR TO CR/LF ******}
  428.     'X': {************************************** X-OUT ALL LINE FEEDS ******}
  429.     'P': {*************** PARAGRAPH FORMAT (CONSECUTIVE LINES JOINED) ******}
  430.     'O': {********** ONE-LINE PARAGRAPHS AT COLUMN 60 FROM LONG LINES ******}
  431.     'W': {*************************************** WORDSTAR FROM ASCII ******}
  432.     'H': {******************** HIGH BITS REMOVED (ALSO ASCII FROM WS) ******}
  433.     'U': {**************************** CONVERT FILE TO ALL UPPER CASE ******}
  434.     'L': {**************************** CONVERT FILE TO ALL LOWER CASE ******}
  435.     'Q': {********************************** QUICKSORT (REALLY MERGE) ******}
  436.     'N': {******************* NUMBER LINES AND REMOVE TRAILING BLANKS ******}
  437.     'B': {***************************** BOMB REPEATED AND BLANK LINES ******}
  438.     'E': {*********************************************** EXPAND TABS ******}
  439.     'T': {****************************** TAG LINES BETWEEN TWO POINTS ******}
  440.     'C': {*********************************************** COLUMN COPY ******}
  441.     'K': {**** CONVERT ALL INITIAL LETTERS TO UPPER & OTHERS TO LOWER ******}
  442.     'I': {******************** INSERT STRING AT GIVEN COLUMN POSITION ******}
  443.     'F': {*********************************************** FIND STRING ******}
  444.     'R': {*************************** REPLACE ONE STRING WITH ANOTHER ******}
  445.     'A': {******************* ASK AND REPLACE ONE STRING WITH ANOTHER ******}
  446.     'J': {***** JOIN TWO FILES BY INSERTING SECOND INTO FIRST AT LINE ******}
  447.     'M': {*************** MERGE TWO FILES ALPHABETICALLY LINE BY LINE ******}
  448.     'G': {********** GLUE FILES BY APPENDING FILE2'S LINES TO FILE1'S ******}
  449.     'D': {******* MAKE FIRST FIELD INTO TWO--LAST WORD TO FIRST FIELD ******}
  450.     '+': {****************************************** MAKE BIG WINDOWS ******}
  451.     '-': {*************************************** MAKE LITTLE WINDOWS ******}
  452.     '?': {*********************************** REPEAT PREVIOUS COMMAND ******}
  453. {****************************************************************************
  454. *
  455. *  Closes input and output files.
  456. *
  457. ****************************************************************************}
  458. {****************************************************************************
  459. *
  460. *                          M A I N   P R O G R A M
  461. *
  462. ****************************************************************************}
  463. begin { DO_ }
  464.   FirstTime := true;
  465.   ShowDirections;
  466.   GetChoice;
  467.   while ValidChoice do
  468.     begin
  469.     GetFiles;
  470.     ConvertFile;
  471.     CloseFiles;
  472.     GetChoice
  473.     end
  474. end. { DO_ }