Module: Readline

Relationships & Source Files
Defined in:	ext/readline/readline.c

Overview

The Readline module provides interface for GNU Readline. This module defines a number of methods to facilitate completion and accesses input history from the Ruby interpreter. This module supported Edit Line(libedit) too. libedit is compatible with GNU Readline.

GNU Readline: www.gnu.org/directory/readline.html
libedit: www.thrysoee.dk/editline/

Reads one inputted line with line edit by .readline method. At this time, the facilitatation completion and the key bind like Emacs can be operated like GNU Readline.

require "readline"
while buf = Readline.readline("> ", true)
  p buf
end

The content that the user input can be recorded to the history. The history can be accessed by ::HISTORY constant.

require "readline"
while buf = Readline.readline("> ", true)
  p Readline::HISTORY.to_a
  print("-> ", buf, "\n")
end

Documented by Kouji Takao <kouji dot takao at gmail dot com>.

Constant Summary

FILENAME_COMPLETION_PROC =

The Object with the call method that is a completion for filename. This is sets by .completion_proc= method.

# File 'ext/readline/readline.c', line 2074
```
fcomp
```
HISTORY =

The history buffer. It extends Enumerable module, so it behaves just like an array. For example, gets the fifth content that the user input by HISTORY[4].

# File 'ext/readline/readline.c', line 2065
```
history
```
USERNAME_COMPLETION_PROC =

The Object with the call method that is a completion for usernames. This is sets by .completion_proc= method.

# File 'ext/readline/readline.c', line 2083
```
ucomp
```
VERSION =

Version string of GNU Readline or libedit.

# File 'ext/readline/readline.c', line 2117
```
version
```

Class Attribute Summary

.basic_quote_characters ⇒ String rw

Gets a list of quote characters which can cause a word break.
.basic_quote_characters=(string) rw

Sets a list of quote characters which can cause a word break.
.basic_word_break_characters ⇒ String rw

Gets the basic list of characters that signal a break between words for the completer routine.
.basic_word_break_characters=(string) rw

Sets the basic list of characters that signal a break between words for the completer routine.
.completer_quote_characters ⇒ String rw

Gets a list of characters which can be used to quote a substring of the line.
.completer_quote_characters=(string) rw

Sets a list of characters which can be used to quote a substring of the line.
.completer_word_break_characters ⇒ String rw

Gets the basic list of characters that signal a break between words for rl_complete_internal().
.completer_word_break_characters=(string) rw

Sets the basic list of characters that signal a break between words for rl_complete_internal().
.completion_append_character ⇒ String rw

Returns a string containing a character to be appended on completion.
.completion_append_character=(char) rw

Specifies a character to be appended on completion.
.completion_case_fold ⇒ Boolean rw

Returns true if completion ignores case.
.completion_case_fold=(bool) rw

Sets whether or not to ignore case on completion.
.completion_proc ⇒ Proc rw

Returns the completion Proc object.
.completion_proc=(proc) rw

Specifies a Proc object proc to determine completion behavior.
.emacs_editing_mode ⇒ nil readonly

Specifies Emacs editing mode.
.emacs_editing_mode? ⇒ Boolean readonly

Returns true if emacs mode is active.
.filename_quote_characters ⇒ String rw

Gets a list of characters that cause a filename to be quoted by the completer when they appear in a completed filename.
.filename_quote_characters=(string) rw

Sets a list of characters that cause a filename to be quoted by the completer when they appear in a completed filename.
.input=(input) writeonly

Specifies a File object input that is input stream for .readline method.
.output=(output) writeonly

Specifies a File object output that is output stream for .readline method.
.point ⇒ Integer rw

Returns the index of the current cursor position in .line_buffer.
.point=(int) rw

Set the index of the current cursor position in .line_buffer.
.pre_input_hook ⇒ Proc rw

Returns a Proc object proc to call after the first prompt has been printed and just before readline starts reading input characters.
.pre_input_hook=(proc) rw

Specifies a Proc object proc to call after the first prompt has been printed and just before readline starts reading input characters.
.quoting_detection_proc ⇒ Proc rw

