gloo-cli 1.5 → 1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a167c3410e526f3dec9aa9f07c430eefd8cd031c07820bd44afa9fccd90673e
-  data.tar.gz: 9addba3dafc9ce19639752a608051c58b9d0d521bf4105bfa5ed8272e92146cc
+  metadata.gz: 7954b2c20f1f5a6cfeba8603a9578e92c439f2890420966a61f502a0af4be0fa
+  data.tar.gz: e97bb3a1cc62b6934a1e24c65004ee015723cde0db1b9693f5958a85b7b5b6b9
 SHA512:
-  metadata.gz: 266e4236bf6f3abd8d5baf20859262eacb7b109da6cce66789587d6d17e4b4b9aed2e7e70d5ebd4a69868868c8fa2636cbb5c68d1265668eb15dff63121c08f5
-  data.tar.gz: 4e47277e9afaf8b01a9cd00312d2ba8bd9b9457705db97acccc8ef323ff09a260aabe6668fdd235c4684d4bdfca48421c3ba32def50343c5f270c8c70987633a
+  metadata.gz: 9f4ff97d30afe5771e50e485f5a00eb75a07675e746a28bd4c6cc6ae76ffe51aa1f1c4cbefd858d9705c7ac68870c651ca23278f5dffcf451743d8832cdb7856
+  data.tar.gz: fc892775cffe97cc74b7f0f4a8f8187c12afbd9dff580d141f6d5dba396737fd8c6c50c41c5594ff6fdd3d8d1e328e8c4563d0ddd97d990c8f80120dd84c33d3

data/README.md

@@ -0,0 +1,26 @@
+# gloo-cli
+
+A core gloo library for command-line interface applications.
+
+## Usage
+
+Load this library in a gloo script:
+
+```gloo
+> load lib cli
+```
+
+## Objects
+
+- `prompt` — CLI prompt for user input
+- `select` — prompt for user to select from a list of options
+- `confirm` — CLI confirmation prompt
+- `menu` — a CLI menu, for a main loop or sub-menu of choices
+- `menu_item` — a single element in a CLI menu
+- `colorize` — write colored/styled output to the terminal
+- `shell` — an interactive command-driven shell (REPL)
+- `command` — a single command in a shell's command tree
+
+## Full Reference
+
+Every object's children and messages are documented in-app once the library is loaded — e.g. `help> object prompt`.

data/lib/cli_colorize.rb

@@ -66,4 +66,40 @@ class CliColorize < Gloo::Core::Obj
     @engine.heap.it.set_to msg.to_s
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'The Colorize object can be used to write output ' \
+        'in color. The Colorize container can contain multiple ' \
+        'strings, each one can have a different color as specified by ' \
+        'the names of the children.',
+      :children => [
+        '[color] (string) — The name of the child or children is the color. The string\'s value is what will be written out.'
+      ],
+      :messages => [
+        'run — Output the string in the color specified.'
+      ],
+      :examples => <<~EXAMPLES.strip
+        color [can] :
+          w [colorize] :
+            white [string] : This is white!
+          m [colorize] :
+            red [string] : red -
+            green [string] : green -
+            blue [string] : blue
+          on_load [script] :
+            run color.w
+            run color.m
+      EXAMPLES
+    }
+  end
+
 end

data/lib/cli_confirm.rb

@@ -89,4 +89,34 @@ class CliConfirm < Gloo::Core::Obj
     set_result result
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'CLI confirmation prompt.',
+      :children => [
+        "prompt (string) — Default: '> '. The confirmation prompt.",
+        'result (boolean) — The result of the prompt.'
+      ],
+      :messages => [
+        'run — Prompt the user and then set the result.'
+      ],
+      :examples => <<~EXAMPLES.strip
+        confirm [confirm] :
+          prompt [string] : Are you sure?
+          result [boolean] :
+          on_load [script] :
+            run confirm
+            show 'Confirmed: ' + confirm.result
+      EXAMPLES
+    }
+  end
+
 end

data/lib/command.rb

@@ -202,9 +202,9 @@ class Command < Gloo::Core::Obj
     return data
   end
 
-  # 
+  #
   # Get the command data for this command.
