gloo 6.1.0 → 6.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d840aa7f080d3daedcc5bbb7311b5403d40ea859edef9d88caca22b76caee6c
-  data.tar.gz: c324e249c1a307000b1de509573a5c03de4420bae941efb69ea0b1adcd927d47
+  metadata.gz: abd0d2250aa7924305d71bc59ae30d88646ca4cca4464a15fb3acec674aa2635
+  data.tar.gz: 928c5dd7dd0a90b28707ec6383958a2f70de344659c0e87a5de79ab37f2dde95
 SHA512:
-  metadata.gz: 48cb54242371f5b6589ba0baacf71da8b75c4f1118fecb6ba78eccb17be0f03d920551f0d93d6512802827c7bfa0cae462cf05a993f77061f525d9d6277c9e8d
-  data.tar.gz: 1bc77db8417820182b27b1f7b797f1587e21dc595d89d06b3250f8db983df149d9564f258bee5b4139182e3af95ceb9dfb23b07b533fcea5bbfe9f803a50eac1
+  metadata.gz: ffffea710873468a26f3fc01e02a141ed001d2960dedfb66288451119df7af7daf2814d530d4436988227c7c3dd21e2f442e8060c8a6f58b644484eef3b36362
+  data.tar.gz: 4daa427abc7ebcb4f054911a1d4bc54b2a9d239cfa7f3aab85894bcd32ce79ffa62b18106ab7e6699bbe9599fe73b73e01270cf6cd774b81b85ad6b3c81ba295

data/CLAUDE.md

@@ -29,7 +29,7 @@ gloo/
 
 This project is the authoritative source for gloo language documentation — not the `vaults/gloo` Obsidian vault, whose old `doc/` folder was renamed to `doc_deprecated/` and retired.
 
-- **Narrative reference** — `docs/*.md`, ten flat files: `getting_started.md`, `application.md`, `language_objects.md`, `language_syntax.md`, `language_scripting.md`, `operators.md`, `iterators.md`, `objects.md`, `verbs.md`, `plugins.md`. Linked from the root `README.md`. Convention: no markdown link syntax between pages (plain-text pointers instead, e.g. "see Put" not `[Put](put.md)`) since these are read both on GitHub and in a terminal; `---` separates sections that came from different source material.
+- **Narrative reference** — `docs/*.md`, eleven flat files: `getting_started.md`, `application.md`, `language_objects.md`, `language_syntax.md`, `language_scripting.md`, `operators.md`, `iterators.md`, `objects.md`, `verbs.md`, `plugins.md`, `web_app.md`. Linked from the root `README.md`. Convention: no markdown link syntax between pages (plain-text pointers instead, e.g. "see Put" not `[Put](put.md)`) since these are read both on GitHub and in a terminal; `---` separates sections that came from different source material.
 - **Verb/object reference** — each verb (`lib/gloo/verbs/*.rb`) and object type (`lib/gloo/objs/**/*.rb`) class defines `self.doc_data` (name, shortcut, description, syntax, parameters, result, errors, examples, notes — see `lib/gloo/docs/doc_data.rb`), rendered by the in-app interactive help shell (`help`/`?`, see `lib/gloo/docs/help_shell.rb`). When adding or changing a verb or object type, add/update its `doc_data` too.
 - Core-lib gems (`gloo_core_libraries`) follow the same `doc_data` pattern for their own verbs/objects; a narrative `doc/` folder per gem is planned but not yet built.
 

data/README.md

@@ -47,6 +47,7 @@ Read in order for a guided tour of the language, top to bottom, or jump straight
 8. [Operators](docs/operators.md) — math and comparison operators
 9. [Iterators](docs/iterators.md) — each, repeat
 10. [Plugins](docs/plugins.md) — core libraries and user extensions
+11. [A Trivial Web App](docs/web_app.md) — a two-page "Hello World" built with the `gloo-web` core library
 
 
 ## License

data/docs/application.md