Returns the quoting detection Proc object.
.quoting_detection_proc=(proc) rw

Specifies a Proc object proc to determine if a character in the user’s input is escaped.
.special_prefixes ⇒ String rw

Gets the list of characters that are word break characters, but should be left in text when it is passed to the completion function.
.special_prefixes=(string) rw

Sets the list of characters that are word break characters, but should be left in text when it is passed to the completion function.
.vi_editing_mode ⇒ nil readonly

Specifies VI editing mode.
.vi_editing_mode? ⇒ Boolean readonly

Returns true if vi mode is active.

Class Method Summary

.completion_quote_character ⇒ String

When called during a completion (e.g. from within your completion_proc), it will return a string containing the character used to quote the argument being completed, or nil if the argument is unquoted.
.delete_text([start[, length]]) ⇒ self

Delete text between start and end in the current line.
.get_screen_size ⇒ Array, columns

Returns the terminal’s rows and columns.
.insert_text(string) ⇒ self

Insert text into the line at the current cursor position.
.line_buffer ⇒ String

Returns the full line that is being edited.
.redisplay ⇒ self

Change what’s displayed on the screen to reflect the current contents.
.refresh_line ⇒ nil

Clear the current input line.
.set_screen_size(rows, columns) ⇒ self

Set terminal size to rows and columns.
.readline(prompt = "", add_hist = false) ⇒ String^? mod_func

Shows the prompt and reads the inputted line with line editing.

Class Attribute Details

.basic_quote_characters ⇒ `String` (rw)

Gets a list of quote characters which can cause a word break.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1553


static VALUE
readline_s_get_basic_quote_characters(VALUE self)
{
    if (rl_basic_quote_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_basic_quote_characters);
}

.basic_quote_characters=(string) (rw)

Sets a list of quote characters which can cause a word break.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1520


static VALUE
readline_s_set_basic_quote_characters(VALUE self, VALUE str)
{
    static char *basic_quote_characters = NULL;

    OutputStringValue(str);
    if (basic_quote_characters == NULL) {
        basic_quote_characters =
            ALLOC_N(char, RSTRING_LEN(str) + 1);
    }
    else {
        REALLOC_N(basic_quote_characters, char, RSTRING_LEN(str) + 1);
    }
    strncpy(basic_quote_characters,
            RSTRING_PTR(str), RSTRING_LEN(str));
    basic_quote_characters[RSTRING_LEN(str)] = '\0';
    rl_basic_quote_characters = basic_quote_characters;

    return self;
}

.basic_word_break_characters ⇒ `String` (rw)

Gets the basic list of characters that signal a break between words for the completer routine.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1383


static VALUE
readline_s_get_basic_word_break_characters(VALUE self)
{
    if (rl_basic_word_break_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_basic_word_break_characters);
}

.basic_word_break_characters=(string) (rw)

Sets the basic list of characters that signal a break between words for the completer routine. The default is the characters which break words for completion in Bash: “ tn"\‘`@$><=;|&{(”.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1350


static VALUE
readline_s_set_basic_word_break_characters(VALUE self, VALUE str)
{
    static char *basic_word_break_characters = NULL;

    OutputStringValue(str);
    if (basic_word_break_characters == NULL) {
        basic_word_break_characters =
            ALLOC_N(char, RSTRING_LEN(str) + 1);
    }
    else {
        REALLOC_N(basic_word_break_characters, char, RSTRING_LEN(str) + 1);
    }
    strncpy(basic_word_break_characters,
            RSTRING_PTR(str), RSTRING_LEN(str));
    basic_word_break_characters[RSTRING_LEN(str)] = '\0';
    rl_basic_word_break_characters = basic_word_break_characters;
    return self;
}

.completer_quote_characters ⇒ `String` (rw)

Gets a list of characters which can be used to quote a substring of the line.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1609


static VALUE
readline_s_get_completer_quote_characters(VALUE self)
{
    if (rl_completer_quote_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_completer_quote_characters);
}

.completer_quote_characters=(string) (rw)

