gloo-cli 1.8 → 2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c20054e5d495fde4abf0d067fd09015b02af2de350075834b2f58914f54be0d1
-  data.tar.gz: e363c1996f92d4718b75ed1176ea640a4484efb08cc91737337f8fdd80e65ec0
+  metadata.gz: 26757505cf53f7adb80263e1e9eb6434b4296ddcde50f431b9100ad585c140b5
+  data.tar.gz: d8f910b22f8e47b082069d5fefedb90d16750eb507b10639ec157afc7e76a4c9
 SHA512:
-  metadata.gz: 90750e252eb055d6378177d2b22cdaac0eb57c1171128f341c37f40b603f7e5231a11cbe4463b9bf145d8a2fecc37a929ef7dcad788cfeee06772ee089e4ab47
-  data.tar.gz: 0d0ddc595fdd62f09ce591e7167df8542ee22eb3dbb97990ed5c3e556c99f52d360f935ae96489744feb906d02f1ba5e51ce32c44cc9d613c8f1722590edd1a9
+  metadata.gz: 0123e410939777c02628748c972d912ef508986d6c4d0e7f4501d7a888e245af572806f96099635ba3702c140491773e29f26e0fdf66671563824c2d23034324
+  data.tar.gz: 26abd327ed5bc25ecb7b608b80b315e044dbb0eb3f6e8a17b3bb28982cb93f8dfbcc183285d78496a803950748bd313d792b803031f797c6f24aa623e95438d5

data/lib/cli_colorize.rb

@@ -55,12 +55,19 @@ class CliColorize < Gloo::Core::Obj
   end
 
   #
-  # Run the colorize command.
+  # Run the colorize command: show the line and put it in it.
+  # A child whose name isn't a color is shown uncolored, with a warning.
   #
   def msg_run
     msg = ''
     children.each do |o|
-      msg += ColorizedString[ o.value_display ].colorize( o.name.to_sym )
+      color = o.name.to_sym
+      if ColorizedString.colors.include?( color )
+        msg += ColorizedString[ o.value_display ].colorize( color )
+      else
+        @engine.warn "Unknown color '#{o.name}' in colorize '#{name}'; shown uncolored."
+        msg += o.value_display.to_s
+      end
     end
     @engine.log.show msg
     @engine.heap.it.set_to msg.to_s
@@ -82,10 +89,10 @@ class CliColorize < Gloo::Core::Obj
         'strings, each one can have a different color as specified by ' \
         'the names of the children.',
       :children => [
-        '[color] (string) — The name of the child or children is the color. The string\'s value is what will be written out.'
+        '[color] (string) — The name of the child or children is the color. The string\'s value is what will be written out. A name that isn\'t a color is written uncolored, with a warning.'
       ],
       :messages => [
-        'run — Output the string in the color specified.'
+        'run — Output the string in the color specified, and put the line in it.'
       ],
       :examples => <<~EXAMPLES.strip
         color [can] :

data/lib/cli_confirm.rb

@@ -27,24 +27,21 @@ class CliConfirm < Gloo::Core::Obj
   end
 
   #
-  # Get the URI from the child object.
-  # Returns nil if there is none.
+  # Get the prompt from the child object.
+  # The default prompt if there is none.
   #
   def prompt_value
     o = find_child PROMPT
-    return nil unless o
-
-    return o.value
+    return o ? o.value : DEFAULT_PROMPT
   end
 
   #
-  # Set the result of the system call.
+  # Set the result to the answer, and put it in it.
+  # The answer is kept even if there is no result child.
   #
   def set_result( data )
-    r = find_child RESULT
-    return nil unless r
-
-    r.set_value data
+    find_child( RESULT )&.set_value data
+    @engine.heap.it.set_to data
   end
 
   # ---------------------------------------------------------------------
@@ -83,8 +80,6 @@ class CliConfirm < Gloo::Core::Obj
   #
   def msg_run
     prompt = prompt_value
-    return unless prompt
-
     result = @engine.platform.prompt.yes?( prompt )
     set_result result
   end