-  # 
+  #
   def get_command_data
     if dynamic?
       return {
@@ -231,4 +231,37 @@ class Command < Gloo::Core::Obj
     end
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'A single command in a shell\'s command tree. ' \
+        'Register it with a shell (via the register message) to make ' \
+        'it selectable at that shell\'s prompt; when selected, its ' \
+        'action script runs.',
+      :children => [
+        'name (string) — The command\'s name, as typed at the shell prompt.',
+        'description (string) — Shown alongside the command name when the shell lists its options.',
+        'action (script) — Run when the command is selected.',
+        'dynamic (string) — Optional. Marks this as a dynamic command whose children are generated at runtime from a named shell context list (set via a sibling command\'s options_key, or directly via Shell#set_context), rather than being declared up front.',
+        'nodes (container) — Optional. A container of child command objects, for a nested command tree under this one.',
+        'context (string) — Populated automatically with the selected child\'s name when a dynamic command\'s action runs.',
+        'options (container) — Optional. A fixed list of values for a dynamic command\'s source list, registered under options_key.',
+        'options_key (string) — Optional. The shell context key that options gets registered under.'
+      ],
+      :messages => [
+        'register ({shell.path}) — Register this command with the given shell object, adding it to that shell\'s command tree. A parameter is required: the path to the shell.'
+      ],
+      :notes => 'No vault documentation exists for this object type — ' \
+        'this was authored directly from the code.'
+    }
+  end
+
 end

data/lib/menu.rb

@@ -363,4 +363,68 @@ class Menu < Gloo::Core::Obj
 
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'A CLI menu. This can be used for the main loop ' \
+        'of a CLI application. Many of the children are optional; some ' \
+        'will be created dynamically if they are not specified in the ' \
+        'source file. Note that a Quit menu item will be added ' \
+        'dynamically if one is not specified in the source file.',
+      :children => [
+        "prompt (string) — Default: '> '. Optional; if not provided a default timestamp option is used. The prompt shown for menu item selection.",
+        'items (container) — The list of menu items.',
+        'loop (boolean) — Run the menu in a loop? If true, once a menu item has run, the menu prompts again; setting it to false ends the menu. Created dynamically if not specified.',
+        'title (string) — Optional title to use rather than manually implementing a menu header. With a title, the default and before_menu items are not needed.',
+        'hide_items (boolean) — Optional, false by default. If false, the menu items are shown each time through the loop; if true, they\'re hidden (can always be shown by typing ? at the prompt).',
+        'default (script) — Optional. Run if no other option is selected (RETURN pressed). Can be used to clear the screen, for example.',
+        'before_menu (script) — Optional. Run at the top of each loop through the menu.'
+      ],
+      :messages => [
+        'run — Show the options and the prompt, then run the script for the user\'s selection. Optionally repeat as long as the loop child is true.'
+      ],
+      :notes => 'Built-in menu items, always available: q — quit this ' \
+        'menu (quits the app if this is the root menu, or goes up to ' \
+        'the prior menu if a sub-menu); qq — quit to the top level ' \
+        'menu (not shown); q! — quit gloo entirely (not shown); ' \
+        ': {command} — run a gloo command not part of the running app; ' \
+        ': (alone) — quit the running app and drop into gloo, keeping ' \
+        'loaded app objects in the stack.',
+      :examples => <<~EXAMPLES.strip
+        simple [menu] :
+          on_load [script] :
+            run simple
+          title [string] : Simple Menu
+          items [can] :
+            h [mitem] : Run Hello World
+              do [script] : show 'Hello World!'
+
+        menu [menu] :
+          on_load [script] :
+            run menu
+          prompt [string] : >
+          loop [bool] : true
+          items [can] :
+            hw [mitem] :
+              shortcut [str] : hw
+              description [str] : Run Hello World
+              do [script] :
+                show 'Hello World!'
+            q [mitem] :
+              shortcut [str] : q
+              description [str] : Quit this menu
+              do [script] :
+                put false into menu.loop
+      EXAMPLES
+    }
+  end
+
 end

data/lib/menu_item.rb

@@ -88,4 +88,24 @@ class MenuItem < Gloo::Core::Obj
     return super
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'A CLI menu item. One element in a CLI menu.',
+      :children => [
+        'shortcut (string) — Optional. May be used to select the menu item. If not provided, the name of the menu item is used instead.',
+        'description (string) — Optional. A textual description of the menu item action. If not provided, the value of the menu item is used instead.',
+        'do (script) — The script that will be run if the menu item is selected.'
+      ]
+    }
+  end
+
 end

data/lib/prompt.rb