Sets a list of characters which can be used to quote a substring of the line. Completion occurs on the entire substring, and within the substring .completer_word_break_characters are treated as any other character, unless they also appear within this list.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1576


static VALUE
readline_s_set_completer_quote_characters(VALUE self, VALUE str)
{
    static char *completer_quote_characters = NULL;

    OutputStringValue(str);
    if (completer_quote_characters == NULL) {
        completer_quote_characters =
            ALLOC_N(char, RSTRING_LEN(str) + 1);
    }
    else {
        REALLOC_N(completer_quote_characters, char, RSTRING_LEN(str) + 1);
    }
    strncpy(completer_quote_characters, RSTRING_PTR(str), RSTRING_LEN(str));
    completer_quote_characters[RSTRING_LEN(str)] = '\0';
    rl_completer_quote_characters = completer_quote_characters;

    return self;
}

.completer_word_break_characters ⇒ `String` (rw)

Gets the basic list of characters that signal a break between words for rl_complete_internal().

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1438


static VALUE
readline_s_get_completer_word_break_characters(VALUE self)
{
    if (rl_completer_word_break_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_completer_word_break_characters);
}

.completer_word_break_characters=(string) (rw)

Sets the basic list of characters that signal a break between words for rl_complete_internal(). The default is the value of .basic_word_break_characters.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1405


static VALUE
readline_s_set_completer_word_break_characters(VALUE self, VALUE str)
{
    static char *completer_word_break_characters = NULL;

    OutputStringValue(str);
    if (completer_word_break_characters == NULL) {
        completer_word_break_characters =
            ALLOC_N(char, RSTRING_LEN(str) + 1);
    }
    else {
        REALLOC_N(completer_word_break_characters, char, RSTRING_LEN(str) + 1);
    }
    strncpy(completer_word_break_characters,
            RSTRING_PTR(str), RSTRING_LEN(str));
    completer_word_break_characters[RSTRING_LEN(str)] = '\0';
    rl_completer_word_break_characters = completer_word_break_characters;
    return self;
}

.completion_append_character ⇒ `String` (rw)

Returns a string containing a character to be appended on completion. The default is a space (“ ”).

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1295


static VALUE
readline_s_get_completion_append_character(VALUE self)
{
    char buf[1];

    if (rl_completion_append_character == '\0')
        return Qnil;

    buf[0] = (char) rl_completion_append_character;
    return rb_locale_str_new(buf, 1);
}

.completion_append_character=(char) (rw)

Specifies a character to be appended on completion. Nothing will be appended if an empty string (“”) or nil is specified.

For example:

require "readline"

Readline.readline("> ", true)
Readline.completion_append_character = " "

Result:

>
Input "/var/li".

> /var/li
Press TAB key.

> /var/lib
Completes "b" and appends " ". So, you can continuously input "/usr".

> /var/lib /usr

NOTE: Only one character can be specified. When “string” is specified, sets only “s” that is the first.

require "readline"

Readline.completion_append_character = "string"
p Readline.completion_append_character # => "s"

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1265


static VALUE
readline_s_set_completion_append_character(VALUE self, VALUE str)
{
    if (NIL_P(str)) {
        rl_completion_append_character = '\0';
    }
    else {
        OutputStringValue(str);
        if (RSTRING_LEN(str) == 0) {
            rl_completion_append_character = '\0';
        } else {
            rl_completion_append_character = RSTRING_PTR(str)[0];
        }
    }
    return self;
}

.completion_case_fold ⇒ `Boolean` (rw)

Returns true if completion ignores case. If no, returns false.

NOTE: Returns the same object that is specified by .completion_case_fold= method.

require "readline"

Readline.completion_case_fold = "This is a String."
p Readline.completion_case_fold # => "This is a String."

[ GitHub ]

# File 'ext/readline/readline.c', line 927


static VALUE
readline_s_get_completion_case_fold(VALUE self)
{
    return rb_attr_get(mReadline, completion_case_fold);
}

.completion_case_fold=(bool) (rw)

Sets whether or not to ignore case on completion.

[ GitHub ]

# File 'ext/readline/readline.c', line 907