@@ -64,6 +64,7 @@ When specifying a file there are a couple ways to reference the gloo file to ope
              - If a file is provided as a parameter this option does not need to be specified.
 --test       - Run in Test mode
 --version    - Show application version
+--help       - Show the help screen
 ```
 
 ## Configuration
@@ -86,12 +87,12 @@ gloo:
   # Run this script when starting up gloo.
   # (Only if a script file is not specified.)
   #
-  start_with: start
+  start_with:
 
   #
   # Indentation (spaces) when showing an object outline.
   #
-  list_indent: 3
+  list_indent: 2
 
   #
   # Show listing the object tree,
@@ -104,6 +105,23 @@ gloo:
   # Show debug statements in the log?
   #
   debug: false
+
+  #
+  # Color theme for console output: dark or light.
+  # Match this to your terminal's background.
+  #
+  theme: dark
+```
+
+## Color Theme
+
+Gloo colors its console output (prompts, `help settings`, warnings/errors, listings, the help shell) to be readable against a terminal background. There's no auto-detection — set `theme: dark` or `theme: light` in `gloo.yml` to match your terminal, and it applies everywhere at once. Defaults to `dark` if unset or set to anything else.
+
+To see the current theme and preview both palettes side by side (handy for comparing across terminals before you switch), use the `theme` help topic:
+
+```gloo
+> help
+help> theme
 ```
 
 ## Logging
