ciat 0.4.8

data/History.txt

@@ -0,0 +1,96 @@
+== 0.4.8 2009-
+* 1 minor feature
+  * Library paths can be specified for parrot executor.
+
+== 0.4.7 2009-09-22
+* 3 major features
+  * File names appear as title attributes for tests and elements in the
+		HTML report.
+  * Folders containing tests are grouped in the HTML report, and each
+		group has a header consisting of the folder's path.
+  * The CIAT::RakeTask class makes defining a rake task a bit cleaner.
+
+== 0.4.1 2009-04-29
+* 1 major feature (bug fix?)
+  * If a test errors or fails, the Suite task will fail.  This sets
+        the command-line status appropriately.
+
+== 0.4.0 2009-04-20
+* 2 major features
+  * All processors now need to read from a file and output to standard output
+ 	and standard error.
+  * All processors now handle command-line arguments.
+
+== 0.3.4 2009-04-05
+* 1 minor feature
+  * Command-line feedback reports number of failures and errors.
+
+== 0.3.3 2009-04-01
+* 1 minor bug fix
+  * Fixed file redirection for Java executor since sh doesn't support &>.
+
+== 0.3.2 2009-02-16
+* 1 minor enhancement
+  * Some line number information in diffs.
+* 1 minor bug fix
+  * in-Java interpreter uses diff output for failures.
+
+== 0.3.1 2009-02-16
+* 1 major bug fix
+  * ACTUALLY added in-Java interpreter executor (missed file in gemspec).
+
+== 0.3.0 2009-02-15
+* 1 major enhancement:
+  * Added in-Java interpreter executor.
+
+== 0.2.0 2008-10-26
+
+* 3 major enhancements:
+  * Elements of a test files are now labeled for greater flexibility; error 
+    checking is done on the elements (missing, unused, etc.).
+  * A test file can specify optional elements for a processor.  Parrot
+    executor uses "command line" for command-line arguments; it provides
+    a default if not specified.
+  * Formatting improvements to the HTML report.
+* 1 minor enhancement:
+  * Java compiler redirects standard error to a file.
+
+== 0.1.1 2008-08-16
+
+* 1 major bug fix
+  * If executor is not run (while compilation fails), its traffic light is
+    unset; the standard output feedback now handles this case.
+
+== 0.1.0 2008-08-14
+
+* 2 major enhancements:
+  * Generates a very useful HTML report, complete with side-by-side diffs.
+  * Immediate feedback while tests are running ("."s, "F"s, and "E"s).
+
+== 0.0.4 2008-08-08
+
+* 2 major enhancements:
+  * Flexible way to specified test files (including recursive search).
+  * Executor triggered only if compilation phase is green.
+* minor
+  * Internal renamings and restructuring.
+
+== 0.0.3 2008-08-02
+
+* 2 major enhancements:
+  * Major refactoring of internals
+  * Feedback mechanisms (for simple status reports, not failure/success yet) added
+* 1 modification:
+  * Expecting .ciat as file extension of CIAT test files.
+
+== 0.0.2 2008-07-28
+
+* 1 major enhancement:
+  * Actual RubyDocs!
+
+== 0.0.1 2008-07-28
+
+* 1 major enhancement:
+  * Initial release
+    * Runs tests over all *.txt files.
+    * Slight abstraction for compiler and executor.

data/README.rdoc