static VALUE
readline_s_set_completion_case_fold(VALUE self, VALUE val)
{
    return rb_ivar_set(mReadline, completion_case_fold, val);
}

.completion_proc ⇒ `Proc` (rw)

Returns the completion Proc object.

[ GitHub ]

# File 'ext/readline/readline.c', line 850


static VALUE
readline_s_get_completion_proc(VALUE self)
{
    return rb_attr_get(mReadline, completion_proc);
}

.completion_proc=(proc) (rw)

Specifies a Proc object proc to determine completion behavior. It should take input string and return an array of completion candidates.

The default completion is used if proc is nil.

The String that is passed to the Proc depends on the .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.

Upon successful completion the .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 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.

[ GitHub ]

# File 'ext/readline/readline.c', line 837


static VALUE
readline_s_set_completion_proc(VALUE self, VALUE proc)
{
    mustbe_callable(proc);
    return rb_ivar_set(mReadline, completion_proc, proc);
}

.emacs_editing_mode ⇒ `nil` (readonly)

Specifies Emacs editing mode. The default is this mode. See the manual of GNU Readline for details of Emacs editing mode.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1200


static VALUE
readline_s_emacs_editing_mode(VALUE self)
{
    rl_emacs_editing_mode(1,0);
    return Qnil;
}

.emacs_editing_mode? ⇒ `Boolean` (readonly)

Returns true if emacs mode is active. Returns false if not.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1219


static VALUE
readline_s_emacs_editing_mode_p(VALUE self)
{
    return rl_editing_mode == 1 ? Qtrue : Qfalse;
}

.filename_quote_characters ⇒ `String` (rw)

Gets a list of characters that cause a filename to be quoted by the completer when they appear in a completed filename.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1663


static VALUE
readline_s_get_filename_quote_characters(VALUE self)
{
    if (rl_filename_quote_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_filename_quote_characters);
}

.filename_quote_characters=(string) (rw)

Sets a list of characters that cause a filename to be quoted by the completer when they appear in a completed filename. The default is nil.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1630


static VALUE
readline_s_set_filename_quote_characters(VALUE self, VALUE str)
{
    static char *filename_quote_characters = NULL;

    OutputStringValue(str);
    if (filename_quote_characters == NULL) {
        filename_quote_characters =
            ALLOC_N(char, RSTRING_LEN(str) + 1);
    }
    else {
        REALLOC_N(filename_quote_characters, char, RSTRING_LEN(str) + 1);
    }
    strncpy(filename_quote_characters, RSTRING_PTR(str), RSTRING_LEN(str));
    filename_quote_characters[RSTRING_LEN(str)] = '\0';
    rl_filename_quote_characters = filename_quote_characters;

    return self;
}

.input=(input) (writeonly)

Specifies a File object input that is input stream for .readline method.

[ GitHub ]

# File 'ext/readline/readline.c', line 551


static VALUE
readline_s_set_input(VALUE self, VALUE input)
{
    rb_io_t *ifp;
    int fd;
    FILE *f;

    if (NIL_P(input)) {
        clear_rl_instream();
    }
    else {
        Check_Type(input, T_FILE);
        GetOpenFile(input, ifp);
        clear_rl_instream();
        fd = rb_cloexec_dup(ifp->fd);
        if (fd == -1)
            rb_sys_fail("dup");
        f = fdopen(fd, "r");
        if (f == NULL) {
            int save_errno = errno;
            close(fd);
            rb_syserr_fail(save_errno, "fdopen");
        }
        rl_instream = readline_rl_instream = f;
        readline_instream = input;
    }
    return input;
}

.output=(output) (writeonly)

Specifies a File object output that is output stream for .readline method.

[ GitHub ]

# File 'ext/readline/readline.c', line 587


