gloo 6.0 → 6.1.0

data/docs/plugins.md

@@ -0,0 +1,54 @@
+# Plugins
+
+**Contents**
+
+- Core Libraries
+- User Extensions
+
+## Core Libraries
+
+Core Libraries extend gloo functionality, primarily by adding object types and potentially verbs.
+
+Be sure to load a core library (or extension) prior to loading a gloo file that includes object types defined in the library.
+
+Use the Load Verb to use an extension.
+
+### Available Core Libraries
+
+- **CLI** — Use the `gloo-cli` gem when building CLI applications.
+    - Library Objects: Prompt, Colorize, Confirm, Select, Menu, Menu Item, Shell, Command
+- **Database** — Use the `gloo-db` gem and one or more of `gloo-sqlite`, `gloo-mysql`, `gloo-pg` connector gems.
+    - Library Objects: Query, Table, SQLite, MySQL, Postgres
+- **Email** — Use the `gloo-email` gem to send and receive email.
+    - Library Objects: Email, Email SMTP, Email IMAP
+- **Markdown** — Use the `gloo-md` gem to render markdown.
+    - Library Objects: Markdown, MD Doc (a markdown file with YAML frontmatter), Markdown Extensions (part of the markdown object)
+- **Test** — Use the `gloo-test` gem to manually include. See Test Runner for notes about the gloo test runner.
+    - Library Objects: Test
+    - Library Verbs: Assert, Refute
+    - See also: Eval, It
+- **Web Server** — Use the `gloo-web` gem when building web applications.
+    - Library Objects: Server, Page, Partial, Form, Field, Element
+- **YAML** — Use the `gloo-yaml` gem for YAML file read/write support.
+    - Library Objects: YAML
+
+## User Extensions
+
+A User Extension is a mechanism that can be used to add verbs and objects that are not built into gloo.
+
+Extensions are ruby code that live in the `extensions` folder inside the gloo root folder.
+
+An extension is structured thus:
+
+```
+~/gloo/extensions/
+  /ext_name
+    /doc/
+    /src/
+    /test/
+    /ext_name.rb
+```
+
+Be sure to load an extension (or core library) prior to loading a gloo file that includes object types defined in the extension.
+
+Use the Load Verb to use an extension.

data/docs/verbs.md

@@ -0,0 +1,64 @@
+# Verbs
+
+Verbs are the commands that make up a gloo script — `put`, `show`, `run`, `tell`, and 25 others. Every statement in gloo starts with a verb.
+
+Verbs aren't just for scripts, though. They're also the interactive language of the gloo application itself: run `gloo` in CLI mode (see Application, Running Gloo) and you can type these same verbs directly at the prompt, one at a time, in a REPL.
+
+**Contents**
+
+- Run
+- Tell
+- Put
+
+This page walks through three of the most commonly used verbs to get a feel for how they work together. For the complete list of verbs, their full syntax, and every error they can raise, use the in-app help: enter `help` (or `?`), then `verbs` to list them all, or `verb {name}` for detail on one (see Application, Help).
+
+## Run
+
+`run` runs a script or other runnable object — the same as sending it a `run` message.
+
+```gloo
+run {path.to.object}
+```
+
+```gloo
+> run my.script
+
+> create s as script : "show 3 + 4"
+> run s
+```
+
+## Tell
+
+`tell` sends a message to an object, asking it to do something. Where `run` executes a runnable object, `tell` is the general-purpose way to invoke any message an object supports (`up`, `count`, `inc`, `randomize` — see Objects).
+
+```gloo
+tell {path.to.object} to {message}
+```
+
+```gloo
+> tell an.obj to unload
+> tell the.script to run
+> tell my.str to up
+> tell the.container to count
+```
+
+## Put
+
+`put` evaluates an expression and stores the result in an object.
+
+```gloo
+put {expression} into {dst.path}
+```
+
+```gloo
+> put 'one' into str
+> put 123 into x
+> put 3 + 5 into x
+> put TRUE into flag
+```
+
+`it` also picks up the result of the evaluation, same as with other verbs — see It.
+
+---
+
+`run`, `tell`, and `put` cover a lot of ground on their own, but there are 26 more verbs — `show`, `if`, `create`, `each`, `check`, and so on — all documented in-app. Enter `help` (or `?`), then `verbs` to browse them. (This page itself is also viewable in-app: `help> doc verbs`.)

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
@@ -33,10 +35,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'minitest', '~> 5.1', '>= 5.14.2'
   spec.add_development_dependency "rake", '~> 13.0', '>= 13.0.1'
-  spec.add_development_dependency 'concurrent-ruby', '1.3.4'
+  spec.add_development_dependency 'concurrent-ruby', '~> 1.3.7'
 
   # Used by many objects
-  spec.add_dependency "activesupport", '~> 6.1', ">= 6.1.5" 
+  spec.add_dependency "activesupport", '~> 7.2.3.1'
 
   # Used by date and time tools
   spec.add_dependency 'chronic', '~> 0.10', '>= 0.10.2'

data/lib/VERSION

@@ -1 +1 @@
-6.0
+6.1.0

data/lib/VERSION_NOTES

@@ -1,3 +1,17 @@
+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.
+
+
 6.0 - 2026.07.12
  - General code cleanup, additional tests added.
  - ERB object's template can now be an alias.

data/lib/gloo/app/platform.rb

@@ -13,6 +13,9 @@ 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
 
@@ -31,6 +34,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 +83,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/settings.rb

@@ -34,7 +34,7 @@ module Gloo
       #
       def show
         puts "\n Application Settings:".blue
-        puts '   Startup with:  '.yellow + @start_with.white
+        puts '   Startup with:  '.yellow + @start_with.to_s.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

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/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