@@ -119,4 +119,35 @@ class Prompt < Gloo::Core::Obj
     set_result result
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'CLI prompt for user input.',
+      :children => [
+        "prompt (string) — Default: '>'. The prompt displayed to the user.",
+        "result (string) — The result with the user's input."
+      ],
+      :messages => [
+        'run — Prompt the user and then set the result.',
+        'multiline — Show a multiline prompt.'
+      ],
+      :examples => <<~EXAMPLES.strip
+        ask [ask] :
+          prompt [string] : What is your name?
+          result [string] :
+          on_load [script] :
+            run ask
+            show 'Hello, ' + ask.result + '!  Thanks for playing'
+      EXAMPLES
+    }
+  end
+
 end

data/lib/select.rb

@@ -120,4 +120,39 @@ class Select < Gloo::Core::Obj
     set_result self.key_for_option( result )
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'Prompt for user to select from a list of options.',
+      :children => [
+        "prompt (string) — Default: '> '. The prompt displayed to the user.",
+        'options (container) — The list of options for the selection list. The name of each option is presented to the user, but the value is put in the result.',
+        "result (string) — The result with the user's selection."
+      ],
+      :messages => [
+        'run — Prompt the user for a selection and then set the result.'
+      ],
+      :examples => <<~EXAMPLES.strip
+        select [select] :
+          prompt [string] : What is your favorite color?
+          options [can] :
+            red : r
+            green : g
+            blue : b
+          result [string] :
+          on_load [script] :
+            run select
+            show select.result
+      EXAMPLES
+    }
+  end
+
 end

data/lib/shell.rb

@@ -205,12 +205,52 @@ class Shell < Gloo::Core::Obj
   #
   def add_quit_command
     return unless include_quit?
-    
+
     @runner.add_command_node({
       name: "quit",
-      description: "Quit the application", 
+      description: "Quit the application",
       method: "cmd_quit"
     })
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'A CLI shell — an interactive command-driven ' \
+        'REPL, or a one-shot command executor when the app is invoked ' \
+        'with extra command-line arguments. Build up the command tree ' \
+        'by adding command objects (see the command object type) that ' \
+        'register themselves with this shell.',
+      :children => [
+        "prompt (string) — Default: '> '. The prompt shown at each turn of the REPL.",
+        'default_action (script) — Run when the user presses RETURN with no input.',
+        'include_quit (boolean) — Optional. If true, a built-in quit command is added automatically.',
+        'on_error (script) — Optional. Run when a command raises an error.',
+        "on_unknown_command (script) — Optional. Run when the input doesn't match any known command; if absent, a default \"Unknown command\" message is shown instead.",
+        'on_empty_command (script) — Optional. Run when the user submits an empty line.',
+        'before_action (script) — Optional. Run before every command executes.',
+        'after_action (script) — Optional. Run after every command executes.'
+      ],
+      :messages => [
+        'start — Start the shell. If the app was invoked with extra command-line arguments, execute that one command and return; otherwise enter the interactive REPL.',
+        'stop — Stop a running shell.'
+      ],
+      :notes => 'No vault documentation exists for this object type — ' \
+        'this was authored directly from the code. Commands attach to ' \
+        'a shell either by declaring a command object as a child and ' \
+        'sending it the register message with this shell\'s path, or ' \
+        'by calling add_command directly. The underlying tree/REPL ' \
+        'engine here was later ported into dev/gloo itself (as ' \
+        'Gloo::Shell::Runner) to power the interactive help shell.'
+    }
+  end
+
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gloo-cli
 version: !ruby/object:Gem::Version
-  version: '1.5'
+  version: '1.6'
 platform: ruby
 authors:
 - Eric Crane
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Adds CLI support to Gloo.
 email:
@@ -17,6 +16,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/cli_colorize.rb
 - lib/cli_confirm.rb
 - lib/command.rb
@@ -29,12 +29,12 @@ files:
 - lib/shell.rb
 - lib/shell_context.rb
 - lib/shell_runner.rb
-homepage: https://gloo.ecrane.us/
+homepage: https://github.com/ecrane/gloo
 licenses:
 - MIT
 metadata:
   gloo.type: core-library
-post_install_message:
+  documentation_uri: https://github.com/ecrane/gloo
 rdoc_options: []
 require_paths:
 - lib
@@ -49,8 +49,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Gloo core library. CLI support.
 test_files: []