gloo 6.1.0 → 6.2.1

data/lib/gloo/core/invoker.rb

@@ -0,0 +1,102 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Resolves, validates and invokes a function. Shared by the
+# `invoke`/`~>` verb (lib/gloo/verbs/invoke.rb) and inline calls
+# inside any expression (lib/gloo/expr/call.rb), so both go through
+# the same error handling instead of maintaining two copies of it.
+#
+
+module Gloo
+  module Core
+    class Invoker
+
+      NO_TARGET_ERR = 'Missing function reference!'.freeze
+      NOT_FOUND_ERR = 'Object was not found: '.freeze
+      NOT_FUNCTION_ERR = 'Not a function: '.freeze
+      PARAM_COUNT_ERR = 'Wrong number of parameters for function: '.freeze
+
+      #
+      # Resolve, validate and invoke the function at the given
+      # target path, with the given raw (unevaluated) arg tokens.
+      # Reports an error and returns nil for any failure - including
+      # a failure inside the function itself (see Function#invoke,
+      # which leaves `it` alone rather than setting it to an
+      # unreliable result when that happens).
+      #
+      def self.invoke( engine, target, arg_tokens )
+        if target.nil? || target.to_s.strip.empty?
+          engine.err NO_TARGET_ERR
+          return nil
+        end
+
+        func = resolve_function( engine, target )
+        return nil unless func
+
+        args = evaluate_arg_tokens( engine, arg_tokens )
+        return nil unless params_count_ok?( engine, func, args )
+
+        return invoke_function( engine, func, args )
+      end
+
+      #
+      # Resolve the function object at the target path. Reports an
+      # error and returns nil if the path doesn't resolve to
+      # anything, or resolves to an object that isn't a function.
+      #
+      def self.resolve_function( engine, target )
+        pn = Gloo::Core::Pn.new( engine, target )
+        func = pn.resolve
+
+        unless func
+          engine.err "#{NOT_FOUND_ERR}#{target}"
+          return nil
+        end
+
+        unless func.is_function?
+          engine.err "#{NOT_FUNCTION_ERR}#{target}"
+          return nil
+        end
+
+        return func
+      end
+
+      #
+      # Evaluate a list of raw tokens, each as its own single-token
+      # expression (a literal or object reference) - the standalone
+      # invoke verb's long-standing per-token semantics, now shared
+      # with the inline-call form too.
+      #
+      def self.evaluate_arg_tokens( engine, tokens )
+        return ( tokens || [] ).map do |t|
+          Gloo::Expr::Expression.new( engine, [ t ] ).evaluate
+        end
+      end
+
+      #
+      # Confirm the number of args given matches the number the
+      # function declares. Reports an error and returns false if
+      # they don't match.
+      #
+      def self.params_count_ok?( engine, func, args )
+        expected = func.params_hash&.keys&.length || 0
+        return true if args.count == expected
+
+        engine.err "#{PARAM_COUNT_ERR}#{func.pn} " \
+          "(expected #{expected}, got #{args.count})"
+        return false
+      end
+
+      #
+      # Invoke the function and return its result.
+      #
+      def self.invoke_function( engine, func, args )
+        engine.log.debug "invoking function: #{func.pn}"
+        result = func.invoke( args )
+        engine.log.debug "function returned: #{result}"
+        return result
+      end
+
+    end
+  end
+end

data/lib/gloo/core/parser.rb

@@ -39,17 +39,58 @@ module Gloo
       # If additional params were provided, split them out
       # from the token list.
       #
+      # A trailing (...) is normally the optional-param convention
+      # (eg. show "text" (color)) and gets split off here. But a
+      # trailing (...) can also be an inline function call that
+      # happens to be the last thing in the command (eg.
+      # show invoke( functions.add 3 4 )) - that must be left alone
+      # so it flows into tokenizing as part of the main command.
+      #
       def split_params( cmd )
-        params = nil
-        i = cmd.rindex( '(' )
-        if i && cmd.strip.end_with?( ')' )
-          pstr = cmd[ i + 1..-1 ]
-          params = pstr.strip[ 0..-2 ] if pstr
-          cmd = cmd[ 0, i].strip
-        end
+        i = matching_open_paren_index( cmd )
+        return cmd, nil unless i
+        return cmd, nil if inline_call_opener?( cmd, i )
+
+        pstr = cmd[ i + 1..-1 ]
+        params = pstr.strip[ 0..-2 ] if pstr
+        cmd = cmd[ 0, i ].strip
         return cmd, params
       end
 
+      #
+      # Find the index of the '(' that balances the command's final
+      # ')', counting depth from the end so an inline call earlier
+      # in the command (or nested parens) doesn't confuse the match.
+      # Returns nil if the command doesn't end with ')', or the
+      # parens aren't balanced.
+      #
+      def matching_open_paren_index( cmd )
+        return nil unless cmd.strip.end_with?( ')' )
+
+        depth = 0
+        ( cmd.length - 1 ).downto( 0 ) do |idx|
+          case cmd[ idx ]
+          when ')' then depth += 1
+          when '('
+            depth -= 1
+            return idx if depth.zero?
+          end
+        end
+        return nil
+      end
+
+      #
+      # Is the '(' at the given index immediately preceded (no
+      # space) by an inline-call keyword, eg. invoke( or ~>( ?
+      # Shares its keyword list with Gloo::Core::Tokens, which is
+      # where such a call actually gets recognized as one token.
+      #
+      def inline_call_opener?( cmd, paren_index )
+        before = cmd[ 0...paren_index ]
+        word = before[ /\S*\z/ ]
+        return Gloo::Core::Tokens::CALL_OPENERS.include?( word )
+      end
+
       #
       # Parse a command and then run it if it parsed correctly.
       #

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/help_shell.rb

