Module: Linenoise

Defined in:
ext/linenoise/linenoise.c,
lib/linenoise/version.rb,
ext/linenoise/linenoise.c

Overview

The Linenoise module provides interface for the Linenoise library, which is a Readline replacement used in Redis, MongoDB, and Android.

This module defines a number of methods to facilitate completion and accesses input history from the Ruby interpreter.

Linenoise

github.com/antirez/linenoise

Reads one inputted line with line edit via the Linenoise.linenoise method.

require 'linenoise'

while buf = Linenoise.linenoise('> ')
  p buf
end

User input can be persisted via the history feature. The history can be accessed through the HISTORY constant.

require 'linenoise'

while buf = Linenoise.linenoise('> ')
  p Linenoise::HISTORY.to_a
  print('-> ', buf, '\n')
end

Using history

History can be accessed through HISTORY. It can be saved to a file, or loaded from a file.

Adding lines to the history

Linenoise::HISTORY << '1 + 1'

# Or push multiple items.
Linenoise::HISTORY.push('2', '3')
Linenoise::HISTORY.size
#=> 3

Iterating lines & accessing individual entries

# Read a line at given index.
Linenoise::HISTORY[0]
#=> '1 + 1'

# Replace a line in the history with another one.
Linenoise::HISTORY[0] = 'begin'
Linenoise::HISTORY[0]
#=> 'begin'

# Iterate over lines like an array (HISTORY is enumerable).
Linenoise::HISTORY.each { |line| puts line }

Saving & loading

# Save to file.
Linenoise::HISTORY.save('linenoise_history')

# Load from file.
Linenoise::HISTORY.load('linenoise_history')

# Wipe out current history (doesn't delete the file).
Linenoise::HISTORY.clear
Linenoise::HISTORY.size
#=> 0

Setting maximum size of history

# The cap sets how many entries history can hold. When the capacity is
# exceeded, older entries are removed.
Linenoise::HISTORY.max_size = 3

Constant Summary collapse

GEM_VERSION = 
'1.1.0'.freeze
VERSION =

Version string of Linenoise.

rb_str_new_cstr("1.0")
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
DEFAULT =

Hint color helpers

Qnil
RED = 
INT2NUM(red)
GREEN = 
INT2NUM(green)
YELLOW = 
INT2NUM(yellow)
BLUE = 
INT2NUM(blue)
MAGENTA = 
INT2NUM(magenta)
CYAN = 
INT2NUM(cyan)
WHITE = 
INT2NUM(white)

Class Method Summary collapse

Class Method Details

.clear_screen ⇒ self

Clears screen from characters.

Returns:

  • (self) 


388
389
390
391
392
393
 
# File 'ext/linenoise/linenoise.c', line 388

static VALUE
linenoise_clear_screen(VALUE self)
{
    linenoiseClearScreen();
    return self;
}

.completion_proc ⇒ Proc

Returns the completion Proc object.

Returns:

  • (Proc) 


197
198
199
200
201
 
# File 'ext/linenoise/linenoise.c', line 197

