               Collate
               =======

Do you prefer to write your Lua program in many source files?

Drag a directory of source files to !Collate's iconbar icon
and a Lua bytecode file called "!RunImage" will be added at the
top level of it directory.

This source directory must contain a text Lua source file
called "main" at the top level, and optionally another called
"prelude". All other files at the top level are ignored.
All the text files in subdirectories of the source directory
will be treated as source files, recursively. We refer to them
as "ancillary" files. The prelude file is compiled first,
then the ancillary files, and finally the main file. The order
in which the anciliary files are compiled is indeterminate
(and depends on the settings of the filer).

It follows that global variables defined in the prelude are
in scope in all the source files (and in the prelude itself,
after the line where they  have been defined), and that all global
variables defined before a point in the main file will be in scope
there.

There arises the question of dependence within the ancillary files.
What happens if the same variable is defined differently in
more than one ancillary file?

The following regime is suggested. For each ancillary file choose
a different label, to suit your fancy; its leafname, for example,
if these are all distinct.

At the end of the prelude put

         _ancillary = { _G = _G }

and in each ancillary file put at the beginning

         local label = setmetatable ({ }, {__index = _ancillary._G})
         _ancillary[label] = label
         _ENV = label

where label is what you chose for this particular file. Then  a global
variable "foo" defined in the ancillary file that has been labelled "bar"
will be visible as

         _ancillary.bar.foo

in the main file.

With this regime the definitions in the prelude will be usable in each
ancillary file, but those in other ancillary files, and in the main file,
will not. Furthermore, nameclashes between ancillary files have been
resolved.

Other schemes are possible, of course.

Options
=======
The program "Collate" takes as its firstargument a directory
and may be followed by an optional second argument:

-r       Run the collated code quietly.
-c       Create the collated !RunImage file noisily.
-cq, -qc Create the collated !RunImage file quietly.
-cr, -rc Create the collated !RunImage file quietly and run it.

If no options are given the -c option is the default.
          