Goldie: GOLD Engine for D v0.01
by Nick Sabalausky

See LICENSE.txt for license information.

=============================
| Goldie: GOLD Engine for D |
=============================

Goldie is written in The D Programming Language (http://www.digitalmars.com/d).

Homepage:
----------
http://www.dsource.org/projects/goldie

About:
-------
Goldie (pronounced "goal D") is a GOLD Engine for D.

It gives D developers the ability to easily load, lex and parse a text/source
file according to any grammar defined using the excellent GOLD Parser Builder
tool (http://www.devincook.com/goldparser/).

Alternatively, Goldie can be used to merely load a GOLD .cgt file ("Compiled
Grammar Table") if you would like to create your own GOLD lexer/parser.

Goldie is fully-usable, although the API is still subject to change.

=================
| Requirements: |
=================

This has been tested to work on Windows and Linux x86. In theory, FreeBSD
*should* work, but I haven't tried it. OSX x86 may also work, but will
probably need some tweaking.

- [Required]    Tango 0.99.8
- [Required]    DMD 1.043 (LDC untested) (Get DMD bundled with Tango)
- [Required]    SemiTwist D Tools trunk r82
- [Required]    GOLD Parser Builder
- [Recommended] Rebuild 0.76 (Only needed to build the included sample apps)
- [Optional]    Programmer's Notepad 2 (ie, PN2 Project files are included)

Notes:
- DMD 1.044+ with Tango Trunk might work, but is untested.
- Rebuild 0.78 might work, but is quirky and not recommended.
- Rebuild can be obtained as part of DSSS: http://www.dsource.org/projects/dsss
- Other build systems besides rebuild can probably be used, but you'll be on
your own.

Digital Mars D Compiler (DMD) v1.043:
--------------------------------------
Reference compiler for The D Programming Language.

Newer versions of the 1.x branch may also work, *if* you also use
Tango trunk (or Tango 0.99.9 once it's released) instead of Tango 0.99.8.
However, this has not yet been tested.

The 2.x branch of DMD most likely will *not* work. (It is still the "unstable"
branch of DMD.)

LDC (The D compiler from the LLVM project) might work (at least on Linux),
but I haven't tried.

DMD Homepage: http://www.digitalmars.com/d/
Download: Get this together with Tango.

Tango 0.99.8:
--------------
Library for The D Programming Language.
It is recommended to get the download that includes DMD.
You may want (or need) to then update DMD to 1.043 (all you need to do is
overwrite the executables in "bin" - but only the executables).

Tango trunk (or Tango 0.99.9 once it's released) may also work, *if* you also
use DMD 1.044 or later. However, this has not yet been tested.

Tango Homepage: http://www.dsource.org/projects/tango
Download Page: http://www.dsource.org/projects/tango/wiki/DmdDownloads
Direct Win Download Link: http://downloads.dsource.org/projects/tango/0.99.8/tango-0.99.8-bin-win32-dmd.1.041.zip

SemiTwist D Tools:
-------------------
This is a set of tools and a library for D. The library is required by Goldie.
Also included in SemiTwist D Tools is STBuild, which uses Rebuild and can be
used to build Goldie's sample apps.

SemiTwist D Tools Homepage: http://www.dsource.org/projects/semitwist

GOLD Parser Builder:
---------------------
Excellent freeware tool. Needed to create/modify languages that can be used
with Goldie. Not actually included with Goldie though.

Homepage: http://www.devincook.com/goldparser/
Download Page: http://www.devincook.com/goldparser/builder/index.htm
Direct Download Link: http://www.devincook.com/goldparser/builder/download/gold-parser-builder.zip

Rebuild 0.76 (Part of DSSS):
-----------------------------
Not strictly needed, but highly recommended.

The main 'dsss' program isn't used, but DSS includes the very useful tool
'rebuild'. This 'rebuild' is similar to make, except it is designed specifically
for D and doesn't require (or support) any sort of makefile or build script. To
use 'rebuild', you just pass it the file containing the 'main()' function
(in STC and semitwistlib, this is always 'main.d'), and it will automatically
find all dependencies and rebuild them if necessary.

There are alternatives to DSSS's 'rebuild', such as 'bud' and 'xfBuild', but I
haven't tried them on Goldie.

Rebuild 0.78 might also work, but it is quirky and not recommended.

DSSS Homepage: http://www.dsource.org/projects/dsss

Programmer's Notepad 2:
------------------------
Optional, but the included project files are for Programmer's Notepad 2, so it
could help. Note, the *.ppg files are always the main project files (the
*.pnproj files are secondary).

Homepage: http://www.pnotepad.org/
Download Page: http://www.pnotepad.org/download/

===================
| How to Install: |
===================

Assuming you already have DMD, Tango and DSSS/Rebuild installed (DSSS/Rebuild
is only needed if you want to build the sample apps):

1. Download Goldie and SemiTwist D Tools. You can obtain both via Subversion:
     > svn co -r 82 http://svn.dsource.org/projects/semitwist/trunk SemiTwistDTools
     > svn co http://svn.dsource.org/projects/goldie/tags/latest-stable Goldie
	 
   Direct download links are also available from the Goldie website:
     http://www.dsource.org/projects/goldie

2. [This step is only needed if you wish to build the sample apps and you're
   not using Windows or Linux x86.]

   Build SemiTwist D Tools. From SemiTwist D Tools's root directory:
     > ./buildAll

3. [This step is only needed if you wish to build the sample apps or use
   the tools in SemiTwist D Tools for your own projects.]

   Add SemiTwist D Tools's "bin" directory to your PATH environment variable.
   
   (On WinXP, environment variables can be accessed by: Right-Click on
   "My Computer", "Properties", "Advanced" tab, "Environment Variables" button.)

4. Tell your compiler where to find Goldie and SemiTwist D Tools.
   To do this for DMD:

   Go to DMD's "bin" directory and open "sc.ini" (Windows) or "dmd.conf" (All
   other OSes). On the line that starts with...

     DFLAGS=

   ...add the following flags...

     -Ipath_to_SemiTwistDTools/src -Ipath_to_Goldie/src

   ...and save.

=================
| How to Build: |
=================

In Your Own Project
--------------------
Once you've installed Goldie and SemiTwistDTools as instructed above, all
that's left to do is import it in your code:

  import goldie.all;

And build your project as you normally would.

See the API documentation (on Goldie's website) and the included sample apps
for instructions on how to use Goldie.

Sample Apps
------------
The included sample apps can be built using STBuild (part of SemiTwist D Tools).

1. Make sure your path includes DSSS's "bin" directory (for Rebuild) and
   SemiTwist D Tools's "bin" directory (for STBuild).

2. If you're not using Windows or Linux x86, you'll need to build SemiTwist D
   Tools. From SemiTwist D Tools's root directory:
   > ./buildAll

3. From Goldie's root directory:
   > stbuild all

(See the SemiTwist D Tools documentation for more detailed information on
STBuild.)
