gloo 6.0.1 → 6.2.0

data/lib/gloo/core/tokens.rb

@@ -9,6 +9,15 @@ module Gloo
   module Core
     class Tokens
 
+      # Keywords that open an inline function call, eg. invoke( ... )
+      # or ~>( ... ). Kept here since Tokens is where they get
+      # recognized as a single bounded token; Parser#split_params
+      # reuses this same list to avoid mistaking a trailing call for
+      # its unrelated trailing-optional-param convention.
+      CALL_OPENERS = %w[invoke ~>].freeze
+
+      QUOTE_CHARS = [ '"', "'" ].freeze
+
       attr_reader :cmd, :tokens
 
       # ---------------------------------------------------------------------
@@ -142,8 +151,19 @@ module Gloo
       #
       # Create a list of token from the given string.
       #
+      # An inline call (invoke( ... ) / ~>( ... )) is checked for
+      # first since it needs to be quote-aware in its own right (a
+      # call's args can include a quoted string) - see
+      # find_call_range. Falls through to the original quote-then-
+      # plain-split handling, unchanged, when there's no call.
+      #
       def tokenize( str )
-        if str.index( '"' )
+        range = find_call_range( str )
+        if range
+          tokenize( str[ 0...range.first ] ) if range.first.positive?
+          @tokens << str[ range ]
+          tokenize( str[ range.last + 1..-1 ] ) if range.last + 1 < str.length
+        elsif str.index( '"' )
           i = str.index( '"' )
           j = str.index( '"', i + 1 )
           j ||= str.length
@@ -164,6 +184,66 @@ module Gloo
         end
       end
 
+      #
+      # Find the char range of the first top-level (not inside a
+      # quoted string) invoke(...)/~>(...) call in str. Returns nil
+      # if there isn't one, or it's never properly closed.
+      #
+      def find_call_range( str )
+        i = 0
+        while i < str.length
+          ch = str[ i ]
+
+          if QUOTE_CHARS.include?( ch )
+            close = str.index( ch, i + 1 )
+            return nil unless close
+
+            i = close + 1
+            next
+          end
+
+          CALL_OPENERS.each do |kw|
+            opener = "#{kw}("
+            next unless str[ i, opener.length ] == opener
+            next unless i.zero? || str[ i - 1 ] =~ /\s/
+
+            close = find_matching_close_paren( str, i + opener.length - 1 )
+            return ( i..close ) if close
+          end
+
+          i += 1
+        end
+        return nil
+      end
+
+      #
+      # Given the index of an open paren, find the index of its
+      # balancing close paren - skipping over quoted substrings so
+      # a stray paren character inside a quoted arg doesn't throw
+      # off the depth count. Returns nil if it's never closed.
+      #
+      def find_matching_close_paren( str, open_index )
+        depth = 0
+        i = open_index
+        while i < str.length
+          ch = str[ i ]
+          if QUOTE_CHARS.include?( ch )
+            close = str.index( ch, i + 1 )
+            return nil unless close
+
+            i = close + 1
+            next
+          elsif ch == '('
+            depth += 1
+          elsif ch == ')'
+            depth -= 1
+            return i if depth.zero?
+          end
+          i += 1
+        end
+        return nil
+      end
+
     end
   end
 end

data/lib/gloo/docs/doc_data.rb