@@ -41,11 +41,12 @@ module Gloo
       # List all verbs.
       #
       def cmd_show_verbs( _obj, _context )
+        theme = @engine.theme
         data = "\n"
-        data << " Verbs (shortcut, name)\n".blue
+        data << theme.heading( " Verbs (shortcut, name)\n" )
         @engine.dictionary.get_verbs.sort_by( &:keyword ).each do |v|
-          cut = v.keyword_shortcut.ljust( 5, ' ' ).yellow
-          name = v.keyword.ljust( 20, ' ' ).white
+          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"
@@ -55,14 +56,15 @@ module Gloo
       # List all object types.
       #
       def cmd_show_objects( _obj, _context )
+        theme = @engine.theme
         data = "\n"
-        data << " Objects \n".blue
+        data << theme.heading( " Objects \n" )
         @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}"
+            short = theme.accent( "(#{o.short_typename})" )
+            name = "#{theme.emphasis( o.typename )}  #{short}"
           else
-            name = o.typename.white
+            name = theme.emphasis( o.typename )
           end
           data << "   #{name.ljust( 30, ' ' )}\n"
         end
@@ -76,21 +78,44 @@ module Gloo
         @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 << " Extensions\n".blue
-        data << "   Use `load ext {name}` to load a User Extension, \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".light_black
+          "   Only loaded extensions are listed below.\n\n" )
         loaded = @engine.ext_manager.loaded_extensions
         if loaded.empty?
-          data << "   (none loaded)\n".light_black
+          data << theme.muted( "   (none loaded)\n" )
         else
           loaded.sort.each do |name, _ext|
-            data << "   #{name.white} \n"
+            data << "   #{theme.emphasis( name )} \n"
           end
         end
         @engine.log.show "#{data}\n"
@@ -100,17 +125,19 @@ module Gloo
       # List loaded libraries.
       #
       def cmd_show_libraries( _obj, _context )
+        theme = @engine.theme
         data = "\n"
-        data << " Libraries\n".blue
-        data << "   Use `load lib {name}` to load a core library, \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".light_black
+          "   Only loaded libraries are listed below.\n\n" )
         loaded = @engine.lib_manager.loaded_libraries
         if loaded.empty?
-          data << "   (none loaded)\n".light_black
+          data << theme.muted( "   (none loaded)\n" )
         else
           loaded.sort.each do |name, _lib|
-            data << "   #{name.white} \n"
+            data << "   #{theme.emphasis( name )} \n"
           end
         end
         @engine.log.show "#{data}\n"
@@ -120,10 +147,11 @@ module Gloo
       # List all narrative doc pages (dev/gloo/docs/*.md).
       #
       def cmd_show_docs( _obj, _context )
+        theme = @engine.theme
         data = "\n"
-        data << " Docs\n".blue
+        data << theme.heading( " Docs\n" )
         doc_page_names.each do |name|
-          data << "   #{name.white}\n"
+          data << "   #{theme.emphasis( name )}\n"
         end
         @engine.log.show "#{data}\n"
       end
@@ -199,6 +227,22 @@ module Gloo
 
       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.
@@ -206,7 +250,7 @@ module Gloo
       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.platform.page( Gloo::Docs::MarkdownRenderer.colorize( bracketed, @engine.theme ) )
       end
 
       #
@@ -257,6 +301,9 @@ module Gloo
           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(

data/lib/gloo/docs/markdown_renderer.rb

@@ -16,18 +16,18 @@ module Gloo
 
       #
       # Colorize the given markdown text for terminal display.
-      def self.colorize( text )
+      def self.colorize( text, theme )
         in_code = false
         lines = text.split( "\n" ).map do |line|
           if line.start_with?( '```' )
             in_code = !in_code
-            next line.light_black
+            next theme.muted( line )
           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/
+          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

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

data/lib/gloo/expr/expression.rb

@@ -47,6 +47,7 @@ module Gloo
         end
 
         return @left.value if @left.is_a? Gloo::Core::Literal
+        return @left.value if @left.is_a? Gloo::Expr::Call
         return resolve_ref @left if @left.is_a? Gloo::Core::Pn
 
         return @left
@@ -75,6 +76,7 @@ module Gloo
       #
       def evaluate_sym( sym )
         return sym.value if sym.is_a? Gloo::Core::Literal
+        return sym.value if sym.is_a? Gloo::Expr::Call
         return resolve_ref sym if sym.is_a? Gloo::Core::Pn
 
         return sym
@@ -109,6 +111,7 @@ module Gloo
         return LInteger.new( token ) if LInteger.integer?( token )
         return LString.new( token ) if LString.string?( token )
         return LDecimal.new( token ) if LDecimal.decimal?( token )
+        return Gloo::Expr::Call.new( @engine, token ) if Gloo::Expr::Call.call?( token )
 
         # last chance: an Object reference
         return Gloo::Core::Pn.new( @engine, token )

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

@@ -59,31 +59,11 @@ module Gloo
           :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.'
-          ],
+            'see the erb object type. Shares the same messages as the ' \
+            'text object type; the two differ mainly by convention — ' \
+            'string for a single word or line, text for longer, ' \
+            'multi-line blocks.',
+          :messages => StringMsgs.message_docs,
           :examples => <<~EXAMPLES.strip
             s [can] :
               msg [string] : Hello World!