static VALUE
readline_s_set_output(VALUE self, VALUE output)
{
    rb_io_t *ofp;
    int fd;
    FILE *f;

    if (NIL_P(output)) {
        clear_rl_outstream();
    }
    else {
        Check_Type(output, T_FILE);
        GetOpenFile(output, ofp);
        clear_rl_outstream();
        fd = rb_cloexec_dup(ofp->fd);
        if (fd == -1)
            rb_sys_fail("dup");
        f = fdopen(fd, "w");
        if (f == NULL) {
            int save_errno = errno;
            close(fd);
            rb_syserr_fail(save_errno, "fdopen");
        }
        rl_outstream = readline_rl_outstream = f;
        readline_outstream = output;
    }
    return output;
}

.point ⇒ `Integer` (rw)

Returns the index of the current cursor position in .line_buffer.

The index in .line_buffer which matches the start of input-string passed to completion_proc is computed by subtracting the length of input-string from point.

start = (the length of input-string) - Readline.point

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 974


static VALUE
readline_s_get_point(VALUE self)
{
    return INT2NUM(rl_point);
}

.point=(int) (rw)

Set the index of the current cursor position in .line_buffer.

Raises NotImplementedError if the using readline library does not support.

See .point.

[ GitHub ]

# File 'ext/readline/readline.c', line 991


static VALUE
readline_s_set_point(VALUE self, VALUE pos)
{
    rl_point = NUM2INT(pos);
    return pos;
}

.pre_input_hook ⇒ `Proc` (rw)

Returns a Proc object proc to call after the first prompt has been printed and just before readline starts reading input characters. The default is nil.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 648


static VALUE
readline_s_get_pre_input_hook(VALUE self)
{
    return rb_attr_get(mReadline, id_pre_input_hook);
}

.pre_input_hook=(proc) (rw)

Specifies a Proc object proc to call after the first prompt has been printed and just before readline starts reading input characters.

See GNU Readline’s rl_pre_input_hook variable.

Raises ArgumentError if proc does not respond to the call method.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 631


static VALUE
readline_s_set_pre_input_hook(VALUE self, VALUE proc)
{
    mustbe_callable(proc);
    return rb_ivar_set(mReadline, id_pre_input_hook, proc);
}

.quoting_detection_proc ⇒ `Proc` (rw)

Returns the quoting detection Proc object.

[ GitHub ]

# File 'ext/readline/readline.c', line 891


static VALUE
readline_s_get_quoting_detection_proc(VALUE self)
{
    return rb_attr_get(mReadline, quoting_detection_proc);
}

.quoting_detection_proc=(proc) (rw)

Specifies a Proc object proc to determine if a character in the user’s input is escaped. It should take the user’s input and the index of the character in question as input, and return a boolean (true if the specified character is escaped).

Readline will only call this proc with characters specified in .completer_quote_characters, to discover if they indicate the end of a quoted argument, or characters specified in .completer_word_break_characters, to discover if they indicate a break between arguments.

If .completer_quote_characters is not set, or if the user input doesn’t contain one of the .completer_quote_characters or a ++ character, Readline will not attempt to use this proc at all.

Raises ArgumentError if proc does not respond to the call method.

[ GitHub ]

# File 'ext/readline/readline.c', line 878


static VALUE
readline_s_set_quoting_detection_proc(VALUE self, VALUE proc)
{
    mustbe_callable(proc);
    return rb_ivar_set(mReadline, quoting_detection_proc, proc);
}

.special_prefixes ⇒ `String` (rw)

Gets the list of characters that are word break characters, but should be left in text when it is passed to the completion function.

See GNU Readline’s rl_special_prefixes variable.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1494


static VALUE
readline_s_get_special_prefixes(VALUE self)
{
    VALUE str;
    if (rl_special_prefixes == NULL) return Qnil;
    str = rb_ivar_get(mReadline, id_special_prefixes);
    if (!NIL_P(str)) {
        str = rb_str_dup_frozen(str);
        rb_obj_reveal(str, rb_cString);
    }
    return str;
}

.special_prefixes=(string) (rw)

Sets the list of characters that are word break characters, but should be left in text when it is passed to the completion function. Programs can use this to help determine what kind of completing to do. For instance, Bash sets this variable to “$@” so that it can complete shell variables and hostnames.

See GNU Readline’s rl_special_prefixes variable.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1464