@@ -0,0 +1,160 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Documentation data for a primitive: a verb or an object.
+#
+# Renders as plain markdown - no color/ANSI here. Color is applied
+# separately, at display time, by Gloo::Docs::MarkdownRenderer, so
+# this stays reusable wherever the raw markdown is useful (paging,
+# export, tests).
+#
+
+module Gloo
+  module Docs
+    class DocData
+
+      DESCRIPTION = '## Description'.freeze
+      SYNTAX = '## Syntax'.freeze
+      PARAMETERS = '## Parameters'.freeze
+      CHILDREN = '## Children'.freeze
+      MESSAGES = '## Messages'.freeze
+      RESULT = '## Result'.freeze
+      ERRORS = '## Errors'.freeze
+      EXAMPLES = '## Examples'.freeze
+      NOTES = '## Notes'.freeze
+      FENCE = '```gloo'.freeze
+
+      attr_accessor :name, :shortcut, :description, :syntax,
+        :parameters, :children, :messages, :result, :errors,
+        :examples, :notes
+
+      def initialize( value_hash )
+        @name = value_hash[:name]
+        @shortcut = value_hash[:shortcut]
+        @description = value_hash[:description]
+        @syntax = value_hash[:syntax]
+        @parameters = value_hash[:parameters]
+        @children = value_hash[:children]
+        @messages = value_hash[:messages]
+        @result = value_hash[:result]
+        @errors = value_hash[:errors]
+        @examples = value_hash[:examples]
+        @notes = value_hash[:notes]
+      end
+
+      #
+      # Render the documentation as a markdown string.
+      def render
+        buf = +''
+        add_name buf
+        add_description buf
+        add_syntax buf
+        add_parameters buf
+        add_children buf
+        add_messages buf
+        add_result buf
+        add_errors buf
+        add_examples buf
+        add_notes buf
+        buf << "\n"
+        return buf
+      end
+
+      #
+      # Show the documentation in the terminal.
+      def show_in_terminal
+        puts render
+      end
+
+      private
+
+      #
+      # Append the name and shortcut, if there is a name.
+      def add_name( buf )
+        return unless @name
+
+        buf << "\n# #{@name}\n"
+        buf << "#{@shortcut}\n" if @shortcut
+      end
+
+      #
+      # Append the description, if there is one.
+      def add_description( buf )
+        return unless @description
+
+        buf << "\n#{DESCRIPTION}\n#{@description}\n"
+      end
+
+      #
+      # Append the syntax lines, if there are any.
+      def add_syntax( buf )
+        return unless @syntax
+
+        buf << "\n#{SYNTAX}\n#{FENCE}\n"
+        @syntax.each { |line| buf << "#{line}\n" }
+        buf << "```\n"
+      end
+
+      #
+      # Append the parameter lines, if there are any.
+      def add_parameters( buf )
+        return unless @parameters
+
+        buf << "\n#{PARAMETERS}\n"
+        @parameters.each { |line| buf << "- #{line}\n" }
+      end
+
+      #
+      # Append the child lines, if there are any.
+      def add_children( buf )
+        return unless @children
+
+        buf << "\n#{CHILDREN}\n"
+        @children.each { |line| buf << "- #{line}\n" }
+      end
+
+      #
+      # Append the message lines, if there are any.
+      def add_messages( buf )
+        return unless @messages
+
+        buf << "\n#{MESSAGES}\n"
+        @messages.each { |line| buf << "- #{line}\n" }
+      end
+
+      #
+      # Append the result, if there is one.
+      def add_result( buf )
+        return unless @result
+
+        buf << "\n#{RESULT}\n#{@result}\n"
+      end
+
+      #
+      # Append the error lines, if there are any.
+      def add_errors( buf )
+        return unless @errors
+
+        buf << "\n#{ERRORS}\n"
+        @errors.each { |line| buf << "- #{line}\n" }
+      end
+
+      #
+      # Append the example code, if there is any.
+      def add_examples( buf )
+        return unless @examples
+
+        buf << "\n#{EXAMPLES}\n#{FENCE}\n#{@examples}\n```\n"
+      end
+
+      #
+      # Append the notes, if there are any.
+      def add_notes( buf )
+        return unless @notes
+
+        buf << "\n#{NOTES}\n#{@notes}\n"
+      end
+
+    end
+  end
+end

data/lib/gloo/docs/help_shell.rb

