Browse files

Use more obvious header formatting

The # and ## can get lost when skimming the file, and the = and -
underlines are far more obvious for the more important headers.
  • Loading branch information...
1 parent 262c35d commit c8a35b089e6229212c7c9f6f2787af0dfc6858da @Benabik Benabik committed Apr 18, 2012
Showing with 42 additions and 21 deletions.
  1. +4 −2 README.mkd
  2. +8 −4 TODO.mkd
  3. +12 −6 docs/compiling.mkd
  4. +12 −6 docs/nodes.mkd
  5. +6 −3 docs/stages.mkd
@@ -1,4 +1,5 @@
-# Parrot Alternate Compiler Toolkit
+Parrot Alternate Compiler Toolkit
This is a redesign and rebuild of the Parrot Compiler Toolkit (PCT), which
is installed with Parrot. PCT provides a quick and easy framework to build
@@ -10,7 +11,8 @@ benabik++'s comments during his Google Summer of Code 2011 project.
Currently the project is in the planning stages and this repository contains
notes and design documents. Assistance, forks, and commentary are welcome!
-## Project Goals
+Project Goals
* Ease of Hacking
* Similar to PCT
@@ -1,6 +1,8 @@
-## Short Term
+Short Term
Most of the items in this list are the subject of a GSoC 2012 proposal by
@@ -22,7 +24,8 @@ The next steps for that are:
`src/packfile/` contains the beginning of a set of classes to handle PBC
files in a structured way. It's mostly full of design notes and ideas.
-## Long Term
+Long Term
One of the main motivations of PACT is generating bytecode. Instead of
starting at the top and trying to ensure we keep everything we'll need
@@ -58,7 +61,8 @@ integer constant, remember that all the way down to the bytecode.
After that, start building top-down. Add features to the AST and see if
any additional CFG/bytecode features are needed to support it.
-## Languages
Both as a sanity check and as a kind of textual IR, it would be extremely
useful to build extremely simple languages on top of several layers of
@@ -1,4 +1,5 @@
-# PACT Compiler Structure
+PACT Compiler Structure
This document describes the "action" half of PACT, the parts responsible
for converting PACT trees from one format to another.
@@ -9,7 +10,8 @@ stage system was intended to be similar to that of tree-optimizer.
-## Stage
(see Tree::Optimizer::Pass)
@@ -79,7 +81,8 @@ When encountering a PACT node, we should recurse.
-## Stage Runner
+Stage Runner
(see Tree::Optimizer)
@@ -106,7 +109,8 @@ This could be brought into PACT's stages for automatic stage resolution.
-## Compiler
This class provides the full compiler API from PDD31. It inherits from the
stage runner class, and uses it's compile function to implement eval. The
@@ -118,7 +122,8 @@ likely be available.
-## REPL
Given a Compiler object, this class handles maintaining an outer context,
interacting with the user, printing results, and catching exceptions. Each
@@ -127,7 +132,8 @@ subclassing.
-## Command Line
+Command Line
Given a Compiler object, this class performs some basic command line option
handling, passing options to stages, target to the compiler, saving the
@@ -1,4 +1,5 @@
-# PACT Nodes
+PACT Nodes
PACT is based around the concept of tree transformations. The High Level
Language (HLL) handles parsing source text however it wants to and builds
@@ -14,7 +15,8 @@ at all so that name isn't very good.
-## Layers
There are four layers of PACT nodes.
@@ -48,7 +50,8 @@ format. It does use some more abstract concepts like labels. It may also
be able to automatically generate constant tables and other meta-data where
-## Common Nodes
+Common Nodes
Any concept used at multiple layers of PACT should have a single common
representation. This may be subclasses at different layers, but we should
@@ -84,7 +87,8 @@ objects. Things this handles include:
-## AST
This level contains high level concepts like "for loops", "exception
handlers", and "lexical variables". It is intended to be as easy as
@@ -121,7 +125,8 @@ Named blocks only have copies inlined.
-## CFG
This level is structured along the lines of the flow of the program. Each
sub is represented by a graph of simple blocks that describe the execution
@@ -146,7 +151,8 @@ Conditions at the end of a Block. A Condition contains a test, generally a
comparison, and two blocks: one for true and another for false.
-## Bytecode
This level is _exactly_ a 1:1 mapping of nodes to Parrot opcodes. The
focus is completely on simplicity of code generation. Bytecode structures
@@ -1,15 +1,18 @@
-# PACT Compiler Stages
+PACT Compiler Stages
This document describe possible stages that get composed together into a
-## Factories
We may wish to provide factory objects that the core stages use to build
PACT nodes so that HLLs can specific default option or alter nodes at
create to inject custom classes.
-## Available Stages
+Available Stages
First the obviously needed stages:

0 comments on commit c8a35b0

Please sign in to comment.