static VALUE
readline_s_set_special_prefixes(VALUE self, VALUE str)
{
    if (!NIL_P(str)) {
        OutputStringValue(str);
        str = rb_str_dup_frozen(str);
        rb_obj_hide(str);
    }
    rb_ivar_set(mReadline, id_special_prefixes, str);
    if (NIL_P(str)) {
        rl_special_prefixes = NULL;
    }
    else {
        rl_special_prefixes = RSTRING_PTR(str);
    }
    return self;
}

.vi_editing_mode ⇒ `nil` (readonly)

Specifies VI editing mode. See the manual of GNU Readline for details of VI editing mode.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1161


static VALUE
readline_s_vi_editing_mode(VALUE self)
{
    rl_vi_editing_mode(1,0);
    return Qnil;
}

.vi_editing_mode? ⇒ `Boolean` (readonly)

Returns true if vi mode is active. Returns false if not.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1180


static VALUE
readline_s_vi_editing_mode_p(VALUE self)
{
    return rl_editing_mode == 0 ? Qtrue : Qfalse;
}

Class Method Details

.completion_quote_character ⇒ `String`

When called during a completion (e.g. from within your completion_proc), it will return a string containing the character used to quote the argument being completed, or nil if the argument is unquoted.

When called at other times, it will always return nil.

Note that .completer_quote_characters must be set, or this method will always return nil.

[ GitHub ]

# File 'ext/readline/readline.c', line 1324


static VALUE
readline_s_get_completion_quote_character(VALUE self)
{
    char buf[1];

    if (rl_completion_quote_character == '\0')
        return Qnil;

    buf[0] = (char) rl_completion_quote_character;
    return rb_locale_str_new(buf, 1);
}

.delete_text([start[, length]]) ⇒ `self` .delete_text(start..end) ⇒ `self` .delete_text ⇒ `self`

Delete text between start and end in the current line.

See GNU Readline’s rl_delete_text function.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 715


static VALUE
readline_s_delete_text(int argc, VALUE *argv, VALUE self)
{
    rb_check_arity(argc, 0, 2);
    if (rl_line_buffer) {
        const char *p, *ptr = rl_line_buffer;
        long beg = 0, len = strlen(ptr);
        const char *end = ptr + len;
        rb_encoding *enc = rb_locale_encoding();
        if (argc == 2) {
            beg = NUM2LONG(argv[0]);
            len = NUM2LONG(argv[1]);
          num_pos:
            p = str_subpos(ptr, end, beg, &len, enc);
            if (!p) rb_raise(rb_eArgError, "invalid index");
            beg = p - ptr;
        }
        else if (argc == 1) {
            len = rb_enc_strlen(ptr, ptr + len, enc);
            if (!rb_range_beg_len(argv[0], &beg, &len, len, 1)) {
                beg = NUM2LONG(argv[0]);
                goto num_pos;
            }
        }
        rl_delete_text(rb_long2int(beg), rb_long2int(beg + len));
    }
    return self;
}

.get_screen_size ⇒ `Array`, `columns`

Returns the terminal’s rows and columns.

See GNU Readline’s rl_get_screen_size function.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1134


static VALUE
readline_s_get_screen_size(VALUE self)
{
    int rows, columns;
    VALUE res;

    rl_get_screen_size(&rows, &columns);
    res = rb_ary_new();
    rb_ary_push(res, INT2NUM(rows));
    rb_ary_push(res, INT2NUM(columns));
    return res;
}

.insert_text(string) ⇒ `self`

Insert text into the line at the current cursor position.

See GNU Readline’s rl_insert_text function.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 680


static VALUE
readline_s_insert_text(VALUE self, VALUE str)
{
    OutputStringValue(str);
    rl_insert_text(RSTRING_PTR(str));
    return self;
}

.line_buffer ⇒ `String`

Returns the full line that is being edited. This is useful from within the complete_proc for determining the context of the completion request.

The length of line_buffer and GNU Readline’s rl_end are same.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 947


static VALUE
readline_s_get_line_buffer(VALUE self)
{
    if (rl_line_buffer == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_line_buffer);
}

