rcodetools 0.5.0.0 → 0.7.0.0

data/CHANGES

@@ -1,5 +1,19 @@
 rcodetools history
 ==================
+User-visible changes since 0.5.0
+--------------------------------
+* "test-driven completion" (TDC) support for Emacs and vim (see README.TDC)
+* --test (-t), --filename options for rct-complete and rct-doc, allowing to
+  specify the test to be run for 100% accurate completion/documentation in the
+  corresponding implementation
+* ruby-toggle-file: finds the test file corresponding to a given
+  implementation and vice versa
+* rct-fork, rct-fork-client: allow to eliminate the overhead due to library
+  loading (esp. useful for Rails)
+* rbtest: executes unit tests in a single Ruby script
+* --fork, --rbtest, --detect-rbtest supported by several commands
+* xmpfilter's --spec now autodetects the RSpec version and generates
+  specifications with the appropriate syntax
 
 User-visible changes since 0.4.1
 --------------------------------

data/README

@@ -14,6 +14,10 @@ Currently, rcodetools comprises:
 * 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
+* rct-fork: Pre-load heavy library(Rails etc) and speed up rct-complete/rct-doc (server)
+* rct-fork-client: Run Ruby programs from state the rct-fork server has
+* ruby-toggle-file: Toggle implementation file and test file
+* rbtest: Embedded Test::Unit for small scripts
 
 See also README.xmpfilter.
 
@@ -29,7 +33,66 @@ stdout. They can run in several modes; see
  rct-complete -h 
  rct-doc -h 
  rct-meth-args -h
+ rct-fork -h
+ rct-fork-client -h
+ ruby-toggle-file -h
+ rbtest -h
 README.emacs and README.vim describe how to use rcodetools from your editor.
 
+= Accurate Completion Internal and Caveat
+rct-complete and rct-doc use xmpfilter engine, ie they get runtime information by executing code.
+In Ruby (dynamic languages), type of any expressions except literals cannot be known without actually executing code.
+Moreover Ruby has open classes and singleton methods.
+Rcodetools asks `ruby' run-time informations, so we can get very accurate informations.
+Completion and document browsing are essentially identical operations,
+they both need the object value in question.
+Therefore we discuss completion.
+
+rct-complete does:
+(1) replaces target line with completion magic
+    (it calculates methods the target object has).
+(2) executes modified script.
+(3) once the control reaches completion magic, modified script exits.
+(4) outputs in specified format. (list candidates, EmacsLisp...)
+
+But this methodology has two big drawbacks, side-effects and inability to get any informations of uncovered code!
+
+An extreme side-effect example:
+  File.unlink a_file
+  File. <-
+
+If you call rct-complete, it removes a_file (sends a mail, accesses DB ...).
+So you must be careful to use, especially at TOPLEVEL.
+I (rubikitch) often experiment at TOPLEVEL with rcodetools, I NEVER use irb(sh) since rcodetools!
+
+An uncovered code example:
+  def foo
+    1. <-
+  end
+
+If the code does not call foo, we cannot do any completions.
+
+Useless eh? But we already have a way to elude the drawbacks, test scripts (unit tests)!
+Test scripts are self-enclosed and expected to be executed, so side-effects are not problem.
+Moreover tests call methods we write.
+Because Ruby's Test::Unit has an ability to test only one test method, we can do lightning-fast completion.
+Let's call it Test-Driven Completion (TDC).
+
+To support TDC, rct-complete has -t option.
+With -t, it concatenate modified script and test/unit code.
+If the control does not reach target line, test/unit code calls the line.
+
+How do we select test script and test method?
+The editor selects recently selected buffer of test script as test script of TDC,
+because the test-infected tend to go and return between test script and implementation script.
+It considers files matching /test.*\.rb/ as test script.
+It selects test method at the cursor position.
+
+TDC adds roles of test scripts.
+Enjoy TDC magic!
+
+See also README.TDC.
+
+
 = License
 rcodetools is licensed under the same terms as Ruby.

data/README.TDC

@@ -0,0 +1,158 @@
+
+= Overview
+
+Ruby is very dynamic language, therefore it is impossible to do
+accurate completion without executing script.  While executing script
+from start to cursor point is often dangerous, executing unit test
+script covering current point is SAFE.  I call this methodology
+`Test-Driven Completion' (TDC).
+
+As I have already stated in README, browsing documentation of method
+(rct-doc) is almost identical operation to completion.  This
+discussion is applicable to rct-doc.
+
+= Why TDD Is Needed
+
+In the following code snippet:
+
+  File.unlink a_file
+  File. <-
+
+If you complete after `File.', rct-complete actually deletes a_file.
+Normally it is unpleasant.
+In real-life development, side-effect is inevitable.
+
+In the foo method which are not called:
+
+  def foo
+    1. <-
+  end
+
+If the code does not call foo, rct-complete cannot do any completions.
+Before TDC, if you want to do completion in methods, you have to write
+method call and remove it after completion. Too useless!!
+
+= Messianic Unit Test Script
+
+Recently Test-Driven Development (TDD) is widespread.  Many developers
+write unit tests.  Fortunately Ruby's unit tester, Test::Unit, is
+sophisticated enough to test one test method.  Unit tests are
+self-enclosed: they must tear down resources, so executing unit tests
+are SAFE.  TDC uses unit test to do completion.
+
+= TDC Methodology
+
+(1) Switch to unit test script.
+(2) Write a test for target method.
+(3) Switch to implementation script.
+(4) You can write target method WITH COMPLETION!
+(5) Back to (1)
+
+TDC methodology is almost identical to TDD. TDC is very easy for TDDers.
+
+= TDC With Example
+
+For simplicity, suppose that you are unfamiliar with Time class and
+you want to write a method to format date string.
+
+The directory structure and file contents is following:
+
+  /tmp/mylib0/
+  /tmp/mylib0/lib/
+     mylib0.rb
+  /tmp/mylib0/test/
+     test_mylib0.rb
+
+  List: mylib0.rb
+  # contrived example of long-runtime method
+  def mysleep(x)
+    sleep x
+  end
+
+  def mytime(tm)
+
+  end
+
+
+  List: test_mylib0.rb
+  require 'test/unit'
+  require 'mylib0'
+  class TestMylib0 < Test::Unit::TestCase
+    def test_0_mysleep
+      s = Time.now
+      mysleep 3.0
+      e = Time.now
+      assert_in_delta 3.0, e-s, 0.01
+    end
+
+    def test_1_mytime
+
+    end
+  end
+
+These sample files are in demo/ directory.
+
+
+== Switch to unit test script.
+
+TDC starts with writing unit test as TDD does.
+Open test_mylib0.rb.
+
+== Write a test for target method.
+
+Suppose that you want to write mytime method and test_1_mytime test
+method, and that you want to experiment Time class first (before
+forming an assertion).
+
+In TDC, you do not have to write an assertion first: just write only a
+method call.  If you are familiar with Time class, you are free to
+write an assertion, of course.
+
+    def test_1_mytime
+      mytime(Time.now)
+    end
+
+At this time, the cursor position is in test_1_mytime test method.
+
+== Switch to implementation script.
+
+Open mylib0.rb with the `ruby-toggle-file' script.  For example, in Emacs use
+the `ruby-toggle-buffer' command, and in vim the <localleader>t (by default
+\t) binding.  Since in TDD/TDC you often switch between the test and the
+implementation, it is much handier than typing the filename manually.
+
+The rct-complete uses latest-selected test script as TDC test script
+and test method at cursor position as TDC test method.  In this case,
+test_mylib0.rb is TDC test script and test_1_mytime is TDC test
+method.  If the cursor position of test_mylib0.rb is at the top,
+rct-complete executes whole test methods in test_mylib0.rb.  Therefore
+latency of completion is longer.
+
+== You can write target method WITH COMPLETION!
+
+Fill mytime method.
+
+  def mytime(tm)
+    tm.
+  end
+
+Do completion after `tm.'. Here! Your editor is listing methods `tm'
+accepts!!  If your editor has help-on-candidate mechanism (eg. Emacs +
+Icicles), you would see documentation of each listed method.
+
+Then you find `Time#strftime' method. Type `str' and do completion.
+
+  def mytime(tm)
+    tm.strftime 
+  end
+
+Usage is... use `rct-doc' (in Emacs, `rct-ri') after `strftime'.
+
+After you are familiar with Time class, switch to test script and write assertions.
+
+= When Modifying Another Method
+
+If you want to modify already-written method, setting cursor position
+of corresponding test script to corresponding test method is better.
+It tells rct-complete new test script and test method, so you can do
+completion in the new method.

data/README.ja

@@ -0,0 +1,84 @@
+
+ rcodetools  http://eigenclass.org/hiki.rb?rcodetools
+ Copyright (c) 2005-2007 Mauricio Fernandez <mfp@acm.org> http://eigenclass.org
+ Copyright (c) 2006-2007 rubikitch <rubikitch@ruby-lang.org> http://www.rubyist.net/~rubikitch/
+Use and distribution subject to the terms of the Ruby license.
+
+= ����
+rcodetools �� Ruby �Υ����ɤ򰷤��ġ��뷲�Ǥ���
+rcodetools �ˤ� xmpfilter �ȥ��ǥ����˰�¸���ʤ���ȯ�ٱ�ġ��뤬�ޤޤ�Ƥ��ޤ���
+Emacs �� Vim �Υ��󥿡��ե��������Ѱդ��Ƥ��ޤ���
+
+* xmpfilter: Test::Unit assert* / RSpec should* ��ư����������������
+* rct-complete: �����٥᥽�å�̾�����饹̾�����̾���䴰
+* rct-doc: �ɥ�����Ȼ��ȡ������ɥʥӥ�������
+* rct-meth-args: �����٥᥽�åɾ���ꥹ�ȡ�TAGS �ե��������
+* rct-fork: Rails ���Ť��饤�֥���ͽ������ɤ����䴰���®������ʥ����С�
+* rct-fork-client: rct-fork �����Ф��ݻ�������֤��� Ruby ������ץȤ�¹Ԥ���
+* ruby-toggle-file: �ƥ��ȥ�����ץȤȼ���������ץȤ��ڤ괹����
+* rbtest: �����ϥ�����ץȤΤ���������� Test::Unit
+
+
+= �Ȥ���
+
+== ����������
+�����ͤ�ɽ���������Ԥ� # => ��ä��ޤ���
+
+ a, b = "foo", "baz"
+ a + b                                             # =>
+ a.size                                            # =>
+
+xmpfilter ���̤��Ȳ��Τ褦�˼����ͤ�ɽ�����Ƥ���ޤ���
+
+ a, b = "foo", "baz"
+ a + b                                             # => "foobaz"
+ a.size                                            # => 3
+
+
+== Test::Unit assert ʸ����
+
+���ǤˤǤ������äƤ���ץ������Υƥ��ȥ�����ץȤ�񤯤Τ����ݤǤ��͡�
+
+  def test_insertion
+    @o.insert "bar"
+    @o.insert "baz"
+    @o.size                                        # =>
+    @o.last                                        # =>
+    @o.first                                       # =>
+    @o.complex_computation                         # =>
+    @o.last(2)                                     # =>
+  end
+
+xmpfilter��-u ���ץ����ˤ���֤�ڸ����Ƥ���ޤ���
+
+  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
+
+RSpec �ˤĤ��Ƥ�Ʊ�ͤΤ��Ȥ��Ǥ��ޤ�����-s ���ץ�����
+
+== �䴰���ɥ�����Ȼ���
+
+ư��ˤ�륹���꡼�󥷥�åȤ򸫤Ƥ���������
+
+http://eigenclass.org/hiki.rb?rcodetools-screenshots
+
+== �ܤ����Ȥ���
+-h ���ץ�����Ĥ���Ȼ��Ѳ�ǽ�ʥ��ץ����ɽ������ޤ���
+
+ xmpfilter -h 
+ rct-complete -h 
+ rct-doc -h 
+ rct-meth-args -h
+ rct-fork -h
+ rct-fork-client -h
+ ruby-toggle-file -h
+ rbtest -h
+
+README.emacs �� README.vim �˥��ǥ�����ǤλȤ������ܤ����񤤤Ƥ���ޤ���

data/README.vim

@@ -3,6 +3,17 @@ 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.
 
+Switching between implementation and test files
+===============================================
+The <localleader>t binding (by default \t) will call ruby-toggle-file to
+switch from test to implementation and vice versa. Moreover, when you switch
+from the test to the implementation, rcodetools will remember which test
+you were editing (based on the cursor position), and call it as needed for
+advanced code completion or precise RI documentation, as documented below.
+
+The actual binding can be changed in your .vimrc as follows:
+ let g:RCT_toggle_binding="<C-X><C-t>"  " use ^X^T to go test <=> implementation
+
 Code completion
 ===============
 rcodetools.vim redefines user-defined completion for Ruby programs, so you can

