relevance-rcov 0.8.2.1

data/doc/readme_for_api

@@ -0,0 +1,41 @@
+
+= +rcov+
+
++rcov+ is a:
+1. tool for code coverage analysis for Ruby
+2. library for collecting code coverage and execution count information
+   introspectively
+
+If you want to use the command line tool, the output from
+ rcov -h
+is self-explicative.
+
+If you want to automate the execution of +rcov+ via Rake take a look at
+readme_for_rake[link:files/README_rake.html].
+
+If you want to use the associated library, read on.
+
+== Usage of the +rcov+ runtime/library
+
++rcov+ is primarily a tool for code coverage analysis, but since 0.4.0 it
+exposes some of its code so that you can build on top of its heuristics for
+code analysis and its capabilities for coverage information and execution
+count gathering.
+
+The main classes of interest are Rcov::FileStatistics,
+Rcov::CodeCoverageAnalyzer and Rcov::CallSiteAnalyzer. 
+
+Rcov::FileStatistics can use some heuristics to determine
+which parts of the file are executable and which are mere comments.
+
+Rcov::CodeCoverageAnalyzer is used to gather code coverage and execution
+count information inside a running Ruby program.
+
+Rcov::CallSiteAnalyzer is used to obtain information about where methods are
+defined and who calls them.
+
+The parts of +rcov+'s runtime meant to be reused (i.e. the external API) are
+documented with RDoc. Those not meant to be used are clearly marked as so or
+were deliberately removed from the present documentation.
+
+

data/doc/readme_for_emacs

@@ -0,0 +1,64 @@
+
+<tt>rcov.el</tt> allows you to use rcov from Emacs conveniently.
+* Run unit tests and jump to uncovered code by <tt>C-x `</tt>.
+* Run unit tests and save the current coverage status.
+* Run unit tests and jump to uncovered code introduced since the last run.
+* View cross-reference annotated code.
+
+== Installation
+
+Copy <tt>rcov.el</tt> to the appropriate directory, which is in load-path.
+Then require it.
+  (require 'rcov)
+
+
+== Usage
+
+There are some commands to run rcov in Emacs.
+All of them displays +rcov+ window, whose major-mode is compilation-mode.
+Therefore you can jump to uncovered code by <tt>C-x `</tt>.
+
++rcov-command-line+, +rcovsave-command-line+, and +rcovdiff-command-line+ define
+command line to run rcov.
+If you do not use +rcov+ from Rake, you must modify them.
+
+=== Finding uncovered code
+
+Type the following while editing your program:
+  M-x rcov
+  
+=== Setting the reference point
+
++rcov+'s <tt>--text-coverage-diff</tt> mode compares the current coverage status against
+the saved one. It therefore needs that information to be recorded
+before you write new code (typically right after you perform a commit) in
+order to have something to compare against.
+
+You can save the current status with the <tt>--save</tt> option.
+
+Type the following to save the current status in Emacs:
+  M-x rcovsave
+If you do not use +rcov+ from Rake, you must modify +rcovsave-command-line+ variable.
+
+=== Finding new uncovered code
+
+Type the following to save the current status in Emacs:
+  M-x rcovdiff
+
+=== Viewing cross-reference annotated code
+
+If you read cross-reference annotated code, issue
+  rake rcov RCOVOPTS='-a'
+at the beginning.
+This command creates +coverage+ directory and many *.rb files in it.
+Filenames of these Ruby scripts are converted from original path.
+You can browse them by normally <tt>C-x C-f</tt>.
+You can think of <tt>-a</tt> option as <tt>--xrefs</tt> option and output format is Ruby script.
+
+After find-file-ed annotated script, the major-mode is rcov-xref-mode,
+which is derived from ruby-mode and specializes navigation.
+
+<tt>Tab</tt> and <tt>M-Tab</tt> goes forward/backward links.
+<tt>Ret</tt> follows selected link.
+
+This feature is useful to read third-party code or to follow control flow.

data/doc/readme_for_rake