.readline(prompt = "", add_hist = false) ⇒ `String`^? (mod_func)

Shows the prompt and reads the inputted line with line editing. The inputted line is added to the history if add_hist is true.

Returns nil when the inputted line is empty and user inputs EOF (Presses ^D on UNIX).

Raises IOError exception if one of below conditions are satisfied.

stdin was closed.
stdout was closed.

This method supports thread. Switches the thread context when waits inputting line.

Supports line edit when inputs line. Provides VI and Emacs editing mode. Default is Emacs editing mode.

NOTE: Terminates ruby interpreter and does not return the terminal status after user pressed ‘^C’ when wait inputting line. Give 3 examples that avoid it.

Catches the Interrupt exception by pressed ^C after returns terminal status:

require "readline"

stty_save = `stty -g`.chomp
begin
  while buf = Readline.readline
      p buf
      end
    rescue Interrupt
      system("stty", stty_save)
      exit
    end
  end
end

Catches the INT signal by pressed ^C after returns terminal status:

require "readline"

stty_save = `stty -g`.chomp
trap("INT") { system "stty", stty_save; exit }

while buf = Readline.readline
  p buf
end

Ignores pressing ^C:

require "readline"

trap("INT", "SIG_IGN")

while buf = Readline.readline
  p buf
end

Can make as follows with ::HISTORY constant. It does not record to the history if the inputted line is empty or the same it as last one.

require "readline"

while buf = Readline.readline("> ", true)
  # p Readline::HISTORY.to_a
  Readline::HISTORY.pop if /^\s*$/ =~ buf

  begin
    if Readline::HISTORY[Readline::HISTORY.length-2] == buf
      Readline::HISTORY.pop
    end
  rescue IndexError
  end

  # p Readline::HISTORY.to_a
  print "-> ", buf, "\n"
end

[ GitHub ]

# File 'ext/readline/readline.c', line 486


static VALUE
readline_readline(int argc, VALUE *argv, VALUE self)
{
    VALUE tmp, add_hist, result;
    char *prompt = NULL;
    char *buff;
    int status;

    if (rb_scan_args(argc, argv, "02", &tmp, &add_hist) > 0) {
        OutputStringValue(tmp);
#if USE_INSERT_IGNORE_ESCAPE
        tmp = insert_ignore_escape(self, tmp);
        rb_str_locktmp(tmp);
#endif
        prompt = RSTRING_PTR(tmp);
    }

    prepare_readline();

#ifdef _WIN32
    rl_prep_terminal(1);
#endif
    buff = (char*)rb_protect(readline_get, (VALUE)prompt, &status);
#if USE_INSERT_IGNORE_ESCAPE
    if (prompt) {
        rb_str_unlocktmp(tmp);
    }
#endif
    if (status) {
#if defined HAVE_RL_CLEANUP_AFTER_SIGNAL
        /* restore terminal mode and signal handler*/
#if defined HAVE_RL_FREE_LINE_STATE
        rl_free_line_state();
#endif
        rl_cleanup_after_signal();
#elif defined HAVE_RL_DEPREP_TERM_FUNCTION
        /* restore terminal mode */
        if (rl_deprep_term_function != NULL) /* NULL in libedit. [ruby-dev:29116] */
            (*rl_deprep_term_function)();
        else
#else
        rl_deprep_terminal();
#endif
        rb_jump_tag(status);
    }

    if (RTEST(add_hist) && buff) {
        add_history(buff);
    }
    if (buff) {
        result = rb_locale_str_new_cstr(buff);
    }
    else
        result = Qnil;
    if (buff) free(buff);
    return result;
}

.redisplay ⇒ `self`

Change what’s displayed on the screen to reflect the current contents.

See GNU Readline’s rl_redisplay function.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 759


static VALUE
readline_s_redisplay(VALUE self)
{
    rl_redisplay();
    return self;
}

.refresh_line ⇒ `nil`

Clear the current input line.

[ GitHub ]

# File 'ext/readline/readline.c', line 1682


static VALUE
readline_s_refresh_line(VALUE self)
{
    prepare_readline();
    rl_refresh_line(0, 0);
    return Qnil;
}

