gloo 6.0.1 → 6.2.0

data/gloo.gemspec

@@ -11,9 +11,11 @@ Gem::Specification.new do |spec|
 
   spec.summary       = %q{Gloo scripting language.  A scripting language built on ruby.}
   spec.description   = %q{A scripting languge to keep it all together.}
-  spec.homepage      = "http://github.com/ecrane/gloo"
+  spec.homepage      = "https://github.com/ecrane/gloo"
   spec.license       = 'MIT'
 
+  spec.metadata['documentation_uri'] = 'https://github.com/ecrane/gloo'
+
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do

data/lib/VERSION

@@ -1 +1 @@
-6.0.1
+6.2.0

data/lib/VERSION_NOTES

@@ -1,3 +1,19 @@
+6.2.0 - 2026.08.18
+ - Adds light | dark mode option for terminal output.
+ - Adds inline function invocation.
+ - Adds split messages for strings and text objects.
+
+
+6.1.0 - 2026.08.04
+ - Adds narrative documentation: 10 pages in `docs/`, covering getting started, application, language objects/syntax/scripting, operators, iterators, objects, verbs, and plugins
+ - Adds an in-app interactive help shell (`help`/`?`) to look up verbs, objects, settings, libraries, extensions, and doc pages, with tab completion
+ - Adds `doc_data` to every verb and object type, in the interpreter and its core library gems, rendered by the help shell
+ - Fixes gemspecs so docs and READMEs are actually packaged with the gem and its core libraries
+ - Adds a table of contents and reading order to the README's documentation list
+ - Fixes the rubygems.org "Documentation" link
+ - Adds page message to string and text
+
+
 6.0.1 - 2026.07.16
  - Update dependencies to newer versions for better security.
 

data/lib/gloo/app/engine.rb

@@ -31,10 +31,14 @@ module Gloo
         @args = Args.new( self, context.params )
         @settings = Settings.new( self, context.user_root )
 
+        # Platform (and its theme) needs to be ready before Log is
+        # constructed - Log reads engine.theme, which reads through
+        # to platform.theme, in its own initialize.
+        @platform = context.platform
+        @platform.theme = Gloo::App::Theme.new( @settings.theme )
+
         @log = context.log.new( self, @args.quiet? )
         @log.debug "log (class: #{@log.class.name}) in use ..."
-
-        @platform = context.platform
         @log.debug "platform (class: #{@platform.class.name}) in use ..."
 
         @handling_exception = false
@@ -42,6 +46,17 @@ module Gloo
         @log.debug 'engine intialized...'
       end
 
+      #
+      # Get the active theme. Platform is the single source of
+      # truth for it (Prompt/Table only hold a @platform reference,
+      # not an @engine one) - this just reads through to that,
+      # rather than keeping a second ivar that could drift out of
+      # sync if something reassigns platform.theme directly.
+      #
+      def theme
+        return @platform.theme
+      end
+
       #
       # Start the engine.
       # Load object and verb definitions and setup engine elements.

data/lib/gloo/app/log.rb

@@ -38,6 +38,7 @@ module Gloo
         @engine = engine
         @quiet = quiet
         @debug = engine.settings.debug
+        @theme = engine.theme
 
         create_loggers
 
@@ -160,7 +161,7 @@ module Gloo
       def warn( msg )
         @logger.warn msg
         @error.warn msg
-        puts msg.yellow unless @quiet
+        puts @theme.warn( msg ) unless @quiet
       end
 
       #
@@ -175,11 +176,11 @@ module Gloo
         if ex
           @error.error ex.message
           @error.error ex.backtrace
-          puts msg.red unless @quiet
-          puts ex.message.red unless @quiet
+          puts @theme.error( msg ) unless @quiet
+          puts @theme.error( ex.message ) unless @quiet
           puts ex.backtrace unless @quiet
         else
-          puts msg.red unless @quiet
+          puts @theme.error( msg ) unless @quiet
         end
       end
 

data/lib/gloo/app/platform.rb

@@ -13,8 +13,12 @@ module Gloo
 
       DEFAULT_TMP_FILE = 'tmp.txt'.freeze
       RETURN = "\n".freeze
+      DEFAULT_LINES = 24
+      DEFAULT_COLS = 80
+      PAGER_CMD = 'less -R -F -X'.freeze
 
       attr_reader :prompt, :table
+      attr_accessor :theme
 
       #
       # Set up Platform.
@@ -22,6 +26,10 @@ module Gloo
       def initialize
         @prompt = Gloo::App::Prompt.new( self )
         @table = Gloo::App::Table.new( self )
