lib/voodoo.rb

   1 require 'voodoo/config'
   2 require 'voodoo/code_generator'
   3 require 'voodoo/compiler'
   4 require 'voodoo/parser'
   5
   6 # = Voodoo - Code Generation for Multiple Target Platforms
   7 #
   8 # This module implements a compiler for the {Voodoo programming
   9 # language}[http://inglorion.net/documents/designs/voodoo/], a simple
  10 # programming language designed to be a thin abstraction of the CPU's
  11 # native instruction set.
  12 #
  13 # The compiler consists of three parts:
  14 #
  15 # 1. The parser (Voodoo::Parser), which reads
  16 #    Voodoo[http://inglorion.net/documents/designs/voodoo/] source code and
  17 #    turns it into Ruby[http://www.ruby-lang.org/] objects.
  18 #
  19 # 2. The code generator (a class that implements the methods of
  20 #    Voodoo::CommonCodeGenerator), which provides methods that generate
  21 #    code for the target platform.
  22 #
  23 # 3. The compiler driver (Voodoo::Compiler), which reads from the parser
  24 #    and calls the appropriate methods of the code generator.
  25 #
  26 # Both the parser and the code generators can be used on their own. For
  27 # example, you could use the code generator to generate native code for
  28 # your own programming language without first creating a
  29 # Voodoo[http://inglorion.net/documents/designs/voodoo/] program.
  30 #
  31 # Instead of instantiating a code generator directly, it is recommended
  32 # that you use Voodoo::CodeGenerator.get_generator to obtain a suitable
  33 # code generator for your target platform.
  34 #
  35 # A few examples to clarify the usage of the module:
  36 #
  37 # The following code compiles the source file <tt>test.voo</tt> to an ELF
  38 # object file called <tt>test.o</tt> containing object code for i386:
  39 #
  40 #   require 'voodoo'
  41 #
  42 #   File.open('test.voo') do |infile|
  43 #     parser = Voodoo::Parser.new infile
  44 #     generator = Voodoo::CodeGenerator.get_generator :architecture => :i386,
  45 #                                                     :format => :elf
  46 #     File.open('test.o', 'w') do |outfile|
  47 #       compiler = Voodoo::Compiler.new parser, generator, outfile
  48 #       compiler.compile
  49 #     end
  50 #   end
  51 #
  52 # The following code uses the code generator API to create an object file
  53 # without the need to create a
  54 # Voodoo[http://inglorion.net/documents/designs/voodoo/] program:
  55 #
  56 #   require 'voodoo'
  57 #
  58 #   generator = Voodoo::CodeGenerator.get_generator
  59 #
  60 #   generator.add :functions, [:export, :fact], [: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   @features = {
  75     :voodoo => 1,
  76   }.freeze
  77
  78   module_function
  79
  80   # Returns a hash describing the features supported by this Voodoo
  81   # implementation. Features defined by the Voodoo specification
  82   # have names not starting in 'x-', whereas extensions to the
  83   # standard start in 'x-'. Each feature has a version, where a
  84   # higher version number indicates compatibility with older versions;
  85   # i.e. if the indicated version is 2, then both version 1 and 2
  86   # are supported.
  87   def features
  88     @features
  89   end
  90
  91   # Tests if this Voodoo implementation supports the named feature.
  92   # The optional version argument can be used to test for a specific
  93   # version of the feature. In that case, the tests succeeds if the
  94   # supported version is equal to or greater than the requested
  95   # version.
  96   def has_feature? name, version = 1
  97     v = @features[name]
  98     v != nil && v >= version
  99   end
 100 end