.set_screen_size(rows, columns) ⇒ `self`

Set terminal size to rows and columns.

See GNU Readline’s rl_set_screen_size function.

Raises NotImplementedError if the using readline library does not support.

[ GitHub ]

# File 'ext/readline/readline.c', line 1113


static VALUE
readline_s_set_screen_size(VALUE self, VALUE rows, VALUE columns)
{
    rl_set_screen_size(NUM2INT(rows), NUM2INT(columns));
    return self;
}

Module: Readline

Overview

Constant Summary

Class Attribute Summary

Class Method Summary

Class Attribute Details

.basic_quote_characters ⇒ String (rw)

.basic_quote_characters=(string) (rw)

.basic_word_break_characters ⇒ String (rw)

.basic_word_break_characters=(string) (rw)

.completer_quote_characters ⇒ String (rw)

.completer_quote_characters=(string) (rw)

.completer_word_break_characters ⇒ String (rw)

.completer_word_break_characters=(string) (rw)

.completion_append_character ⇒ String (rw)

.completion_append_character=(char) (rw)

.completion_case_fold ⇒ Boolean (rw)

.completion_case_fold=(bool) (rw)

.completion_proc ⇒ Proc (rw)

.completion_proc=(proc) (rw)

Examples

Completion for a Static List

Completion For Directory Contents

Autocomplete strategies

.emacs_editing_mode ⇒ nil (readonly)

.emacs_editing_mode? ⇒ Boolean (readonly)

.filename_quote_characters ⇒ String (rw)

.filename_quote_characters=(string) (rw)

.input=(input) (writeonly)

.output=(output) (writeonly)

.point ⇒ Integer (rw)

.point=(int) (rw)

.pre_input_hook ⇒ Proc (rw)

.pre_input_hook=(proc) (rw)

.quoting_detection_proc ⇒ Proc (rw)

.quoting_detection_proc=(proc) (rw)

.special_prefixes ⇒ String (rw)

.special_prefixes=(string) (rw)

.vi_editing_mode ⇒ nil (readonly)

.vi_editing_mode? ⇒ Boolean (readonly)

Class Method Details

.completion_quote_character ⇒ String

.delete_text([start[, length]]) ⇒ self .delete_text(start..end) ⇒ self .delete_text ⇒ self

.get_screen_size ⇒ Array, columns

.insert_text(string) ⇒ self

.line_buffer ⇒ String

.readline(prompt = "", add_hist = false) ⇒ String? (mod_func)

.redisplay ⇒ self

.refresh_line ⇒ nil

.set_screen_size(rows, columns) ⇒ self

.basic_quote_characters ⇒ `String` (rw)

.basic_word_break_characters ⇒ `String` (rw)

.completer_quote_characters ⇒ `String` (rw)

.completer_word_break_characters ⇒ `String` (rw)

.completion_append_character ⇒ `String` (rw)

.completion_case_fold ⇒ `Boolean` (rw)

.completion_proc ⇒ `Proc` (rw)

.emacs_editing_mode ⇒ `nil` (readonly)

.emacs_editing_mode? ⇒ `Boolean` (readonly)

.filename_quote_characters ⇒ `String` (rw)

.point ⇒ `Integer` (rw)

.pre_input_hook ⇒ `Proc` (rw)

.quoting_detection_proc ⇒ `Proc` (rw)

.special_prefixes ⇒ `String` (rw)

.vi_editing_mode ⇒ `nil` (readonly)

.vi_editing_mode? ⇒ `Boolean` (readonly)

.completion_quote_character ⇒ `String`

.delete_text([start[, length]]) ⇒ `self` .delete_text(start..end) ⇒ `self` .delete_text ⇒ `self`

.get_screen_size ⇒ `Array`, `columns`

.insert_text(string) ⇒ `self`

.line_buffer ⇒ `String`

.readline(prompt = "", add_hist = false) ⇒ `String`^? (mod_func)

.redisplay ⇒ `self`

.refresh_line ⇒ `nil`

.set_screen_size(rows, columns) ⇒ `self`