+
+        # Default theme, in case this platform is ever used
+        # standalone, without an Engine to set the real one.
+        @theme = Gloo::App::Theme.new
       end
 
       #
@@ -31,6 +39,22 @@ module Gloo
         puts msg
       end
 
+      #
+      # Show a message in a pager (less), for long content.
+      # Falls back to a plain puts when there is no real terminal
+      # to page in (piped output, captured test output, etc) or
+      # when less isn't available on the system.
+      #
+      def page( msg )
+        return show( msg ) unless $stdout.tty?
+
+        IO.popen( PAGER_CMD, 'w' ) { |less| less.puts msg }
+      rescue Errno::ENOENT
+        show( msg )
+      rescue Errno::EPIPE
+        # The user quit the pager early. Nothing more to do.
+      end
+
       #
       # Clear the screen.
       #
@@ -64,18 +88,26 @@ module Gloo
       # ---------------------------------------------------------------------
       #
       # Get the number of vertical lines on screen.
+      # Falls back to a default when stdout has no real screen behind it
+      # (piped/captured output, no controlling TTY, etc).
       #
       def lines
-        rows, columns = $stdout.winsize
+        rows, _columns = $stdout.winsize
         return rows
+      rescue StandardError
+        return DEFAULT_LINES
       end
 
       #
       # Get the number of horizontal columns on screen.
+      # Falls back to a default when stdout has no real screen behind it
+      # (piped/captured output, no controlling TTY, etc).
       #
       def cols
-        rows, columns = $stdout.winsize
+        _rows, columns = $stdout.winsize
         return columns
+      rescue StandardError
+        return DEFAULT_COLS
       end
 
       # ---------------------------------------------------------------------

data/lib/gloo/app/prompt.rb

@@ -87,7 +87,8 @@ module Gloo
         dt = DateTime.now
         d = dt.strftime( '%Y.%m.%d' )
         t = dt.strftime( '%I:%M:%S' )
-        return "#{'gloo'.blue} #{d.yellow} #{t.white} >"
+        theme = @platform.theme
+        return "#{theme.heading( 'gloo' )} #{theme.accent( d )} #{theme.emphasis( t )} >"
       end
 
     end

data/lib/gloo/app/settings.rb

@@ -10,10 +10,13 @@ module Gloo
   module App
     class Settings
 
+      DEFAULT_THEME = 'dark'.freeze
+      THEMES = %w[dark light].freeze
+
       attr_reader :user_root, :log_path,
         :config_path, :project_path, :ext_path,
         :start_with, :list_indent, :list_levels, :tmp_path,
-        :debug_path, :debug
+        :debug_path, :debug, :theme
 
       #
       # Load setting from the yml file.
@@ -33,26 +36,29 @@ module Gloo
       # Can be seen in app with 'help settings'
       #
       def show
-        puts "\n Application Settings:".blue
-        puts '   Startup with:  '.yellow + @start_with.white
-        puts '   Indent in Listing:  '.yellow + @list_indent.to_s.white
-        puts '   List Levels:  '.yellow + @list_levels.to_s.white
-        puts '   Debug?  '.yellow + @debug.to_s.white
-        puts '   Screen Lines:  '.yellow + Gloo::App::Settings.lines( @engine ).to_s.white
-        puts '   Page Size:  '.yellow + Gloo::App::Settings.page_size( @engine ).to_s.white
+        theme = @engine.theme
+        puts theme.heading( "\n Application Settings:" )
+        puts theme.accent( '   Startup with:  ' ) + theme.emphasis( @start_with.to_s )
+        puts theme.accent( '   Indent in Listing:  ' ) + theme.emphasis( @list_indent.to_s )
+        puts theme.accent( '   List Levels:  ' ) + theme.emphasis( @list_levels.to_s )
+        puts theme.accent( '   Debug?  ' ) + theme.emphasis( @debug.to_s )
+        puts theme.accent( '   Theme:  ' ) + theme.emphasis( @theme )
+        puts theme.accent( '   Screen Lines:  ' ) + theme.emphasis( Gloo::App::Settings.lines( @engine ).to_s )
+        puts theme.accent( '   Page Size:  ' ) + theme.emphasis( Gloo::App::Settings.page_size( @engine ).to_s )
         self.show_paths
       end
-      
+
       #
       # Show path settings
       #
       def show_paths