@@ -0,0 +1,332 @@
+# 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 )
+        theme = @engine.theme
+        data = "\n"
+        data << theme.heading( " Verbs (shortcut, name)\n" )
+        @engine.dictionary.get_verbs.sort_by( &:keyword ).each do |v|
+          cut = theme.accent( v.keyword_shortcut.ljust( 5, ' ' ) )
+          name = theme.emphasis( v.keyword.ljust( 20, ' ' ) )
+          data << "   #{cut}  #{name} \n"
+        end
+        @engine.log.show "#{data}\n"
+      end
+
+      #
+      # List all object types.
+      #
+      def cmd_show_objects( _obj, _context )
+        theme = @engine.theme
+        data = "\n"
+        data << theme.heading( " Objects \n" )
+        @engine.dictionary.get_obj_types.sort_by( &:typename ).each do |o|
+          if o.short_typename != o.typename
+            short = theme.accent( "(#{o.short_typename})" )
+            name = "#{theme.emphasis( o.typename )}  #{short}"
+          else
+            name = theme.emphasis( o.typename )
+          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
+
+      #
+      # Show the current theme, how to change it, and a color preview
+      # of both palettes - handy for checking how they actually render
+      # in whatever terminal you're sitting in.
+      #
+      def cmd_show_theme( _obj, _context )
+        theme = @engine.theme
+        settings = @engine.settings
+        config_file = File.join( settings.config_path, 'gloo.yml' )
+
+        data = "\n"
+        data << theme.heading( " Theme\n" )
+        data << "   Current theme:  #{theme.emphasis( settings.theme )}\n\n"
+        data << theme.muted( "   Change it in #{config_file}:\n" )
+        data << theme.muted( "     theme: dark   (or: light)\n\n" )
+        data << theme_preview( ' Dark palette', Gloo::App::Theme.new( 'dark' ) )
+        data << "\n"
+        data << theme_preview( ' Light palette', Gloo::App::Theme.new( 'light' ) )
+        @engine.log.show "#{data}\n"
+      end
+
+      #
+      # List loaded extensions.
+      #
+      def cmd_show_extensions( _obj, _context )
+        theme = @engine.theme
+        data = "\n"
+        data << theme.heading( " Extensions\n" )
+        data << theme.muted(
+          "   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" )
+        loaded = @engine.ext_manager.loaded_extensions
+        if loaded.empty?
+          data << theme.muted( "   (none loaded)\n" )
+        else
+          loaded.sort.each do |name, _ext|
+            data << "   #{theme.emphasis( name )} \n"
+          end
+        end
+        @engine.log.show "#{data}\n"
+      end
+
+      #
+      # List loaded libraries.
+      #
+      def cmd_show_libraries( _obj, _context )
+        theme = @engine.theme
+        data = "\n"
+        data << theme.heading( " Libraries\n" )
+        data << theme.muted(
+          "   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" )
+        loaded = @engine.lib_manager.loaded_libraries
+        if loaded.empty?
+          data << theme.muted( "   (none loaded)\n" )
+        else
+          loaded.sort.each do |name, _lib|
+            data << "   #{theme.emphasis( name )} \n"
+          end
+        end
+        @engine.log.show "#{data}\n"
+      end
+
+      #
+      # List all narrative doc pages (dev/gloo/docs/*.md).
+      #
+      def cmd_show_docs( _obj, _context )
+        theme = @engine.theme
+        data = "\n"
+        data << theme.heading( " Docs\n" )
+        doc_page_names.each do |name|
+          data << "   #{theme.emphasis( name )}\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
+
+      #
+      # Build a labeled preview block for one theme's palette: one line
+      # per role, colored in that role's own color, labeled with the
+      # role's name. Padding is applied to the plain label before it's
+      # colorized, so the ANSI codes don't throw off the alignment.
+      #
+      def theme_preview( title, theme )
+        lines = "#{theme.heading( title )}\n"
+        Gloo::App::Theme::ROLES.each do |role|
+          label = role.to_s.ljust( 12 )
+          lines << theme.send( role, "   #{label}#{role}" )
+          lines << "\n"
+        end
+        return lines
+      end
+
+      #
+      # 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, @engine.theme ) )
+      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: 'theme', description: 'Show the current theme and preview both palettes',
+          method: 'cmd_show_theme' )
+        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, theme )
+        in_code = false
+        lines = text.split( "\n" ).map do |line|
+          if line.start_with?( '```' )
+            in_code = !in_code
+            next theme.muted( line )
+          end
+          next theme.muted( line ) if in_code
+          next theme.heading( line.sub( /^#\s*/, '' ) ) if line.start_with?( '# ' )
+          next theme.subheading( line.sub( /^##\s*/, '' ) ) if line.start_with?( '## ' )
+          next theme.subheading( line ) if line.start_with?( '### ' ) || line.start_with?( '#### ' )
+          next theme.muted( line ) if line =~ /\A-{3,}\z/
+
+          line
+        end
+        return lines.join( "\n" )
+      end
+
+    end
+  end
+end

data/lib/gloo/expr/call.rb

@@ -0,0 +1,54 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# An inline function call inside an expression, eg.
+# invoke( functions.add 3 4 ) or ~>( functions.add 3 4 ).
+#
+# Gloo::Core::Tokens recognizes the whole invoke(...)/~>(...) span
+# as one token; Call takes that single token, splits it back out
+# into a target path and raw arg tokens (reusing Tokens itself, so
+# quoted args and nested calls tokenize the same way they would
+# anywhere else), and hands both to Gloo::Core::Invoker - the same
+# resolve/validate/invoke path the standalone invoke verb uses.
+#
+
+module Gloo
+  module Expr
+    class Call
+
+      attr_reader :target, :arg_tokens
+
+      #
+      # Does the given token look like an inline call?
+      #
+      def self.call?( token )
+        return false unless token.is_a?( String )
+
+        return Gloo::Core::Tokens::CALL_OPENERS.any? do |kw|
+          token.start_with?( "#{kw}(" ) && token.end_with?( ')' )
+        end
+      end
+
+      #
+      # Parse the call token into a target path and raw arg tokens.
+      #
+      def initialize( engine, token )
+        @engine = engine
+
+        inner = token[ token.index( '(' ) + 1..-2 ].to_s
+        tokens = Gloo::Core::Tokens.new( inner )
+        @target = tokens.first
+        @arg_tokens = tokens.params || []
+      end
+
+      #
+      # Resolve, validate and invoke - returns the result value, or
+      # nil if it failed (an error will already have been reported).
+      #
+      def value
+        return Gloo::Core::Invoker.invoke( @engine, @target, @arg_tokens )
+      end
+
+    end
+  end
+end