rcodetools 0.4.0.0

data/CHANGES

@@ -0,0 +1,18 @@
+
+xmpfilter was integrated into rcodetools as of 0.4.0.
+
+xmpfilter history
+=================
+User-visible changes since 0.3.1 (2006-10-17)
+* implemented --debug
+* --[no]-warnings
+* --cd working_dir
+* --rails
+* --no-poetry
+* more intelligent assertions: try to find which local variables hold the
+  values compared against in assertions/expectations
+* editor-independent completion (-C, --completion-emacs, --completion-vim)
+* quick method/class reference with -D (--refe, --ri*)
+
+User-visible changes since 0.3.0 (2006-10-16)
+* xmpfilter.rb --spec works on win32 too

data/README

@@ -0,0 +1,34 @@
+
+ rcodetools  http://eigenclass.org/hiki.rb?rcodetools
+ Copyright (c) 2005-2006 Mauricio Fernandez <mfp@acm.org> http://eigenclass.org
+ Copyright (c)      2006 rubikitch <rubikitch@ruby-lang.org> http://www.rubyist.net/~rubikitch/
+Use and distribution subject to the terms of the Ruby license.
+
+= Overview
+rcodetools is a collection of Ruby code manipulation tools. 
+It includes xmpfilter and editor-independent Ruby development helper tools,
+as well as emacs and vim interfaces.
+
+Currently, rcodetools comprises:
+* xmpfilter: Automagic Test::Unit assertions/RSpec expectations and code annotations
+* rct-complete: Accurate method/class/constant etc. completions
+* rct-doc: Document browsing and code navigator
+* rct-meth-args: Precise method info (meta-prog. aware) and TAGS generation
+
+See also README.xmpfilter.
+
+Originally rct-complete and rct-doc were subcommands of xmpfilter.
+Actually they use xmpfilter's code heavily.
+But the relationship between xmpfilter (annotation) and completion/doc is not
+intuitive, so I (rubikitch) split it into separate executables.
+
+= Usage
+xmpfilter, rct-complete and rct-doc take its input from stdin and write to
+stdout. They can run in several modes; see 
+ xmpfilter -h 
+ rct-complete -h 
+ rct-doc -h 
+README.emacs and README.vim describe how to use rcodetools from your editor.
+
+= License
+rcodetools is licensed under the same terms as Ruby.

data/README.emacs