-        puts "\n Application Paths:".blue
-        puts '   User Root Path is here:  '.yellow + @user_root.white
-        puts '   Projects Path:  '.yellow + @project_path.white
-        puts '   Extensions Path:  '.yellow + @ext_path.white
-        puts '   Tmp Path:  '.yellow + @tmp_path.white
-        puts '   Debug Path:  '.yellow + @debug_path.white
+        theme = @engine.theme
+        puts theme.heading( "\n Application Paths:" )
+        puts theme.accent( '   User Root Path is here:  ' ) + theme.emphasis( @user_root )
+        puts theme.accent( '   Projects Path:  ' ) + theme.emphasis( @project_path )
+        puts theme.accent( '   Extensions Path:  ' ) + theme.emphasis( @ext_path )
+        puts theme.accent( '   Tmp Path:  ' ) + theme.emphasis( @tmp_path )
+        puts theme.accent( '   Debug Path:  ' ) + theme.emphasis( @debug_path )
         puts "\n"
       end
 
@@ -154,6 +160,9 @@ module Gloo
         @list_levels = settings[ 'gloo' ][ 'list_levels' ]
 
         @debug = settings[ 'gloo' ][ 'debug' ]
+
+        @theme = settings[ 'gloo' ][ 'theme' ]&.strip&.downcase
+        @theme = DEFAULT_THEME unless THEMES.include?( @theme )
       end
 
       #
@@ -184,6 +193,7 @@ module Gloo
             list_indent: 2
             list_levels: 3
             debug: false
+            theme: #{DEFAULT_THEME}
         TEXT
         return str
       end

data/lib/gloo/app/table.rb

@@ -3,7 +3,6 @@
 #
 # CLI input.
 #
-require 'colorize'
 require 'terminal-table'
 
 module Gloo
@@ -28,14 +27,19 @@ module Gloo
       #
       # Show the given table data.
       #
+      # Deliberately left uncolored: box-drawing borders and text read
+      # fine against the terminal's own default colors, and forcing a
+      # fixed foreground/background (as this used to do) fought
+      # whatever theme the terminal was actually running.
+      #
       def show( headers, data, title = nil )
         unless title.blank?