@@ -102,11 +97,11 @@ class CliConfirm < Gloo::Core::Obj
       :shortcut => KEYWORD_SHORT,
       :description => 'CLI confirmation prompt.',
       :children => [
-        "prompt (string) — Default: '> '. The confirmation prompt.",
+        "prompt (string) — Default: '> '. The confirmation prompt; the default is used if there is no prompt child.",
         'result (boolean) — The result of the prompt.'
       ],
       :messages => [
-        'run — Prompt the user and then set the result.'
+        'run — Prompt the user; the answer (true or false) is put in result and in it.'
       ],
       :examples => <<~EXAMPLES.strip
         confirm [confirm] :

data/lib/command.rb

@@ -17,7 +17,6 @@ class Command < Gloo::Core::Obj
   CONTEXT = 'context'.freeze
   OPTIONS = 'options'.freeze
   OPTIONS_KEY = 'options_key'.freeze
-  ON_ERROR = 'on_error'.freeze
 
   #
   # The name of the object type.
@@ -120,18 +119,6 @@ class Command < Gloo::Core::Obj
     Gloo::Exec::Dispatch.message( @engine, 'run', o )
   end
 
-  #
-  # Run the on_error script if one exists.
-  # Returns true if the script was found and run, false otherwise.
-  #
-  def run_on_error
-    o = find_child ON_ERROR
-    return false unless o
-
-    Gloo::Exec::Dispatch.message( @engine, 'run', o )
-    return true
-  end
-
 
   # ---------------------------------------------------------------------
   #    Children
@@ -171,21 +158,45 @@ class Command < Gloo::Core::Obj
   end
 
   #
-  # Register the command with the shell.
+  # Register the command with the shell given as the parameter.
   #
   def msg_register
-    if @params&.token_count&.positive?
-      pn = Gloo::Core::Pn.new( @engine, @params.first )
-      shell = pn.resolve
-      shell.add_command( self, get_command_data )
-
-      # Are there options to add?
-      if options_key
-        shell.set_context( options_key, options )
-      end
+    shell = param_shell
+    return unless shell
+
+    shell.add_command( self, get_command_data )
+
+    # Are there options to add?
+    if options_key
+      shell.set_context( options_key, options )
     end
   end
 
+  #
+  # The shell named by the message's parameter. Otherwise report it
+  # (a syntax error if there's no parameter) and return nil.
+  #
+  def param_shell
+    unless @params&.token_count&.positive?
+      @engine.syntax_err "Missing the shell to register with! eg. tell #{name} to register (my.shell)"
+      return nil
+    end
+
+    pn = @params.first
+    shell = Gloo::Core::Pn.new( @engine, pn ).resolve
+    if shell.nil?
+      @engine.err Gloo::Core::NotFound.object( pn )
+      return nil
+    end
+
+    unless shell.is_a?( Shell )
+      @engine.err "'#{pn}' is not a shell."
+      return nil
+    end
+
+    return shell
+  end
+
 
   # ---------------------------------------------------------------------
   #    Helpers
@@ -257,7 +268,7 @@ class Command < Gloo::Core::Obj
         'options_key (string) — Optional. The shell context key that options gets registered under.'
       ],
       :messages => [
-        'register ({shell.path}) — Register this command with the given shell object, adding it to that shell\'s command tree. A parameter is required: the path to the shell.'
+        'register ({shell.path}) — Register this command with the given shell object, adding it to that shell\'s command tree. A parameter is required: the path to the shell. It is an error if it doesn\'t exist or isn\'t a shell.'
       ],
       :notes => 'No vault documentation exists for this object type — ' \
         'this was authored directly from the code.'

data/lib/prompt.rb

@@ -11,6 +11,7 @@ class Prompt < Gloo::Core::Obj
   PROMPT = 'prompt'.freeze
   RESULT = 'result'.freeze
   DEFAULT = 'default'.freeze
+  DEFAULT_PROMPT = '>'.freeze
 
   #
   # The name of the object type.
