Class: Rink::Console

Inherits:
Object show all
Extended by:
Delegation
Includes:
IOMethods
Defined in:
lib/rink/console.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Delegation

delegate

Methods included from IOMethods

#setup_input_method, #setup_output_method

Constructor Details

#initialize(options = {}) ⇒ Console

One caveat: if you override #initialize, make sure to do as much setup as possible before calling super – or, call super with :defer => true – because otherwise Rink will start the console before your init code executes.



12
13
14
15
16
17
 
# File 'lib/rink/console.rb', line 12

def initialize(options = {})
  options = default_options.merge(options)
  @namespace = Rink::Namespace.new
  apply_options(options)
  run(options) unless options[:defer]
end

Instance Attribute Details

#input ⇒ Object (readonly)

Returns the value of attribute input.



6
7
8
 
# File 'lib/rink/console.rb', line 6

def input
  @input
end

#line_processor ⇒ Object (readonly)

Returns the value of attribute line_processor.



4
5
6
 
# File 'lib/rink/console.rb', line 4

def line_processor
  @line_processor
end

#output ⇒ Object (readonly)

Returns the value of attribute output.



6
7
8
 
# File 'lib/rink/console.rb', line 6

def output
  @output
end

#silenced=(value) ⇒ Object (writeonly)

Sets the attribute silenced

Parameters:

  • value —

    the value to set the attribute silenced to.



5
6
7
 
# File 'lib/rink/console.rb', line 5

def silenced=(value)
  @silenced = value
end

Class Method Details

Sets or returns the banner displayed when the console is started.



122
123
124
125
126
127
128
 
# File 'lib/rink/console.rb', line 122

def banner(msg = nil)
  if msg.nil?
    @banner ||= ">> Interactive Console <<"
  else
    @banner = msg
  end
end

.command(name, case_sensitive = false, &block) ⇒ Object

Adds a custom command to the console. When the command is typed, a custom block of code will fire. The command may contain spaces. Any words following the command will be sent to the block as an array of arguments.



154
155
156
 
# File 'lib/rink/console.rb', line 154

def command(name, case_sensitive = false, &block)
  commands[name.to_s] = { :case_sensitive => case_sensitive, :block => block }
end

.commands ⇒ Object

Returns a hash containing all registered commands.



159
160
161
 
# File 'lib/rink/console.rb', line 159

def commands
  @commands ||= {}
end

.default_options ⇒ Object

Default options are:

:processor => Rink::LineProcessor::PureRuby.new(self),
:output => STDOUT,
:input  => STDIN,
:banner => true,             # if false, Rink won't show a banner.
:silent => false,            # if true, Rink won't produce output.
:rescue_errors => true       # if false, Rink won't catch errors.
:defer => false              # if true, Rink won't automatically wait for input.
:allow_ruby => true          # if false, Rink won't execute unmatched commands as Ruby code.



172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/rink/console.rb', line 172

def default_options
  @default_options ||= {
    :output => STDOUT,
    :input  => STDIN,
    :banner => true,
    :silent => false,
    :processor => Rink::LineProcessor::PureRuby.new(self),
    :rescue_errors => true,
    :defer => false,
    :allow_ruby => true,
  }
end

.option(options) ⇒ Object

Sets or overrides a default option.

Example:

class MyConsole < Rink::Console
  option :allow_ruby => false, :greeting => "Hi there!"
end



138
139
140
 
# File 'lib/rink/console.rb', line 138

def option(options)
  default_options.merge! options
end

.prompt(msg = nil) ⇒ Object

Sets or returns the prompt for this console.



143
144
145
146
147
148
149
 
# File 'lib/rink/console.rb', line 143

def prompt(msg = nil)
  if msg.nil?
    @prompt ||= "#{name} > "
  else
    @prompt = msg
  end
end

Instance Method Details

#apply_options(options) ⇒ Object

Applies a new set of options. Options that are currently unset or nil will not be modified.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/rink/console.rb', line 86

def apply_options(options)
  return unless options
  
  options.each do |key, value|
    options[key] = value.call if value.kind_of?(Proc)
  end
  @_options ||= {}
  @_options.merge! options
  @input  = setup_input_method(options[:input] || @input)
  @output = setup_output_method(options[:output] || @output)
  @output.silenced = options.key?(:silent) ? options[:silent] : !@output || @output.silenced?
  @line_processor = options[:processor] || options[:line_processor] || @line_processor
  @allow_ruby = options.key?(:allow_ruby) ? options[:allow_ruby] : @allow_ruby

  if options[:namespace]
    ns = options[:namespace] == :self ? self : options[:namespace]
    @namespace.replace(ns)
  end
  
  if @input
    @input.output = @output
    @input.prompt = prompt
    if @input.respond_to?(:completion_proc)
      @input.completion_proc = proc { |line| autocomplete(line) }
    end
  end
end

#gather_options ⇒ Object Also known as: options

Returns the current set of options.



115
116
117
 
# File 'lib/rink/console.rb', line 115

def gather_options
  @_options
end

#namespace ⇒ Object

The Ruby object within whose context the console will be run. For example:

class CustomNamespace
  def save_the_world
    'maybe later'
  end
end

Rink::Console.new(:namespace => CustomNamespace.new)
# ...
Rink::Console > save_the_world
=> "maybe later"

This is most useful if you have an object with a lot of methods that you wish to treat as console commands. Also, it segregates the user from the Rink::Console instance, preventing them from making any changes to it.

Note that you can set a console’s namespace to itself if you want the user to have access to it:

Rink::Console.new(:namespace => :self)



44
45
46
 
# File 'lib/rink/console.rb', line 44

def namespace
  @namespace.ns
end

#namespace=(ns) ⇒ Object 



19
20
21
 
# File 'lib/rink/console.rb', line 19

def namespace=(ns)
  @namespace.replace(ns)
end

#run(input = {}, options = {}) ⇒ Object

Runs a series of commands in the context of this Console. Input can be either a string or an input stream. Other options include:

:input     => a string or an input stream
:output    => a string or an output stream.
:banner    => boolean: whether to print a welcome banner.
:silent    => boolean: whether to print any output at all.
:namespace => any object (other than nil). Will be used as the default namespace.

Note also that any value can be a proc. In this case, the proc will be called while applying the options and the return value of that proc will be used. This is useful for lazy loading a value or for setting options based on some condition.



61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/rink/console.rb', line 61

def run(input = {}, options = {})
  if input.kind_of?(Hash)
    options = options.merge(input)
  else
    options.merge! :input => input
  end
  
  temporary_options(options) do
    puts banner if options.key?(:banner) ? options[:banner] : default_options[:banner]
    enter_input_loop
  end
end

#temporary_options(options) ⇒ Object

runs a block of code with the specified options set, and then sets them back to their previous state. Options that are nil or not specified will be inherited from the previous state; and options in the previous state that are nil or not specified will not be reverted.



77
78
79
80
81
82
83
 
# File 'lib/rink/console.rb', line 77

def temporary_options(options)
  old_options = gather_options
  apply_options(options)
  yield
ensure
  apply_options(old_options)
end