@@ -133,11 +151,12 @@ Gloo has a built-in `help` verb (shortcut `?`) that enters an interactive help s
 help
 ```
 
-From the `help>` prompt, look up verbs, object types, settings, extensions, libraries, and narrative doc pages, or get detailed help for a specific verb, object, doc page, loaded library, or loaded extension:
+From the `help>` prompt, look up verbs, object types, settings, the color theme, extensions, libraries, and narrative doc pages, or get detailed help for a specific verb, object, doc page, loaded library, or loaded extension:
 
 - `verbs` — list all verbs
 - `objects` — list all object types
 - `settings` — show application settings
+- `theme` — show the current color theme, how to change it, and a preview of both palettes
 - `extensions` — list loaded extensions (only loaded extensions are shown; use `load ext {name}` first)
 - `libraries` — list loaded libraries (only loaded libraries are shown; use `load lib {name}` first)
 - `docs` — list all narrative doc pages (this page and its siblings)
@@ -153,6 +172,7 @@ From the `help>` prompt, look up verbs, object types, settings, extensions, libr
 help> verbs
 help> verb put
 help> object container
+help> theme
 help> docs
 help> doc getting_started
 help> library db
@@ -161,4 +181,4 @@ help> quit
 
 ### Narrative Docs in the Shell
 
-This page and its nine siblings (`docs/*.md` in the interpreter's source) are the same files shown by `help> doc {name}` — there's no separate doc server or web mode. A `gloo --doc` local web server was considered and put off in favor of this: one system, no separate build/serve step.
+This page and its ten siblings (`docs/*.md` in the interpreter's source) are the same files shown by `help> doc {name}` — there's no separate doc server or web mode. A `gloo --doc` local web server was considered and put off in favor of this: one system, no separate build/serve step.

data/docs/getting_started.md

@@ -55,9 +55,7 @@ Once Gloo is running you can interact with the gloo interpreter. Type the follow
 
 ### CLI, On Ruby
 
-Gloo is a scripting language and a CLI runtime engine. It was built primarily to run on the Mac and has hooks into several Mac technologies. It runs, at least nominally, on Windows and Linux as well.
-
-Gloo was built in Ruby as a gem. More than that, it has hooks into ruby, can run ruby code, and shares a lot the way ruby works.
+Gloo is a scripting language and a CLI runtime engine. It was built and tested primarily on the Mac. It runs, at least nominally, on Windows and Linux as well.
 
 ### The Name "Gloo" and a Bit of History
 
@@ -109,4 +107,4 @@ Interaction with objects is done by sending messages to them.
 
 ## Source Code
 
-Gloo source code is in GitHub (https://github.com/ecrane/gloo), although the repository is currently private. It might be made public in the future if there is interest or need.
+Gloo source code is in GitHub (https://github.com/ecrane/gloo). It's shared publicly for visibility rather than as a maintained open-source project.

data/docs/language_objects.md

@@ -129,7 +129,7 @@ Here are some of the value conversions that gloo will attempt:
     - decimal with integer value
     - `put 1 into d` => 1.0
 - string to boolean
-    - if the string is ~ 'true' then the boolean is true, otherwise false
+    - if the string is (trimmed, case-insensitive) 'true' or 't' then the boolean is true; 'false' or 'f' is false; anything else is false
     - `put 'true' into bool` => true
 - boolean to string
     - simple to-string conversion: 'true' or 'false'

data/docs/language_syntax.md

@@ -5,6 +5,7 @@
 - Color
 - Errors
 - Events
+- Function Calls
 - Gloo System Objects
 - Here
 - It
@@ -24,6 +25,8 @@ black
 yellow
 ```
 
+These are the common ones, but any color name from the `colorize` gem works too (e.g. `cyan`, `magenta`, or a `light_` variant of any of the above).
+
 The color names are considered as virtual objects but may also be referenced in variables. See the example below.
 
 ```gloo
@@ -54,14 +57,14 @@ To run a command that generates an error:
 
 ```
 > put 3 into
-'put' must include 'into' target
+Target (into) missing!
 ```
 
 Then, showing the error:
 
 ```
 > show error
-'put' must include 'into' target
+Target (into) missing!
 ```
 
 But, as mentioned, the next command will clear out the last error. If you need to keep track of the result of a command, you should put the error into another object.
@@ -144,6 +147,30 @@ error_data [can] :
 
 See also: Load, Reload, Unload, Save, Quit.
 
+## Function Calls
+
+The `invoke` verb (shortcut `~>`) calls a function object (`[ƒ]`) as a standalone command, space-separated params:
+
+```gloo
+invoke functions.add 3 4
+show it
+```
+
+`invoke( ... )` and `~>( ... )` are the inline forms of the same thing — usable anywhere an expression is evaluated (`show`, `put ... into`, `if`, `unless`, `eval`, and more), not just as a standalone command:
+
+```gloo
+show invoke( functions.add 3 4 )
+put ~>( functions.add 3 4 ) into total
+show "Total: " + invoke( functions.add 3 4 )
+if invoke( checks.is_ready ) then show 'ready'
+```
+
+`invoke(...)` and `~>(...)` are exactly equivalent — just the full keyword and its shortcut, same as the standalone verb. Params stay space-separated inside the parens; each one is evaluated as a single token (a literal or object reference), same as the standalone verb — not a multi-token sub-expression, so `invoke( f 3+4 )` won't parse `3+4` as one param.
+
+The parens must immediately follow the keyword with no space (`invoke(`, not `invoke (`) — that's what tells gloo it's a function call rather than `show`'s unrelated trailing `(color)` syntax, which always has a space before the paren.
+
+See also: Color.
+
 ## Gloo System Objects
 
 The gloo system objects are virtual objects. That is, they can be accessed like other objects, but the values are set by the system. The values cannot be updated. The other difference is that the virtual objects do not show up in the object heap.

data/docs/plugins.md

@@ -13,30 +13,74 @@ Be sure to load a core library (or extension) prior to loading a gloo file that
 
 Use the Load Verb to use an extension.
 
+A core library ships as its own gem (`gloo-<name>`). `load lib <name>` requires the gem, installing it first via `gem install` if it isn't already present — so the explicit `gem install` step below is optional, but doing it yourself ahead of time is recommended so the install doesn't happen mid-script. Once loaded, a library's objects and verbs show up in the `help`/`?` shell exactly like built-ins:
+
+```gloo
+> gem install gloo-yaml
+> load lib yaml
+help> object yaml
+```
+
 ### Available Core Libraries
 
 - **CLI** — Use the `gloo-cli` gem when building CLI applications.
     - Library Objects: Prompt, Colorize, Confirm, Select, Menu, Menu Item, Shell, Command
+    ```gloo
+    > gem install gloo-cli
+    > load lib cli
+    help> object prompt
+    ```
 - **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
+    ```gloo
+    > gem install gloo-db gloo-sqlite
+    > load lib db
+    > load lib sqlite
+    help> object query
+    ```
 - **Email** — Use the `gloo-email` gem to send and receive email.
     - Library Objects: Email, Email SMTP, Email IMAP
+    ```gloo
+    > gem install gloo-email
+    > load lib email
+    help> object email_smtp
+    ```
 - **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)
+    ```gloo
+    > gem install gloo-md
+    > load lib md
+    help> object markdown
+    ```
 - **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
+    ```gloo
+    > gem install gloo-test
+    > load lib test
+    help> verb assert
+    ```
 - **Web Server** — Use the `gloo-web` gem when building web applications.
     - Library Objects: Server, Page, Partial, Form, Field, Element
+    ```gloo
+    > gem install gloo-web
+    > load lib web
+    help> object page
+    ```
 - **YAML** — Use the `gloo-yaml` gem for YAML file read/write support.
     - Library Objects: YAML
+    ```gloo
+    > gem install gloo-yaml
+    > load lib yaml
+    help> object 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.
+Extensions are ruby code that live in the `extensions` folder inside the gloo root folder (`~/gloo/extensions` by default — see `ext_path` in Settings).
 
 An extension is structured thus:
 
@@ -46,9 +90,287 @@ An extension is structured thus:
     /doc/
     /src/
     /test/
-    /ext_name.rb
+    /ext_name_ext.rb
 ```
 
+- `ext_name_ext.rb` — the extension's entry point. Loaded and registered when `load ext ext_name` runs.
+- `src/` — the verb and/or object classes themselves, one file per class.
+- `doc/` — narrative markdown for the extension (a `README.md` at the extension root plus optional per-object/verb `.md` files under `doc/` are the convention used by the built-in extensions — see e.g. `extensions/beep/`).
+- `test/` — both Ruby unit tests (`*_test.rb`, minitest, same conventions as this project's own `test/` — see Test Suites in the root `CLAUDE.md`) and/or a gloo-language integration test (`*.test.gloo`).
+
 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.
+Use the Load Verb to use an extension: `load ext ext_name`.
+
+### The extension entry point
+
+`ext_name_ext.rb` defines a class named `<ExtName>Ext` (the extension's folder name, capitalized, plus `Ext`) that derives from `Gloo::Plugin::Base` and implements `register`. `register` is handed a `Gloo::Plugin::Callback` that it uses to register one or more verb and/or object classes:
+
+```ruby
+#
+# Registers the beep extension.
+#
+# This extension provides a simple beep command.
+#
+class BeepExt < Gloo::Plugin::Base
+
+    #
+    # Register verbs and objects.
+    #
+    def register( callback )
+      require_relative 'src/beep'
+
+      callback.register_verb( Beep )
+    end
+
+end
+```
+
+`callback.register_verb` and `callback.register_obj` both take a class, not an instance. Wrap the calls in a `begin`/`rescue` if the extension has external dependencies (a gem, a CLI tool on the `PATH`, etc.) that might not be present, so a missing dependency logs an error instead of crashing the whole extension load — see `extensions/stats/stats_ext.rb` or `extensions/git/git_ext.rb` for the pattern:
+
+```ruby
+def register( callback )
+  require_relative 'src/git'
+
+  begin
+    callback.register_obj( Git )
+  rescue => e
+    puts "Failed to load Git extension: #{e.message}"
+  end
+end
+```
+
+### Adding a Verb
+
+A verb subclasses `Gloo::Core::Verb` and must implement `self.keyword`, `self.keyword_shortcut`, and `run`. Inside `run`, `@tokens` gives access to the parsed command line and `@engine` is the running engine (use `@engine.err` for user-facing errors, `@engine.heap.it` to set the implicit `it` result).
+
+The simplest possible verb — `beep`, which takes no parameters (`extensions/beep/src/beep.rb`):
+
+```ruby
+#
+# Play a standard system beep sound.
+#
+class Beep < Gloo::Core::Verb
+
+  KEYWORD = 'beep'.freeze
+  KEYWORD_SHORT = 'b'.freeze
+
+  def self.keyword
+    return KEYWORD
+  end
+
+  def self.keyword_shortcut
+    return KEYWORD_SHORT
+  end
+
+  def run
+    print 7.chr
+  end
+
+  # ---------------------------------------------------------------------
+  #    Verb Documentation
+  # ---------------------------------------------------------------------
+
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'Play a standard system beep sound.',
+      :syntax => [ 'beep' ],
+      :result => 'A system beep (chime) is sounded.',
+      :examples => <<~EXAMPLES.strip
+        > beep
+      EXAMPLES
+    }
+  end
+
+end
+```
+
+A verb that reads a parameter — `alert`, which evaluates an expression and shows it as a system notification (`extensions/alert/src/alert.rb`):
+
+```ruby
+class Alert < Gloo::Core::Verb
+
+  KEYWORD = 'alert'.freeze
+  KEYWORD_SHORT = '!'.freeze
+
+  MISSING_EXPR_ERR = 'Missing Expression!'.freeze
+  NO_RESULT_ERR = 'Expression evaluated with no result!'.freeze
+
+  def run
+    unless @tokens.token_count > 1
+      @engine.err MISSING_EXPR_ERR
+      return
+    end
+
+    expr = Gloo::Expr::Expression.new( @engine, @tokens.params )
+    result = expr.evaluate
+
+    if result
+      @engine.heap.it.set_to result
+      post_alert result
+    else
+      @engine.err NO_RESULT_ERR
+    end
+  end
+
+  def self.keyword
+    return KEYWORD
+  end
+
+  def self.keyword_shortcut
+    return KEYWORD_SHORT
+  end
+
+  private
+
+  def post_alert( msg )
+    @engine.log.info msg
+    return if @engine.args.quiet?
+
+    post_osx msg
+  end
+
+  def post_osx( msg )
+    cmd1 = '/usr/bin/osascript -e "display notification \"'
+    cmd2 = '\" with title \"Gloo\" "'
+    system( cmd1 + msg.to_s + cmd2 )
+  end
+
+end
+```
+
+Register it from `alert_ext.rb` with `callback.register_verb( Alert )`, and the verb `alert {message}` becomes available anywhere after `load ext alert`.
+
+### Adding an Object
+
+An object subclasses `Gloo::Core::Obj` and must implement `self.typename` and `self.short_typename`. Objects typically:
+
+- expose named children (settings/parameters) that are read with `find_child`
+- optionally auto-add default children on creation, via `add_children_on_create?` and `add_default_children`
+- respond to messages (`tell obj to some_message`) by overriding `self.messages` to list the message names and defining a `msg_<name>` method for each
+
+`stats`, from `extensions/stats/src/stats.rb`, shows all three. It declares three children (`folder`, `types`, `skip`), adds them automatically on `create`, and implements three messages that delegate to a plain Ruby helper class (`Gloo::Utils::Stats`, in `extensions/stats/src/stats_util.rb`) that does the real work:
+
+```ruby
+class Stats < Gloo::Core::Obj
+
+  KEYWORD = 'stats'.freeze
+  KEYWORD_SHORT = 'stat'.freeze
+  FOLDER = 'folder'.freeze
+  TYPES = 'types'.freeze
+  SKIP = 'skip'.freeze
+
+  def self.typename
+    return KEYWORD
+  end
+
+  def self.short_typename
+    return KEYWORD_SHORT
+  end
+
+  def path_value
+    o = find_child FOLDER
+    return o ? o.value : nil
+  end
+
+  def types_value
+    o = find_child TYPES
+    return o ? o.value : ''
+  end
+
+  def skip_list
+    o = find_child SKIP
+    val = o ? o.value : ''
+    return val.split ' '
+  end
+
+  # ---------------------------------------------------------------------
+  #    Children
+  # ---------------------------------------------------------------------
+
+  def add_children_on_create?
+    return true
+  end
+
+  def add_default_children
+    fac = @engine.factory
+    fac.create_file FOLDER, '', self
+    fac.create_string TYPES, '', self
+    fac.create_can SKIP, self
+  end
+
+  # ---------------------------------------------------------------------
+  #    Messages
+  # ---------------------------------------------------------------------
+
+  def self.messages
+    all = %w[show_all]
+    more = %w[show_busy_folders show_types]
+    return super + all + more
+  end
+
+  def msg_show_all
+    o = Gloo::Utils::Stats.new(
+      @engine, path_value, types_value, skip_list )
+    o.show_all
+  end
+
+  def msg_show_types
+    o = Gloo::Utils::Stats.new(
+      @engine, path_value, types_value, skip_list )
+    o.file_types
+  end
+
+  def msg_show_busy_folders
+    o = Gloo::Utils::Stats.new(
+      @engine, path_value, types_value, skip_list )
+    o.busy_folders
+  end
+
+end
+```
+
+`self.messages` should call `super` and append to it — the base `Gloo::Core::Obj` already contributes messages every object receives (`reload`, `unload`, `blank?`, `contains?`, `responds_to?`).
+
+Used from gloo, once loaded:
+
+```gloo
+main [can] :
+  stats [stats] :
+    folder [file] : /Users/me/dev/project
+    types [string] : rb erb js
+    skip [string] : .git tmp
+  on_load [script] :
+    tell main.stats to show_all
+```
+
+Register it from `stats_ext.rb` with `callback.register_obj( Stats )`.
+
+### Custom `each` iterators
+
+An extension's object can also plug into the built-in `each` verb by providing its own iterator. `extensions/git/src/each_repo.rb` shows the shape: a plain Ruby class (not a `Gloo::Core::Obj`) with `self.use_for?( iterator_obj )` — which returns `true` when the `each` loop's iterator object looks like a match (here, when it has a `repo` child) — and a `run` method that walks whatever it's iterating over, setting the loop's child value and calling `@iterator_obj.run_do` for each item. See the git extension for the full pattern; this hook only makes sense for extensions that also register a matching object type (here, `git_repo`).
+
+### Documenting the extension
+
+Add `self.doc_data` to every verb/object class (see the `beep` and `stats` examples above) — this is what powers the in-app `help`/`?` shell once the extension is loaded, exactly as it does for built-in verbs and objects (see `lib/gloo/docs/doc_data.rb`). Also add a top-level `README.md` for the extension (usage, `load ext` line, list of verbs/objects, a pointer to `help> verb <name>` / `help> object <name>` for the full reference) — see `extensions/beep/README.md` or `extensions/git/README.md` for the expected shape and length.
+
+### Testing an extension
+
+Add a Ruby unit test per verb/object class under `test/` (mirrors the conventions in the root `CLAUDE.md`'s Test Suites section — inherit from the project's `GlooTest`/`BaseEngineTest` base), and add a `*.test.gloo` integration test that loads the extension and exercises it end to end, e.g. `extensions/beep/test/beep.test.gloo`:
+
+```gloo
+tests [can] :
+  beep [can] :
+
+    on_load [script] :
+      load ext beep
+
+    assert_verb [test] :
+      description [string] : The beep verb exists
+      on_test [script] :
+        exists? verb beep
+        assert "beep verb should exist"
+        beep
+```