Class: Shell

Inherits:
Gloo::Core::Obj
  • Object
show all
Defined in:
lib/shell.rb

Overview

Author

Eric Crane (mailto:eric.crane@mac.com)

Copyright

Copyright (c) 2026 Eric Crane. All rights reserved.

A CLI shell.

Constant Summary collapse

KEYWORD = 
'shell'.freeze
KEYWORD_SHORT = 
'shell'.freeze
PROMPT = 
'prompt'.freeze
DEFAULT_ACTION = 
'default_action'.freeze
INCLUDE_QUIT = 
'include_quit'.freeze
ON_ERROR = 
'on_error'.freeze
ON_UNKNOWN_CMD = 
'on_unknown_command'.freeze
ON_EMPTY_CMD = 
'on_empty_command'.freeze
BEFORE_ACTION = 
'before_action'.freeze
AFTER_ACTION = 
'after_action'.freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.doc_data ⇒ Object

Get the object's documentation data.



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/shell.rb', line 223

def self.doc_data
  {
    :name => KEYWORD,
    :shortcut => KEYWORD_SHORT,
    :description => 'A CLI shell — an interactive command-driven ' \
      'REPL, or a one-shot command executor when the app is invoked ' \
      'with extra command-line arguments. Build up the command tree ' \
      'by adding command objects (see the command object type) that ' \
      'register themselves with this shell.',
    :children => [
      "prompt (string) — Default: '> '. The prompt shown at each turn of the REPL.",
      'default_action (script) — Run when the user presses RETURN with no input.',
      'include_quit (boolean) — Optional. If true, a built-in quit command is added automatically.',
      'on_error (script) — Optional. Run when a command raises an error.',
      "on_unknown_command (script) — Optional. Run when the input doesn't match any known command; if absent, a default \"Unknown command\" message is shown instead.",
      'on_empty_command (script) — Optional. Run when the user submits an empty line.',
      'before_action (script) — Optional. Run before every command executes.',
      'after_action (script) — Optional. Run after every command executes.'
    ],
    :messages => [
      'start — Start the shell. If the app was invoked with extra command-line arguments, execute that one command and return; otherwise enter the interactive REPL.',
      'stop — Stop a running shell.'
    ],
    :notes => 'No vault documentation exists for this object type — ' \
      'this was authored directly from the code. Commands attach to ' \
      'a shell either by declaring a command object as a child and ' \
      'sending it the register message with this shell\'s path, or ' \
      'by calling add_command directly. The underlying tree/REPL ' \
      'engine here was later ported into dev/gloo itself (as ' \
      'Gloo::Shell::Runner) to power the interactive help shell.'
  }
end

.messages ⇒ Object

Get a list of message names that this object receives.



88
89
90
 
# File 'lib/shell.rb', line 88

def self.messages
  return super + [ 'start', 'stop' ]
end

.short_typename ⇒ Object

The short name of the object type.



30
31
32
 
# File 'lib/shell.rb', line 30

def self.short_typename
  return KEYWORD_SHORT
end

.typename ⇒ Object

The name of the object type.



23
24
25
 
# File 'lib/shell.rb', line 23

def self.typename
  return KEYWORD
end

Instance Method Details

#add_children_on_create? ⇒ Boolean

Does this object have children to add when an object is created in interactive mode? This does not apply during obj load, etc.

Returns:

  • (Boolean) 


65
66
67
 
# File 'lib/shell.rb', line 65

def add_children_on_create?
  return true
end

#add_command(obj, command_data) ⇒ Object

Add a command to the shell.



128
129
130
131
 
# File 'lib/shell.rb', line 128

def add_command obj, command_data
  runner = get_runner
  runner.add_command_node( command_data )
end

#add_default_children ⇒ Object

Add children to this object. This is used by containers to add children needed for default configurations.



74
75
76
77
78
 
# File 'lib/shell.rb', line 74

def add_default_children
  fac = @engine.factory
  fac.create_string PROMPT, '> ', self
  fac.create_script DEFAULT_ACTION, '', self
end

#add_quit_command ⇒ Object

Quit the shell.



206
207
208
209
210
211
212
213
214
 
# File 'lib/shell.rb', line 206

def add_quit_command
  return unless include_quit?

  @runner.add_command_node({
    name: "quit",
    description: "Quit the application",
    method: "cmd_quit"
  })
end

#get_runner ⇒ Object

Get the shell runner or initialize it if it doesn't exist.



95
96
97
 
# File 'lib/shell.rb', line 95

def get_runner
  return @runner ||= ShellRunner.new( @engine, self )
end

#include_quit? ⇒ Boolean

Get the value of the include_quit child object. Returns false if there is none.

Returns:

  • (Boolean) 


49
50
51
52
53
 
# File 'lib/shell.rb', line 49

def include_quit?
  o = find_child INCLUDE_QUIT
  return o.value if o
  return false
end

#msg_start ⇒ Object

Start the shell. If CLI args were passed, execute that command once and return. Otherwise, enter the interactive REPL.



104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/shell.rb', line 104

def msg_start
  runner = get_runner

  # add_test_commands
  add_quit_command

  cmd_tokens = @engine.args.files
  if cmd_tokens.any?
    runner.execute_once( cmd_tokens )
  else
    runner.start
  end
end

#msg_stop ⇒ Object

Stop the shell.



121
122
123
 
# File 'lib/shell.rb', line 121

def msg_stop
  @runner.stop if @runner
end

#prompt ⇒ Object

Get the value of the prompt child object. Returns nil if there is none.



38
39
40
41
42
43
 
# File 'lib/shell.rb', line 38

def prompt
  o = find_child PROMPT
  return '' unless o

  return o.value
end

#run_after_action ⇒ Object

Run the after_action script if one exists.



191
192
193
194
195
196
 
# File 'lib/shell.rb', line 191

def run_after_action
  o = find_child AFTER_ACTION
  return unless o

  Gloo::Exec::Dispatch.message( @engine, 'run', o )
end

#run_before_action ⇒ Object

Run the before_action script if one exists.



181
182
183
184
185
186
 
# File 'lib/shell.rb', line 181

def run_before_action
  o = find_child BEFORE_ACTION
  return unless o

  Gloo::Exec::Dispatch.message( @engine, 'run', o )
end

#run_on_empty_cmd ⇒ Object

Run the on_empty_command script if one exists. Returns true if the script was found and run, false otherwise.



170
171
172
173
174
175
176
 
# File 'lib/shell.rb', line 170

def run_on_empty_cmd
  o = find_child ON_EMPTY_CMD
  return false unless o

  Gloo::Exec::Dispatch.message( @engine, 'run', o )
  return true
end

#run_on_error ⇒ Object

Run the on_error script if one exists. Returns true if the script was found and run, false otherwise.



146
147
148
149
150
151
152
 
# File 'lib/shell.rb', line 146

def run_on_error
  o = find_child ON_ERROR
  return false unless o

  Gloo::Exec::Dispatch.message( @engine, 'run', o )
  return true
end

#run_on_unknown_cmd ⇒ Object

Run the on_unknown_cmd script if one exists. Returns true if the script was found and run, false otherwise.



158
159
160
161
162
163
164
 
# File 'lib/shell.rb', line 158

def run_on_unknown_cmd
  o = find_child ON_UNKNOWN_CMD
  return false unless o

  Gloo::Exec::Dispatch.message( @engine, 'run', o )
  return true
end

#set_context(key, value) ⇒ Object

Context



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

def set_context key, value
  @runner.set_context( key, value )
end