gloo 6.0 → 6.1.0

data/lib/gloo/docs/help_shell.rb

@@ -0,0 +1,285 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# The interactive help shell, entered by the `help`/`?` verb.
+# Built on Gloo::Shell::Runner (see lib/gloo/shell/).
+#
+require_relative '../shell/runner'
+require_relative 'markdown_renderer'
+
+module Gloo
+  module Docs
+    class HelpShell < Gloo::Shell::Runner
+
+      PROMPT = 'help>'.freeze
+      NO_DOC_YET = 'No documentation available yet for'.freeze
+
+      VERB_NAMES = :verb_names
+      OBJECT_NAMES = :object_names
+      DOC_NAMES = :doc_names
+      LIBRARY_NAMES = :library_names
+      EXTENSION_NAMES = :extension_names
+
+      DOCS_DIR = File.expand_path( '../../../docs', __dir__ ).freeze
+      README_GLOB = 'README*'.freeze
+      NO_README_YET = 'No README found for library'.freeze
+
+      #
+      # Initialize the help shell for the given engine.
+      #
+      def initialize( engine )
+        super( engine, prompt: PROMPT, include_quit: true )
+        populate_context
+        build_commands
+      end
+
+      # ---------------------------------------------------------------------
+      #    Root commands - lists (mirrors the old help v/o/s/e/l dispatch)
+      # ---------------------------------------------------------------------
+
+      #
+      # List all verbs.
+      #
+      def cmd_show_verbs( _obj, _context )
+        data = "\n"
+        data << " Verbs (shortcut, name)\n".blue
+        @engine.dictionary.get_verbs.sort_by( &:keyword ).each do |v|
+          cut = v.keyword_shortcut.ljust( 5, ' ' ).yellow
+          name = v.keyword.ljust( 20, ' ' ).white
+          data << "   #{cut}  #{name} \n"
+        end
+        @engine.log.show "#{data}\n"
+      end
+
+      #
+      # List all object types.
+      #
+      def cmd_show_objects( _obj, _context )
+        data = "\n"
+        data << " Objects \n".blue
+        @engine.dictionary.get_obj_types.sort_by( &:typename ).each do |o|
+          if o.short_typename != o.typename
+            short = "(#{o.short_typename})".yellow
+            name = "#{o.typename.white}  #{short}"
+          else
+            name = o.typename.white
+          end
+          data << "   #{name.ljust( 30, ' ' )}\n"
+        end
+        @engine.log.show "#{data}\n"
+      end
+
+      #
+      # Show application settings.
+      #
+      def cmd_show_settings( _obj, _context )
+        @engine.settings.show
+      end
+
+      #
+      # List loaded extensions.
+      #
+      def cmd_show_extensions( _obj, _context )
+        data = "\n"
+        data << " Extensions\n".blue
+        data << "   Use `load ext {name}` to load a User Extension, \n" \
+          "   then `object {name}` / `verb {name}` / `extension {name}` here to see what it adds. \n" \
+          "   Only loaded extensions are listed below.\n\n".light_black
+        loaded = @engine.ext_manager.loaded_extensions
+        if loaded.empty?
+          data << "   (none loaded)\n".light_black
+        else
+          loaded.sort.each do |name, _ext|
+            data << "   #{name.white} \n"
+          end
+        end
+        @engine.log.show "#{data}\n"
+      end
+
+      #
+      # List loaded libraries.
+      #
+      def cmd_show_libraries( _obj, _context )
+        data = "\n"
+        data << " Libraries\n".blue
+        data << "   Use `load lib {name}` to load a core library, \n" \
+          "   then `object {name}` / `verb {name}` here to see what it adds. \n" \
+          "   Only loaded libraries are listed below.\n\n".light_black
+        loaded = @engine.lib_manager.loaded_libraries
+        if loaded.empty?
+          data << "   (none loaded)\n".light_black
+        else
+          loaded.sort.each do |name, _lib|
+            data << "   #{name.white} \n"
+          end
+        end
+        @engine.log.show "#{data}\n"
+      end
+
+      #
+      # List all narrative doc pages (dev/gloo/docs/*.md).
+      #
+      def cmd_show_docs( _obj, _context )
+        data = "\n"
+        data << " Docs\n".blue
+        doc_page_names.each do |name|
+          data << "   #{name.white}\n"
+        end
+        @engine.log.show "#{data}\n"
+      end
+
+      # ---------------------------------------------------------------------
+      #    Detail commands - verb {name}, object {name}, doc {name},
+      #    library {name}
+      # ---------------------------------------------------------------------
+
+      #
+      # Show detailed help for one verb.
+      #
+      def cmd_show_verb_detail( obj, _context )
+        verb_class = @engine.dictionary.find_verb( obj )
+        return @engine.log.show "#{NO_DOC_YET} '#{obj}'." unless verb_class.respond_to?( :doc_data )
+
+        page_markdown( Gloo::Docs::DocData.new( verb_class.doc_data ).render )
+      end
+
+      #
+      # Show detailed help for one object type.
+      #
+      def cmd_show_object_detail( obj, _context )
+        obj_class = @engine.dictionary.find_obj( obj )
+        return @engine.log.show "#{NO_DOC_YET} '#{obj}'." unless obj_class.respond_to?( :doc_data )
+
+        page_markdown( Gloo::Docs::DocData.new( obj_class.doc_data ).render )
+      end
+
+      #
+      # Show one narrative doc page (dev/gloo/docs/{name}.md).
+      #
+      def cmd_show_doc_detail( obj, _context )
+        path = File.join( DOCS_DIR, "#{obj}.md" )
+        return @engine.log.show "#{NO_DOC_YET} '#{obj}'." unless File.exist?( path )
+
+        page_markdown( File.read( path ) )
+      end
+
+      #
+      # Show the README for one loaded core library (from the root of
+      # its installed gem). Only loaded libraries are tab-completable
+      # here - see cmd_show_libraries.
+      #
+      def cmd_show_library_detail( obj, _context )
+        gem_name = @engine.lib_manager.loaded_libraries[ obj ]
+        return @engine.log.show "#{NO_DOC_YET} '#{obj}'." unless gem_name
+
+        readme_path = find_readme( gem_name )
+        return @engine.log.show "#{NO_README_YET} '#{obj}' (#{gem_name})." unless readme_path
+
+        page_markdown( File.read( readme_path ) )
+      end
+
+      #
+      # Show the README for one loaded user extension (from the root of
+      # its extension folder, e.g. ~/gloo/extensions/{name}). Only loaded
+      # extensions are tab-completable here - see cmd_show_extensions.
+      #
+      def cmd_show_extension_detail( obj, _context )
+        start_file = @engine.ext_manager.loaded_extensions[ obj ]
+        return @engine.log.show "#{NO_DOC_YET} '#{obj}'." unless start_file
+
+        readme_path = find_extension_readme( start_file )
+        return @engine.log.show "#{NO_README_YET} '#{obj}'." unless readme_path
+
+        page_markdown( File.read( readme_path ) )
+      end
+
+      # ---------------------------------------------------------------------
+      #    Private
+      # ---------------------------------------------------------------------
+
+      private
+
+      #
+      # Colorize markdown and page it, bracketed with a '---' rule above
+      # and below so the content stands out from surrounding CLI output.
+      #
+      def page_markdown( md )
+        rule = '-' * @engine.platform.cols
+        bracketed = "#{rule}\n#{md.strip}\n#{rule}\n"
+        @engine.platform.page( Gloo::Docs::MarkdownRenderer.colorize( bracketed ) )
+      end
+
+      #
+      # Snapshot the verb, object type, doc page, and loaded library
+      # names for tab-completion.
+      #
+      def populate_context
+        set_context( VERB_NAMES, @engine.dictionary.get_verbs.map( &:keyword ).sort )
+        set_context( OBJECT_NAMES, @engine.dictionary.get_obj_types.map( &:typename ).sort )
+        set_context( DOC_NAMES, doc_page_names )
+        set_context( LIBRARY_NAMES, @engine.lib_manager.loaded_libraries.keys.sort )
+        set_context( EXTENSION_NAMES, @engine.ext_manager.loaded_extensions.keys.sort )
+      end
+
+      #
+      # Find the README file at the root of an installed gem, if any.
+      #
+      def find_readme( gem_name )
+        spec = Gem::Specification.find_by_name( gem_name )
+        return Dir.glob( File.join( spec.gem_dir, README_GLOB ) ).first
+      rescue Gem::MissingSpecError
+        return nil
+      end
+
+      #
+      # Find the README file at the root of an extension's folder, given
+      # the full path to its {name}_ext.rb start file.
+      #
+      def find_extension_readme( start_file )
+        root = File.dirname( start_file )
+        return Dir.glob( File.join( root, README_GLOB ) ).first
+      end
+
+      #
+      # List the narrative doc page names (dev/gloo/docs/*.md, without extension).
+      #
+      def doc_page_names
+        return Dir.glob( File.join( DOCS_DIR, '*.md' ) ).map { |f| File.basename( f, '.md' ) }.sort
+      end
+
+      #
+      # Build the help shell's command tree.
+      #
+      def build_commands
+        add_command_node(
+          name: 'verbs', description: 'List all verbs', method: 'cmd_show_verbs' )
+        add_command_node(
+          name: 'objects', description: 'List all object types', method: 'cmd_show_objects' )
+        add_command_node(
+          name: 'settings', description: 'Show application settings', method: 'cmd_show_settings' )
+        add_command_node(
+          name: 'extensions', description: 'List loaded extensions', method: 'cmd_show_extensions' )
+        add_command_node(
+          name: 'libraries', description: 'List loaded libraries', method: 'cmd_show_libraries' )
+        add_command_node(
+          name: 'docs', description: 'List all narrative doc pages', method: 'cmd_show_docs' )
+        add_command_node(
+          name: 'verb', description: 'Show detailed help for a verb',
+          dynamic: true, source: VERB_NAMES, child_method: 'cmd_show_verb_detail' )
+        add_command_node(
+          name: 'object', description: 'Show detailed help for an object type',
+          dynamic: true, source: OBJECT_NAMES, child_method: 'cmd_show_object_detail' )
+        add_command_node(
+          name: 'doc', description: 'Show one narrative doc page',
+          dynamic: true, source: DOC_NAMES, child_method: 'cmd_show_doc_detail' )
+        add_command_node(
+          name: 'library', description: "Show a loaded library's README",
+          dynamic: true, source: LIBRARY_NAMES, child_method: 'cmd_show_library_detail' )
+        add_command_node(
+          name: 'extension', description: "Show a loaded extension's README",
+          dynamic: true, source: EXTENSION_NAMES, child_method: 'cmd_show_extension_detail' )
+      end
+
+    end
+  end
+end

