Module: Readline

Defined in:
ext/rubysl/readline/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.

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.

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (String) 


1008
1009
1010
1011
1012
1013
1014
1015
 
# File 'ext/rubysl/readline/readline.c', line 1008

static VALUE
readline_s_get_basic_quote_characters(VALUE self, VALUE str)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.



972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
 
# File 'ext/rubysl/readline/readline.c', line 972

static VALUE
readline_s_set_basic_quote_characters(VALUE self, VALUE str)
{
    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;
}

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

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (String) 


888
889
890
891
892
893
894
895
 
# File 'ext/rubysl/readline/readline.c', line 888

static VALUE
readline_s_get_basic_word_break_characters(VALUE self, VALUE str)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.



852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
 
# File 'ext/rubysl/readline/readline.c', line 852

static VALUE
readline_s_set_basic_word_break_characters(VALUE self, VALUE str)
{
    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;
}

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

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (String) 


1070
1071
1072
1073
1074
1075
1076
1077
 
# File 'ext/rubysl/readline/readline.c', line 1070

static VALUE
readline_s_get_completer_quote_characters(VALUE self, VALUE str)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.



1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
 
# File 'ext/rubysl/readline/readline.c', line 1034

static VALUE
readline_s_set_completer_quote_characters(VALUE self, VALUE str)
{
    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;
}

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

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (String) 


949
950
951
952
953
954
955
956
 
# File 'ext/rubysl/readline/readline.c', line 949

static VALUE
readline_s_get_completer_word_break_characters(VALUE self, VALUE str)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.



913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
 
# File 'ext/rubysl/readline/readline.c', line 913

static VALUE
readline_s_set_completer_word_break_characters(VALUE self, VALUE str)
{
    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;
}

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

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (String) 


823
824
825
826
827
828
829
830
831
832
833
834
 
# File 'ext/rubysl/readline/readline.c', line 823

static VALUE
readline_s_get_completion_append_character(VALUE self)
{
    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);
}

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

Raises SecurityError exception if $SAFE is 4.



790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
 
# File 'ext/rubysl/readline/readline.c', line 790

static VALUE
readline_s_set_completion_append_character(VALUE self, VALUE str)
{
    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;
}

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

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (Boolean) 


490
491
492
493
494
495
 
# File 'ext/rubysl/readline/readline.c', line 490

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) ⇒ Object

Sets whether or not to ignore case on completion.

Raises SecurityError exception if $SAFE is 4.



467
468
469
470
471
472
 
# File 'ext/rubysl/readline/readline.c', line 467

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

Returns the completion Proc object.

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (Proc) 


452
453
454
455
456
457
 
# File 'ext/rubysl/readline/readline.c', line 452

static VALUE
readline_s_get_completion_proc(VALUE self)
{
    rb_secure(4);
    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.

Set default if proc is nil.

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

Raises SecurityError exception if $SAFE is 4.



435
436
437
438
439
440
441
442
 
# File 'ext/rubysl/readline/readline.c', line 435

static VALUE
readline_s_set_completion_proc(VALUE self, VALUE proc)
{
    rb_secure(4);
    if (!NIL_P(proc) && !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

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.

Returns:

  • (nil) 


719
720
721
722
723
724
725
 
# File 'ext/rubysl/readline/readline.c', line 719

static VALUE
readline_s_emacs_editing_mode(VALUE self)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (Boolean) 


741
742
743
744
745
746
 
# File 'ext/rubysl/readline/readline.c', line 741

static VALUE
readline_s_emacs_editing_mode_p(VALUE self)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (String) 


1130
1131
1132
1133
1134
1135
1136
1137
 
# File 'ext/rubysl/readline/readline.c', line 1130

static VALUE
readline_s_get_filename_quote_characters(VALUE self, VALUE str)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.



1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
 
# File 'ext/rubysl/readline/readline.c', line 1094

static VALUE
readline_s_set_filename_quote_characters(VALUE self, VALUE str)
{
    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;
}

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

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (Array) 


646
647
648
649
650
651
652
653
654
655
656
657
658
 
# File 'ext/rubysl/readline/readline.c', line 646

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

    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.



385
386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'ext/rubysl/readline/readline.c', line 385

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);
#ifdef HAVE_RL_GETC_FUNCTION
    readline_instream = input;
#endif
    return input;
}

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

Returns:

  • (String) 


509
510
511
512
513
514
515
516
 
# File 'ext/rubysl/readline/readline.c', line 509

static VALUE
readline_s_get_line_buffer(VALUE self)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.



409
410
411
412
413
414
415
416
417
418
419
 
# File 'ext/rubysl/readline/readline.c', line 409

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?

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.

  1. stdin is not tty.

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

Returns:

  • (String, nil) 


319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'ext/rubysl/readline/readline.c', line 319

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);
#if USE_INSERT_IGNORE_ESCAPE
	tmp = insert_ignore_escape(self, tmp);
	rb_str_locktmp(tmp);
#endif
	prompt = RSTRING_PTR(tmp);
    }

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

#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*/
        rl_free_line_state();
        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;
}

.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

Returns:

  • (Integer) 


535
536
537
538
539
540
 
# File 'ext/rubysl/readline/readline.c', line 535

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

.refresh_line ⇒ nil

Clear the current input line.

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (nil) 


1151
1152
1153
1154
1155
1156
1157
 
# File 'ext/rubysl/readline/readline.c', line 1151

static VALUE
readline_s_refresh_line(VALUE self)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (self) 


622
623
624
625
626
627
628
 
# File 'ext/rubysl/readline/readline.c', line 622

static VALUE
readline_s_set_screen_size(VALUE self, VALUE rows, VALUE columns)
{
    rb_secure(4);
    rl_set_screen_size(NUM2INT(rows), NUM2INT(columns));
    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.

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (nil) 


675
676
677
678
679
680
681
 
# File 'ext/rubysl/readline/readline.c', line 675

static VALUE
readline_s_vi_editing_mode(VALUE self)
{
    rb_secure(4);
    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.

Raises SecurityError exception if $SAFE is 4.

Returns:

  • (Boolean) 


697
698
699
700
701
702
 
# File 'ext/rubysl/readline/readline.c', line 697

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