lib/ruby/voodoo.rb

   1 require 'voodoo/code_generator'
   2 require 'voodoo/compiler'
   3 require 'voodoo/parser'
   4
   5 # = Voodoo - Code Generation for Multiple Target Platforms
   6 #
   7 # This module implements a compiler for the {Voodoo programming
   8 # language}[http://inglorion.net/documents/designs/voodoo/], a simple
   9 # programming language designed to be a thin abstraction of the CPU's
  10 # native instruction set.
  11 #
  12 # The compiler consists of three parts:
  13 #
  14 # 1. The parser (Voodoo::Parser), which reads Voodoo source code and
  15 #    turns it into Ruby objects.
  16 #
  17 # 2. The code generator (a class that implements the methods of
  18 #    Voodoo::CommonCodeGenerator), which provides methods that generate
  19 #    code for the target platform.
  20 #
  21 # 3. The compiler driver (Voodoo::Compiler), which reads from the parser
  22 #    and calls the appropriate methods of the code generator.
  23 #
  24 # Both the parser and the code generators can be used on their own. For
  25 # example, you could use the code generator to generate native code for
  26 # your own programming language without first creating a
  27 # Voodoo[http://inglorion.net/documents/designs/voodoo/] program.
  28 #
  29 # Instead of instantiating a code generator directly, it is recommended
  30 # that you use Voodoo::CodeGenerator.get_generator to obtain a suitable
  31 # code generator for your target platform.
  32 #
  33 # A few examples to clarify the usage of the module:
  34 #
  35 # The following code compiles the source file <tt>test.voo</tt> to an ELF
  36 # object file called <tt>test.o</tt> containing object code for i386:
  37 #
  38 #   require 'voodoo'
  39 #
  40 #   File.open('test.voo') do |infile|
  41 #     parser = Voodoo::Parser.new infile
  42 #     generator = Voodoo::CodeGenerator.get_generator :architecture => :i386,
  43 #                                                     :format => :elf
  44 #     File.open('test.o', 'w') do |outfile|
  45 #       compiler = Voodoo::Compiler.new parser, generator, outfile
  46 #       compiler.compile
  47 #     end
  48 #   end
  49 #
  50 # The following code uses the code generator API to create an object file
  51 # without creating a Voodoo[http://inglorion.net/documents/designs/voodoo/]
  52 # program:
  53 #
  54 #   require 'voodoo'
  55 #
  56 #   generator = Voodoo::CodeGenerator.get_generator :architecture => :i386,
  57 #                                                   :format => :elf
  58 #
  59 #   generator.export :fact
  60 #   generator.add_function_label :fact
  61 #   generator.add_function [:n],
  62 #     [:ifle, [:n, 1],
  63 #       # then
  64 #       [[:return, 1]],
  65 #       # else
  66 #       [[:let, :x, :sub, :n, 1],
  67 #        [:set, :x, :call, :fact, :x],
  68 #        [:return, :mul, :n, :x]]]
  69 #
  70 #   File.open('fact.o', 'w') { |outfile| generator.write outfile }
  71 #
  72
  73 module Voodoo
  74 end