gloo 6.0 → 6.1.0

data/lib/gloo/shell/runner.rb

@@ -0,0 +1,315 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# A shell runner.  Drives a command-tree REPL with readline
+# tab-completion.
+#
+# Adapted from gloo-cli's ShellRunner: that version took a `Shell`
+# Gloo::Core::Obj and read its config (prompt, on_error, etc) from
+# gloo-script-declared children. There's no such object tree for an
+# interpreter-internal shell, so this version takes plain options
+# instead. The Command Obj / cmd_obj_action(_with_context) mechanism
+# was gloo-cli's way of running a gloo-declared Command object's
+# action script; it isn't ported either — command nodes here always
+# dispatch to a named method on the Runner (or a subclass of it).
+#
+# One addition beyond the gloo-cli original: a :dynamic node's
+# generated children can carry a :child_method, so each one dispatches
+# to a handler with the source item itself as `obj` (e.g. "verb put"
+# dispatching to a detail-lookup method with "put" as the argument).
+# gloo-cli didn't need this since it resolved a Command Obj instead.
+#
+require 'readline'
+
+module Gloo
+  module Shell
+    class Runner
+
+      DEFAULT_PROMPT = ' -> '.freeze
+      UNKNOWN_COMMAND = 'Unknown command'.freeze
+
+      QUIT_NAME = 'quit'.freeze
+      QUIT_DESCRIPTION = 'Quit the application'.freeze
+      QUIT_METHOD = 'cmd_quit'.freeze
+
+      #
+      # Initialize the shell runner.
+      #
+      # @param engine [Gloo::App::Engine] The running gloo engine.
+      #   Not used directly by the base Runner, but stored for
+      #   subclasses' command methods to query (dictionary, heap, etc).
+      # @param opts [Hash] :prompt, :on_error, :on_unknown_command,
+      #   :on_empty_command, :before_action, :after_action - all Procs
+      #   except :prompt (String) and :include_quit (Boolean).
+      #
+      def initialize( engine, opts = {} )
+        @engine = engine
+        @prompt_text = opts[ :prompt ]
+        @on_error = opts[ :on_error ]
+        @on_unknown_command = opts[ :on_unknown_command ]
+        @on_empty_command = opts[ :on_empty_command ]
+        @before_action = opts[ :before_action ]
+        @after_action = opts[ :after_action ]
+        @include_quit = opts[ :include_quit ] || false
+
+        @context = Gloo::Shell::Context.new
+        @root = Gloo::Shell::CommandNode.new( nil )
+
+        add_quit_command if @include_quit
+      end
+
+      # ---------------------------------------------------------------------
+      #    Shell control: start and stop
+      # ---------------------------------------------------------------------
+
+      #
+      # Start the shell.
+      #
+      def start
+        repl
+      end
+
+      #
+      # Flag the shell as done. Next time through the loop it will stop.
+      #
+      def stop
+        @context.done = true
+      end
+
+      #
+      # Get the prompt string.
+      #
+      def prompt
+        return @prompt_text ? "#{@prompt_text} " : DEFAULT_PROMPT
+      end
+
+      #
+      # Handle an empty command - run the on_empty_command hook if given.
+      #
+      def handle_empty_command
+        @on_empty_command&.call
+      end
+
+      #
+      # Handle an unknown command - run the on_unknown_command hook if
+      # given, otherwise show the default message.
+      #
+      def handle_unknown_command
+        return if @on_unknown_command&.call
+
+        puts UNKNOWN_COMMAND
+      end
+
+      #
+      # Run the before_action hook, if given.
+      #
+      def run_before_action
+        @before_action&.call
+      end
+
+      #
+      # Run the after_action hook, if given.
+      #
+      def run_after_action
+        @after_action&.call
+      end
+
+      #
+      # Run the on_error hook, if given.
+      #
+      def run_on_error
+        @on_error&.call
+      end
+
+      #
+      # Quit the shell.
+      #
+      def cmd_quit( _obj, context )
+        puts 'Quitting…'
+        context.done = true
+      end
+
+      # ---------------------------------------------------------------------
+      #    Context
+      # ---------------------------------------------------------------------
+
+      #
+      # Set a context list, available to dynamic command nodes.
+      #
+      def set_context( key, value_list )
+        @context.set( key, value_list )
+      end
+
+      # ---------------------------------------------------------------------
+      #    Tree building
+      # ---------------------------------------------------------------------
+
+      #
+      # Execute a command.
+      #
+      def execute_command( command_node, _args, _parent_node = nil )
+        if command_node.method
+          send( command_node.method, command_node.obj, @context )
+        elsif command_node.name && !command_node.description.empty?
+          puts "#{command_node.description}: #{command_node.name}"
+        end
+      end
+
+      #
+      # Build a command node from data.
+      #
+      def build_node_from_data( data )
+        if data[ :dynamic ]
+          return Gloo::Shell::CommandNode.new(
+            data[ :name ], description: data[ :description ], obj: data[ :obj ] ) do |ctx|
+            ctx.send( data[ :source ] ).map do |item|
+              Gloo::Shell::CommandNode.new( item, method: data[ :child_method ], obj: item )
+            end
+          end
+        elsif data[ :children ]
+          return Gloo::Shell::CommandNode.new(
+            data[ :name ], description: data[ :description ],
+            method: data[ :method ], obj: data[ :obj ] ) do |_ctx|
+            data[ :children ].map { |child_data| build_node_from_data( child_data ) }
+          end
+        else
+          return Gloo::Shell::CommandNode.new(
+            data[ :name ], description: data[ :description ],
+            method: data[ :method ], obj: data[ :obj ] )
+        end
+      end
+
+      #
+      # Add a command node to the root, dynamically.
+      #
+      # @param command_data [Hash] The command data hash.
+      #
+      def add_command_node( command_data )
+        node = build_node_from_data( command_data )
+
+        existing_block = @root.instance_variable_get( :@children_block )
+        if existing_block
+          existing_nodes = existing_block.call( @context )
+          all_nodes = existing_nodes + [ node ]
+          @root.instance_variable_set( :@children_block, proc { |_ctx| all_nodes } )
+        else
+          @root.instance_variable_set( :@children_block, proc { |_ctx| [ node ] } )
+        end
+
+        return node
+      end
+
+      # ---------------------------------------------------------------------
+      #    REPL
+      # ---------------------------------------------------------------------
+
+      #
+      # Execute a single command from the given tokens and return.
+      #
+      def execute_once( tokens )
+        result = traverse( @root, tokens )
+        if result[ :node ]
+          run_before_action
+          execute_command( result[ :node ], tokens, result[ :parent ] )
+          run_after_action
+        else
+          handle_unknown_command
+        end
+      end
+
+      #
+      # Traverse the command tree to find the matching node.
+      #
+      # @param node [CommandNode] The current node.
+      # @param tokens [Array<String>] The tokens to traverse.
+      #
+      # @return [Hash] Hash with :node and :parent keys.
+      #
+      def traverse( node, tokens )
+        current = node
+        parent = nil
+
+        tokens.each do |token|
+          children = current.children( @context )
+          match = children.find { |c| c.name == token }
+          return { node: nil, parent: nil } unless match
+
+          parent = current
+          current = match
+        end
+
+        return { node: current, parent: parent }
+      end
+
+      #
+      # Setup readline completion.
+      #
+      def setup_completion
+        Readline.completion_append_character = ' '
+        Readline.basic_word_break_characters = " \t\n\"\\'`@$><=;|&{("
+
+        Readline.completion_proc = proc do |input|
+          buffer = Readline.line_buffer
+          tokens = buffer.split( ' ' )
+          tokens << '' if buffer.end_with?( ' ' )
+
+          result = traverse( @root, tokens[ 0..-2 ] )
+          current = result[ :node ]
+          options = current ? current.children( @context ).map( &:name ) : []
+
+          matches = options.grep( /^#{Regexp.escape( input )}/ )
+
+          if matches.length > 1
+            puts
+            current.children( @context ).each do |child|
+              puts "#{child.name.ljust( 15 )} #{child.description}" if matches.include?( child.name )
+            end
+            print "#{prompt}#{buffer}"
+          end
+
+          matches
+        end
+      end
+
+      #
+      # Run the REPL loop.
+      #
+      def repl
+        setup_completion
+
+        while !@context.done && ( line = Readline.readline( prompt, true ) )
+          tokens = line.strip.split( ' ' )
+          if tokens.empty?
+            handle_empty_command
+            next
+          end
+
+          result = traverse( @root, tokens )
+
+          if result[ :node ]
+            run_before_action
+            execute_command( result[ :node ], tokens, result[ :parent ] )
+            run_after_action
+          else
+            handle_unknown_command
+          end
+        end
+      end
+
+      # ---------------------------------------------------------------------
+      #    Private
+      # ---------------------------------------------------------------------
+
+      private
+
+      #
+      # Add the built-in quit command, if enabled.
+      #
+      def add_quit_command
+        add_command_node(
+          { name: QUIT_NAME, description: QUIT_DESCRIPTION, method: QUIT_METHOD } )
+      end
+
+    end
+  end
+end

data/lib/gloo/verbs/break.rb

@@ -39,6 +39,38 @@ module Gloo
 
       private
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Break out of the current script, stop running.',
+          :syntax => [ 'break' ],
+          :result => 'No more commands are executed in the currently ' \
+            'running script. If there are other scripts in the stack, ' \
+            'they will resume normally.',
+          :examples => <<~EXAMPLES.strip
+            #
+            # Break out of a script.
+            #
+            break_out [can] :
+              x [bool] : false
+              on_load [script] :
+                if ^.x then break
+                show 'should see this'
+                put true into ^.x
+                if ^.x then break
+                show 'should not see this'
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/check.rb

@@ -49,6 +49,55 @@ module Gloo
 
       private
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Send a message to an object to check for an ' \
+            'object condition. This is the same as the tell verb, but ' \
+            'gives better syntactical naming.',
+          :syntax => [ 'check {path.to.object} for {condition_message}' ],
+          :parameters => [
+            '{path.to.object} — The object that we want to send a condition_message to.',
+            '{message} — The condition_message to send.'
+          ],
+          :result => 'The result depends on the message that is sent, but ' \
+            'by convention the result of the check will be in it.',
+          :errors => [
+            "#{UNKNOWN_MSG_ERR} — No message was specified, or the 'for' keyword is missing.",
+            'Object was not found — The target of the message was not found.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Base object checks.
+            #
+            obj [container] :
+              msg [string] :
+              on_load [script] :
+                show 'Does the obj container have children?'
+                check obj for contains?
+                show it
+
+                show 'Is the msg blank?'
+                check obj.msg for blank?
+                show it
+
+                put 'Hello, world!' into obj.msg
+                show obj.msg
+                show 'Is the msg still blank?'
+                check obj.msg for blank?
+                show it
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/cls.rb

@@ -32,6 +32,24 @@ module Gloo
         return KEYWORD_SHORT
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      # 
+      # Get the verb's documentation data.
+      # 
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Clear the console screen.',
+          :syntax => [ 'clear' ],
+          :result => 'The screen is cleared and cursor set to the top.',
+          :examples => '> clear'
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/context.rb

@@ -57,6 +57,53 @@ module Gloo
         @engine.log.debug "Context set to #{@engine.heap.context}"
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Get or set the current context. When no ' \
+            'parameter is provided, the context will be shown. When the ' \
+            "optional path parameter is provided, the context will be set " \
+            "to that path. Use 'context root' to set the context back to " \
+            'the root level. When context has been set, the pathname can ' \
+            'start from the context container by use of the @. prefix.',
+          :syntax => [ 'context {path.to.new.context}' ],
+          :parameters => [
+            '{path.to.new.context} — Optional. The path to the new context when setting the context.'
+          ],
+          :result => 'Context is optionally set. It will be set to the ' \
+            'new context path when we are changing context. Context is ' \
+            'shown in either case.',
+          :notes => 'Providing a context that does not exist will not ' \
+            'initially be a problem — you can set the context to an ' \
+            "object before it exists. However, use of a context that " \
+            "doesn't exist will be a problem.\n\n" \
+            "CLI Example:\n" \
+            "> context\n" \
+            "  Context: root\n\n" \
+            "> context my.object.path\n" \
+            "  Context: my.object.path\n\n" \
+            "> context root\n" \
+            "  Context: root",
+          :examples => <<~EXAMPLES.strip
+            context [container] :
+              sub [container] :
+                msg [string] : Hello Gloo World!
+                on_load [script] :
+                    @ context.sub
+                    show @.msg
+                    @ root
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/create.rb

@@ -69,6 +69,48 @@ module Gloo
         @engine.heap.it.set_to value
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Create a new object of given type with given ' \
+            'value. Both type and value are optional when creating an object.',
+          :syntax => [ 'create {new.object.path} as {type} : {value}' ],
+          :parameters => [
+            '{new.object.path} — The path and name of the new object.',
+            '{type} — The type of the new object. Optional; if not provided the object will be untyped.',
+            "{value} — The initial value for the new object. Optional; if not provided the object will have the default value for the type."
+          ],
+          :result => "The new object will be created and added to the " \
+            "object heap. It will be set to the new object's initial value.",
+          :errors => [
+            "#{NO_NAME_ERR} — The name of the object was not specified and the object cannot be created."
+          ],
+          :examples => <<~EXAMPLES.strip
+            # Basic examples of creating an object from the gloo shell:
+            > create x as integer : 1
+            > create s : "abc"
+            > create t
+
+            # Example of creating an object with an alias:
+            a [can] :
+              ln [alias] : x
+
+              on_load [script] :
+                create a.ln* as string
+                put 'test' into x
+                show a.ln
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/eval.rb

@@ -38,6 +38,33 @@ module Gloo
         end
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Evaluate an expression and put the result into it.',
+          :syntax => [ 'eval {expression}' ],
+          :parameters => [
+            '{expression} — The expression that will be evaluated. The expression is optional. If not provided, eval will result in true.'
+          ],
+          :result => 'The result of the expression evaluation is put ' \
+            'into it. No other action is performed.',
+          :examples => <<~EXAMPLES.strip
+            > eval "me"
+            > eval "hello " "world"
+            > eval 132 * 23
+            > eval path.to.num = 1
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/execute.rb

@@ -49,6 +49,33 @@ module Gloo
         return KEYWORD_SHORT
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Execute a shell command. This verb is not ' \
+            'available in the Web app.',
+          :syntax => [ 'exec {expression}' ],
+          :parameters => [
+            '{expression} — Evaluate the expression and execute in the shell.'
+          ],
+          :result => 'There is no result within gloo, any output is in the terminal.',
+          :errors => [
+            "#{MISSING_EXPR_ERR} — No expression is provided as parameter to the verb."
+          ],
+          :examples => <<~EXAMPLES.strip
+            > exec 'rake test'
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/exists.rb

@@ -72,9 +72,9 @@ module Gloo
         return false
       end
 
-      # 
+      #
       # Check to see if an instance of an object exists.
-      # 
+      #
       def instance_exists?( pn )
         pn = Gloo::Core::Pn.new( @engine, pn )
         o = pn.resolve
@@ -82,6 +82,58 @@ module Gloo
         return true
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Check to see if a verb or object type has ' \
+            'been defined (or loaded). This verb can be used to check ' \
+            'if a core library or extension has been loaded.',
+          :syntax => [ 'exists? |any,object,verb,instance| {keyword}' ],
+          :parameters => [
+            "Kind of Keyword — Check for the presence of a keyword of a kind. " \
+              "any (default, optional) checks for either an object or a verb; " \
+              "object checks for an object matching the keyword or keyword " \
+              "shortcut; verb checks for a verb matching the keyword or " \
+              "keyword shortcut; instance checks to see if an object " \
+              "instance exists at the pathname represented by keyword. " \
+              "`exists? any markdown` is identical to `exists? markdown`.",
+            '{keyword} — The verb or object keyword or keyword shortcut. ' \
+              'Must be specified. For the instance option, the keyword is ' \
+              'the pathname to an object instance.'
+          ],
+          :result => 'If the object or verb has been defined, then true, ' \
+            'otherwise false. The result will be in it.',
+          :errors => [
+            "#{WRONG_NUM_ARGS_ERR} The kind of keyword is optional."
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Example of exists? keyword.
+            #
+            exists [container] :
+
+            \ton_load [script] :
+            \t\texists? object markdown
+            \t\tshow it # false
+
+            \t\tload lib md
+            \t\texists? object markdown
+            \t\tshow it # true
+
+            \t\texists? instance exists.on_load
+            \t\tshow it # true
+          EXAMPLES
+        }
+      end
+
     end
   end
 end