Module: Readline

Defined in:
readline.c

Constant Summary collapse

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

history
FILENAME_COMPLETION_PROC =

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

fcomp
USERNAME_COMPLETION_PROC =

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

ucomp
VERSION =

Version string of GNU Readline or libedit.

version

Class Method Summary collapse

Class Method Details

.basic_quote_characters ⇒ String

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

Raises NotImplementedError if the using readline library does not support.

Returns:

  • (String) 


1553
1554
1555
1556
1557
1558
1559
 
# File '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) ⇒ Object

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

Raises NotImplementedError if the using readline library does not support.



1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
 
# File '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

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.

Returns:

  • (String) 


1383
1384
1385
1386
1387
1388
1389
 
# File '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) ⇒ Object

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.



1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
 
# File '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

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.

Returns:

  • (String) 


1609
1610
1611
1612
1613
1614
1615
 
# File '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) ⇒ Object

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



1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
 
# File '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

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.

Returns:

  • (String) 


1438
1439
1440
1441
1442
1443
1444
 
# File '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) ⇒ Object

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

Raises NotImplementedError if the using readline library does not support.



1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
 
# File '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

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.

Returns:

  • (String) 


1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
 
# File '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) ⇒ Object

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.



1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
 
# File '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

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

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

require "readline"

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

Returns:

  • (Boolean) 


927
928
929
930
931
 
# File '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) ⇒ Object

Sets whether or not to ignore case on completion.



907
908
909
910
911
 
# File '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

Returns the completion Proc object.

Returns:

  • (Proc) 


850
851
852
853
854
 
# File 'readline.c', line 850

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

.completion_proc=(proc) ⇒ Object

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

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



837
838
839
840
841
842
 
# File '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);
}

.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 Readline.completer_quote_characters must be set, or this method will always return nil.

Returns:

  • (String) 


1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
 
# File '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.

Overloads:

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

    Returns:

    • (self)
  • .delete_text(start..end) ⇒ self

    Returns:

    • (self)
  • .delete_text ⇒ self

    Returns:

    • (self) 


715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
 
# File '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;
}

.emacs_editing_mode ⇒ nil

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.

Returns:

  • (nil) 


1200
1201
1202
1203
1204
1205
 
# File '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

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

Raises NotImplementedError if the using readline library does not support.

Returns:

  • (Boolean) 


1219
1220
1221
1222
1223
 
# File '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

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.

Returns:

  • (String) 


1663
1664
1665
1666
1667
1668
1669
 
# File '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) ⇒ Object

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.



1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
 
# File '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;
}

.get_screen_size ⇒ Array

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.

Returns:

  • (Array) 


1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
 
# File '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;
}

.input=(input) ⇒ Object

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



551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
 
# File '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;
}

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

Returns:

  • (self) 


680
681
682
683
684
685
686
 
# File '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 Readline.line_buffer and GNU Readline’s rl_end are same.

Raises NotImplementedError if the using readline library does not support.

Returns:

  • (String) 


947
948
949
950
951
952
953
 
# File '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);
}

.output=(output) ⇒ Object

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



587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
 
# File '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

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

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

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

Raises NotImplementedError if the using readline library does not support.

Returns:

  • (Integer) 


974
975
976
977
978
 
# File 'readline.c', line 974

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

.point=(int) ⇒ Object

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

Raises NotImplementedError if the using readline library does not support.

See Readline.point.



991
992
993
994
995
996
 
# File 'readline.c', line 991

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

.pre_input_hook ⇒ Proc

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.

Returns:

  • (Proc) 


648
649
650
651
652
 
# File '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) ⇒ Object

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.



631
632
633
634
635
636
 
# File '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

Returns the quoting detection Proc object.

Returns:

  • (Proc) 


891
892
893
894
895
 
# File '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) ⇒ Object

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.



878
879
880
881
882
883
 
# File '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);
}

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

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.

  1. stdin was closed.

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

Returns:

  • (String, nil) 


486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
 
# File '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.

Returns:

  • (self) 


759
760
761
762
763
764
 
# File 'readline.c', line 759

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

.refresh_line ⇒ nil

Clear the current input line.

Returns:

  • (nil) 


1682
1683
1684
1685
1686
1687
1688
 
# File '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.

Returns:

  • (self) 


1113
1114
1115
1116
1117
1118
 
# File '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;
}

.special_prefixes ⇒ String

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.

Returns:

  • (String) 


1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
 
# File '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) ⇒ Object

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.



1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
 
# File '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

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.

Returns:

  • (nil) 


1161
1162
1163
1164
1165
1166
 
# File '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

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

Raises NotImplementedError if the using readline library does not support.

Returns:

  • (Boolean) 


1180
1181
1182
1183
1184
 
# File 'readline.c', line 1180

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