@@ -0,0 +1,62 @@
+
+== Code coverage analysis automation with Rake
+
+Since 0.4.0, <tt>rcov</tt> features a <tt>Rcov::RcovTask</tt> task for rake
+which can be used to automate test coverage analysis.  Basic usage is as
+follows:
+
+ require 'rcov/rcovtask'
+ Rcov::RcovTask.new do |t|
+   t.test_files = FileList['test/test*.rb']
+   # t.verbose = true     # uncomment to see the executed command
+ end
+
+This will create by default a task named <tt>rcov</tt>, and also a task to
+remove the output directory where the XHTML report is generated.
+The latter will be named <tt>clobber_rcob</tt>, and will be added to the main
+<tt>clobber</tt> target.
+
+=== Passing command line options to <tt>rcov</tt>
+
+You can provide a description, change the name of the generated tasks (the
+one used to generate the report(s) and the clobber_ one) and pass options to
+<tt>rcov</tt>:
+
+ desc "Analyze code coverage of the unit tests."
+ Rcov::RcovTask.new(:coverage) do |t|
+   t.test_files = FileList['test/test*.rb']
+   t.verbose = true
+   ## get a text report on stdout when rake is run:
+   t.rcov_opts << "--text-report"  
+   ## only report files under 80% coverage
+   t.rcov_opts << "--threshold 80"
+ end
+
+That will generate a <tt>coverage</tt> task and the associated
+<tt>clobber_coverage</tt> task to remove the directory the report is dumped
+to ("<tt>coverage</tt>" by default).
+
+You can specify a different destination directory, which comes handy if you
+have several <tt>RcovTask</tt>s; the <tt>clobber_*</tt> will take care of
+removing that directory:
+
+ desc "Analyze code coverage for the FileStatistics class."
+ Rcov::RcovTask.new(:rcov_sourcefile) do |t|
+   t.test_files = FileList['test/test_FileStatistics.rb']
+   t.verbose = true
+   t.rcov_opts << "--test-unit-only"
+   t.output_dir = "coverage.sourcefile"
+ end
+ 
+ Rcov::RcovTask.new(:rcov_ccanalyzer) do |t|
+   t.test_files = FileList['test/test_CodeCoverageAnalyzer.rb']
+   t.verbose = true
+   t.rcov_opts << "--test-unit-only"
+   t.output_dir = "coverage.ccanalyzer"
+ end
+
+=== Options passed through the <tt>rake</tt> command line
+
+You can override the options defined in the RcovTask by passing the new
+options at the time you invoke rake. 
+The documentation for the Rcov::RcovTask explains how this can be done.

data/doc/readme_for_vim

@@ -0,0 +1,47 @@
+
+<tt>rcov.vim</tt> allows you to run unit tests from vim and enter quickfix mode in
+order to jump to uncovered code introduced since the last run.
+
+== Installation
+Copy <tt>rcov.vim</tt> to the appropriate "compiler" directory (typically
+<tt>$HOME/.vim/compiler</tt>).
+
+== Usage
+
+=== Setting the reference point
+
++rcov+'s <tt>--text-coverage-diff</tt> mode compares the current coverage status against
+the saved one. It therefore needs that information to be recorded
+before you write new code (typically right after you perform a commit) in
+order to have something to compare against.
+
+You can save the current status with the <tt>--save</tt> option.
+If you're running +rcov+ from Rake, you can do something like
+  rake rcov_units RCOVOPTS="-T --save --rails"
+in order to take the current status as the reference point.
+
+=== Finding new uncovered code
+
+Type the following in command mode while editing your program:
+   :compiler rcov
+
+rcov.vim assumes +rcov+ can be invoked with a rake task (see 
+readme_for_rake[link:files/README_rake.html] for
+information on how to create it). 
+
+You can then execute +rcov+ and enter quickfix mode by typing
+
+   :make <taskname>
+
+where taskname is the +rcov+ task you want to use; if you didn't override the
+default name in the Rakefile, just
+  
+   :make rcov
+
+will do.
+
+vim will then enter quickfix mode, allowing you to jump to the areas that were
+not covered since the last time you saved the coverage data.
+
+--------
+# vim: ft=text :

