module Readline

readline.rb – GNU Readline module Copyright (C) 1997-2001 Shugo Maeda

Ruby translation by Park Heesob phasis@gmail.com

Constants

FILENAME_COMPLETION_PROC

The Fcomp class provided to encapsulate typical filename completion procedure. You will not typically use this directly, but will instead use the Readline::FILENAME_COMPLETION_PROC.

HISTORY

The History class encapsulates a history of all commands entered by users at the prompt, providing an interface for inspection and retrieval of all commands.

USERNAME_COMPLETION_PROC

The Ucomp class provided to encapsulate typical filename completion procedure. You will not typically use this directly, but will instead use the Readline::USERNAME_COMPLETION_PROC.

Note that this feature currently only works on Unix systems since it ultimately uses the Etc module to iterate over a list of users.

VERSION

Public Class Methods

basic_quote_characters() click to toggle source

Returns the list of quote characters that can cause a word break. The default is “'"” (single and double quote characters).

# File lib/readline.rb, line 268
def self.basic_quote_characters()
  if RbReadline.rl_basic_quote_characters.nil?
    nil
  else
    RbReadline.rl_basic_quote_characters.dup
  end
end
basic_quote_characters=(str) click to toggle source

Sets the list of quote characters that can cause a word break.

# File lib/readline.rb, line 261
def self.basic_quote_characters=(str)
  RbReadline.rl_basic_quote_characters = str.dup
end
basic_word_break_characters() click to toggle source

Returns the character string that signal a break between words for the completion proc. The default is “ tn"\'`@$><=|&{(”.

# File lib/readline.rb, line 233
def self.basic_word_break_characters()
  if RbReadline.rl_basic_word_break_characters.nil?
    nil
  else
    RbReadline.rl_basic_word_break_characters.dup
  end
end
basic_word_break_characters=(str) click to toggle source

Sets the character string that signal a break between words for the completion proc.

# File lib/readline.rb, line 226
def self.basic_word_break_characters=(str)
  RbReadline.rl_basic_word_break_characters = str.dup
end
completer_quote_characters() click to toggle source

Returns the list of characters that can be used to quote a substring of the line, i.e. a group of characters inside quotes.

# File lib/readline.rb, line 286
def self.completer_quote_characters()
  if RbReadline.rl_completer_quote_characters.nil?
    nil
  else
    RbReadline.rl_completer_quote_characters.dup
  end
end
completer_quote_characters=(str) click to toggle source

Sets the list of characters that can be used to quote a substring of the line, i.e. a group of characters within quotes.

# File lib/readline.rb, line 279
def self.completer_quote_characters=(str)
  RbReadline.rl_completer_quote_characters = str.dup
end
completer_word_break_characters() click to toggle source

Returns the character string that signal the start or end of a word for the completion proc.

# File lib/readline.rb, line 251
def self.completer_word_break_characters()
  if RbReadline.rl_completer_word_break_characters.nil?
    nil
  else
    RbReadline.rl_completer_word_break_characters.dup
  end
end
completer_word_break_characters=(str) click to toggle source

Sets the character string that signal the start or end of a word for the completion proc.

# File lib/readline.rb, line 244
def self.completer_word_break_characters=(str)
  RbReadline.rl_completer_word_break_characters = str.dup
end
completion_append_character() click to toggle source

Returns the character that is automatically appended after the ::completion_proc method is called.

# File lib/readline.rb, line 216
def self.completion_append_character()
  if RbReadline.rl_completion_append_character == ?\0
    return nil
  end
  return RbReadline.rl_completion_append_character
end
completion_append_character=(char) click to toggle source

Sets the character that is automatically appended after the ::completion_proc method is called.

If char is nil or empty, then a null character is used.

# File lib/readline.rb, line 203
def self.completion_append_character=(char)
  if char.nil?
    RbReadline.rl_completion_append_character = ?\0
  elsif char.length==0
    RbReadline.rl_completion_append_character = ?\0
  else
    RbReadline.rl_completion_append_character = char[0].chr
  end
end
completion_case_fold() click to toggle source

Returns whether or not the completion proc is case sensitive. The default is false, i.e. completion procs are case sensitive.

# File lib/readline.rb, line 113
def self.completion_case_fold()
  @completion_case_fold
end
completion_case_fold=(bool) click to toggle source

Sets whether or not the completion proc should ignore case sensitivity. The default is false, i.e. completion procs are case sensitive.

# File lib/readline.rb, line 106
def self.completion_case_fold=(bool)
  @completion_case_fold = bool
end
completion_proc() click to toggle source

Returns the current auto-completion procedure.

# File lib/readline.rb, line 99
def self.completion_proc()
  @completion_proc
end
completion_proc=(proc) click to toggle source

Sets the auto-completion procedure (i.e. tab auto-complete).

The proc argument is typically a Proc object. It must respond to .call, take a single String argument and return an Array of candidates for completion.

Example:

list = ['search', 'next', 'clear']
Readline.completion_proc = proc{ |s| list.grep( /^#{Regexp.escape(s)}/) }
# File lib/readline.rb, line 90
def self.completion_proc=(proc)
  unless proc.respond_to? :call
    raise ArgumentError,"argument must respond to `call'"
  end
  @completion_proc = proc
end
emacs_editing_mode() click to toggle source

Sets emacs editing mode

# File lib/readline.rb, line 193
def self.emacs_editing_mode()
  RbReadline.rl_emacs_editing_mode(1,0)
  nil
end
filename_quote_characters() click to toggle source

Returns the character string used to indicate quotes for the filename completion of user input.

# File lib/readline.rb, line 304
def self.filename_quote_characters()
  if RbReadline.rl_filename_quote_characters.nil?
    nil
  else
    RbReadline.rl_filename_quote_characters.dup
  end
end
filename_quote_characters=(str) click to toggle source

Sets the character string of one or more characters that indicate quotes for the filename completion of user input.

# File lib/readline.rb, line 297
def self.filename_quote_characters=(str)
  RbReadline.rl_filename_quote_characters = str.dup
end
input=(input) click to toggle source

Sets the input stream (an IO object) for readline interaction. The default is $stdin.

# File lib/readline.rb, line 62
def self.input=(input)
  RbReadline.rl_instream = input
end
line_buffer() click to toggle source

Returns current line buffer

# File lib/readline.rb, line 75
def self.line_buffer
  RbReadline.rl_line_buffer
end
output=(output) click to toggle source

Sets the output stream (an IO object) for readline interaction. The default is $stdout.

# File lib/readline.rb, line 69
def self.output=(output)
  RbReadline.rl_outstream = output
end
point() click to toggle source

Returns the current offset in the current input line.

# File lib/readline.rb, line 314
def self.point()
  RbReadline.rl_point
end
readline(prompt = "", add_history = nil) click to toggle source

Begins an interactive terminal process using prompt as the command prompt that users see when they type commands. The method returns the line entered whenever a carriage return is encountered.

If an add_history argument is provided, commands entered by users are stored in a history buffer that can be recalled for later use.

Note that this method depends on $stdin and $stdout both being open. Because this is meant as an interactive console interface, they should generally not be redirected.

If you would like to add non-visible characters to the the prompt (for example to add colors) you must prepend the character 001 (^A) before each sequence of non-visible characters and add the character 002 (^B) after, otherwise line wrapping may not work properly.

Example:

loop{ Readline.readline('> ') }
# File lib/readline.rb, line 35
def readline(prompt = "", add_history = nil)
  if $stdin.closed?
    raise IOError, "stdin closed"
  end

  RbReadline.rl_instream = $stdin
  RbReadline.rl_outstream = $stdout

  begin
    buff = RbReadline.readline(prompt)
  rescue Exception => e
    buff = nil
    RbReadline.rl_cleanup_after_signal()
    RbReadline.rl_deprep_terminal()
    raise e
  end

  if add_history && buff
    RbReadline.add_history(buff)
  end

  return buff ? buff.dup : nil
end
readline_attempted_completion_function(text,start,_end) click to toggle source

Returns nil if no matches are found or an array of strings:

[0] is the replacement for text
[1..n] the possible matches
[n+1] nil

The possible matches should not include [0].

If this method sets RbReadline#rl_attempted_completion_over to true, then the default completion function will not be called when this function returns nil.

# File lib/readline.rb, line 128
def self.readline_attempted_completion_function(text,start,_end)
  proc = @completion_proc
  return nil if proc.nil?

  RbReadline.rl_attempted_completion_over = true

  case_fold = @completion_case_fold
  ary = proc.call(text)
  if ary.class != Array
    ary = Array(ary)
  else
    ary.compact!
  end

  matches = ary.length
  return nil if (matches == 0)
  result = Array.new(matches+2)
  for i in 0 ... matches
    result[i+1] = ary[i].dup
  end
  result[matches+1] = nil

  if(matches==1)
    result[0] = result[1].dup
    result[1] = nil
  else
    i = 1
    low = 100000

    while (i < matches)
      if (case_fold)
        si = 0
        while ((c1 = result[i][si,1].downcase) &&
               (c2 = result[i + 1][si,1].downcase))
          break if (c1 != c2)
          si += 1
        end
      else
        si = 0
        while ((c1 = result[i][si,1]) &&
               (c2 = result[i + 1][si,1]))
          break if (c1 != c2)
          si += 1
        end
      end
      if (low > si)
        low = si
      end
      i+=1
    end
    result[0] = result[1][0,low]
  end

  result
end
vi_editing_mode() click to toggle source

Sets vi editing mode.

# File lib/readline.rb, line 186
def self.vi_editing_mode()
  RbReadline.rl_vi_editing_mode(1,0)
  nil
end

Private Instance Methods

readline(prompt = "", add_history = nil) click to toggle source

Begins an interactive terminal process using prompt as the command prompt that users see when they type commands. The method returns the line entered whenever a carriage return is encountered.

If an add_history argument is provided, commands entered by users are stored in a history buffer that can be recalled for later use.

Note that this method depends on $stdin and $stdout both being open. Because this is meant as an interactive console interface, they should generally not be redirected.

If you would like to add non-visible characters to the the prompt (for example to add colors) you must prepend the character 001 (^A) before each sequence of non-visible characters and add the character 002 (^B) after, otherwise line wrapping may not work properly.

Example:

loop{ Readline.readline('> ') }
# File lib/readline.rb, line 35
def readline(prompt = "", add_history = nil)
  if $stdin.closed?
    raise IOError, "stdin closed"
  end

  RbReadline.rl_instream = $stdin
  RbReadline.rl_outstream = $stdout

  begin
    buff = RbReadline.readline(prompt)
  rescue Exception => e
    buff = nil
    RbReadline.rl_cleanup_after_signal()
    RbReadline.rl_deprep_terminal()
    raise e
  end

  if add_history && buff
    RbReadline.add_history(buff)
  end

  return buff ? buff.dup : nil
end