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_screenself

Clears screen from characters.


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

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

.completion_procProc

Returns the completion Proc object.


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

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.


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_colorInteger

Checks hint font color.


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

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_procProc

Returns the hint Proc object.


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.


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.


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.


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);
}