data/editor-extensions/rcov.el

@@ -0,0 +1,131 @@
+;;; rcov.el -- Ruby Coverage Analysis Tool
+
+;;; Copyright (c) 2006 rubikitch <rubikitch@ruby-lang.org>
+;;;
+;;; Use and distribution subject to the terms of the rcov license.
+
+(defvar rcov-xref-before-visit-source-hook nil
+  "Hook executed before jump.")
+(defvar rcov-xref-after-visit-source-hook nil
+  "Hook executed after jump.")
+(defvar rcov-command-line "rake rcov RCOVOPTS='--gcc --no-html'"
+  "Rcov command line to find uncovered code.
+It is good to use rcov with Rake because it `cd's appropriate directory.
+`--gcc' option is strongly recommended because `rcov' uses compilation-mode.")
+(defvar rcovsave-command-line "rake rcov RCOVOPTS='--gcc --no-html --save=coverage.info'"
+  "Rcov command line to save coverage status. See also `rcov-command-line'.")
+(defvar rcovdiff-command-line "rake rcov RCOVOPTS='-D --gcc --no-html'"
+  "Rcov command line to find new uncovered code. See also `rcov-command-line'.")
+
+;;;; rcov-xref-mode
+(define-derived-mode rcov-xref-mode ruby-mode "Rxref"
+  "Major mode for annotated Ruby scripts (coverage/*.rb) by rcov."
+  (setq truncate-lines t)
+  ;; ruby-electric-mode / pabbrev-mode hijacks TAB binding.
+  (and ruby-electric-mode (ruby-electric-mode -1))
+  (and (boundp 'pabbrev-mode) pabbrev-mode (pabbrev-mode -1))
+  (suppress-keymap rcov-xref-mode-map)
+  (define-key rcov-xref-mode-map "\C-i" 'rcov-xref-next-tag)
+  (define-key rcov-xref-mode-map "\M-\C-i" 'rcov-xref-previous-tag)
+  (define-key rcov-xref-mode-map "\C-m" 'rcov-xref-visit-source)
+  (set (make-local-variable 'automatic-hscrolling) nil)
+  )
+  
+(defvar rcov-xref-tag-regexp "\\[\\[\\(.*?\\)\\]\\]")
+
+(defun rcov-xref-next-tag (n)
+  "Go to next LINK."
+  (interactive "p")
+  (when (looking-at rcov-xref-tag-regexp)
+    (goto-char (match-end 0)))
+  (when (re-search-forward rcov-xref-tag-regexp nil t n)
+    (goto-char (match-beginning 0)))
+  (rcov-xref-show-link))
+
+(defun rcov-xref-previous-tag (n)
+  "Go to previous LINK."
+  (interactive "p")
+  (re-search-backward rcov-xref-tag-regexp nil t n)
+  (rcov-xref-show-link))
+
+(defvar rcov-xref-link-tempbuffer " *rcov-link*")
+(defun rcov-xref-show-link ()
+  "Follow current LINK."
+  (let ((link (match-string 1))
+        (eol (point-at-eol)))
+    (save-excursion
+      (when (and link
+                 (re-search-backward "# \\(>>\\|<<\\) " (point-at-bol) t))
+        (while (re-search-forward rcov-xref-tag-regexp eol t)
+          (let ((matched (match-string 1)))
+            (when (string= link matched)
+              (add-text-properties 0 (length matched) '(face highlight) matched))
+            (with-current-buffer (get-buffer-create rcov-xref-link-tempbuffer)
+              (insert matched "\n"))))
+        (let (message-log-max)          ; inhibit *Messages*
+          (message "%s" (with-current-buffer rcov-xref-link-tempbuffer
+                          (substring (buffer-string) 0 -1)))) ; chomp
+        (kill-buffer rcov-xref-link-tempbuffer)))))
+
+
+;; copied from jw-visit-source
+(defun rcov-xref-extract-file-lines (line)
+  "Extract a list of file/line pairs from the given line of text."
+  (let*
+      ((unix_fn "[^ \t\n\r\"'([<{]+")
+       (dos_fn  "[a-zA-Z]:[^ \t\n\r\"'([<{]+")
+       (flre (concat "\\(" unix_fn "\\|" dos_fn "\\):\\([0-9]+\\)"))
+       (start nil)
+       (result nil))
+    (while (string-match flre line start)
+      (setq start (match-end 0))
+      (setq result
+            (cons (list
+                   (substring line (match-beginning 1) (match-end 1))
+                   (string-to-int (substring line (match-beginning 2) (match-end 2))))
+                  result)))
+    result))
+
+(defun rcov-xref-select-file-line (candidates)
+  "Select a file/line candidate that references an existing file."
+  (cond ((null candidates) nil)
+        ((file-readable-p (caar candidates)) (car candidates))
+        (t (rcov-xref-select-file-line (cdr candidates))) ))
+
+(defun rcov-xref-visit-source ()
+  "If the current line contains text like '../src/program.rb:34', visit
+  that file in the other window and position point on that line."
+  (interactive)
+  (let* ((line (progn (looking-at rcov-xref-tag-regexp) (match-string 1)))
+         (candidates (rcov-xref-extract-file-lines line))
+         (file-line (rcov-xref-select-file-line candidates)))
+    (cond (file-line
+           (run-hooks 'rcov-xref-before-visit-source-hook)
+           (find-file (car file-line))
+           (goto-line (cadr file-line))
+           (run-hooks 'rcov-xref-after-visit-source-hook))
+          (t
+           (error "No source location on line.")) )))
+
+;;;; Running rcov with various options.
+(defun rcov-internal (cmdline)
+  "Run rcov with various options."
+  (compile-internal cmdline ""
+                    nil nil nil (lambda (x) "*rcov*")))
+
+(defun rcov ()
+  "Run rcov to find uncovered code."
+  (interactive)
+  (rcov-internal rcov-command-line))
+
+(defun rcovsave ()
+  "Run rcov to save coverage status."
+  (interactive)
+  (rcov-internal rcovsave-command-line))
+
+(defun rcovdiff ()
+  "Run rcov to find new uncovered code."
+  (interactive)
+  (rcov-internal rcovdiff-command-line))
+
+(provide 'rcov)

data/editor-extensions/rcov.vim

@@ -0,0 +1,38 @@
+" Vim compiler file
+" Language:	Ruby
+" Function:	Code coverage information with rcov
+" Maintainer:	Mauricio Fernandez <mfp at acm dot org>
+" Info:		
+" URL:		http://eigenclass.org/hiki.rb?rcov
+" ----------------------------------------------------------------------------
+"
+" Changelog:
+" 0.1:	initial version, shipped with rcov 0.6.0
+"
+" Comments:
+" Initial attempt. 
+" ----------------------------------------------------------------------------
+
+if exists("current_compiler")
+  finish
+endif
+let current_compiler = "rcov"
+
+if exists(":CompilerSet") != 2		" older Vim always used :setlocal
+  command -nargs=* CompilerSet setlocal <args>
+endif
+
+let s:cpo_save = &cpo
+set cpo-=C
+
+CompilerSet makeprg=rake\ $*\ RCOVOPTS=\"-D\ --no-html\ --no-color\"\ $*
+
+CompilerSet errorformat=
+     \%+W\#\#\#\ %f:%l\,
+     \%-C\ \ \ ,
+     \%-C!!\ 
+
+let &cpo = s:cpo_save
+unlet s:cpo_save
+
+" vim: nowrap sw=2 sts=2 ts=8 ff=unix :

data/ext/rcovrt/1.8/callsite.c

@@ -0,0 +1,242 @@
+#include <ruby.h>
+#include <env.h>
+#include <node.h>
+#include <st.h>
+#include <stdlib.h>
+
+
+static char callsite_hook_set_p;
+
+typedef struct {
+        char *sourcefile;
+        unsigned int sourceline;
+        VALUE curr_meth;
+} type_def_site;       
+static VALUE caller_info = 0;
+static VALUE method_def_site_info = 0;
+
+static caller_stack_len = 1;
+
+/*
+ *
+ * callsite hook and associated functions
+ *
+ * */
+
+static VALUE
+record_callsite_info(VALUE args)
+{
+  VALUE caller_ary;
+  VALUE curr_meth;
+  VALUE count_hash;
+  VALUE count;
+  VALUE *pargs = (VALUE *)args;
+
+  caller_ary = pargs[0];
+  curr_meth = pargs[1];
+  count_hash = rb_hash_aref(caller_info, curr_meth);
+  if(TYPE(count_hash) != T_HASH) { 
+          /* Qnil, anything else should be impossible unless somebody's been
+           * messing with ObjectSpace */
+          count_hash = rb_hash_new();
+          rb_hash_aset(caller_info, curr_meth, count_hash);
+  }
+  count = rb_hash_aref(count_hash, caller_ary);
+  if(count == Qnil) 
+          count = INT2FIX(0);
+  count = INT2FIX(FIX2UINT(count) + 1);
+  rb_hash_aset(count_hash, caller_ary, count);
+  /*
+  printf("CALLSITE: %s -> %s   %d\n", RSTRING(rb_inspect(curr_meth))->ptr,
+                  RSTRING(rb_inspect(caller_ary))->ptr, FIX2INT(count));
+  */
+
+  return Qnil;
+}
+
+
+static VALUE
+record_method_def_site(VALUE args)
+{
+  type_def_site *pargs = (type_def_site *)args;
+  VALUE def_site_info;
+  VALUE hash;
+
+  if( RTEST(rb_hash_aref(method_def_site_info, pargs->curr_meth)) )
+          return Qnil;
+  def_site_info = rb_ary_new();
+  rb_ary_push(def_site_info, rb_str_new2(pargs->sourcefile));
+  rb_ary_push(def_site_info, INT2NUM(pargs->sourceline+1));
+  rb_hash_aset(method_def_site_info, pargs->curr_meth, def_site_info);
+  /*
+  printf("DEFSITE: %s:%d  for %s\n", pargs->sourcefile, pargs->sourceline+1,
+                  RSTRING(rb_inspect(pargs->curr_meth))->ptr);
+  */
+  
+  return Qnil;
+}
+
+static VALUE
+callsite_custom_backtrace(int lev)
+{
+  struct FRAME *frame = ruby_frame;
+  VALUE ary;
+  NODE *n;
+  VALUE level;
+  VALUE klass;
+
+  ary = rb_ary_new();
+  if (frame->last_func == ID_ALLOCATOR) {
+          frame = frame->prev;
+  }
+  for (; frame && (n = frame->node); frame = frame->prev) {
+          if (frame->prev && frame->prev->last_func) {
+                  if (frame->prev->node == n) continue;
+                  level = rb_ary_new();
+                  klass = frame->prev->last_class ? frame->prev->last_class : Qnil;
+                  if(TYPE(klass) == T_ICLASS) {
+                          klass = CLASS_OF(klass);
+                  }
+                  rb_ary_push(level, klass);
+                  rb_ary_push(level, ID2SYM(frame->prev->last_func));
+                  rb_ary_push(level, rb_str_new2(n->nd_file));
+                  rb_ary_push(level, INT2NUM(nd_line(n)));
+          }
+          else {
+                  level = rb_ary_new();
+                  rb_ary_push(level, Qnil);
+                  rb_ary_push(level, Qnil);
+                  rb_ary_push(level, rb_str_new2(n->nd_file));
+                  rb_ary_push(level, INT2NUM(nd_line(n)));
+          }
+          rb_ary_push(ary, level);
+          if(--lev == 0)
+                  break;
+  }
+
+  return ary;
+}
+  
+static void
+coverage_event_callsite_hook(rb_event_t event, NODE *node, VALUE self, 
+                ID mid, VALUE klass)
+{
+ VALUE caller_ary;
+ VALUE curr_meth;
+ VALUE args[2];
+ int status;
+
+ caller_ary = callsite_custom_backtrace(caller_stack_len);
+
+ if(TYPE(klass) == T_ICLASS) {
+         klass = CLASS_OF(klass);
+ }
+ curr_meth = rb_ary_new();
+ rb_ary_push(curr_meth, klass);
+ rb_ary_push(curr_meth, ID2SYM(mid));
+
+ args[0] = caller_ary;
+ args[1] = curr_meth;
+ rb_protect(record_callsite_info, (VALUE)args, &status);
+ if(!status && node) {
+         type_def_site args;        
+         
+         args.sourcefile = node->nd_file;
+         args.sourceline = nd_line(node) - 1;
+         args.curr_meth = curr_meth;
+         rb_protect(record_method_def_site, (VALUE)&args, NULL);
+ }
+ if(status)
+         rb_gv_set("$!", Qnil);
+}
+
+
+static VALUE
+cov_install_callsite_hook(VALUE self)
+{
+  if(!callsite_hook_set_p) {
+          if(TYPE(caller_info) != T_HASH)
+                  caller_info = rb_hash_new();
+          callsite_hook_set_p = 1;
+          rb_add_event_hook(coverage_event_callsite_hook, 
+                          RUBY_EVENT_CALL);
+          
+          return Qtrue;
+  } else
+          return Qfalse;
+}
+
+
+static VALUE
+cov_remove_callsite_hook(VALUE self)
+{
+ if(!callsite_hook_set_p) 
+         return Qfalse;
+ else {
+         rb_remove_event_hook(coverage_event_callsite_hook);
+         callsite_hook_set_p = 0;
+         return Qtrue;
+ }
+}
+
+
+static VALUE
+cov_generate_callsite_info(VALUE self)
+{
+  VALUE ret;
+
+  ret = rb_ary_new();
+  rb_ary_push(ret, caller_info);
+  rb_ary_push(ret, method_def_site_info);
+  return ret;
+}
+
+
+static VALUE
+cov_reset_callsite(VALUE self)
+{
+  if(callsite_hook_set_p) {
+	  rb_raise(rb_eRuntimeError, 
+		  "Cannot reset the callsite info in the middle of a traced run.");
+	  return Qnil;
+  }
+
+  caller_info = rb_hash_new();
+  method_def_site_info = rb_hash_new();
+  return Qnil;
+}
+
+void
+Init_rcov_callsite()
+{
+ VALUE mRcov;
+ VALUE mRCOV__;
+ ID id_rcov = rb_intern("Rcov");
+ ID id_coverage__ = rb_intern("RCOV__");
+ ID id_script_lines__ = rb_intern("SCRIPT_LINES__");
+
+ if(rb_const_defined(rb_cObject, id_rcov)) 
+         mRcov = rb_const_get(rb_cObject, id_rcov);
+ else
+         mRcov = rb_define_module("Rcov");
+
+ if(rb_const_defined(mRcov, id_coverage__))
+         mRCOV__ = rb_const_get_at(mRcov, id_coverage__);
+ else
+         mRCOV__ = rb_define_module_under(mRcov, "RCOV__");
+
+ callsite_hook_set_p = 0;
+ caller_info = rb_hash_new();
+ method_def_site_info = rb_hash_new();
+ rb_gc_register_address(&caller_info);
+ rb_gc_register_address(&method_def_site_info);
+ 
+ rb_define_singleton_method(mRCOV__, "install_callsite_hook", 
+                 cov_install_callsite_hook, 0);
+ rb_define_singleton_method(mRCOV__, "remove_callsite_hook", 
+                 cov_remove_callsite_hook, 0);
+ rb_define_singleton_method(mRCOV__, "generate_callsite_info", 
+		 cov_generate_callsite_info, 0);
+ rb_define_singleton_method(mRCOV__, "reset_callsite", cov_reset_callsite, 0);
+}
+/* vim: set sw=8 expandtab: */