-          table = Terminal::Table.new( 
+          table = Terminal::Table.new(
             :title => title, :headings => headers, :rows => data )
         else
           table = Terminal::Table.new( :headings => headers, :rows => data )
         end
-        puts table.to_s.colorize( color: :white, background: :black )
+        puts table.to_s
       end
 
       

data/lib/gloo/app/theme.rb

@@ -0,0 +1,144 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Maps semantic color roles (heading, emphasis, etc) onto actual
+# ANSI colors for the app's UI chrome (prompt, settings, log,
+# tables, listings, help). Callers ask for a role, never a literal
+# color, so a single palette swap (dark/light) fixes every call
+# site at once.
+#
+# NOT used by the user-facing `show {target} (color)` verb or the
+# `[colorize]` core-lib object - those are explicit color choices
+# made in gloo scripts, not app chrome, and are intentionally left
+# alone.
+#
+# Design note: most of the base 8 ANSI colors (red/green/yellow/
+# blue/magenta/cyan) are exactly what a well-built terminal color
+# scheme remaps per-background to stay legible - that's what
+# switching a terminal profile from dark to light is for. `white`
+# is the exception: by convention it stays "lightest foreground"
+# regardless of background, so text forced to `.white` goes
+# near-invisible on a light background no matter how good the
+# terminal theme is. That's why :emphasis flips color between the
+# two palettes below.
+#
+# `yellow` and `cyan` turned out to be further exceptions in
+# practice: tested against a real light-background terminal, both
+# were washed out and hard to read - the terminal's own theme
+# wasn't remapping them as dark/saturated as hoped. So the light
+# palette diverges from dark on more than just :emphasis, using
+# explicit 256-color values (:ansi, raw SGR codes - none of these
+# have a true equivalent in the base 16 ANSI colors) picked by eye
+# against a real light terminal:
+#   - :warn uses orange instead of yellow
+#   - :accent uses a dark green instead of yellow
+#   - :subheading uses navy instead of cyan
+#
+require 'colorize'
+require 'colorized_string'
+
+module Gloo
+  module App
+    class Theme
+
+      # 256-color values picked by eye against a real light-background
+      # terminal - see design note above. 256-color support has been
+      # effectively universal in terminals for well over a decade.
+      ORANGE = '38;5;208'.freeze
+      NAVY = '38;5;18'.freeze
+      DARK_GREEN = '38;5;22'.freeze
+
+      #
+      # Dark-background palette. This matches the colors gloo
+      # has always used, so it's the default and non-breaking.
+      #
+      DARK = {
+        :heading    => { :color => :blue, :mode => :bold },
+        :subheading => { :color => :cyan, :mode => :bold },
+        :accent     => { :color => :yellow },
+        :emphasis   => { :color => :white },
+        :muted      => { :color => :light_black },
+        :warn       => { :color => :yellow },
+        :error      => { :color => :red }
+      }.freeze
+
+      #
+      # Light-background palette.
+      #
+      LIGHT = {
+        :heading    => { :color => :blue, :mode => :bold },
+        :subheading => { :ansi => NAVY },
+        :accent     => { :ansi => DARK_GREEN },
+        :emphasis   => { :color => :black },
+        :muted      => { :color => :light_black },
+        :warn       => { :ansi => ORANGE },
+        :error      => { :color => :red }
+      }.freeze
+
+      PALETTES = { 'dark' => DARK, 'light' => LIGHT }.freeze
+      ROLES = DARK.keys.freeze
+
+      attr_reader :name
+
+      #
+      # Set up the theme for the given theme name ('dark' or 'light').
+      # Falls back to the default (dark) for anything else.
+      #
+      def initialize( name = nil )
+        @name = PALETTES.key?( name ) ? name : Gloo::App::Settings::DEFAULT_THEME
+        @palette = PALETTES[ @name ]
+      end
+
+      #
+      # Build a Theme from the engine's settings.
+      #
+      def self.for_engine( engine )
+        return new( engine&.settings&.theme )
+      end
+
+      #
+      # Colorize the given string for the given semantic role.
+      # Unknown roles are returned unchanged rather than raising,
+      # so a typo'd role degrades to plain text instead of crashing.
+      #
+      # Named colors (:color/:mode) go through the colorize gem;
+      # :ansi is a raw SGR parameter string for colors the gem's
+      # named palette doesn't have (eg. 256-color orange).
+      #
+      def apply( str, role )
+        style = @palette[ role ]
+        return str.to_s unless style
+        return ansi_wrap( str.to_s, style ) if style[ :ansi ]
+
+        params = {}
+        params[ :color ] = style[ :color ] if style[ :color ]
+        params[ :mode ] = style[ :mode ] if style[ :mode ]
+        return ColorizedString[ str.to_s ].colorize( params ).to_s
+      end
+
+      #
+      # Define a convenience method per role, eg. theme.heading( str ).
+      #
+      ROLES.each do |role|
+        define_method( role ) do |str|
+          apply( str, role )
+        end
+      end
+
+      private
+
+      #
+      # Wrap a string in a raw SGR escape sequence - used for :ansi
+      # styles (eg. 256-color orange) that the colorize gem's named
+      # 16-color palette can't express.
+      #
+      def ansi_wrap( str, style )
+        codes = []
+        codes << String.mode_codes[ style[ :mode ] ] if style[ :mode ]
+        codes << style[ :ansi ]
+        return "\e[#{codes.join( ';' )}m#{str}\e[0m"
+      end
+
+    end
+  end
+end

data/lib/gloo/core/gloo_system.rb

@@ -278,13 +278,64 @@ module Gloo
       def self.open_for_platform
         return 'open' if OS.mac?
         return 'xdg-open' if OS.posix?
-        
+
         return 'Start-Process' if OS.windows?
         return 'explorer.exe' if self.wsl?
 
         return nil
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'The gloo system objects are virtual objects — ' \
+            "accessed like other objects (via 'gloo' or the shortcut " \
+            '$), but their values are set by the system and cannot be ' \
+            'updated. They also do not show up in the object heap. Some ' \
+            'names include an underscore to separate words; a period ' \
+            'can be used instead, so gloo.working_dir and ' \
+            'gloo.working.dir are identical.',
+          :children => [
+            'app — Path of the running app (same as gloo_projects).',
+            'hostname — Get the system hostname.',
+            'user — Get the logged in user.',
+            'line — A carriage return (line feed) character.',
+            "user_home — Get the user's home directory.",
+            'working_dir — Get the working directory.',
+            'gloo_home — Get the gloo home directory.',
+            'gloo_config — Get the gloo configuration directory.',
+            'gloo_projects — Get the gloo projects directory.',
+            'gloo_log — Get the gloo logging directory.',
+            'screen_lines — Get the number of lines on screen.',
+            'screen_cols — Get the number of columns on screen.',
+            'platform_cpu — Get the platform CPU.',
+            'platform_os — Get the platform operating system.',
+            'platform_version — Get the platform version.',
+            'platform_windows? — Is the platform Windows?',
+            'platform_unix? — Is the platform Unix?',
+            'platform_linux? — Is the platform Linux?',
+            'platform_mac? — Is the platform Mac?'
+          ],
+          :examples => <<~EXAMPLES.strip
+            > show gloo.user
+            > show $.user
+
+            > show gloo.working_dir
+            > show gloo.working.dir
+            > show $.working_dir
+            > show $.working.dir
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

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.
       #