Readline

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 Readline::HISTORY constant.

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

Most of methods raise SecurityError exception if $SAFE is 4.

Documented by TAKAO Kouji <kouji at takao7 dot net>.

Constants

FILENAME_COMPLETION_PROC: The Object with the call method that is a completion for filename. This is sets by ::completion_proc= method.
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.
USERNAME_COMPLETION_PROC: The Object with the call method that is a completion for usernames. This is sets by ::completion_proc= method.
VERSION: Version string of GNU Readline or libedit.

Public Class Methods

basic_quote_characters → string click to toggle source

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

Raises NotImplementedError if the using readline library does not support.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_get_basic_quote_characters(VALUE self, VALUE str)
{
#ifdef HAVE_RL_BASIC_QUOTE_CHARACTERS
    rb_secure(4);
    if (rl_basic_quote_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_basic_quote_characters);
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_BASIC_QUOTE_CHARACTERS */
}

basic_quote_characters = string click to toggle source

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

Raises NotImplementedError if the using readline library does not support.

Raises SecurityError exception if $SAFE is 4.

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

    rb_secure(4);
    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;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_BASIC_QUOTE_CHARACTERS */
}

basic_word_break_characters → string click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_get_basic_word_break_characters(VALUE self, VALUE str)
{
#ifdef HAVE_RL_BASIC_WORD_BREAK_CHARACTERS
    rb_secure(4);
    if (rl_basic_word_break_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_basic_word_break_characters);
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_BASIC_WORD_BREAK_CHARACTERS */
}

basic_word_break_characters = string click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

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

    rb_secure(4);
    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;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_BASIC_WORD_BREAK_CHARACTERS */
}

completer_quote_characters → string click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_get_completer_quote_characters(VALUE self, VALUE str)
{
#ifdef HAVE_RL_COMPLETER_QUOTE_CHARACTERS
    rb_secure(4);
    if (rl_completer_quote_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_completer_quote_characters);
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_COMPLETER_QUOTE_CHARACTERS */
}

completer_quote_characters = string click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

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

    rb_secure(4);
    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;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_COMPLETER_QUOTE_CHARACTERS */
}

completer_word_break_characters → string click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_get_completer_word_break_characters(VALUE self, VALUE str)
{
#ifdef HAVE_RL_COMPLETER_WORD_BREAK_CHARACTERS
    rb_secure(4);
    if (rl_completer_word_break_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_completer_word_break_characters);
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_COMPLETER_WORD_BREAK_CHARACTERS */
}

completer_word_break_characters = string click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

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

    rb_secure(4);
    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;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_COMPLETER_WORD_BREAK_CHARACTERS */
}

completion_append_character → char click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

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

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

    buf[0] = (char) rl_completion_append_character;
    return rb_locale_str_new(buf, 1);
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_COMPLETION_APPEND_CHARACTER */
}

completion_append_character = char click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_set_completion_append_character(VALUE self, VALUE str)
{
#ifdef HAVE_RL_COMPLETION_APPEND_CHARACTER
    rb_secure(4);
    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;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_COMPLETION_APPEND_CHARACTER */
}

completion_case_fold → bool click to toggle source

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."

Raises SecurityError exception if $SAFE is 4.

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

completion_case_fold = bool click to toggle source

Sets whether or not to ignore case on completion.

Raises SecurityError exception if $SAFE is 4.

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

completion_proc → proc click to toggle source

Returns the completion Proc object.

Raises SecurityError exception if $SAFE is 4.

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

completion_proc = proc click to toggle source

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

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

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_set_completion_proc(VALUE self, VALUE proc)
{
    rb_secure(4);
    if (!rb_respond_to(proc, rb_intern("call")))
        rb_raise(rb_eArgError, "argument must respond to `call'");
    return rb_ivar_set(mReadline, completion_proc, proc);
}

emacs_editing_mode → nil click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_emacs_editing_mode(VALUE self)
{
#ifdef HAVE_RL_EMACS_EDITING_MODE
    rb_secure(4);
    rl_emacs_editing_mode(1,0);
    return Qnil;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_EMACS_EDITING_MODE */
}

emacs_editing_mode? → bool click to toggle source

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

Raises NotImplementedError if the using readline library does not support.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_emacs_editing_mode_p(VALUE self)
{
#ifdef  HAVE_RL_EDITING_MODE
    rb_secure(4);
    return rl_editing_mode == 1 ? Qtrue : Qfalse;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_EDITING_MODE */
}

filename_quote_characters → string click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_get_filename_quote_characters(VALUE self, VALUE str)
{
#ifdef HAVE_RL_FILENAME_QUOTE_CHARACTERS
    rb_secure(4);
    if (rl_filename_quote_characters == NULL)
        return Qnil;
    return rb_locale_str_new_cstr(rl_filename_quote_characters);
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_FILENAME_QUOTE_CHARACTERS */
}

filename_quote_characters = string click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

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

    rb_secure(4);
    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;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_FILENAME_QUOTE_CHARACTERS */
}

input = input click to toggle source

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

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_set_input(VALUE self, VALUE input)
{
    rb_io_t *ifp;

    rb_secure(4);
    Check_Type(input, T_FILE);
    GetOpenFile(input, ifp);
    rl_instream = rb_io_stdio_file(ifp);
    return input;
}

output = output click to toggle source

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

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_set_output(VALUE self, VALUE output)
{
    rb_io_t *ofp;

    rb_secure(4);
    Check_Type(output, T_FILE);
    GetOpenFile(output, ofp);
    rl_outstream = rb_io_stdio_file(ofp);
    return output;
}

readline(prompt = "", add_hist = false) → string or nil click to toggle source

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 below conditions are satisfied.

stdin is not tty.
stdin was closed. (errno is EBADF after called isatty(2).)

This method supports thread. Switchs 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 Readline::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

Raises SecurityError exception if $SAFE is 4.

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

    rb_secure(4);
    if (rb_scan_args(argc, argv, "02", &tmp, &add_hist) > 0) {
        OutputStringValue(tmp);
        prompt = RSTRING_PTR(tmp);
    }

    if (!isatty(0) && errno == EBADF) rb_raise(rb_eIOError, "closed stdin");

#ifdef _WIN32
    rl_prep_terminal(1);
#endif
    buff = (char*)rb_protect((VALUE(*)_((VALUE)))readline, (VALUE)prompt,
                              &status);
    if (status) {
#if defined HAVE_RL_CLEANUP_AFTER_SIGNAL
        /* restore terminal mode and signal handler*/
        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;
}

vi_editing_mode → nil click to toggle source

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.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_vi_editing_mode(VALUE self)
{
#ifdef HAVE_RL_VI_EDITING_MODE
    rb_secure(4);
    rl_vi_editing_mode(1,0);
    return Qnil;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_VI_EDITING_MODE */
}

vi_editing_mode? → bool click to toggle source

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

Raises NotImplementedError if the using readline library does not support.

Raises SecurityError exception if $SAFE is 4.

 
               static VALUE
readline_s_vi_editing_mode_p(VALUE self)
{
#ifdef HAVE_RL_EDITING_MODE
    rb_secure(4);
    return rl_editing_mode == 0 ? Qtrue : Qfalse;
#else
    rb_notimplement();
    return Qnil; /* not reached */
#endif /* HAVE_RL_EDITING_MODE */
}

Home Classes Methods

In Files

Methods

Class/Module Index

Readline

Constants

Public Class Methods