@@ -0,0 +1,54 @@
+
+rcodetools.el allows you to run rcodetools on a buffer.
+
+To eval the sexp, type C-e C-x C-e; `end-of-line' and `eval-last-sexp'.
+
+installation
+============
+
+If you use RI document feature, you must install ri-emacs first.
+  http://rubyforge.org/projects/ri-emacs/
+
+If you feel RI and ri-emacs.rb startup is SLOW, you want to install FastRI.
+FastRI offers ri-emacs compatible layer, so you can use it with ri-ruby.el.
+  http://eigenclass.org/hiki.rb?fastri
+
+Copy <tt>rcodetools.el</tt> to the appropriate directory, which is in load-path.
+Then require it.
+  (require 'rcodetools)
+
+If you use icicles copy <tt>icicles-rcodetools.el</tt> too.
+Then require it.
+  (require 'icicles-rcodetools)
+It provides wonderful `help on candidate' feature, RI document on each candidate during completion.
+I'm addicted to icicles!
+  http://www.emacswiki.org/cgi-bin/wiki/Icicles
+
+xmpfilter on buffer
+===================
+
+# [EVAL IT] (describe-function 'xmp)
+
+If you want to add => marks, call comment-dwim twice.
+
+# [EVAL IT] (describe-function 'comment-dwim)
+
+method/class/constant completion
+================================
+
+# [EVAL IT] (describe-function 'rct-complete-symbol)
+
+If you use icicles-rcodetools, you can browse RI document for selected candidate
+by typing C-M-RET. It is wonderful icicles feature!!
+
+show RI document / jump to the definition
+=========================================
+
+# [EVAL IT] (describe-function 'rct-ri)
+
+By default rct-ri asks for a TAGS file, which is generated by tag generator like rtags.
+If there is a TAGS file, this command jumps to the definition of current method.
+If use do not use this feature, evaluate:
+  (setq rct-find-tag-if-available nil)
+
+# [EVAL IT] (describe-variable 'rct-find-tag-if-available)

data/README.method_analysis

@@ -0,0 +1,13 @@
+
+method_analyzer.rb can be used to gather precise information about the exact
+methods called in your code, allowing you to explore it better with rct-doc
+(see README.emacs and README.vim for more information). This requires high
+code coverage, since it can only record such data when the code is executed.
+
+rct-meth-args can be used to generate fairly complete TAGS files. It operates
+by loading the specified files and tracking method definitions; therefore, it
+is meta-programming aware, unlike other implementations.
+
+You can use them conveniently by adding the code shown in
+Rakefile.method_analysis to your Rakefile.
+

data/README.vim

@@ -0,0 +1,84 @@
+
+Copy rcodetools.vim to your plugin directory (typically $HOME/.vim/plugin) in
+order to enable accurate code completion, quick RI execution and exact tag
+jumping.
+
+Code completion
+===============
+rcodetools.vim redefines user-defined completion for Ruby programs, so you can
+use the intelligent, 100%-accurate completion with <C-X><C-U> in insert mode.
+Note that this runs the code to obtain the exact candidate list.
+
+Quick RI documentation and exact tag jumping
+============================================
+When you're editing a Ruby file, <C-]> will jump to the definition of the
+chosen element if found in the TAGS file; otherwise, it will call RI and show
+the documentation in a new window.
+You can specify the RI executable to use by adding something like
+    let g:RCT_ri_cmd = "ri -T -f plain "
+to your .vimrc. (rcodetools.vim also honors b:RCT_RI_cmd and w:RCT_RI_cmd if set).
+By default, "fri -f plain " will be used. fri (FastRI) is an improved RI
+documentation browser, which features more intelligent search modes, gem
+integration, vastly better performance... You can find it at
+http://eigenclass.org/hiki.rb?fastri  and it's also available in gem format
+gem install fastri
+
+If you want to call RI for the word the cursor is on (instead of jumping to
+the definition if found), you can use this binding:
+ <LocalLeader>r   (\r by default if you haven't changed your localleader)
+You can specify another binding in your .vimrc as follows:
+ let g:RCT_ri_binding="<C-X><C-R>" " use ^X^R to call vim on current word
+
+Using xmpfilter
+===============
+xmpfilter takes code from stdin and outputs to stdout so you can filter
+your code with ! as usual. 
+
+If you use xmpfilter often, you might want to use mappings like the
+following, which allow you to:
+* add annotations
+* expand assertions
+* insert/remove # => markers
+
+
+
+" plain annotations
+map <silent> <F10> !xmpfilter -a<cr>
+nmap <silent> <F10> V<F10>
+imap <silent> <F10> <ESC><F10>a
+
+" Test::Unit assertions; use -s to generate RSpec expectations instead
+map <silent> <S-F10> !xmpfilter -u<cr>
+nmap <silent> <S-F10> V<S-F10>
+imap <silent> <S-F10> <ESC><S-F10>a
+
+" Annotate the full buffer
+" I actually prefer ggVG to %; it's a sort of poor man's visual bell 
+nmap <silent> <F11> mzggVG!xmpfilter -a<cr>'z
+imap <silent> <F11> <ESC><F11>
+
+" assertions
+nmap <silent> <S-F11> mzggVG!xmpfilter -u<cr>'z
+imap <silent> <S-F11> <ESC><S-F11>a
+
+" Add # => markers
+vmap <silent> <F12> !xmpfilter -m<cr>
+nmap <silent> <F12> V<F12>
+imap <silent> <F12> <ESC><F12>a
+
+" Remove # => markers
+vmap <silent> <S-F12> ms:call RemoveRubyEval()<CR>
+nmap <silent> <S-F12> V<S-F12>
+imap <silent> <S-F12> <ESC><S-F12>a
+
+
+function! RemoveRubyEval() range
+  let begv = a:firstline
+  let endv = a:lastline
+  normal Hmt
+  set lz
+  execute ":" . begv . "," . endv . 's/\s*# \(=>\|!!\).*$//e'
+  normal 'tzt`s
+  set nolz
+  redraw
+endfunction

data/README.xmpfilter

@@ -0,0 +1,202 @@
+
+xmpfilter  http://eigenclass.org/hiki.rb?xmpfilter
+Copyright (c) 2005-2006 Mauricio Fernandez <mfp@acm.org> http://eigenclass.org
+Use and distribution subject to the terms of the Ruby license.
+
+Overview
+========
+xmpfilter is a small tool that can be used to
+* generate Test::Unit assertions and RSpec expectations semi-automatically
+* annotate source code with intermediate results (a bit like irb
+  --simple-prompt but only for the lines explicitly marked with # =>)
+  Very useful for example code (such as postings to ruby-talk).
+
+Usage
+=====
+xmpfilter takes its input from stdin and writes to stdout. It can run in
+several modes (annotation, Test::Unit assertion expansion, RSpec expectation
+generation, marker insertion); see 
+ xmpfilter -h 
+README.emacs and README.vim describe how to use xmpfilter from your editor.
+
+Example: code annotation
+========================
+Just add "# =>" markers to the lines whose values you want to be shown:
+
+ a, b = "foo", "baz"
+ a + b                                             # =>
+ a.size                                            # =>
+
+will be expanded to (in one keypress in a decent editor, see README.emacs and
+README.vim)
+
+ a, b = "foo", "baz"
+ a + b                                             # => "foobaz"
+ a.size                                            # => 3
+
+This saves much cut&pasting when you're posting to ruby-talk/ruby-core (I use
+it all the time).
+
+Example: assertion generation
+=============================
+
+xmpfilter can generate assertions based on the current behavior of the code
+to be tested (iow. the current behavior is assumed to be correct and is used
+to generate assertions which won't be modified by further runs of
+xmpfilter), making it quite useful for regression testing.
+
+Imagine you have a ComplexClass you want to test. You might start with
+
+    class TestComplexClass < Test::Unit::TestCase
+      def setup; @o = ComplexClass.new("foo", false) end
+    end
+
+and then want to add some tests:
+
+  def test_insertion
+    @o.insert "bar"
+    @o.insert "baz"
+    # ... assertions here
+  end
+
+At this point, you want to add several assertions to verify that the values
+returned by @o.size, @o.last, @o.first, @o.complex_computation and @o.last(2)
+are correct. You can just write the following and feed the file to
+xmpfilter in -u mode (the # => markers can also be inserted by
+xmpfilter, see README.vim for more information:
+
+  def test_insertion
+    @o.insert "bar"
+    @o.insert "baz"
+    @o.size                                        # =>
+    @o.last                                        # =>
+    @o.first                                       # =>
+    @o.complex_computation                         # =>
+    @o.last(2)                                     # =>
+  end
+
+xmpfilter will run the test and remember what happened in each marked line,
+and then rewrite the code so that it looks for instance like
+
+  def test_insertion
+    @o.insert "bar"
+    @o.insert "baz"
+    assert_equal(2, @o.size)
+    assert_equal("baz", @o.last)
+    assert_equal("bar", @o.first)
+    assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
+    assert_equal(["baz", "bar"], @o.last(2))
+  end
+
+As you can see, it can save some typing.
+
+You can edit the generated assertions as you want: xmpfilter will not
+modify lines without the "# =>" marker. xmpfilter can be used repeatedly as
+you add more assertions. Imagine you want to verify that @o.last(3) raises an
+ArgumentError. You can simply add one line marked with # => :
+  
+  ...
+    assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
+    assert_equal(["baz", "bar"], @o.last(2))
+    @o.last(3)                                     # =>
+  end
+
+and have it expanded by xmpfilter:
+
+  ...
+    assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
+    assert_equal(["baz", "bar"], @o.last(2))
+    assert_raise(ArgumentError){ @o.last(3) } 
+  end
+
+
+Example: RSpec expectations
+===========================
+Here's some code before and after filtering it with xmpfilter:
+
+    class X
+      Y = Struct.new(:a)
+      def foo(b); b ? Y.new(2) : 2 end
+      def bar; raise "No good" end
+      def baz; nil end
+      def fubar(x); x ** 2.0 + 1 end
+      def babar; [1,2] end
+      A = 1
+      A = 1
+    end
+
+    context "Testing xmpfilter's expectation expansion" do
+      setup do
+	@o = X.new
+      end
+
+      specify "Should expand should_equal expectations" do
+	@o.foo(true)   # =>
+	@o.foo(true).a # =>
+	@o.foo(false)  # =>
+      end
+      
+      specify "Should expand should_raise expectations" do
+	@o.bar         # =>
+      end
+
+      specify "Should expand should_be_nil expectations" do
+	@o.baz         # =>
+      end
+
+      specify "Should expand correct expectations for complex values" do
+	@o.babar       # =>
+      end
+
+      specify "Should expand should_be_close expectations" do
+	@o.fubar(10)   # =>
+      end
+    end
+
+
+after piping it to xmpfilter -s:
+
+    class X
+      Y = Struct.new(:a)
+      def foo(b); b ? Y.new(2) : 2 end
+      def bar; raise "No good" end
+      def baz; nil end
+      def fubar(x); x ** 2.0 + 1 end
+      def babar; [1,2] end
+      A = 1
+      A = 1 # !> already initialized constant A
+    end
+
+    context "Testing xmpfilter's expectation expansion" do
+      setup do
+	@o = X.new
+      end
+
+      specify "Should expand should_equal expectations" do
+	(@o.foo(true)).should_be_a_kind_of X::Y
+	(@o.foo(true).inspect).should_equal "#<struct X::Y a=2>"
+	(@o.foo(true).a).should_equal 2
+	(@o.foo(false)).should_equal 2
+      end
+      
+      specify "Should expand should_raise expectations" do
+	lambda{(@o.bar)}.should_raise RuntimeError
+      end
+
+      specify "Should expand should_be_nil expectations" do
+	(@o.baz).should_be_nil
+      end
+
+      specify "Should expand correct expectations for complex values" do
+	(@o.babar).should_equal [1, 2]
+      end
+
+      specify "Should expand should_be_close expectations" do
+	(@o.fubar(10)).should_be_close(101.0, 0.0001)
+      end
+    end
+
+
+License
+=======
+xmpfilter is licensed under the same terms as Ruby.

data/Rakefile

@@ -0,0 +1,123 @@
+
+PKG_REVISION = ".0"
+RCT_VERSION  = "0.4.0"
+
+$:.unshift "lib" if File.directory? "lib"
+require 'rake/testtask'
+
+desc "Run the unit tests in pure-Ruby mode ."
+Rake::TestTask.new(:test) do |t|
+  t.libs << "ext/rcovrt"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+require 'rcov/rcovtask'
+desc "Run rcov."
+Rcov::RcovTask.new do |t|
+  t.rcov_opts << "--xrefs"  # comment to disable cross-references
+  t.test_files = FileList['test/test_*.rb'].to_a - ["test/test_functional.rb"]
+  t.verbose = true
+end
+
+desc "Save current coverage state for later comparisons."
+Rcov::RcovTask.new(:rcovsave) do |t|
+  t.rcov_opts << "--save"
+  t.test_files = FileList['test/test_*.rb'].to_a - ["test/test_functional.rb"]
+  t.verbose = true
+end
+
+task :default => :test
+
+## test data file dependency
+basetestfiles = []
+copy = lambda do |t|
+  cp t.prerequisites.first, t.name
+end
+
+#  DO NOT EDIT!!                         EDITABLE
+[ ["test/data/rspec_poetry-input.rb", "test/data/rspec-input.rb"],
+  ["test/data/unit_test_poetry-input.rb", "test/data/unit_test-input.rb"],
+  ["test/data/completion_emacs-input.rb", "test/data/completion-input.rb"]
+].each do |outfile, infile|
+  basetestfiles << outfile
+  file(outfile => infile, &copy)
+end
+for test in %w[refe ri ri_emacs ri_vim]
+  outfile = "test/data/#{test}-input.rb"
+  basetestfiles << outfile
+  file(outfile => "test/data/doc-input.rb", &copy)
+end
+task :base_update => basetestfiles
+task :test => :base_update
+task :rcov => :base_update
+
+#{{{ Package tasks
+PKG_FILES = FileList[
+"bin/rct-complete", "bin/rct-doc", "bin/xmpfilter", "bin/rct-meth-args",
+"lib/**/*.rb",
+"CHANGES", "rcodetools.*", "icicles-rcodetools.el", "README", "README.*", "THANKS", 
+"Rakefile", "Rakefile.method_analysis",
+"setup.rb",
+"test/**/*.rb",
+]
+
+begin
+  require 'rake/gempackagetask'
+  Spec = Gem::Specification.new do |s|
+    s.name = "rcodetools"
+    s.version = RCT_VERSION + PKG_REVISION
+    s.summary = "rcodetools is a collection of Ruby code manipulation tools"
+    s.description = <<EOF
+rcodetools is a collection of Ruby code manipulation tools. 
+It includes xmpfilter and editor-independent Ruby development helper tools,
+as well as emacs and vim interfaces.
+
+Currently, rcodetools comprises:
+* xmpfilter: Automagic Test::Unit assertions/RSpec expectations and code annotations
+* rct-complete: Accurate method/class/constant etc. completions
+* rct-doc: Document browsing and code navigator
+* rct-meth-args: Precise method info (meta-prog. aware) and TAGS generation
+EOF
+    s.files = PKG_FILES.to_a
+    s.require_path = 'lib'
+    s.author = "rubikitch and Mauricio Fernandez"
+    s.email = %{"rubikitch" <rubikitch@ruby-lang.org>, "Mauricio Fernandez" <mfp@acm.org>}
+    s.homepage = "http://eigenclass.org/hiki.rb?rcodetools"
+    s.bindir = "bin"
+    s.executables = %w[rct-complete rct-doc xmpfilter rct-meth-args]
+    s.has_rdoc = true
+    s.extra_rdoc_files = %w[README]
+    s.rdoc_options << "--main" << "README" << "--title" << 'rcodetools'
+    s.test_files = Dir["test/test_*.rb"]
+    s.post_install_message = <<EOF
+
+==============================================================================
+
+rcodetools will work better if you use it along with FastRI, an alternative to
+the standard 'ri' documentation browser which features intelligent searching,
+better RubyGems integration, vastly improved performance, remote queries via
+DRb... You can find it at http://eigenclass.org/hiki.rb?fastri and it is also
+available in RubyGems format:
+
+    gem install fastri
+
+Read README.emacs and README.vim for information on how to integrate
+rcodetools in your editor.
+
+==============================================================================
+
+EOF
+
+  end
+
+  task :gem => [:test]
+  Rake::GemPackageTask.new(Spec) do |p|
+    #p.need_tar = true
+  end
+
+rescue LoadError
+  # RubyGems not installed
+end
+
+# vim: set sw=2 ft=ruby: