summaryrefslogtreecommitdiff
path: root/ext/readline
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-07-22 04:52:22 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-07-22 04:52:22 +0000
commitc1fa17c13897f4c1343da1cc3ef7c67f34e98634 (patch)
tree644ae236d6cf8194497276c4658c32aef83a15e1 /ext/readline
parentaf017841509b5cce4b82466f564186ea53774688 (diff)
* ext/readline/readline.c: Add examples for Readline.completion_proc=.
[Ruby 1.9 - Bug #5057] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32612 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/readline')
-rw-r--r--ext/readline/readline.c68
1 files changed, 62 insertions, 6 deletions
diff --git a/ext/readline/readline.c b/ext/readline/readline.c
index 65c0c41..c035b67 100644
--- a/ext/readline/readline.c
+++ b/ext/readline/readline.c
@@ -454,15 +454,71 @@ readline_s_set_output(VALUE self, VALUE output)
* call-seq:
* Readline.completion_proc = proc
*
- * Specifies a Proc object +proc+ to determine completion behavior. It
- * should take input-string, and return an array of completion
- * candidates.
+ * Specifies a Proc object +proc+ to determine completion behavior. It
+ * should take input string and return an array of completion candidates.
*
- * Set default if +proc+ is nil.
+ * The default completion is used if +proc+ is nil.
*
- * Raises ArgumentError exception if +proc+ does not respond to call method.
+ * The String that is passed to the Proc depends on the
+ * Readline.completer_word_break_characters property. By default the word
+ * under the cursor is passed to the Proc. For example, if the input is "foo
+ * bar" then only "bar" would be passed to the completion Proc.
*
- * Raises SecurityError exception if $SAFE is 4.
+ * Upon successful completion the Readline.completion_append_character will be
+ * appended to the input so the user can start working on their next argument.
+ *
+ * = Examples
+ *
+ * == Completion for a Static List
+ *
+ * require 'readline'
+ *
+ * LIST = [
+ * 'search', 'download', 'open',
+ * 'help', 'history', 'quit',
+ * 'url', 'next', 'clear',
+ * 'prev', 'past'
+ * ].sort
+ *
+ * comp = proc { |s| LIST.grep(/^#{Regexp.escape(s)}/) }
+ *
+ * Readline.completion_append_character = " "
+ * Readline.completion_proc = comp
+ *
+ * while line = Readline.readline('> ', true)
+ * p line
+ * end
+ *
+ * == Completion For Directory Contents
+ *
+ * require 'readline'
+ *
+ * Readline.completion_append_character = " "
+ * Readline.completion_proc = Proc.new do |str|
+ * Dir[str+'*'].grep(/^#{Regexp.escape(str)}/)
+ * end
+ *
+ * while line = Readline.readline('> ', true)
+ * p line
+ * end
+ *
+ * = Autocomplete strategies
+ *
+ * When working with auto-complete there are some strategies that work well.
+ * To get some ideas you can take a look at the
+ * completion.rb[http://svn.ruby-lang.org/repos/ruby/trunk/lib/irb/completion.rb]
+ * file for irb.
+ *
+ * The common strategy is to take a list of possible completions and filter it
+ * down to those completions that start with the user input. In the above
+ * examples Enumerator.grep is used. The input is escaped to prevent Regexp
+ * special characters from interfering with the matching.
+ *
+ * It may also be helpful to use the Abbrev library to generate completions.
+ *
+ * Raises ArgumentError if +proc+ does not respond to the call method.
+ *
+ * Raises SecurityError if $SAFE is 4.
*/
static VALUE
readline_s_set_completion_proc(VALUE self, VALUE proc)