@@ -28,13 +29,11 @@ class Prompt < Gloo::Core::Obj
 
   #
   # Get the prompt from the child object.
-  # Returns nil if there is none.
+  # The default prompt if there is none.
   #
   def prompt_value
     o = find_child PROMPT
-    return nil unless o
-
-    return o.value
+    return o ? o.value : DEFAULT_PROMPT
   end
 
   # 
@@ -51,13 +50,12 @@ class Prompt < Gloo::Core::Obj
   end
 
   #
-  # Set the result of the system call.
+  # Set the result to the answer, and put it in it.
+  # The answer is kept even if there is no result child.
   #
   def set_result( data )
-    r = find_child RESULT
-    return nil unless r
-
-    r.set_value data
+    find_child( RESULT )&.set_value data
+    @engine.heap.it.set_to data
   end
 
 
@@ -81,7 +79,7 @@ class Prompt < Gloo::Core::Obj
   #
   def add_default_children
     fac = @engine.factory
-    fac.create_string PROMPT, '>', self
+    fac.create_string PROMPT, DEFAULT_PROMPT, self
     fac.create_string RESULT, nil, self
   end
 
@@ -102,8 +100,6 @@ class Prompt < Gloo::Core::Obj
   #
   def msg_multiline
     prompt = prompt_value
-    return unless prompt
-
     result = @engine.platform.prompt.multiline( prompt )
     set_result result.join
   end
@@ -113,8 +109,6 @@ class Prompt < Gloo::Core::Obj
   #
   def msg_run
     prompt = prompt_value
-    return unless prompt
-
     result = @engine.platform.prompt.ask( prompt, default_value )
     set_result result
   end
@@ -132,12 +126,12 @@ class Prompt < Gloo::Core::Obj
       :shortcut => KEYWORD_SHORT,
       :description => 'CLI prompt for user input.',
       :children => [
-        "prompt (string) — Default: '>'. The prompt displayed to the user.",
+        "prompt (string) — Default: '>'. The prompt displayed to the user; the default is used if there is no prompt child.",
         "result (string) — The result with the user's input."
       ],
       :messages => [
-        'run — Prompt the user and then set the result.',
-        'multiline — Show a multiline prompt.'
+        'run — Prompt the user; the answer is put in result and in it.',
+        'multiline — Show a multiline prompt; the answer is put in result and in it.'
       ],
       :examples => <<~EXAMPLES.strip
         ask [ask] :

data/lib/select.rb

@@ -11,6 +11,7 @@ class Select < Gloo::Core::Obj
   PROMPT = 'prompt'.freeze
   OPTIONS = 'options'.freeze
   RESULT = 'result'.freeze
+  DEFAULT_PROMPT = '>'.freeze
 
   #
   # The name of the object type.
@@ -28,13 +29,11 @@ class Select < Gloo::Core::Obj
 
   #
   # Get the prompt from the child object.
-  # Returns nil if there is none.
+  # The default prompt if there is none.
   #
   def prompt_value
     o = find_child PROMPT
-    return nil unless o
-
-    return o.value
+    return o ? o.value : DEFAULT_PROMPT
   end
 
   #
@@ -62,13 +61,12 @@ class Select < Gloo::Core::Obj
   end
 
   #
-  # Set the result of the system call.
+  # Set the result to the answer, and put it in it.
+  # The answer is kept even if there is no result child.
   #
   def set_result( data )
-    r = find_child RESULT
-    return nil unless r
-
-    r.set_value data
+    find_child( RESULT )&.set_value data
+    @engine.heap.it.set_to data
   end
 
   # ---------------------------------------------------------------------
@@ -91,7 +89,7 @@ class Select < Gloo::Core::Obj
   #
   def add_default_children
     fac = @engine.factory
-    fac.create_string PROMPT, '>', self
+    fac.create_string PROMPT, DEFAULT_PROMPT, self
     fac.create_can OPTIONS, self
     fac.create_string RESULT, nil, self
   end