data/Rakefile

@@ -4,7 +4,7 @@ PKG_REVISION = ".0"
 $:.unshift "lib" if File.directory? "lib"
 require 'rcodetools/xmpfilter'
 require 'rake/testtask'
-
+include Rcodetools
 RCT_VERSION  = XMPFilter::VERSION
 
 desc "Run the unit tests in pure-Ruby mode ."
@@ -40,7 +40,20 @@ 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"]
+  ["test/data/completion_emacs-input.rb", "test/data/completion-input.rb"],
+  ["test/data/unit_test_detect_rbtest-input.rb", "test/data/unit_test-input.rb"],
+  ["test/data/unit_test_detect_rbtest-output.rb", "test/data/unit_test-output.rb"],
+  ["test/data/unit_test_detect_rbtest2-input.rb", "test/data/unit_test_rbtest-input.rb"],
+  ["test/data/unit_test_detect_rbtest2-output.rb", "test/data/unit_test_rbtest-output.rb"],
+  ["test/data/completion_detect_rbtest-input.rb", "test/data/completion_rbtest-input.rb"],
+  ["test/data/completion_detect_rbtest-output.rb", "test/data/completion_rbtest-output.rb"],
+  ["test/data/completion_detect_rbtest2-input.rb", "test/data/completion-input.rb"],
+  ["test/data/completion_detect_rbtest2-output.rb", "test/data/completion-output.rb"],
+  ["test/data/doc_detect_rbtest-input.rb", "test/data/doc-input.rb"],
+  ["test/data/doc_detect_rbtest-output.rb", "test/data/doc-output.rb"],
+  ["test/data/doc_detect_rbtest2-input.rb", "test/data/doc_rbtest-input.rb"],
+  ["test/data/doc_detect_rbtest2-output.rb", "test/data/doc_rbtest-output.rb"],
+
 ].each do |outfile, infile|
   basetestfiles << outfile
   file(outfile => infile, &copy)

data/THANKS

@@ -4,3 +4,8 @@ rubikitch
 * expanded xmp3.rb (a previous version of xmpfilter.rb) to support RSpec expectations
 * wrote the elisp magic to use xmpfilter.rb with emacs
 * made the 100% accurate, editor-independent completion system
+[rubikitch took xmpfilter and turned it into the much more powerful
+rcodetools, so there are way too many things to list them here :)]
+
+Adagios
+* found & fixed problem with rcodetools.vim plugin on win32

data/bin/rct-complete

@@ -1,8 +1,9 @@
-#! /home/batsman/usr//bin/ruby
+#! /home/batsman/usr/bin/ruby
 require 'rcodetools/xmpfilter'
 require 'rcodetools/completion'
 require 'rcodetools/options'
 
+include Rcodetools
 options = DEFAULT_OPTIONS
 klass = XMPCompletionFilter
 
@@ -32,9 +33,10 @@ end
 
 set_extra_opts options
 opts.parse!(ARGV)
+check_opts options
 
 targetcode = ARGF.read
 Dir.chdir options[:wd] if options[:wd]
-
+XMPFilter.detect_rbtest(targetcode, options)
 # Do the job. dispatched by klass.
 puts klass.run(targetcode, options)

data/bin/rct-doc

@@ -1,8 +1,9 @@
-#! /home/batsman/usr//bin/ruby
+#! /home/batsman/usr/bin/ruby
 require 'rcodetools/xmpfilter'
 require 'rcodetools/doc'
 require 'rcodetools/options'
 
+include Rcodetools
 options = DEFAULT_OPTIONS
 klass = XMPDocFilter
 
@@ -42,9 +43,10 @@ end
 
 set_extra_opts options
 opts.parse!(ARGV)
+check_opts options
 
 targetcode = ARGF.read
 Dir.chdir options[:wd] if options[:wd]
-
+XMPFilter.detect_rbtest(targetcode, options)
 # Do the job. dispatched by klass.
 puts klass.run(targetcode, options)

data/bin/rct-meth-args

@@ -1,4 +1,4 @@
-#! /home/batsman/usr//bin/ruby
+#! /home/batsman/usr/bin/ruby
 # Copyright (c) 
 #  2006-2007 Mauricio Fernandez <mfp@acm.org>    http://eigenclass.org
 #  2006-2007 rubikitch <rubikitch@ruby-lang.org> http://www.rubyist.net/~rubikitch/