static VALUE
linenoise_get_completion_proc(VALUE self)
{
    return rb_attr_get(mLinenoise, 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.

require 'linenoise'

LIST = %w[
  search download open help history quit url next clear prev past
].freeze

Linenoise.completion_proc = proc do |input|
  LIST.grep(/\A#{Regexp.escape(input)}/)
end

while line = Linenoise.linenoise('> ')
  p line
end

Raises:

  • ArgumentError if proc is not a Proc



183
184
185
186
187
188
189
 
# File 'ext/linenoise/linenoise.c', line 183

static VALUE
linenoise_set_completion_proc(VALUE self, VALUE proc)
{
    mustbe_callable(proc);
    linenoiseSetCompletionCallback(linenoise_attempted_completion_function);
    return rb_ivar_set(mLinenoise, completion_proc, proc);
}

.hint_bold=(bool) ⇒ Boolean

Sets hint boldness. false means normal text, true means bold. Defults to false.

Linenoise.hint_bold = true

Returns:

  • (Boolean) 


363
364
365
366
367
368
 
# File 'ext/linenoise/linenoise.c', line 363

static VALUE
linenoise_set_hint_boldness(VALUE self, VALUE boldness)
{
    hint_boldness = boldness;
    return rb_ivar_set(mLinenoise, id_hint_bold, boldness);
}

.hint_bold? ⇒ Boolean

Checks if the hint font is bold.

Returns:

  • (Boolean) 


376
377
378
379
380
 
# File 'ext/linenoise/linenoise.c', line 376

static VALUE
linenoise_get_hint_boldness(VALUE self)
{
    return rb_attr_get(mLinenoise, id_hint_bold);
}

.hint_color ⇒ Integer

Checks hint font color.

Returns:

  • (Integer) 


348
349
350
351
352
 
# File 'ext/linenoise/linenoise.c', line 348

static VALUE
linenoise_get_hint_color(VALUE self)
{
    return rb_attr_get(mLinenoise, id_hint_color);
}

.hint_color=(Integer) ⇒ Integer

Sets the hint color. Allowed values are in a range from 31 to 37. Setting this option to 0 removes the color and uses the default font color.

There are convenience constants for setting colors:

# Make the hint red.
Linenoise.hint_color = Linenoise::RED

# Remove the color.
Linenoise.hint_color = Linenoise::DEFAULT

Returns:

  • (Integer)

Raises:

  • TypeError if color is not an Integer

  • ArgumentError if color is not 0 or in range of 31-37



318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'ext/linenoise/linenoise.c', line 318

static VALUE
linenoise_set_hint_color(VALUE self, VALUE color)
{
    int c = 0;

    switch (TYPE(color)) {
      case T_NIL:
        break;
      case T_FIXNUM:
        c = NUM2INT(color);
        break;
      default:
        rb_raise(rb_eTypeError, "hint color is not an Integer");
    }

    if (c == 0 || (c >= 31 && c <= 37)) {
        hint_color = c;
    }
    else
        rb_raise(rb_eArgError, "color '%d' is not in range (31-37)", c);

    return rb_ivar_set(mLinenoise, id_hint_color, color);
}

.hint_proc ⇒ Proc

Returns the hint Proc object.

Returns:

  • (Proc) 


294
295
296
297
298
 
# File 'ext/linenoise/linenoise.c', line 294

static VALUE
linenoise_get_hint_proc(VALUE self)
{
    return rb_attr_get(mLinenoise, hint_proc);
}

.hint_proc=(proc) ⇒ Object

Specifies a Proc object proc to determine hint behavior. It should take input string and return the completion according to the input.

require 'linenoise'

Linenoise.hint_proc = proc do |input|
  case input
  when /git show/
    ' [<options>] [<object>...]'
  when /git log/
    ' [<options>] [<revision range>]'
  else
    ' --help'
  end
end

while line = Linenoise.linenoise('> ')
  p line
end

Raises:

  • ArgumentError if proc is not a Proc



280
281
282
283
284
285
286
 
# File 'ext/linenoise/linenoise.c', line 280

static VALUE
linenoise_set_hint_proc(VALUE self, VALUE proc)
{
    mustbe_callable(proc);
    linenoiseSetHintsCallback(linenoise_attempted_hint_function);
    return rb_ivar_set(mLinenoise, hint_proc, proc);
}

.linenoise(prompt) ⇒ String?

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

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

Aliased as readline for easier integration with Readline-enabled apps.

Returns:

  • (String, nil) 


113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'ext/linenoise/linenoise.c', line 113

static VALUE
linenoise_linenoise(VALUE self, VALUE prompt)
{
    VALUE result;
    char *line;

    line = linenoise(StringValueCStr(prompt));
    if (line) {
        result = rb_locale_str_new_cstr(line);
    }
    else
        result = Qnil;
    if (line) free(line);

    return result;
}

.multiline=(bool) ⇒ Boolean

Specifies multiline mode. By default, Linenoise uses single line editing, that is, a single row on the screen will be used, and as the user types more, the text will scroll towards left to make room.

Returns:

  • (Boolean) 


211
212
213
214
215
216
217
218
 
# File 'ext/linenoise/linenoise.c', line 211

static VALUE
linenoise_set_multiline(VALUE self, VALUE vbool)
{
    int i = RTEST(vbool) ? 1 : 0;
    rb_ivar_set(mLinenoise, id_multiline, vbool);
    linenoiseSetMultiLine(i);
    return vbool;
}

.multiline? ⇒ Boolean

Checks if multiline mode is enabled.

Returns:

  • (Boolean) 


226
227
228
229
230
 
# File 'ext/linenoise/linenoise.c', line 226

static VALUE
linenoise_get_multiline(VALUE self)
{
    return rb_attr_get(mLinenoise, id_multiline);
}