= Part I - Introduction

== Rationale

Please read the README file - it's short and to the point.

If you're too lazy:

* I don't know haskell, forth or parrot
* I am going to write a forth to parrot compiler in haskell
* I hope it will teach me all three
* I hope I can document how I got there in this tutorial.

== Background

I'm a Perl programmer, sucked into Pugs development. Haskell seemed very
attractive, but every time I tried to learn it, I got through a tutorial, and I
said "ok, now what".

I did not grok monads.

I mean, I could use them, and I sort of knew what they were doing, but I had no
clue what they were good for.

I had no clue when something becomes a monad, and when it isn't.

I had even less of a clue when something should be a monad.

== This Tutorial Thing

This tutorial-journal thing is supposed to be a document, following I did to
try and get myself moving forward. It's supposed to be written in a way that
any reader can follow along, and hopefully reproduce the process.

Maybe if I figured out what the hell is going on, someone else could too =)

== What I Do Know

First of all, I must say I lied in the README. I do know a bit:

* Naive functional programming
* Primitive haskell
* X86 Assembly
* Stack based state machines

What I don't know:

* Thinking in Haskell
** Monads
** Structure
* Thinking in Forth
* Parrot's Assembly

I plan to touch on the things that I do know, but I don't think I can introduce
them very well.

Instead I'll point you to some other documents, and hope for the best. Not
"getting" these tutorials probably isn't going to be a problem, because I
didn't.

== The Plan

Our Forth compiler will be based around some ideas from the Pugs project.

=== The parser

We will write a parser that creates an AST with Parsec. This will teach us how
to design an AST, and how to write Parsec parsers to generate our AST.

=== The evaluator

We will write an evaluator for that AST in Haskell. This will teach us about
monadic constructs, avoiding laziness, structures for the interpretation,
interaction with the real world, and meta-language way of thought.

=== GADT

We will validate the AST with GADT, to learn GADT and to check the correctness of compiled forth programs.

=== Pretty printing

We will pretty print parrot code from the AST, and possibly other languages
later. This will test our code's interoperability, and teach us Parrot.

=== Embedding

We will embed parrot later, to encapsulate the process in one command. This
will teach us some parrot APIs, and haskell constructs.

=== Optimization

We will try to optimize the AST, and the pretty printed code. Forth is
notoriously optimizable. This should be a test for our design, and abilities.

== Language Feature Summary

What I hope to get of the three languages:

* Haskell
** Monads
*** IO
**** Interactive
**** Files
*** Storage
** Tools
*** Parsec
*** GADT
*** C code embedding
**** of parrot
* Forth
** The concept in general
* Parrot
** The details
*** PMC implementations
*** builtin ops
*** general usage

= Summary

Writing these words, and committing them to darcs, I've yet to write a single
line of code.

I hope the plan will change, and that the only things I will go back in time
for are grammatical corrections and the likes.

I plan to edit out my mistakes only if I think they create too much confusion.

The tutorial is supposed to track my thoughts - a sort of journal, but not in
journal format. If it's not readable as instructions one can follow, please
submit a bug.

Wish me luck!