data/lib/gloo/docs/markdown_renderer.rb

@@ -0,0 +1,39 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Lightly colorize markdown for terminal display: headings and code
+# fences get ANSI color, everything else passes through unchanged.
+# Not a full markdown renderer - just enough that the raw
+# `#`/```` ``` ```` syntax doesn't have to be read literally.
+#
+# Shared by the narrative doc pages (dev/gloo/docs/*.md) and the
+# verb/object detail pages (Gloo::Docs::DocData#render), so both are
+# paged through the same visual style.
+#
+module Gloo
+  module Docs
+    class MarkdownRenderer
+
+      #
+      # Colorize the given markdown text for terminal display.
+      def self.colorize( text )
+        in_code = false
+        lines = text.split( "\n" ).map do |line|
+          if line.start_with?( '```' )
+            in_code = !in_code
+            next line.light_black
+          end
+          next line.light_black if in_code
+          next line.sub( /^#\s*/, '' ).blue.bold if line.start_with?( '# ' )
+          next line.sub( /^##\s*/, '' ).cyan.bold if line.start_with?( '## ' )
+          next line.cyan if line.start_with?( '### ' ) || line.start_with?( '#### ' )
+          next line.light_black if line =~ /\A-{3,}\z/
+
+          line
+        end
+        return lines.join( "\n" )
+      end
+
+    end
+  end
+end

data/lib/gloo/objs/basic/alias.rb

@@ -73,6 +73,59 @@ module Gloo
         return ln.resolve
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A pointer to another object. Normal ' \
+            'path-name references will refer to the aliased object. To ' \
+            'refer to the alias itself, add an * at the end of the ' \
+            'path-name — needed, for example, to set the value of the ' \
+            'alias. The value of the alias is merely the path-name of ' \
+            'the referenced object. Well constructed aliases will ' \
+            'redirect to the referenced object through any number of ' \
+            'steps, and relative references will also work in an alias.',
+          :messages => [
+            'resolve — Check to see if the object referenced exists. Sets it to true or false.'
+          ],
+          :notes => 'The alias also reflects (forwards) the messages of the object it points to.',
+          :examples => <<~EXAMPLES.strip
+            #
+            # Alias object.
+            #
+
+            a [can] :
+              s [string] : a string
+              i [integer] : 13
+              ln [alias] : a.s
+
+              on_load [script] :
+                show a.ln
+                show a.ln*
+                put 'a.i' into a.ln*
+                put 7 into a.ln
+                show a.ln
+                run a.add
+
+              #
+              # Example of creating an object using an alias.
+              #
+              add [script] :
+                put 'x' into a.ln*
+                create a.ln* as string
+                put 'test' into x
+                show a.ln
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/basic/boolean.rb

@@ -115,6 +115,36 @@ module Gloo
         return false
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A boolean value. Value will be either true or false.',
+          :messages => [
+            'not — Set the boolean to the opposite of what it is now.',
+            'true — Set the boolean to true.',
+            'false — Set the boolean to false.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            b [can] :
+              flag [boolean] : true
+              on_load [script] :
+                show b.flag
+                put false into b.flag
+                show b.flag
+                tell b.flag to not
+                show b.flag
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/basic/container.rb

@@ -75,6 +75,44 @@ module Gloo
         @engine.heap.it.set_to val
         return val
       end
+
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A container of other objects. A container is ' \
+            'similar to a folder in a file system. It can contain any ' \
+            'number of objects including other containers. The ' \
+            'container structure provides direct access to any object ' \
+            'within it through the object.object.object path-name structure.',
+          :children => [
+            'None by default — but any container can have any number of objects added to it, at runtime.'
+          ],
+          :messages => [
+            'count — Count the number of children objects in the container. The result is put in it.',
+            'delete_children — Delete all children objects from the container.',
+            'show_key_value_table — Show a table with key (name) and values for all children in the container.',
+            'child_exists ({name}) — Check to see if there is a child with the given name. A parameter is required. It will have a boolean.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            can [can] :
+              data [can] :
+                1 : one
+                2 : two
+                3 : three
+              on_load [script] :
+                tell can.data to show_key_value_table
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/basic/decimal.rb

@@ -92,6 +92,36 @@ module Gloo
         @engine.heap.it.set_to formatted
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A decimal (numeric) value.',
+          :messages => [
+            'round ({precision}) — Round to the nearest whole value. If ' \
+              'an optional parameter is included, round to the precision specified.',
+            'format ({fmt}) — With no parameter, adds comma separators to the whole part (e.g. 1000.5 -> 1,000.5). With a parameter, uses it as a sprintf-style format string (e.g. \'%.2f\'). It will have the formatted string.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            d [can] :
+              x [decimal] : 100
+              on_load [script] :
+                show d.x
+                put d.x / 3 into d.x
+                show d.x
+                tell d.x to round (1)
+                show d.x
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/basic/integer.rb

@@ -118,6 +118,64 @@ module Gloo
         @engine.heap.it.set_to formatted
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'An integer (numeric) value.',
+          :messages => [
+            'inc — Increment the integer value by 1.',
+            'dec — Decrement the integer value by 1.',
+            'randomize ({max}) — Set the value of the integer to a random ' \
+              'number. By default the range is 0..99 inclusive. Use an ' \
+              'optional parameter to set the maximum of the range; the ' \
+              'range always starts at 0. To model a 6-sided die, set the ' \
+              'range to 6 and add 1 to the result.',
+            'format ({fmt}) — With no parameter, adds comma separators (e.g. 1000 -> 1,000). With a parameter, uses it as a sprintf-style format string (e.g. \'%05d\'). It will have the formatted string.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Integer object.
+            #
+
+            i [can] :
+
+              #
+              # The integer value.
+              #
+              x [integer] : 0
+
+              #
+              # Do some basic tests with it
+              #
+              on_load [script] :
+                show i.x
+                tell i.x to inc
+                show i.x
+                put i.x * 10 into i.x
+                show i.x
+
+                # Show a random number
+                tell ^.x to randomize
+                show 'Random number (up to 100 by default): ' + ^.x
+
+                tell ^.x to randomize(6)
+                tell ^.x to inc
+                show '6-sided dice: ' + ^.x
+
+              # An uninitialized integer.
+              y [integer] :
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/basic/script.rb

@@ -94,6 +94,37 @@ module Gloo
         s.run
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'An executable script — a set of commands to be run.',
+          :messages => [
+            'run — Run the script. The script can be run by telling the ' \
+              'object to run, or via the run verb.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            script [can] :
+              on_load [script] :
+                show "Showing multiple lines..."
+                show script.msg1
+                show script.msg2
+                show script.msg3
+                show "Done."
+              msg1 [string] : one
+              msg2 [string] : two
+              msg3 [string] : three
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/basic/string.rb

@@ -44,10 +44,57 @@ module Gloo
       # Get a list of message names that this object receives.
       #
       def self.messages
-        return super + %w[up down size starts_with? ends_with? substring? sub gsub
-          count_lines count_words count_chars trim
-          format_for_html encode64 decode64 escape unescape
-          gen_alphanumeric gen_uuid gen_hex gen_base64]
+        return super + StringMsgs.messages
+      end
+
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A string value. For string interpolation, ' \
+            'see the erb object type.',
+          :messages => [
+            'up — Convert the string to uppercase. This message changes the value of the string.',
+            'down — Convert the string to lowercase. This message changes the value of the string.',
+            'size — Get the size of the string. It will have the string size.',
+            'count_chars — Count the number of characters in the string. It will have the character count.',
+            'count_words — Count the number of words in the string. It will have the word count.',
+            'count_lines — Count the number of lines in the string. It will have the line count.',
+            'starts_with? ({str}) — Check if the string starts with the given string. A parameter is required: the string to look for at the beginning of this string. It will have a boolean.',
+            'ends_with? ({str}) — Check if the string ends with the given string. A parameter is required: the string to look for at the end of this string. It will have a boolean.',
+            'substring? ({str}) — Check if the string includes the given sub-string. A parameter is required: the string to look for in this string. It will have a boolean.',
+            'format_for_html — Format this string for HTML output. Tabs, spaces and returns are converted to HTML elements. The value of the string is changed.',
+            'encode64 — Base64 encode the string. This message changes the value of the string. It will have the encoded string.',
+            'decode64 — Decode the string from Base64. This message changes the value of the string. It will have the decoded string.',
+            'escape — Escape the string to make it URL safe. This message changes the value of the string. It will have the escaped string.',
+            'unescape — Unescape the string (from URL safe format). This message changes the value of the string. It will have the unescaped string.',
+            'gen_uuid — Set the value of the string to a newly generated, random UUID. This message changes the value of the string.',
+            'gen_alphanumeric ({len}) — Set the value of the string to a newly generated, random alphanumeric string. The {len} parameter is optional; the length is 10 if not specified. This message changes the value of the string.',
+            'gen_hex ({len}) — Set the value of the string to a newly generated, random hex string. The {len} parameter is optional; the length is 10 if not specified. This message changes the value of the string.',
+            'gen_base64 ({len}) — Set the value of the string to a newly generated, random base64 string. The {len} parameter is optional; the length is 12 if not specified. This message changes the value of the string.',
+            'trim — Strip whitespace from the beginning and end of the string. This message changes the value of the string. It will have the trimmed string.',
+            'sub ({from}, {to}) — Substitute the first occurrence of {from} with {to}. Both parameters are required. This message changes the value of the string. It will have the result.',
+            'gsub ({from}, {to}) — Substitute all occurrences of {from} with {to}. Both parameters are required. This message changes the value of the string. It will have the result.',
+            'page — Show the value in a pager (less), for viewing long content a screen at a time.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            s [can] :
+              msg [string] : Hello World!
+              on_load [script] :
+                show s.msg
+                tell s.msg to up
+                show s.msg
+                tell s.msg to size
+                show it
+          EXAMPLES
+        }
       end
 
     end