@@ -111,9 +109,13 @@ class Select < Gloo::Core::Obj
   # Show the prompt and get the user's selection.
   #
   def msg_run
-    prompt = prompt_value
-    return unless prompt
+    if options.empty?
+      @engine.err "select '#{name}' has no options."
+      @engine.heap.it.set_to false
+      return
+    end
 
+    prompt = prompt_value
     # Page size was part of the tty-prompt but not used now.
     # per = Gloo::App::Settings.page_size( @engine )
     result = @engine.platform.prompt.select( prompt, options )
@@ -133,12 +135,12 @@ class Select < Gloo::Core::Obj
       :shortcut => KEYWORD_SHORT,
       :description => 'Prompt for user to select from a list of options.',
       :children => [
-        "prompt (string) — Default: '> '. The prompt displayed to the user.",
+        "prompt (string) — Default: '>'. The prompt displayed to the user; the default is used if there is no prompt child.",
         'options (container) — The list of options for the selection list. The name of each option is presented to the user, but the value is put in the result.',
         "result (string) — The result with the user's selection."
       ],
       :messages => [
-        'run — Prompt the user for a selection and then set the result.'
+        'run — Prompt the user for a selection; the chosen option\'s value is put in result and in it. It is an error if there are no options (it is false).'
       ],
       :examples => <<~EXAMPLES.strip
         select [select] :

data/lib/shell.rb

@@ -11,11 +11,11 @@ class Shell < Gloo::Core::Obj
   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
+  WITH_COMMAND = 'with_command'.freeze
 
   #
   # The name of the object type.
@@ -89,17 +89,37 @@ class Shell < Gloo::Core::Obj
     return super + [ 'start', 'stop' ]
   end
 
-  # 
+  #
   # Get the shell runner or initialize it if it doesn't exist.
+  # In App mode, any CLI parameter(s) after the app path become the
+  # runner's single command (see ShellRunner#single_command?) rather
+  # than files for gloo to load - @engine.args keeps those out of
+  # @engine.args.files for exactly this reason.
   #
   def get_runner
-    return @runner ||= ShellRunner.new( @engine, self )
+    set_with_command
+    return @runner ||= ShellRunner.new( @engine, self, command: @engine.args.command_tokens )
   end
-  
+
+  #
+  # If the app was invoked with a supplied command, record it on a
+  # with_command child (creating it if the script hasn't declared one
+  # itself), so scripts can tell a one-shot run from an interactive
+  # session - even before the shell starts (e.g. to skip a banner or
+  # menu). Left untouched (and uncreated) when no command was given.
+  #
+  def set_with_command
+    tokens = @engine.args.command_tokens
+    return if tokens.empty?
+
+    o = find_child( WITH_COMMAND ) || @engine.factory.create_string( WITH_COMMAND, '', self )
+    o.set_value( tokens.join( ' ' ) )
+  end
+
   #
   # Start the shell.
-  # If CLI args were passed, execute that command once and return.
-  # Otherwise, enter the interactive REPL.
+  # If the app was invoked with extra command-line arguments, execute
+  # that one command and return. Otherwise, enter the interactive REPL.
   #
   def msg_start
     runner = get_runner
@@ -107,12 +127,7 @@ class Shell < Gloo::Core::Obj
     # add_test_commands
     add_quit_command
 
-    cmd_tokens = @engine.args.files
-    if cmd_tokens.any?
-      runner.execute_once( cmd_tokens )
-    else
-      runner.start
-    end
+    runner.start
   end
 
   #
@@ -139,18 +154,6 @@ class Shell < Gloo::Core::Obj
     @runner.set_context( key, value )
   end
 
-  #
-  # Run the on_error script if one exists.
-  # Returns true if the script was found and run, false otherwise.
-  #
-  def run_on_error
-    o = find_child ON_ERROR
-    return false unless o
-
-    Gloo::Exec::Dispatch.message( @engine, 'run', o )
-    return true
-  end
-
   #
   # Run the on_unknown_cmd script if one exists.
   # Returns true if the script was found and run, false otherwise.