@@ -0,0 +1,135 @@
+= CIAT (Compiler and Interpreter Acceptance Tester)
+
+== DESCRIPTION:
+
+CIAT (pronounced "dog") provides a system for writing high-level acceptance
+tests for compilers and interpreters. Each acceptance test is entered into a
+single file, and that file identifies the elements of a test.
+
+
+== SYNOPSIS:
+
+Suppose you have a compiler written in Java that compiles a language named
+Hobbes. Your compiler targets the Parrot Virtual Machine. So you want to
+provide <em>source code</em> which is <em>compiled with a Java program</em>
+and that result is <em>interpreted by Parrot</em>.
+
+=== Input File
+
+Input files should be named with a <code>.ciat</code> extension and saved in a
+<code>ciat</code> folder.
+
+A sample input file (<code>simpleinteger5.ciat</code>) for the scenario
+described above might look like this:
+
+  Compiles a simple integer.
+  ==== source
+  5
+  ==== compilation
+  .sub main
+    print 5
+    print "\n"
+  .end
+  ==== execution
+  5
+
+This file specifies <em>four</em> elements: description, <b>source</b>,
+<b>compilation</b>, and <b>execution</b>. The description is always the first
+element, always unlabeled, and used prominently in the HTML report. All of the
+other elements are dependent on the processors that you use.
+
+In this example, we're using a "Java compiler" (a compiler <em>written in</em>
+Java) and a "Parrot executor". CIAT's "Java compiler" runs your compiler over
+the <b>source</b>, and that output is compared to the <b>compilation</b>
+element. Then the "Parrot executor" is executed with the <em>generated</em>
+compilation, and that output is compared to the <b>execution</b> element.
+
+If any processor fails, either due to an error while running or a failure
+during checking the output, the remaining processors are not executed.
+
+Some processors will use optional elements in a test file.  For example, the "Parrot executor" knows about command-line arguments:
+
+  Compiles a simple integer and ignores the command-line arguments.
+  ==== source
+  5
+  ==== compilation
+  .sub main
+    print 5
+    print "\n"
+  .end
+  ==== command line
+  89 pqp
+  ==== execution
+  5
+	
+When the "Parrot executor" is run on the compilation, it'll also pass in <code>89 pqp</code> as command-line arguments.
+
+=== The Rakefile
+
+This sample +Rakefile+ will pull everything together:
+
+  require 'ciat'
+  require 'ciat/compilers/java'
+  require 'ciat/executors/parrot'
+
+  def compiler
+    classpath = Dir.glob('../lib/*.jar').join(':') + ":../bin"
+    CIAT::Compilers::Java.new(classpath, 'org.norecess.hobbes.drivers.PIRCompiler')
+  end
+
+  def executor
+    CIAT::Executors::Parrot.new
+  end
+
+  CIAT::RakeTask.new do |t|
+    t.processors << compiler
+    t.processors << executor
+  end
+
+This rakefile will find all of the <code>.ciat</code> files inside a +ciat+
+directory, each one representing a test. Each test will be executed, and the
+results are put into a folder named +temp+, including the HTML report
+<code>report.html</code>. All of these settings can be tweaked; see the
+documentation for CIAT::RakeTask for more information.
+
+
+== REQUIREMENTS:
+
+* Pronounce "CIAT" as "dog".  (See this funny video[http://www.youtube.com/watch?v=tyQvjKqXA0Y].)
+* Must have +diff+ executable.
+* You have to provide your own target-code executors (e.g., +parrot+ for the
+  Parrot Virtual Machine, +spim+ for MIPS emulation, etc.)
+
+
+== INSTALL:
+
+* Install +diff+.
+* Install Ruby and Ruby Gems.
+* <code>sudo gem sources -a http</code><code>://gems.github.com</code> (only needed once)
+* <code>sudo gem install jdfrens-ciat</code>
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Jeremy D. Frens
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+task :default => :specs
+
+desc "Run all examples"
+Spec::Rake::SpecTask.new(:specs) do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+desc "Run all examples with rcov"
+Spec::Rake::SpecTask.new(:specs_with_rcov) do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end
+
+desc "Generate documentation for CIAT"
+Rake::RDocTask.new(:doc) do |t|
+  t.rdoc_dir = 'doc'
+  t.title    = "CIAT"
+  t.options << '--line-numbers' << '--inline-source'
+  t.options << '--charset' << 'utf-8'
+  t.rdoc_files.include('README.rdoc')
+  t.rdoc_files.include('History.txt')
+  t.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Make and install gem"
+task :gem => [:specs_with_rcov] do
+  system "sudo gem uninstall ciat"
+  system "rm *.gem"
+  system "gem build ciat.gemspec"
+  system "sudo gem install ciat*.gem"
+end
+CLOBBER << FileList['*.gem']

data/ciat.gemspec

@@ -0,0 +1,53 @@
+Gem::Specification.new do |s|
+  s.name     = "ciat"
+  s.version  = "0.4.8"
+  s.summary  = "Acceptance tester for compilers and interpreters"
+  s.email    = "jdfrens@gmail.com"
+  s.homepage = "http://github.com/jdfrens/ciat"
+  s.description = "CIAT (pronounced \"dog\") is a library of Ruby and rake code to make writing acceptance tests for compilers and interpreters easier (despite their implementation, source, and target languages)."
+  s.has_rdoc = true
+  s.authors  = ["Jeremy D. Frens", "Mark Van Holstyn"]
+  s.files    = 
+    ["History.txt", "README.rdoc", "Rakefile", "ciat.gemspec", 
+      "lib/ciat/version.rb",
+      "lib/ciat.rb",
+      "lib/ciat/rake_task.rb",
+      "lib/ciat/cargo.rb",
+      "lib/ciat/crate.rb",
+      "lib/ciat/suite.rb",
+      "lib/ciat/test.rb",
+      "lib/ciat/erb_helpers.rb",
+      "lib/ciat/test_element.rb",
+      "lib/ciat/traffic_light.rb",
+      "lib/ciat/processors/copy.rb",
+      "lib/ciat/processors/basic_processing.rb",
+      "lib/ciat/processors/compiler.rb",
+      "lib/ciat/processors/interpreter.rb",
+      "lib/ciat/processors/compilation_interpreter.rb",
+      "lib/ciat/compilers/java.rb",
+      "lib/ciat/executors/java.rb",
+      "lib/ciat/executors/parrot.rb",
+      "lib/ciat/differs/html_differ.rb",
+      "lib/ciat/feedback/standard_output.rb",
+      "lib/ciat/feedback/html_feedback.rb",
+      "lib/ciat/feedback/feedback_counter.rb",
+      "lib/ciat/feedback/composite.rb",
+      "lib/ciat/feedback/return_status.rb",
+      "lib/data/ciat.css",
+      "lib/data/prototype.js",
+      "lib/data/elements.yml",
+      "lib/templates/report.html.erb",
+      "lib/templates/group_header.html.erb",
+      "lib/templates/summary_row.html.erb",
+      "lib/templates/test_numbers.html.erb",
+      "lib/templates/detail_row.html.erb",
+      "lib/templates/detail_row/elements.html.erb",
+      "lib/templates/elements/diff.html.erb",
+      "lib/templates/elements/plain.html.erb",
+      ]
+  s.extra_rdoc_files = ["README.rdoc", "History.txt"]
+  s.rdoc_options <<
+    '--title' << 'CIAT -- Compiler and Interpreter Acceptance Tester' <<
+    '--main' << 'README.txt' <<
+    '--line-numbers'
+end

data/lib/ciat.rb

@@ -0,0 +1,22 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+# Loads in the basic files needed to use CIAT.  Compilers and Executors have
+# to be required separately. CIAT::Suite is the class you really want to look
+# at.
+module CIAT; end
+
+require 'ciat/rake_task'
+require 'ciat/traffic_light'
+require 'ciat/suite'
+require 'ciat/test'
+require 'ciat/test_element'
+require 'ciat/cargo'
+require 'ciat/crate'
+require 'ciat/feedback/standard_output'
+require 'ciat/feedback/html_feedback'
+require 'ciat/differs/html_differ'
+require 'ciat/processors/basic_processing'
+require 'ciat/processors/compiler'
+require 'ciat/processors/interpreter'
+require 'ciat/processors/compilation_interpreter'

data/lib/ciat/cargo.rb

@@ -0,0 +1,55 @@
+class CIAT::Cargo #:nodoc:all
+  OUTPUT_FOLDER = "temp"
+  REPORT_FILENAME = "report.html"
+  
+  attr_reader :output_folder
+  attr_reader :crates
+  attr_reader :report_filename
+  
+  def initialize(options={})
+    @output_folder = options[:output_folder] || OUTPUT_FOLDER
+    if options[:files]
+      filenames = options[:files]
+    else  
+      folder = options[:folder] || "ciat"
+      pattern = options[:pattern] || "*.ciat"
+      filenames = Dir[File.join(folder, "**", pattern)]
+    end
+    @crates = filenames.map { |filename| CIAT::Crate.new(filename, @output_folder) }
+    @report_filename = File.join(@output_folder, options[:report_filename] || REPORT_FILENAME)
+  end
+  
+  def size
+    crates.size
+  end
+  
+  def copy_suite_data
+    FileUtils.mkdir_p(output_folder)
+    FileUtils.cp(File.join(File.dirname(__FILE__), "..", "data", "ciat.css"), output_folder)
+    FileUtils.cp(File.join(File.dirname(__FILE__), "..", "data", "prototype.js"), output_folder)
+  end
+  
+  # TODO: get rid of this in favor of the class method
+  def write_file(filename, content)
+    FileUtils.mkdir_p(File.dirname(filename))
+    File.open(filename, "w") do |file|
+      file.write content
+    end
+  end
+  
+  # TODO: get rid of this in favor of the class method
+  def read_file(filename)
+    File.read(filename)
+  end
+
+  def self.write_file(filename, content)
+    FileUtils.mkdir_p(File.dirname(filename))
+    File.open(filename, "w") do |file|
+      file.write content
+    end
+  end
+  
+  def self.read_file(filename)
+    File.read(filename)
+  end
+end

data/lib/ciat/compilers/java.rb

@@ -0,0 +1,54 @@
+module CIAT
+  module Compilers
+    # Implements a processor written in Java.
+    #
+    # It requires <code>source</code> and <code>compilation</code> elements.
+    # * <code>source</code> is used as source to the Java compiler.
+    # * <code>compilation</code> is used for comparsion.
+    #
+    # == Best Practices
+    #     
+    # Suppose you use Eclipse to develop your compiler or interpreter, and you
+    # have this folder structure:
+    # * +bin+ stores your compiled classes (under test)
+    # * +lib+ contains support JAR files
+    # * +acceptance+ is a root folder for your CIAT tests with your +Rakefile+
+    # You may find this classpath useful:
+    #   Dir.glob('../lib/*.jar').join(':') + ":../bin"
+    class Java
+      include CIAT::Processors::BasicProcessing
+      include CIAT::Differs::HtmlDiffer
+
+      # The traffic light to indicate the success or failure of the processor.
+      attr :light, true
+      attr_reader :processor_kind
+      
+      # Constructs a "Java compiler" object.  +classpath+ is the complete
+      # classpath to execute the compiler.  +compiler_class+ is the fully
+      # qualified name of the class that executes your compiler; this driver
+      # should take two command-line arguments: the name of the source file
+      # and the name of the generated target-code file.
+      #
+      # Possible options:
+      # * <code>description</code> specifies a descriptive name for your
+      #   compiler; used in the HTML report.
+      def initialize(classpath, compiler_class, options={})
+        @processor_kind = options[:processor_kind] || CIAT::Processors::Compiler.new
+        @classpath = classpath
+        @compiler_class = compiler_class
+        @descriptions = {}
+        @description = options[:description] || "compiler (implemented in Java)"
+        @light = options[:light] || TrafficLight.new
+      end
+
+      # Return a description of the processor.
+      def describe
+        @description
+      end
+      
+      def executable
+        "java -cp '#{@classpath}' #{@compiler_class}"
+      end
+    end
+  end
+end