                           Assorted Utilities
                           

                     by Reuben Thomas (rrt@sc3d.org)


These are some small utilities which I wrote quickly, generally for a
particular task. Some I've found useful ever since; others I rarely
use.

The utilities are distributed under the GNU Public Licence version 2 or at
your option any later version, and comes with no warranty.

See the appropriate !Help files for instructions on !FlashCar and !TaskBASIC.
The rest are documented below. They are command-line utilities, to be used
from the CLI prompt or a Task Window. It's easier to use them if you put them
in your $.Library or !Boot.Library directory, as then they will be found when
you type their name without having to be in the current directory. Just in
case you don't know, it's not necessary to type the names with capital
letters in all the right places: "ReDirect" can just as well (and more
easily) be typed "redirect", for example.


occurs


Counts the number of times each word occurs in a file. I originally wrote it
to check that every word I used in a poem occurred only once (except for a
few very common words), and later used it to remove unused code from a
program (each identifier that only occurred once was a function that was
defined but never used). Archive found it a useful tool for proofreading
(Archive 11.3).

Syntax:

occurs [options] file...

In the file list, - means read from standard input

Options:
  -c --counts        give output sorted by frequency
  -l --lexical       give output sorted by lexical order [default]
  -a --any           symbols consist of non-white-space characters
  -f --freqs         show the frequencies [default]
  -n --nofreqs       don't show the frequencies
  -i --identifiers   symbols consist of alphanumerics and underscores
  -w --words         symbols consist of letters, and are downcased [default]
  -t --tags          symbols are SGML opening tags <tag>
  -d --debug         increases debugging level
  -h -? --help       show help on the usage syntax

(Each option has a long and a short form.)


DiffN


Finds differences between a pair of binary files. Normal diff just says
"binary files x and y differ", which is pretty useless, or, if you force it
to do a diff, prints out swathes of control characters.

Syntax:

DiffN <file1> <file2> [-diffs <number] [-unit {1|2|4}] [-from <offset>]
      [-org <address>]

-diffs <number> gives the maximum number of differences to report, or 0 to
    report them all [default 1]
-unit {1|2|4} gives the size of chunks to compare in bytes [default 1]
-from <offset> gives the offset in the files at which to start [default 0]
-org <address> gives the address of the start of the file [default 0]


BDiff


Finds differences between two BASIC files. It will report lines that differ
and extra lines in each program, so it relies on them having the same line
numbering scheme (if you take one version of a program numbered in increments
of 1 and one in increments of 10, it'll think they're completely different
programs).

Syntax:

BDiff <file1> <file2>


BASICConv


Converts a BASIC file between 6502/ARM format and Z80 format (as used on
Z88s, Amstrad NCs and the Z80 2nd processor). It's based on a program for
Sheridan Williams written for BEEBUG, who kindly gave permission for its
distribution under the GPL. I made it into a command-line utility with
auto-detection of the type of BASIC file it's reading, so there's no need to
specify which way it should convert.

Although BASICConv overwrites the input file, it's quite safe, provided first
that there are no bugs (I'm fairly confident) and secondly that the input is
a valid BASIC file. If both assumptions hold then running BASICConv twice
leaves a file unaltered.

Syntax:

BASICConv <file>


BCat


Joins BASIC files into a single large file. The output file has its lines
numbered in increments of one, starting at zero, as with RENUMBER 0,1.

Syntax:

BCat -o <file-out> <file-in>...


concat


This copies its argument files to standard output. It's useful for joining
files together.

Syntax:

concat file...

In the file list, '-' means read from standard input


UnCRLF


This changes all occurrences of carriage return followed by line feed (ASCII
&d &a) into line feed. This converts a DOS text file into a RISC OS/Unix text
file; don't use it with other sorts of file! Again, best used with Repeat on
whole directories of files; if you've just got one file to do, you can load
it into Zap, untick "DOS text file" on the File menu and save it again.

Syntax:

UnCRLF <file>


ReWrap


This hard-wraps a soft-wrapped text file to a given wrap width.

Syntax:

ReWrap [-width <width>] <in-file> <out-file>

-width <width> sets the wrap width [default 80]


ReDirect


Renames files between xxx.yyy (or yyy.xxx) and xxx/yyy. If you can't think of
a use for it, you don't need it; it's mainly useful for renaming C files, TeX
files and similar things. It's best used with Repeat, in the form:

Repeat "ReDirect [-options]" @

For interactive reuse, I recommend Rename, from <URL>

Two useful aliases:

Set Alias$direct Repeat "ReDirect -copy" %0
Set Alias$undirect Repeat "Repeat ""ReDirect -undirect -copy"""
    %0 -directories

These convert between xxx.yyy and xxx/yyy, which is useful for TeX files, for
example. The second alias (which must be entered on a single line) is
particularly useful as it's not obvious. If you put these in an Obey file,
each % sign must be repeated.

Note: these aliases don't seem to work with the RISC OS 3.7 version of Repeat
(which is in ROM) but work fine with the 3.5 version (which is supplied on
the hard disk). Personally I've kept the RO 3.5 version, calling it rep, and
use it in preference.

Syntax:

ReDirect [-undirect] [-reverse] [-copy] <file>

-undirect makes xxx.yyy into xxx/yyy; otherwise xxx/yyy goes to xxx.yyy
-reverse swaps xxx and yyy
-copy uses *Copy rather than *Rename (some FSes, such as SparkFS, do not
    support renaming)


DownCase


Changes the name of a file so that the first letter is capitalised and the
rest are lower case. Useful with Repeat (e.g. Repeat DownCase @) for
converting directories of DOS files, though there are better and
easier-to-use programs such as Rename (from
http://www.argonet.co.uk/users/tigger/).

Syntax:

DownCase <file>


Source code


The BASIC utilities are their own source files; the source for concat is
concat/c. The version of occurs supplied is slightly out of date, so the
source is not supplied; it can be found in my portable utilities collection
on the same site as this archive (http://sc3d.org/rrt/program/).

