Readme documentation for CHLEX (CHL Extractor)
for the Lionhead Virtual Machine, version 1.0

by James "Anthem" Costlow.


Readme contents:
================
 1. Zip contents
 2. What is CHLEX?
 3. What is its status?
 4. What if I find a bug?
 5. Can I get the source?
 6. How do I use it?
 7. For additional information
    7.1. Unofficial Lionhead Virtual Machine Reference
 8. Contact Information


1. Zip Contents:
================

The following files and directories should have been included with this
document in the chasm.zip archive:

  -CHLEX.EXE
  -README.TXT (this file)


2. What is CHLEX?
=================
 CHLEX is a small utility I created to aid in reverse engineering the Lionhead
Virtual Machine. It proved invaluable, and made it much easier on the eyes than
looking at hex all day long.


3. What is its status?
======================
 CHLEX is not being actively developed or maintained.


4. What if I find a bug?
========================
 If you find a bug, you are welcome to notify me of the issue at the email
address provided below. However, as CHLEX is not being actively maintained, no
guarantee is provided that it will be resolved in a timely manner, or at all.
 If you have programming experience and would like to resolve the issue
yourself, see the following section, "Can I get the source?"


5. Can I get the source?
========================
 Yes. You may send an email to the address below to request the CHLEX source
code. It has no license, and you may freely use and redistribute it. I ask
only that if you redistribute it with modifications, please have some common
courtesy and credit me for my work.

 If you resolve a bug, or simply do something interesting with it, I'd like to
hear about it.


6. How do I use it?
===================
 NOTE: These instructions assume you're familiar with DOS and/or the Windows
       command prompt.

 Run the program with a command in the format:

    >  chlex chlfile [/options][sourcefile] outfile

 where 'chlfile' is the location of the CHL file to extract/decompile and
'outfile' is the location where the results should be saved, which may vary
depending on the option used. The 'sourcefile' option is described below.

 CHLEX has two types of options: extraction options, and processing options:

 Extraction options:
 -------------------
 Extraction options affect what information about the CHL file gets extracted,
and how that information is saved. Only one extraction option may be used at
a time.

    a : extract each source file separately instead of everything
        being lumped together. 'outfile' specifies the directory where the
        files should be stored.

    d : only the data section of the CHL file gets extracted. The format is
        CHASM-style byte data. This option is not affected by the processing
        options.

    e : extract CHL in its entirety to a single file (this is the default)

    f : extract a single source file (whose name is specified by 'sourcefile'
        from the CHL

    s : extract a list of the source files contained in the CHL

 Processing options:
 -------------------
 Processing options affect the way the extracted information is represented.
Multiple processing options may be specified, but some may be ignored.

    c : output is in CHASM-style source code. This option ignores the /i
        option, since it would produce invalid source.

        If this option is not specified (which is the default), instructions
        and data are translated and output in a generic human-readable form.

    i : do not add line numbers to simple output

    l : do not convert instruction addresses to automatically-generated labels

    n : do not replace function numbers with the function name

    v : do not replace variable numbers with their names


7. For additional information
==============================
   7.1. Unofficial Lionhead Virtual Machine Reference
   ==================================================
    For more information about CHL files and the Lionhead Virtual Machine,
   check out the Unofficial Lionhead Virtual Machine Reference, available
   in the Documents portion of the Team Grey Area website:
       http://www.planetblackandwhite.com/greyarea/


8. Contact information
======================
 To contact me about CHLEX, obtaining its source, or its documentation, please
email me at:
    anthem2112@verizon.net
or contact Team Grey Area through our forums at our website, listed above.