@@ -233,11 +236,15 @@ class Shell < Gloo::Core::Obj
         "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_error (script) — Optional. An ordinary on_error event script: like any on_error, it runs when an error is reported anywhere, including in a command. (A Ruby exception in a command is logged and runs on_exception; the shell carries on.)',
         "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.'
+        'after_action (script) — Optional. Run after every command executes.',
+        'with_command (string) — Not present by default. Set (and created if the ' \
+          'script hasn\'t declared it) to the supplied command text whenever the app ' \
+          'was invoked with extra command-line arguments - check for it to tell a ' \
+          'one-shot run from an interactive session.'
       ],
       :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.',

data/lib/shell_runner.rb

@@ -11,14 +11,18 @@ class ShellRunner
   DEFAULT_PROMPT = " -> "
   UNKNOWN_COMMAND = "Unknown command".freeze
   
-  # 
+  #
   # Initialize the shell runner
-  # 
+  #
   # @param obj [Object] The shell obj.
-  # 
-  def initialize( engine, obj )
+  # @param opts [Hash] :command (Array<String>) - tokens for a single
+  #   command to run once, instead of entering the interactive REPL -
+  #   see #single_command?.
+  #
+  def initialize( engine, obj, opts = {} )
     @engine = engine
     @obj = obj
+    @command = opts[ :command ]
     @context = ShellContext.new
     @root = CommandNode.new( nil )
   end
@@ -27,12 +31,26 @@ class ShellRunner
   # ---------------------------------------------------------------------
   #    Shell, control, start and stop
   # ---------------------------------------------------------------------
-  
-  # 
-  # Start the shell.
-  # 
+
+  #
+  # Were command tokens supplied at construction? When true, #start
+  # runs that one command via #execute_once and returns instead of
+  # entering the REPL.
+  #
+  def single_command?
+    return !( @command.nil? || @command.empty? )
+  end
+
+  #
+  # Start the shell: run the single supplied command and return,
+  # or enter the interactive REPL if none was supplied.
+  #
   def start
-    repl
+    if single_command?
+      execute_once( @command )
+    else
+      repl
+    end
   end
 
   # 
@@ -91,11 +109,7 @@ class ShellRunner
       pn = Gloo::Core::Pn.new( @engine, parent_node.obj )
       command = pn.resolve
       if command
-        begin
-          command.run_action_with_context( cmd_node.name )
-        rescue => e
-          command.run_on_error || @obj.run_on_error
-        end
+        command.run_action_with_context( cmd_node.name )
       end
     end
   end
@@ -189,6 +203,16 @@ class ShellRunner
   # Used when a command is passed directly from the CLI.
   #
   def execute_once( tokens )
+    run_tokens( tokens )
+  end
+
+  #
+  # Find and run the command for the given tokens, with the before and
+  # after actions. An unexpected Ruby exception is handled (logged, and
+  # on_exception is run) and the shell carries on. Errors in a
+  # command's gloo script are reported where they happen (on_error).
+  #
+  def run_tokens( tokens )
     result = traverse( @root, tokens )
     if result[:node]
       @obj.run_before_action
@@ -197,6 +221,8 @@ class ShellRunner
     else
       handle_unknown_command
     end
+  rescue => e
+    @engine.handle_exception e
   end
 
   #
@@ -275,15 +301,7 @@ class ShellRunner
         next
       end
 
-      result = traverse( @root, tokens )
-
-      if result[:node]
-        @obj.run_before_action
-        execute_command( result[:node], tokens, result[:parent] )
-        @obj.run_after_action
-      else
-        handle_unknown_command
-      end
+      run_tokens( tokens )
     end
   end
 

metadata

@@ -1,14 +1,82 @@
 --- !ruby/object:Gem::Specification
 name: gloo-cli
 version: !ruby/object:Gem::Version
-  version: '1.8'
+  version: '2.0'
 platform: ruby
 authors:
 - Eric Crane
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gloo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.1
 description: Adds CLI support to Gloo.
 email:
 - eric.crane@mac.com